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

# Insert or update an invoice

> Creates a new invoice record or updates an existing one based on its unique identifier (`id`). This endpoint supports multiple invoice types (e.g. heat, fuel, electricity, wastes, etc.). - If the `id` exists, the record is updated. - If the `id` does not exist, a new record is inserted.
⚠️ **Special rules:** - `emissionFactor` in `lines` is **optional**. - `companySplitOriginalValues` is **optional**. - `wasteType` and `wasteDisposalMethod` are **required only when `type = waste`**.




## OpenAPI

````yaml /openapi.json post /api/v1/invoices
openapi: 3.0.3
info:
  title: Manglai Public API
  description: Manglai API for Carbon Footprint Management
  contact:
    email: admin@manglai.io
    name: Manglai Support
    url: https://manglai.io
  termsOfService: https://manglai.io/privacy
  version: '1.0'
servers:
  - url: https://www.manglai.io
    description: Production
security:
  - apiTokenAuth: []
tags: []
paths:
  /api/v1/invoices:
    post:
      tags:
        - invoices
      summary: Insert or update an invoice
      description: >
        Creates a new invoice record or updates an existing one based on its
        unique identifier (`id`). This endpoint supports multiple invoice types
        (e.g. heat, fuel, electricity, wastes, etc.). - If the `id` exists, the
        record is updated. - If the `id` does not exist, a new record is
        inserted.

        ⚠️ **Special rules:** - `emissionFactor` in `lines` is **optional**. -
        `companySplitOriginalValues` is **optional**. - `wasteType` and
        `wasteDisposalMethod` are **required only when `type = waste`**.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
                - type
                - companyId
                - totalCost
                - currency
                - startDate
                - endDate
              properties:
                id:
                  type: string
                  description: Unique identifier of the invoice.
                type:
                  type: string
                  description: Type of the invoice.
                  enum:
                    - heat
                    - fuel
                    - electricity
                    - generated-energy
                    - process-emissions
                    - water
                    - wastes
                    - wastes-expenses
                    - others
                    - waste-water
                companyId:
                  type: string
                  description: Company associated with the invoice.
                buildingId:
                  type: string
                  description: Building associated with the invoice.
                cup:
                  type: string
                  description: Unique identifier for the invoice (e.g., CUP code).
                totalCost:
                  type: number
                  description: Total cost of the invoice.
                currency:
                  type: string
                  description: Currency of the invoice (e.g., USD, EUR).
                startDate:
                  type: string
                  format: date
                  description: Start date of the invoice period.
                endDate:
                  type: string
                  format: date
                  description: End date of the invoice period.
                supplier:
                  type: string
                  description: Supplier name.
                rawProvider:
                  type: string
                  description: Raw provider for the invoice.
                wasteType:
                  type: string
                  description: Waste type (⚠️ required only if `type = waste`).
                wasteDisposalMethod:
                  type: string
                  description: Waste disposal method (⚠️ required only if `type = waste`).
                status:
                  type: string
                  description: Invoice status.
                  enum:
                    - valid
                    - draft
                lines:
                  type: array
                  description: Line items associated with the invoice.
                  items:
                    type: object
                    required:
                      - quantity
                      - unit
                    properties:
                      fuel:
                        type: string
                      type:
                        type: string
                      quantity:
                        type: number
                        description: Quantity of the item.
                      unit:
                        type: string
                        description: Measurement unit (e.g., kWh, liters).
                      emissions:
                        type: number
                        description: >-
                          Emissions associated with the line item (in kg of
                          CO2e).
                      emissionFactor:
                        type: number
                        description: Emission factor (optional).
                      gdo:
                        type: string
                      prevGdo:
                        type: string
                      regoId:
                        type: string
                      renewablePercentage:
                        type: number
                      emissionEntityId:
                        type: string
                attachedFilePath:
                  type: string
                  description: Path to the attached file.
                removedAt:
                  type: string
                  format: date
                  description: Date when the invoice was removed.
                countryCode:
                  type: string
                  description: ISO country code of the company (e.g., ES, FR).
                externalId:
                  type: string
                  description: External identifier for the invoice.
                splitPercentage:
                  type: number
                  description: Percentage for splitting the invoice.
                splitYear:
                  type: number
                  description: Year associated with the split.
                splitId:
                  type: string
                  description: Identifier of the split.
                wasValidated:
                  type: boolean
                  description: Indicates if the invoice was validated.
                validation:
                  type: object
                  description: Validation data for the invoice.
                relationalId:
                  type: string
                  description: Relational ID for the invoice.
                companySplitOriginalValues:
                  type: object
                  description: >
                    Snapshot of values before splitting. ⚠️ Optional: only
                    provided if the invoice was split.
                  properties:
                    quantity:
                      type: number
                    totalCost:
                      type: number
                    configurationSnapshot:
                      type: object
        description: Invoice data to be inserted or updated.
      responses:
        '200':
          description: Invoice successfully inserted or updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  invoice:
                    type: object
                    description: The invoice object
        '400':
          description: Bad request — missing required fields or invalid data.
        '500':
          description: Internal server error during upsert operation.
components:
  securitySchemes:
    apiTokenAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````