Invoices (Facturas)

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.

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

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

Electricidad

Usa type: "electricity" y cantidad en lines[0].quantity. La unidad habitual es kWh.

Gas natural

Usa type: "heat". El combustible fijo, por ejemplo natural-gas, va en lines[0].fuel.

Gas refrigerante

Usa type: "fuel". El nombre es contraintuitivo: aquí representa fugas de gases refrigerantes.

Ejemplos por caso

A) Electricidad

{
  "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

{
  "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

{
  "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.

Introducción

API REST

Guías de integración

Ejemplos

MCP (Model Context Protocol)

MCP Tools

Integraciones MCP

Descripción

Endpoints

Campos comunes

Qué tipo usar

Electricidad

Gas natural

Gas refrigerante

Ejemplos por caso

A) Electricidad

B) Gas natural

C) Gas refrigerante

Endpoints auxiliares

Subida con escaneo

​Descripción

​Endpoints

​Campos comunes

​Qué tipo usar

Electricidad

Gas natural

Gas refrigerante

​Ejemplos por caso

​A) Electricidad

​B) Gas natural

​C) Gas refrigerante

​Endpoints auxiliares

​Subida con escaneo

Descripción

Endpoints

Campos comunes

Qué tipo usar

Ejemplos por caso

A) Electricidad

B) Gas natural

C) Gas refrigerante

Endpoints auxiliares

Subida con escaneo