Saltar al contenido principal
POST
/
api
/
v1
/
consumptions
Create or update a consumption record
curl --request POST \
  --url https://www.manglai.io/api/v1/consumptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entityId": "invoice-123-abc",
  "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",
  "provider": "endesa",
  "amount": 250.75,
  "totalCost": 312.5,
  "currency": "EUR",
  "emissionEntityId": "218b2369-b86d-4517-a9f0-392d5f9e80e3",
  "countryCode": "ES",
  "fuelType": "diesel",
  "vehicleType": "vehicle",
  "emission": {},
  "extraData": {
    "fuelType": "<string>",
    "fuelTypeId": "<string>",
    "fuelTypeCode": "<string>",
    "vehicleType": "<string>",
    "vehicleCategory": "<string>",
    "unit": "<string>",
    "emission": {},
    "gdo": "<string>",
    "renewablePercentage": 123,
    "wasteType": "<string>",
    "wasteDisposalMethod": "<string>"
  },
  "attachedFilePath": "gs://bucket/company/invoice.pdf",
  "efficiency": {
    "distance": 123,
    "distanceUnit": "<string>",
    "energy": 123,
    "energyUnit": "<string>"
  },
  "externalId": "EXT-2024-001",
  "relationalId": "batch-123",
  "updateByExternalId": false,
  "emissionsCategoryIds": [
    "493782d7-7c17-4ed6-b75c-4fae0e254ff2",
    "47cb52b3-02e6-446e-bd70-e46316aa876b"
  ],
  "isRecalculated": false,
  "validation": {},
  "removedAt": null
}
'
{
  "status": "ok",
  "isUpdated": false,
  "isCreated": true
}

Autorizaciones

​
Authorization
string
header
requerido

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Cuerpo

application/json

Consumption data to be inserted or updated

​
id
string
requerido

Unique identifier (UUID) for the consumption record

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

​
entityId
string
requerido

Foreign key reference to the source entity (UUID): - For invoices: invoice ID from GET /api/v1/invoices - For vehicles: vehicle ID from GET /api/v1/vehicles?companyId={companyId}. The vehicle must exist and be available during the consumption period. - For surveys: survey answer ID

Ejemplo:

"invoice-123-abc"

​
categoryId
string
requerido

GHG Protocol category ID (UUID). Call GET /api/v1/categories?level=subcategory to obtain the list and send the selected id. - Vehicle categories: LAND_TRANSPORTATION, AIR_TRANSPORTATION, MARITIME_TRANSPORTATION, RAIL_TRANSPORTATION, FORESTRY_MACHINERY, FARM_MACHINERY, INDUSTRIAL_MACHINERY

Ejemplo:

"668f3fcb-7fb0-4b65-b77d-9303c551632f"

​
startDate
string<date-time>
requerido

Start date of the consumption period (ISO 8601)

Ejemplo:

"2024-01-01T00:00:00.000Z"

​
endDate
string<date-time>
requerido

End date of the consumption period (ISO 8601)

Ejemplo:

"2024-01-31T23:59:59.999Z"

​
companyId
string
requerido

Company identifier (UUID). Retrieve it via GET /api/v1/companies and use the returned id.

Ejemplo:

"1b1e07a7-083d-4831-a1d2-84b6e93a1572"

​
buildingId
string
requerido

Building identifier (UUID). Call GET /api/v1/companies/{companyId}/buildings?companyId={companyId} and use the building id. For vehicle consumptions: If the vehicle has a buildingId assigned, you can use that value. Otherwise, use a building from the company.

Ejemplo:

"7fef7760-f9e7-4de9-ae35-8c37db65e4a3"

​
quantity
number
requerido

Quantity consumed (e.g., kWh, liters, km)

Ejemplo:

1500.5

​
unitType
string
requerido

Unit of measurement for the quantity. Common values: kWh, MWh, m3, l, km, kg, mt

Ejemplo:

"kWh"

​
provider
string

Provider/supplier code. For electricity consumptions call GET /api/v1/inputs/recommended?companyId={companyId}&types=provider&countryCode={countryCode} and send the code. Required for vehicle consumptions: If vehicle motorType is electric or hybrid, this field is mandatory.

Ejemplo:

"endesa"

​
amount
number

Cost amount (excluding taxes if applicable)

Ejemplo:

250.75

​
totalCost
number

Total cost including all charges

Ejemplo:

312.5

​
currency
string

Currency code (ISO 4217)

Ejemplo:

"EUR"

​
emissionEntityId
string

Custom emission factor ID (UUID). Obtain it via GET /api/v1/emission-factors/custom?companyId={companyId}&entityName={entityName}&countryCode={countryCode}.

Ejemplo:

"218b2369-b86d-4517-a9f0-392d5f9e80e3"

​
countryCode
string

ISO country code (e.g., ES, FR, US)

Ejemplo:

"ES"

​
fuelType
string

Fuel code. For combustion consumptions call GET /api/v1/inputs/recommended?companyId={companyId}&types=fuel&countryCode={countryCode}. For gas leaks use types=gasLeak. Send the code. Required for vehicle consumptions: If vehicle motorType is combustion or hybrid, this field must be provided in extraData.fuelTypeId or extraData.fuelTypeCode.

Ejemplo:

"diesel"

​
vehicleType
string

Vehicle type code. For vehicle consumptions: This should be included in extraData.vehicleCategory with the vehicle category code. Vehicle types: vehicle, machine, transport

Ejemplo:

"vehicle"

​
emission
object

Pre-calculated emission data (optional, usually system-calculated)

​
extraData
object

Additional metadata specific to the consumption type. May include: concept, gdo, renewablePercentage, wasteType, etc.

​
attachedFilePath
string

Path to attached file (e.g., invoice PDF)

Ejemplo:

"gs://bucket/company/invoice.pdf"

​
efficiency
object

Efficiency data (optional). For vehicle consumptions: Can include distance and energy consumption data. Structure: { distance: number, distanceUnit: string, energy: number, energyUnit: string }

​
externalId
string

External system identifier for integration purposes

Ejemplo:

"EXT-2024-001"

​
relationalId
string

Identifier to relate multiple consumptions

Ejemplo:

"batch-123"

​
updateByExternalId
boolean

If true, updates existing consumption by externalId instead of id. Useful for integrations that don't know internal IDs.

Ejemplo:

false

​
emissionsCategoryIds
string[]

Array of category IDs (UUID) for multi-category emissions. Retrieve IDs via GET /api/v1/categories?level=subcategory. For general consumptions (optional): Used when a consumption should generate emissions in multiple categories (e.g., electricity + energy-related-activities). For vehicle consumptions (required): Must always include two categories: - Primary category (same as categoryId) - Related activity category:

  • Electric/Hybrid vehicles: ENERGY_RELATED_ACTIVITIES (47cb52b3-02e6-446e-bd70-e46316aa876b)
  • Combustion vehicles: FUEL_RELATED_ACTIVITIES (dd16800c-c79f-4717-9de6-07e15f4ceb64)
Ejemplo:
[
  "493782d7-7c17-4ed6-b75c-4fae0e254ff2",
  "47cb52b3-02e6-446e-bd70-e46316aa876b"
]
​
isRecalculated
boolean

If true, bypasses duplicate validation (used for recalculation flows)

Ejemplo:

false

​
validation
object

Validation metadata (timestamps, validator info)

​
removedAt
string<date-time>

Soft delete timestamp (null if active)

Ejemplo:

null

Respuesta

Consumption successfully created/updated and emissions calculated

​
status
string
Ejemplo:

"ok"

​
isUpdated
boolean

True if an existing record was updated

Ejemplo:

false

​
isCreated
boolean

True if a new record was created

Ejemplo:

true