Sending an invoice

To send an invoice you can choose to build a JSON payload as described here. In this case you must send the HTTP header Content-Type: application/json.

Alternatively you can send the invoice in the original FatturaPA format and send the HTTP header Content-Type: application/xml.

In both cases the endpoint is POST /invoices.

If everything is fine you will receive the invoice UUID as the response with a HTTP 202 status code.

Copy
Copied
{
    "uuid": <Invoice UUID>
}

The process of sending invoices is asynchronous. When you send the invoice to the A-Cube API, you will receive the invoice UUID immediately, without having to wait for the SDI response. The platform takes care of the communication with SDI on your behalf by queuing the invoice.

During the communication, the "marking" property of the invoice will be set to "waiting". Your invoice will typically be processed within approximately 60 seconds.

If something wrong happens during communication with SDI, A-Cube will try again the sending 14 times for about 4 days (with an interval of 300s and backoff rate 1.6). The marking property of the invoice will be set at quarantena during the retry period.

When the retry will be successful the marking property will be set at sent. If after the retries the invoice is still not sent, the marking property will be set to invoice-error.

If the platform can not manage the error you will get a response with a body describing the error in JSON and a status code:

  • HTTP 400 if validation will fail.
  • HTTP 500 in case of a general error server side.

In any of the 5xx cases the marking property of the invoice will be set at quarantena and the notice field will describe the problem happened.

Notifications for changes in invoices marking

You can configure your own webhooks that A-CUBE API will call when the invoice marking changes. More information about the webhooks management here.

You will receive a message with the following body:

Copy
Copied
{
  "uuid": <Invoice UUID>,
  "marking": <New marking>,
  "previous_marking": <Previous marking>,
  "notice": <Error description>,
  "transioned_at": <Date of the transition>
}

Currently, the available events to subscribe are:

  • invoice-status-quarantena when the invoice marking changes from waiting to quarantena . This happens when the first attempt to send the invoice to the SDI fails.
  • invoice-status-invoice-error when the invoice marking changes from quarantena to invoice-error . This happens when the last attempt to send the invoice to the SDI fails.

Signature

All invoices to Government (PA) are signed by default, while when the recipient is a company you choose:

  • if you have enabled the invoice signature in your contract
  • by default all the invoices to private companies are signed
  • you can choose to sign invoice by invoice, by sending the HTTP header X-SignInvoice: true
  • if you don't have invoice signature enabled in your contract, invoices will never be signed

Invoice signature is put in the XAdES-BES form.