Sending a Smart Receipt
The Smart Receipt API allows you to issue a Smart Electronic Receipt for a sale.
Create a Receipt
Send a new Smart Receipt with the POST /receipts API.
Example:
POST /receipts
Content-Type: application/json
{
"fiscal_id": "string",
"items": [
{
"quantity": 1,
"description": "test",
"unit_price": 10,
"vat_rate_code": "4"
}
],
"cash_payment_amount": 10
}See the complete API documentation.
Item Transaction ID
Every sent item will receive a transaction id from the Tax Authority.
You can read the transaction ids in the response of the GET /receipts/{id}/details API.
Void a Receipt
You can void a receipt with the DELETE /receipts/{id} API.
Return items on a receipt
To return items on a receipt, use the POST /receipts/{id}/return API.
In the request payload you must send the item ids and quantities you want to return. Example:
{
"items": [
{
"id": "transaction ID",
"quantity": 1
}
]
}The transaction ID is the unique identifier of the item you want to return.
You can find the transaction ID in the response of the GET /receipts/{id}/details API.
Validation errors
Before sending a document to the Tax Authority Portal, A-Cube will perform some checks on the data you sent.
If something is wrong with the data you sent, you'll get back a 400 Bad Request response:
{
"type": "https://tools.ietf.org/html/rfc2616#section-10",
"title": "An error occurred",
"detail": "ERROR MESSAGES",
"violations": [
{
"propertyPath": "PROPERTY PATH",
"message": "ERROR MESSAGE"
},
...
]
}Here is the list of error codes you can receive:
| HTTP ERROR | Detail | Notes |
|---|---|---|
| 422 | INVALID_CREDENTIALS | Credentials of the BusinessRegistryConfiguration are not valid |
| 400 | BAD_REQUEST | Provided data is not valid or a generic error happened |
| 403 | CANNOTSENDDATAFORTHISLEGALENTITY | The BusinessRegistryConfiguration VAT number is not valid |
| 500 | SERVICE_UNAVAILABLE | Agenzia delle Entrate cannot handle your request at the moment |
Validity checks performed on data
Data sent to these APIs have to pass these preliminary valididy checks
Checks on total amount of the receipt
Total paid and uncollected amounts should match the items total amount
For example this receipt is invalid:
{
"fiscal_id": "123456789",
"cash_payment_amount": 1.00,
"discount": 0.5,
"items": [
{
"quantity": 1.0,
"description": "Apples",
"unit_price": 1.00,
"vat_rate_code": "22"
}
]
}So you will get back an HTTP status code of 400 with the following response payload:
{
"type": "https://tools.ietf.org/html/rfc2616#section-10",
"title": "An error occurred",
"detail": "Total paid and uncollected amounts is not matching the items total amount.",
"violations": [
{
"propertyPath": "",
"message": "Total paid and uncollected amounts is not matching the items total amount."
}
]
}No paid or uncollected amounts should be specified when invoice issuing is set
For example this receipt is invalid:
{
"fiscal_id": "123456789",
"cash_payment_amount": 1.00,
"invoice_issuing": true,
"items": [
{
"quantity": 1.0,
"description": "Apples",
"unit_price": 1.00,
"vat_rate_code": "22"
}
]
}Here is the response:
{
"type": "https://tools.ietf.org/html/rfc2616#section-10",
"title": "An error occurred",
"detail": "invoice_issuing: No paid or uncollected amounts should be specified when invoice issuing is set.",
"violations": [
{
"propertyPath": "invoice_issuing",
"message": "No paid or uncollected amounts should be specified when invoice issuing is set."
}
]
}Checks on items amounts
Discount cannot be greater or equal to total amount
For example this receipt is invalid:
{
"fiscal_id": "123456789",
"cash_payment_amount": 1.00,
"items": [
{
"quantity": 1.0,
"description": "Apples",
"unit_price": 1.00,
"discount": 2.0,
"vat_rate_code": "22"
},
{
"quantity": 1.0,
"description": "Oranges",
"unit_price": 2.00,
"vat_rate_code": "22"
}
]
}The returned payload should be this one:
{
"type": "https://tools.ietf.org/html/rfc2616#section-10",
"title": "An error occurred",
"detail": "items[0].gross_discount: Discount cannot be greater or equal to total amount",
"violations": [
{
"propertyPath": "items[0].gross_discount",
"message": "Discount cannot be greater or equal to total amount"
}
]
}Checks on return items
The id of return items must match with the ids of the original receipts
The quantity of the returned items should not be greater than the quantity of the originl item
Checks on lottery code
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
For example this receipt is invalid:
{
"fiscal_id": "123456789",
"cash_payment_amount": 1.00,
"electronic_payment_amount": 1.00,
"lottery_code": "1234567X",
"items": [
{
"quantity": 1.0,
"description": "Oranges",
"unit_price": 2.00,
"vat_rate_code": "22"
}
]
}With the following response:
{
"type": "https://tools.ietf.org/html/rfc2616#section-10",
"title": "An error occurred",
"detail": "lottery_code: The lottery code cannot be used if the total amount is lower than EUR 1.00 or if the payment was not fully electronic. Please remove the lottery code.",
"violations": [
{
"propertyPath": "lottery_code",
"message": "The lottery code cannot be used if the total amount is lower than EUR 1.00 or if the payment was not fully electronic. Please remove the lottery code."
}
]
}Checks ticket restaurant
If ticketrestaurantpaymentAmount is filled, ticketrestaurantquantity must also be filled and vice versa
Checks on fiscal ID
Check if the provided fiscal id has been associated with the current API user
For example this receipt is invalid:
{
"fiscal_id": "not_existent",
"cash_payment_amount": 11.00,
"items": [
{
"quantity": 1.0,
"description": "Apples",
"unit_price": 11.00,
"vat_rate_code": "22"
}
]
}With the following response:
{
"type": "https://tools.ietf.org/html/rfc2616#section-10",
"title": "An error occurred",
"detail": "fiscal_id: Unknown fiscal id",
"violations": [
{
"propertyPath": "fiscal_id",
"message": "Unknown fiscal id"
}
]
}