> ## Documentation Index
> Fetch the complete documentation index at: https://developers.manglai.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Consumptions (Consumos)

> Registro de consumos energéticos, operativos, de vehículos y maquinaria

## Descripción

Los **consumos** son el registro de energía, combustibles o actividad (ej. km recorridos). A partir de ellos se calculan las emisiones según GHG Protocol.

## Endpoints

| Método | Ruta                             | Descripción                |
| ------ | -------------------------------- | -------------------------- |
| GET    | `/api/v1/consumptions`           | Listar consumos            |
| GET    | `/api/v1/consumptions/{id}`      | Obtener un consumo         |
| POST   | `/api/v1/consumptions`           | Crear o actualizar consumo |
| GET    | `/api/v1/consumptions/dashboard` | Dashboard de consumos      |

## Tipos de consumos

* **Facturas:** Electricidad, calor, combustibles, agua, residuos
* **Vehículos:** Consumo de flota
* **Encuestas:** Datos de actividad manual

## Campos requeridos para crear consumo

* `id` (UUID)
* `entityId` (invoice, vehicle o survey answer)
* `categoryId` (de `GET /api/v1/categories`)
* `startDate`, `endDate` (ISO 8601)
* `companyId`, `buildingId`
* `quantity`, `unitType` (kWh, l, km, etc.)

## Consumos de vehículos y maquinaria

<Info>
  Antes de crear estos consumos, crea el vehículo o máquina en [Vehicles (Vehículos)](/api/es/resources/vehicles). Después usa su `id` como `entityId`.
</Info>

Para vehículos o maquinaria de combustión, `emissionsCategoryIds` debe incluir la categoría principal y `FUEL_RELATED_ACTIVITIES`.

### A) Combustible de vehículos

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440011",
  "entityId": "550e8400-e29b-41d4-a716-446655440010",
  "categoryId": "3cba8fda-4e40-4aae-ae76-ead6e24d5e6a",
  "companyId": "1b1e07a7-083d-4831-a1d2-84b6e93a1572",
  "buildingId": "7fef7760-f9e7-4de9-ae35-8c37db65e4a3",
  "startDate": "2025-01-01T00:00:00.000Z",
  "endDate": "2025-01-31T23:59:59.999Z",
  "quantity": 120,
  "unitType": "l",
  "extraData": {
    "fuelTypeCode": "diesel",
    "vehicleCategory": "passenger-cars"
  },
  "emissionsCategoryIds": [
    "3cba8fda-4e40-4aae-ae76-ead6e24d5e6a",
    "dd16800c-c79f-4717-9de6-07e15f4ceb64"
  ]
}
```

`entityId` es el `id` del vehículo creado previamente. `unitType` puede ser, por ejemplo, `l` para litros o `km` para distancia recorrida.

### B) Maquinaria

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440021",
  "entityId": "550e8400-e29b-41d4-a716-446655440020",
  "categoryId": "ec7b571f-bb67-4b08-9a02-46b8f2ef159f",
  "companyId": "1b1e07a7-083d-4831-a1d2-84b6e93a1572",
  "buildingId": "7fef7760-f9e7-4de9-ae35-8c37db65e4a3",
  "startDate": "2025-01-01T00:00:00.000Z",
  "endDate": "2025-01-31T23:59:59.999Z",
  "quantity": 80,
  "unitType": "l",
  "extraData": {
    "fuelTypeCode": "diesel",
    "vehicleCategory": "industrial-machinery"
  },
  "emissionsCategoryIds": [
    "ec7b571f-bb67-4b08-9a02-46b8f2ef159f",
    "dd16800c-c79f-4717-9de6-07e15f4ceb64"
  ]
}
```

Categorías habituales de maquinaria:

| Tipo       | `categoryId`                           | `extraData.vehicleCategory` |
| ---------- | -------------------------------------- | --------------------------- |
| Industrial | `ec7b571f-bb67-4b08-9a02-46b8f2ef159f` | `industrial-machinery`      |
| Agrícola   | `7b34bb95-c224-4b2b-b1df-8ebedff1405f` | `agricultural-machinery`    |
| Forestal   | `0cc0905f-0c7f-4b68-a87b-43700c5257aa` | `forestry-machinery`        |

## Ejemplo genérico

```bash theme={null}
curl -X POST "https://www.manglai.io/api/v1/consumptions" \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "entityId": "invoice-123",
    "categoryId": "668f3fcb-7fb0-4b65-b77d-9303c551632f",
    "startDate": "2024-01-01T00:00:00.000Z",
    "endDate": "2024-01-31T23:59:59.999Z",
    "companyId": "1b1e07a7-083d-4831-a1d2-84b6e93a1572",
    "buildingId": "7fef7760-f9e7-4de9-ae35-8c37db65e4a3",
    "quantity": 1500.5,
    "unitType": "kWh"
  }'
```

## Endpoints auxiliares

| Necesitas              | Endpoint                                                   |
| ---------------------- | ---------------------------------------------------------- |
| Vehículos y maquinaria | `GET /api/v1/vehicles`                                     |
| Combustibles           | `GET /api/v1/inputs/recommended?types=fuel&countryCode=ES` |
| Categorías GHG         | `GET /api/v1/categories?level=subcategory`                 |
| Unidades válidas       | `GET /api/v1/units`                                        |