Invoice

  1. Home
  2. API Library
  3. Invoice
Send Electronic Receipts easily, quickly, and with high security standards to the Italian Revenue Agency.

Automate the submission of commercial documents via API in real time.

All the knowledge you need

Here you can find some advice to consider to approach this API. If you prefer, we provide code samples, OAS3 documentation, the ability to try the API live via the Swagger UI or import the entire collection into Postman. We also offer a Sandbox environment where you can experiment with all kinds of requests completely free of charge.

Useful tips to start with Invoice

Get the token in the appropriate section before you start.

Use the the online tool or generate it via API. Set the expire date, a usefull name and now add a bunch of scopes to limit the possible actions your token can do.
Read more on oauth API Manage my tokens

Company Configuration

Create a new configuration
POST /IT-configurations
This endpoint allows you to create a new company configuration. You can also specify credentials and callback URLs to receive receipt notifications.

Retrieve configurations
GET /IT-configurations
This endpoint returns the list of registered configurations, including credentials and callback URLs.

Update an existing configuration
PATCH /IT-configurations/{fiscal_id}
This endpoint allows you to update credentials, add options, and modify callback URLs for an existing configuration.

Delete a configuration
DELETE /IT-configurations/{fiscal_id}
This endpoint allows you to delete a configuration. Note: If receipts have already been sent with this configuration, deletion will not be possible.

Receipt Management

Use the following endpoints to manage electronic receipts:

Create a new receipt
POST /IT-receipts
This endpoint allows you to send a new electronic receipt. The system will generate a unique id and send a notification to the configured callback URL.

Register a return
PATCH /IT-receipts/{id}
If a customer returns a product, this endpoint allows you to update the existing receipt and generate a new one to record the return.

Cancel a receipt
DELETE /IT-receipts/{id}
This endpoint allows you to cancel a previously sent receipt, generating a cancellation receipt. A cancellation notification will be sent to the configured callback URL.

Retrieve receipts
GET /IT-receipts
This endpoint returns the list of registered receipts, with filtering options based on date, amount, or other parameters.
API docs by Redocly

Invoice (1.0.0)

URL: https://openapi.it/en/support License: Apache 2.0 Terms of Service

API for managing invoice configurations and digital receipts in compliance with tax regulations. This service enables businesses to configure their invoicing settings and manage receipts, ensuring compliance with the Italian Revenue Agency (Agenzia delle Entrate) standards for electronic invoicing (Fatturazione Elettronica) and digital receipt transmission (Scontrino Elettronico). It supports secure data exchange, real-time receipt submission, and configuration updates for tax reporting requirements.

IMPORTANT: Please note that you can not send Receipts between 23:55 and 00:00 (Italian Time Zone) to the Italian Revenue Agency (Agenzia delle Entrate). For this reason, all receipts sent in this time period will be sent at the first available time, i.e. in the first minutes of the new day.

NB: It is necessary to enable the tax code entered in the configuration under receipts_authentication-taxCode for sending receipts. Follow the procedure described at this link.

First time here? Generate a new access token

IT-configuration

Manage company configurations.

Retrieve all IT-configurations.

Retrieve all IT-configurations associated with the user. This endpoint returns a list of configurations, including fiscal details, API notification settings. It allows businesses to manage their integration with the tax authority and monitor receipt-related events.

Authorizations:
bearerAuth

Responses

Response Schema: application/json
Array of objects (ITConfigurationResponse)

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://invoice.openapi.com/IT-configurations");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "success": true,
  • "message": "",
  • "error": null
}

Create a new IT-configuration.

The IT-configuration is a tool used to set and manage company data for your own business. It functions as an entity representing a company managed by your account. Through this configuration, various settings can be customized

IMPORTANT: To receive notification, it is necessary to insert the api_configurations and set the event as indicated in the schemas. It will always be possible to update the data with the PATCH IT-configuration

For sending receipts, it is necessary to enable the receipts option to true.

By default, all will be set to false.

It will be possible to configure up to 10 companies per day for free, subsequently the indicated price will be applied

Authorizations:
bearerAuth
Request Body schema: application/json
fiscal_id
required
string

The unique fiscal identifier (VAT number or tax code) of the company registered with the Agenzia delle Entrate.

name
required
string

The company or entity name associated with the fiscal ID.

email
required
string <email>

The email address used for communication and notifications. Cannot be changed after the configuration is created.

receipts
boolean

Indicates whether the system should handle digital receipts.

object

Authentication credentials required for digital receipt submission.

Array of objects non-empty

Configuration of event-based callbacks for receiving notifications.

Responses

Response Schema: application/json
object
success
boolean
message
string
error
string or null

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true,
  • "message": "",
  • "error": null
}

Retrieve a single IT-configuration by fiscal_id.

This endpoint returns details of an individual configuration, including tax details and API notification settings. It allows companies to manage their integration with the Revenue Agency and monitor events related to receipts

Authorizations:
bearerAuth
path Parameters
fiscal_id
required
string

Responses

Response Schema: application/json
object
success
boolean
message
string
error
string or null

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://invoice.openapi.com/IT-configurations/%7Bfiscal_id%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true,
  • "message": "",
  • "error": null
}

Update an existing IT-configuration.

This service allows you to modify or update authentication data in case they have expired. You can also update the API configurations. If you no longer wish to receive notifications for a specific event, simply set the callback to null.

NB: The credentials in the receipts_authentication have to be update every 90 days(for the Agenzia delle entrate).

Authorizations:
bearerAuth
path Parameters
fiscal_id
required
string
Request Body schema: application/json
receipts
boolean

Indicates whether the system should handle digital receipts.

object

Authentication credentials required for digital receipt submission.

Array of objects non-empty

Configuration of event-based callbacks for receiving notifications.

Responses

Response Schema: application/json
object
success
boolean
message
string
error
string or null

Request samples

Content type
application/json
{
  • "receipts": true,
  • "receipts_authentication": {
    },
  • "api_configurations": []
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true,
  • "message": "",
  • "error": null
}

Delete a IT-configuration by fiscal_id.

This service allows you to delete the configuration.

Note: The configuration can only be deleted if no receipts have been sent. Receipts can be sent via the POST /IT-receipts endpoint. Once receipts have been sent, the configuration cannot be deleted.

Authorizations:
bearerAuth
path Parameters
fiscal_id
required
string

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_easy_setopt(hnd, CURLOPT_URL, "https://invoice.openapi.com/IT-configurations/%7Bfiscal_id%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": "null",
  • "success": true,
  • "message": "Deleted configuration for id: YourCompanyFiscal_id",
  • "error": null
}

IT-receipt

Handle receipt processing.

Retrieve all IT-receipts.

This endpoint retrieves a list of IT receipts, allowing filtering based on various parameters. Users can filter results by fiscal_id, document_number, status, type, created_at, document_date, and parent_receipt_id.

Pagination options include skip to specify the number of records to omit and limit to define the maximum number of records returned (capped at 100).

fiscal_id, status, and type support multiple values by separating them with a comma (e.g., fiscal_id_1,fiscal_id_2).

status valid values: new, retry, submitted, ready, failed, voided.

type valid values: sale, return, void.

created_at and document_date must follow the YYYY-MM-DD format.

This endpoint returns a structured JSON response containing the matching receipts.

Authorizations:
bearerAuth
query Parameters
fiscal_id
string

Filter receipts by fiscal ID.

document_number
string

Filter receipts by document number.

status
Array of strings
Items Enum: "new" "retry" "submitted" "ready" "failed" "voided"

Filter receipts by status. Multiple values can be provided, separated by commas.

type
Array of strings
Items Enum: "sale" "return" "void"

Filter receipts by type. Multiple values can be provided, separated by commas.

created_at
string <date>

Filter receipts by creation date (YYYY-MM-DD format).

document_date
string <date>

Filter receipts by document date (YYYY-MM-DD format).

parent_receipt_id
string

Filter receipts by parent receipt ID.

skip
integer >= 0

Number of records to skip for pagination.

limit
integer [ 1 .. 100 ]

Number of records to return (max 100).

Responses

Response Schema: application/json
Array of objects (ResponseReturnReceipt)

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://invoice.openapi.com/IT-receipts?fiscal_id=SOME_STRING_VALUE&document_number=SOME_STRING_VALUE&status=SOME_ARRAY_VALUE&type=SOME_ARRAY_VALUE&created_at=SOME_STRING_VALUE&document_date=SOME_STRING_VALUE&parent_receipt_id=SOME_STRING_VALUE&skip=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "success": true,
  • "message": "",
  • "error": null
}

Create a new receipt.

This service allows you to create a Smart Electronic Receipt for an online sale. The Smart Receipt replaces the issuance of a receipt through a telematic cash register and is ideal for online transactions.

Unlike an e-invoice B2C, the Smart Electronic Receipt does not require the customer's fiscal ID (codice fiscale). It interacts directly with the Government Tax Portal (cassetto fiscale) to generate and store the receipt, acting as a proxy for the user.

Important: Before using this service, you must set up an IT-configuration, which represents the "Partita IVA" sending the receipts. Ensure that the receipts: true field is included in the IT-configuration request body.

Sandbox Environment: The sandbox simulates communication with the Tax Authority Portal. In this environment, Smart Receipt identifiers will be simulated. Real credentials for the sender's IT-configuration are not needed in the sandbox environment, but they are required for the production environment.

NB: It is important to set the following events for the callbacks:

  • receipt: This event is triggered when a new receipt is submitted and ready
  • receipt-credentials: This event is triggered when there are update about credentials
  • receipt-retry:This event is triggered when the communication with the Tax Authority portal failed, and we will retry to send the receipt again
  • receipt-error This event is triggered when the Tax Authority portal reports an error
  • appointee This event is triggered when the process of giving an appointing for smart receipts succeeded

This is because the receipt details will be updated based on the event type.

Before sending a document to the Tax Authority Portal, OpenaApi will perform some checks on the data you sent. If something is wrong with the data you sent

Authorizations:
bearerAuth
Request Body schema: application/json
fiscal_id
required
string

The VAT number of the company issuing the receipt, without the country prefix.

required
Array of objects

List of items in the receipt.

invoice_issuing
boolean

Flag indicating whether an invoice will be issued.

services_uncollected_amount
number

Uncollected amount in EUR for services.

goods_uncollected_amount
number

Uncollected amount in EUR for delivered goods.

electronic_payment_amount
number

Amount paid electronically in EUR.

ticket_restaurant_payment_amount
number

Amount paid using ticket restaurant in EUR.

ticket_restaurant_quantity
integer

Number of ticket restaurant vouchers used.

discount
number

Discount applied at payment time but does not alter taxable amount.

lottery_code
string

Lottery code for the customer to participate in the 'Lotteria degli scontrini' lottery. the 'lottery_code' must consist of 8 alphanumeric characters. The lottery code cannot be used if the total amount is lower than EUR 1.00 or if the payment was not fully electronic"

linked_receipt
string

Reference to a linked receipt, if applicable.

cash_payment_amount
required
number

Amount paid in cash in EUR.

tags
Array of objects

You can insert details for you receipt.

Responses

Response Schema: application/json
object
success
boolean

Indicates if the operation was successful.

message
string

Additional message related to the operation.

error
string or null

Error message if applicable.

Callbacks

Request samples

Content type
application/json
{
  • "fiscal_id": "YourCompanyFiscal_id",
  • "items": [
    ],
  • "invoice_issuing": false,
  • "services_uncollected_amount": 0,
  • "goods_uncollected_amount": 0,
  • "electronic_payment_amount": 0,
  • "ticket_restaurant_payment_amount": 0,
  • "ticket_restaurant_quantity": 0,
  • "discount": 0,
  • "lottery_code": "1a3v5g7f",
  • "linked_receipt": "string",
  • "cash_payment_amount": 4.5,
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true,
  • "message": "",
  • "error": null
}

Callback payload samples

Callback
POST: {your_url}
Content type
application/json

In the callback, the various types and statuses of the receipt will be returned. This is the response where the receipt has been successfully issued and is ready.

{
  • "data": {
    }
}

Retrieve a single receipt by ID.

Retrieves the details of a single receipt using its unique identifier. The receipt ID must be provided in the request path.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 679cd95***************23

Responses

Response Schema: application/json
object

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://invoice.openapi.com/IT-receipts/%7Bid%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": {
    }
}

Return one or more items from a receipt.

This endpoint allows returning one or more items from a specific receipt. The receipt ID is provided in the path, while the items to be returned are specified in the request body with their respective IDs and quantities.

NB: The response of this endpoint is a new receipt that is linked to the previous one. A new key, parent_receipt_id, is set, which will be populated with the ID of the receipt from which the returns are made.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 679c***6d00d0***b23

Unique identifier of the receipt to be updated.

Request Body schema: application/json
Array of objects

List of items to be returned.

Responses

Response Schema: application/json
object

Callbacks

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Callback payload samples

Callback
POST: postReceiptCallback
Content type
application/json
Example

In the callback, the various types and statuses of the receipt will be returned. This is the response where the receipt has been successfully issued and is ready.

{
  • "data": {
    },
  • "custom": null
}

Delete a receipt by ID.

This endpoint allows voiding a receipt within 24 hours from its submission. The system will generate a new void receipt linked to the original one through the parent_receipt_id parameter.

The void receipt will reflect the cancellation of the original transaction while maintaining traceability.

Upon success, the response will include the newly created void receipt details.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: 6a9**************d077b23

Responses

Response Schema: application/json
object
message
string

Confirmation message for the voided receipt.

success
boolean

Indicates whether the void operation was successful.

error
string or null

Error message in case of failure, null if successful.

Callbacks

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_easy_setopt(hnd, CURLOPT_URL, "https://invoice.openapi.com/IT-receipts/%7Bid%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "voided receipt: 6a9**************d077b23",
  • "success": true,
  • "error": "nulll"
}

Callback payload samples

Callback
POST: postReceiptCallback
Content type
application/json
Example

In the callback, the various types and statuses of the receipt will be returned. This is the response where the receipt has been successfully voided.

{
  • "data": {
    },
  • "custom": null
}
Web Service Revision: 2.0.0