Saltar al contenido principal

​
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étodoRutaDescripción
GET/api/v1/invoicesListar facturas
GET/api/v1/invoices/{id}Obtener factura
POST/api/v1/invoicesCrear o actualizar factura
POST/api/v1/invoices/upload-invoiceSubir y escanear factura
DELETE/api/v1/invoices/{id}Eliminar factura
GET/api/v1/invoices/dashboardDashboard 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

NecesitasEndpoint
EmpresasGET /api/v1/companies
EdificiosGET /api/v1/companies/{companyId}/buildings
ComercializadorasGET /api/v1/inputs/recommended?companyId=...&types=provider&countryCode=ES
CombustiblesGET /api/v1/inputs/recommended?types=fuel&countryCode=ES
Gases refrigerantesGET /api/v1/inputs/recommended?types=gasLeak
Unidades válidasGET /api/v1/units
Categorías GHGGET /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.