Sending a Smart Receipt

The Smart Receipt API allows you to issue a Smart Electronic Receipt for a sale.

Unavailability window for sending Receipts

Please note that you can not send Receipts between 23.55 and 00.00 (Italian Time Zone).

Create a Receipt

Send a new Smart Receipt with the POST /receipts API.

Example:

Copy

Copied

POST /receipts
Content-Type: application/json

{
  "fiscal_id": "1234567890",
  "items": [
    {
      "quantity": 1,
      "description": "demo test",
      "unit_price": 0.01,
      "vat_rate_code": "10"
    }
  ],
  "cash_payment_amount": 0.01
}

Here is the corresponding response:

Copy

Copied

{
  "fiscal_id": "1234567890",
  "uuid": "ef9d9599-2b54-4278-a8fd-e7436653afa6",
  "type": "sale",
  "status": "new",
  "created_at": "2024-10-29 13:02:37",
  "return_receipts": [],
  "voiding_receipt": null,
  "returned_receipt": null,
  "voided_receipt": null,
  "error_message": null,
  "error_code": null,
  "total_amount": 0.01,
  "transaction_id": null,
  "document_number": null,
  "document_date": null
}

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.

In the above sample the Tax Authority has still not given an id to the receipt, while our system gave it the uuid ef9d9599-2b54-4278-a8fd-e7436653afa6.

When the receipt webhook has been notified, you can ask for its status:

Copy

Copied

GET /receipts/ef9d9599-2b54-4278-a8fd-e7436653afa6/details
Accept: application/json

Here is the corresponding response:

Copy

Copied

{
  "uuid": "ef9d9599-2b54-4278-a8fd-e7436653afa6",
  "type": "sale",
  "status": "ready",
  "fiscal_id": "1234567890",
  "created_at": "2024-10-29 13:02:37",
  "total_amount": 0.01,
  "transaction_id": "65957395",
  "document_number": "DCW2024/6596-0317",
  "total_taxable_amount": 0.00909091,
  "total_uncollected_amount": 0,
  "deductible_amount": 0,
  "total_vat_amount": 0.00090909,
  "total_discount": 0,
  "total_gross_discount": 0,
  "discount": 0,
  "items": [
    {
      "id": "105708830",
      "quantity": 1,
      "description": "demo test",
      "gross_price": 0.01,
      "vat_rate": "10",
      "gross_discount": 0,
      "complimentary": false,
      "unit_price": 0.00909091,
      "return": 0,
      "taxable_amount": 0.00909091,
      "net_taxable_amount": 0.00909091,
      "vat_amount": 0.00090909,
      "total_amount": 0.01,
      "unit_discount": 0
    }
  ]
}

If you specify Accept: application/pdf in your headers, you can download the PDF version of the receipt.

Void a Receipt

You can void a receipt with the DELETE /receipts/{id} API.

For example:

Copy

Copied

DELETE /receipts/ef9d9599-2b54-4278-a8fd-e7436653afa6
Accept: application/json

That will get the following response:

Copy

Copied

{
  "uuid": "f50d9dc7-5e1e-46f7-b15a-978359d5bd66",
  "type": "void",
  "status": "new",
  "fiscal_id": "1234567890",
  "created_at": "2024-10-29 13:31:27",
  "total_amount": 0.01,
  "voided_receipt": {
    "uuid": "ef9d9599-2b54-4278-a8fd-e7436653afa6",
    "type": "sale",
    "status": "ready",
    "fiscal_id": "10442360961",
    "created_at": "2024-10-29 13:02:37",
    "total_amount": 0.01,
    "transaction_id": "65957395",
    "document_number": "DCW2024/6596-0317",
    "document_date": "2024-10-29 14:02:55"
  },
  "transaction_id": null,
  "document_number": null,
  "document_date": null,
  "return_receipts": null,
  "voiding_receipt": null,
  "returned_receipt": null,
  "error_message": null,
  "error_code": null
}

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:

Copy

Copied

{
  "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.

Handling discounts

If you want to apply a discount that will not increase the taxable amount, you must specify it at the item level:

Copy

Copied

{
   "fiscal_id":"1234567890",
   "electronic_payment_amount":4,
   "items":[
      {
         "quantity":1,
         "description":"PROVA",
         "unit_price":5,
         "vat_rate_code":"22",
         "discount":1,
         "complimentary":false
      }
   ]
}

Here is the receipt that the above payload produces:

The discount field at the summary level is called "sconto a pagare". It does not change the taxable amount of the receipt that is sent to the Agenzia delle Entrate. It can be considered an unpaid amount, used e.g. to round the total amount down to a whole number.

Copy

Copied

{
  "fiscal_id":"1234567890",
  "electronic_payment_amount":4,
  "discount":1,
  "items":[
    {
      "quantity":1,
      "description":"PROVA",
      "unit_price":5,
      "vat_rate_code":"22",
      "discount":0,
      "complimentary":false
    }
  ]
}

Here is the receipt that the above payload, which uses a "sconto a pagare", produces:

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:

Copy

Copied

{
  "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	`CANNOT_SEND_DATA_FOR_THIS_LEGAL_ENTITY`	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:

Copy

Copied

{
  "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:

Copy

Copied

{
  "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:

Copy

Copied

{
  "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:

Copy

Copied

{
  "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:

Copy

Copied

{
  "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:

Copy

Copied

{
  "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:

Copy

Copied

{
  "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:

Copy

Copied

{
  "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:

Copy

Copied

{
  "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:

Copy

Copied

{
  "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"
    }
  ]
}