Skip to main content

Invoices

This guide explains how to create and upload an invoice associated with an existing contract. It assumes that both the user and the contract (contractId) have already been created.

How it works​

To create an invoice, you need to send a POST request to the corresponding endpoint using the contractId. The API response will return a fileUrl. This is a signed URL to upload the invoice file.

warning

The upload link is temporary (15 minutes), so make sure to upload the PDF file immediately after receiving it. If the PDF is not uploaded, the invoice will not be processed and will not be available to the customer.

Type of invoices​

The system supports several types of invoices. Each invoice type (ELECTRICITY,GAS or OTHER) has specific fields that are optional, but it is highly recommended to include them to enable the invoice breakdown in the invoice module for electricity and consumptions for gas.

Common fields for all invoices​

These fields are required for all types of invoices:

  • issueDate: the date the invoice was issued.
  • invoicePeriodFrom: start date of the billing period.
  • invoicePeriodTo: end date of the billing period.
  • type: invoice type, e.g., ELECTRICITY, GAS, or OTHER.
  • cost: total cost of the invoice.
  • externalId: invoice external number

Electricity invoices​

tip

For electricity invoices, this additional information enables the invoice breakdown feature, helping reduce support tickets related to billing questions.

  • powerCost: cost of the contracted power.
  • totalEnergyConsumption: total energy consumption.
  • energyCost: cost of the energy consumed.
  • totalEnergySurplus: total energy surplus.
  • surplusSaving: savings from surplus energy.
  • otherCost: any other applicable costs (e.g. taxes)
  • discountSaving: any applicable discount savings.
  • virtualWallet: amount credited/used to/from the virtual wallet.

And for pymes also:

  • reactiveEnergyCost: cost for reactive energy.
  • excessPowerCost: cost for exceeding contracted power.

Gas invoices​

tip

For gas, consumption is calculated based on the values provided in the invoice, so it is important to include them. If obtainMethod is set to ESTIMATED, the system will notify the customer when multiple estimated invoices are issued consecutively.

  • totalEnergyConsumption: total energy consumption.
  • obtainMethod: method used to calculate consumption. Can be REAL or ESTIMATED.

Endpoints needed​

createInvoice