> ## 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.

# Invoices (Facturas)

> Crea facturas de electricidad, gas natural y gases refrigerantes

## Descripción

Las **facturas** representan suministros asociados a un edificio. Al crear una factura, Manglai genera el consumo asociado y calcula las emisiones automáticamente.

<Info>
  Electricidad, gas natural y gases refrigerantes se crean con `POST /api/v1/invoices`.
</Info>

## Endpoints

| Método | Ruta                              | Descripción                |
| ------ | --------------------------------- | -------------------------- |
| GET    | `/api/v1/invoices`                | Listar facturas            |
| GET    | `/api/v1/invoices/{id}`           | Obtener factura            |
| POST   | `/api/v1/invoices`                | Crear o actualizar factura |
| POST   | `/api/v1/invoices/upload-invoice` | Subir y escanear factura   |
| DELETE | `/api/v1/invoices/{id}`           | Eliminar factura           |
| GET    | `/api/v1/invoices/dashboard`      | Dashboard de facturas      |

## Campos comunes

Todas las facturas manuales usan `POST /api/v1/invoices` con `Authorization: Bearer TU_TOKEN`.

Campos raíz recomendados:

* `id`, `type`, `companyId`, `buildingId`
* `totalCost`, `currency`, `startDate`, `endDate`
* `countryCode`, `externalId`, `cup`, `supplier`
* `lines`: envía una línea; Manglai genera internamente la línea de actividades relacionadas cuando aplica.

Usa `externalId` para mantener idempotencia con tu sistema. Si `countryCode` no se envía, Manglai usa el país del edificio.

## Qué tipo usar

<CardGroup cols={2}>
  <Card title="Electricidad" icon="zap">
    Usa `type: "electricity"` y cantidad en `lines[0].quantity`. La unidad habitual es `kWh`.
  </Card>

  <Card title="Gas natural" icon="flame">
    Usa `type: "heat"`. El combustible fijo, por ejemplo `natural-gas`, va en `lines[0].fuel`.
  </Card>

  <Card title="Gas refrigerante" icon="snowflake">
    Usa `type: "fuel"`. El nombre es contraintuitivo: aquí representa fugas de gases refrigerantes.
  </Card>
</CardGroup>

## Ejemplos por caso

### A) Electricidad

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "electricity",
  "companyId": "1b1e07a7-083d-4831-a1d2-84b6e93a1572",
  "buildingId": "7fef7760-f9e7-4de9-ae35-8c37db65e4a3",
  "countryCode": "ES",
  "supplier": "iberdrola-clientes-sau",
  "cup": "ES0021000000000000XX",
  "totalCost": 1234.56,
  "currency": "EUR",
  "startDate": "2025-01-01T00:00:00.000Z",
  "endDate": "2025-01-31T23:59:59.999Z",
  "externalId": "FAC-ELEC-001",
  "lines": [
    {
      "quantity": 1500.5,
      "unit": "kWh",
      "gdo": "renewable",
      "renewablePercentage": 100
    }
  ]
}
```

El `supplier` es el código de la comercializadora. Puedes obtener códigos con `GET /api/v1/inputs/recommended?companyId=...&types=provider&countryCode=ES`.

### B) Gas natural

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "type": "heat",
  "companyId": "1b1e07a7-083d-4831-a1d2-84b6e93a1572",
  "buildingId": "7fef7760-f9e7-4de9-ae35-8c37db65e4a3",
  "countryCode": "ES",
  "totalCost": 800,
  "currency": "EUR",
  "startDate": "2025-01-01T00:00:00.000Z",
  "endDate": "2025-01-31T23:59:59.999Z",
  "externalId": "FAC-GAS-001",
  "lines": [
    {
      "fuel": "natural-gas",
      "quantity": 5000,
      "unit": "kWh"
    }
  ]
}
```

Para gas natural, usa `type: "heat"` y `lines[0].fuel: "natural-gas"`. Consulta combustibles con `GET /api/v1/inputs/recommended?types=fuel&countryCode=ES`.

### C) Gas refrigerante

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "type": "fuel",
  "companyId": "1b1e07a7-083d-4831-a1d2-84b6e93a1572",
  "buildingId": "7fef7760-f9e7-4de9-ae35-8c37db65e4a3",
  "countryCode": "ES",
  "totalCost": 0,
  "currency": "EUR",
  "startDate": "2025-01-01T00:00:00.000Z",
  "endDate": "2025-12-31T23:59:59.999Z",
  "externalId": "FAC-REFRIG-001",
  "lines": [
    {
      "fuel": "r-410a",
      "quantity": 2.5,
      "unit": "kg"
    }
  ]
}
```

Para refrigerantes, `lines[0].fuel` es el código del gas, por ejemplo `r-410a`, `hfc-134a` o `r-404a`. Consulta gases con `GET /api/v1/inputs/recommended?types=gasLeak`.

## Endpoints auxiliares

| Necesitas           | Endpoint                                                                     |
| ------------------- | ---------------------------------------------------------------------------- |
| Empresas            | `GET /api/v1/companies`                                                      |
| Edificios           | `GET /api/v1/companies/{companyId}/buildings`                                |
| Comercializadoras   | `GET /api/v1/inputs/recommended?companyId=...&types=provider&countryCode=ES` |
| Combustibles        | `GET /api/v1/inputs/recommended?types=fuel&countryCode=ES`                   |
| Gases refrigerantes | `GET /api/v1/inputs/recommended?types=gasLeak`                               |
| Unidades válidas    | `GET /api/v1/units`                                                          |
| Categorías GHG      | `GET /api/v1/categories?level=subcategory`                                   |

## Subida con escaneo

`POST /api/v1/invoices/upload-invoice` permite enviar un archivo en `multipart/form-data` para que la IA extraiga los datos. Requiere `companyId` y el archivo de la factura.