Receipt

Get receipts collection

Access rules:

  • Merchants: require a valid JWT.
  • Cashiers: require a valid JWT and a valid certificate.
SecurityE-Receipt_IT_API_OAuth2PasswordBearer
Request
path Parameters
serial_number
required
string (Serial Number)

The Point of Sale's serial number

query Parameters
page
integer (Page)
Default: 1

Page identifier

size
integer (Size)
Default: 30

Page size

status
string (E-Receipt_IT_API_ReceiptStatus)
Default: "sent"

Retrieve either receipts not yet sent to MF2 or receipts already sent to MF2. Default: sent receipts.

Enum: "ready" "sent"
order[document_number]
string (Order[Document Number])
Default: "desc"

Order receipts in ascending or descending order with respect to their document_number

Enum: "desc" "asc"
Document Number (string) or Document Number (null) (Document Number)

Retrieve receipt with specified document number

document_datetime[before]
string <date-time> (Document Datetime[Before])
Default: "2025-10-27T15:27:49.552036"

Filter by receipts issued before specified datetime (value included)

Document Datetime[Strictly Before] (string) or Document Datetime[Strictly Before] (null) (Document Datetime[Strictly Before])

Filter by receipts issued before specified datetime (value strictly before)

Document Datetime[After] (string) or Document Datetime[After] (null) (Document Datetime[After])

Filter by receipts issued after specified datetime (value included)

Document Datetime[Strictly After] (string) or Document Datetime[Strictly After] (null) (Document Datetime[Strictly After])

Filter by receipts issued after specified datetime (value strictly after)

ReceiptType (string) or Array of Type (strings) or Type (null) (Type)

Filter by receipts with specified type

Responses
200

Successful Response

403

Forbidden

404

Not Found

422

Validation Error

get/mf1/point-of-sales/{serial_number}/receipts
Request samples
Response samples
application/json
{
  • "members": [
    ],
  • "total": 0,
  • "page": 0,
  • "size": 0
}

Create a new sale receipt

SecurityE-Receipt_IT_API_OAuth2PasswordBearer
Request
Request Body schema: application/json
required
required
Array of objects (Items)

"Elementi contabili". Commercial document items. At least one item is required.

Customer Tax Code (string) or Customer Tax Code (null) (Customer Tax Code)

Tax code of the customer. If set, customer_lottery_code can't be set as well.

Customer Lottery Code (string) or Customer Lottery Code (null) (Customer Lottery Code)

Lottery code of the customer. If set, customer_tax_code can't be set as well.

discount
string (Discount)
Default: "0.00"

"Sconto a Pagare". This discount, expressed in euros as a string with 2 to 8 decimal places, does not affect the taxable amount reported to the Agenzia delle Entrate. It represents an unpaid portion of the total, typically a rounding adjustment, applied at the time of payment.

invoice_issuing
boolean (Invoice Issuing)
Default: false

Set this field to true if the amount has not been collectedsince the issued commercial document will be followed by an invoice. This use case is generally called 'Credito - segue fattura'.

uncollected_dcn_to_ssn
boolean (Uncollected Dcn To Ssn)
Default: false

Set this flag to true when the payment is not collected because the commercial document relates to the Distinta Contabile Riepilogativa that will be transmitted to the Sistema Sanitario Nazionale.

services_uncollected_amount
string (Services Uncollected Amount)
Default: "0.00"

"Credito Non Riscosso - Prestazioni Servizi". Uncollected Amount in EUR as a string with 2 to 8 decimal digits in case of services.

goods_uncollected_amount
string (Goods Uncollected Amount)
Default: "0.00"

"Credito Non Riscosso - Bene Consegnato". Uncollected Amount in EUR as a string with 2 to 8 decimal digits in case of delivered goods.

cash_payment_amount
string (Cash Payment Amount)
Default: "0.00"

"Pagamento in contanti". Cash payment amount in EUR as a string with 2 to 8 decimal digits.

electronic_payment_amount
string (Electronic Payment Amount)
Default: "0.00"

"Pagamento elettronico". Electronic payment amount in EUR as a string with 2 to 8 decimal digits.

ticket_restaurant_payment_amount
string (Ticket Restaurant Payment Amount)
Default: "0.00"

'Pagamento Ticket Restaurant'. Meal voucher payment amount in EUR as a string with 2 to 8 decimal digits.

ticket_restaurant_quantity
integer (Ticket Restaurant Quantity)
Default: 0

'Numero Ticket Restaurant'. Number of meal vouchers used.

Responses
201

Successful Response

403

Forbidden

404

Not Found

422

Validation Error

post/mf1/receipts
Request samples
application/json
{
  • "items": [
    ],
  • "customer_tax_code": "string",
  • "customer_lottery_code": "string",
  • "discount": "0.00",
  • "invoice_issuing": false,
  • "uncollected_dcn_to_ssn": false,
  • "services_uncollected_amount": "0.00",
  • "goods_uncollected_amount": "0.00",
  • "cash_payment_amount": "0.00",
  • "electronic_payment_amount": "0.00",
  • "ticket_restaurant_payment_amount": "0.00",
  • "ticket_restaurant_quantity": 0
}
Response samples
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "type": "sale",
  • "total_amount": "string",
  • "document_number": "stringstr",
  • "document_datetime": "2025-10-08T16:20:42",
  • "parent_receipt_uuid": "8e47e86b-f4e0-4ed8-a82a-e9c693a00a74",
  • "is_voidable": true,
  • "is_returnable": true,
  • "html_url": "string",
  • "pdf_url": "string"
}

Voids a receipt

SecurityE-Receipt_IT_API_OAuth2PasswordBearer
Request
Request Body schema: application/json
required
document_number
required
string (Document Number)

The document number of the original receipt.

Responses
204

Successful Response

403

Forbidden

404

Not Found

422

Validation Error

delete/mf1/receipts
Request samples
application/json
{
  • "document_number": "0001-0001"
}
Response samples
application/json
{
  • "type": "/errors/403",
  • "title": "Forbidden",
  • "status": 403,
  • "detail": "A human-readable explanation specific to this occurrence of the problem",
  • "instance": "A URI reference that identifies the specific occurrence of the problem"
}

Get a receipt

SecurityE-Receipt_IT_API_OAuth2PasswordBearer
Request
path Parameters
receipt_uuid
required
string <uuid> (Receipt Uuid)
Responses
200

Successful Response

403

Forbidden

404

Not Found

422

Validation Error

get/mf1/receipts/{receipt_uuid}
Request samples
Response samples
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "type": "sale",
  • "total_amount": "string",
  • "document_number": "stringstr",
  • "document_datetime": "2025-10-08T16:20:42",
  • "parent_receipt_uuid": "8e47e86b-f4e0-4ed8-a82a-e9c693a00a74",
  • "is_voidable": true,
  • "is_returnable": true,
  • "html_url": "string",
  • "pdf_url": "string"
}

Get returnable quantities for items of a sale receipt

SecurityE-Receipt_IT_API_OAuth2PasswordBearer
Request
path Parameters
receipt_uuid
required
string <uuid> (Receipt Uuid)
Responses
200

Successful Response

403

Forbidden

404

Not Found

422

Validation Error

get/mf1/receipts/{receipt_uuid}/returnable-items
Request samples
Response samples
application/json
[
  • {
    }
]

Voids a receipt issued by another POS

SecurityE-Receipt_IT_API_OAuth2PasswordBearer
Request
Request Body schema: application/json
required
pos_id
required
string (Pos Id)

The ID of the Point of Sale that issued the original receipt.

document_number
required
string (Document Number)

The document number of the original receipt.

document_datetime
required
string (Document Datetime) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

The date and time of the original receipt in ISO format.

required
Array of objects (Items)
Lottery Code (string) or Lottery Code (null) (Lottery Code)

The lottery code of the original receipt, if available.

Responses
204

Successful Response

403

Forbidden

404

Not Found

422

Validation Error

delete/mf1/receipts/void-via-different-pos
Request samples
application/json
{
  • "pos_id": "E001-000001",
  • "document_number": "0001-0001",
  • "document_datetime": "2024-03-20T10:00:00",
  • "items": [
    ],
  • "lottery_code": "123456789"
}
Response samples
application/json
{
  • "type": "/errors/403",
  • "title": "Forbidden",
  • "status": 403,
  • "detail": "A human-readable explanation specific to this occurrence of the problem",
  • "instance": "A URI reference that identifies the specific occurrence of the problem"
}

Void a receipt identified by a proof of purchase

SecurityE-Receipt_IT_API_OAuth2PasswordBearer
Request
Request Body schema: application/json
required
required
Array of objects (Items)
proof
required
string (E-Receipt_IT_API_ReceiptProofType)

The type of proof of purchase: "POS" for POS receipts, "VR" for "Vuoti a rendere", "ND" for other residual cases. Used in place of device serial number/unique PEM identifier.

Enum: "POS" "VR" "ND"
document_datetime
required
string (Document Datetime) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

The date and time of the proof of purchase in ISO format.

Responses
204

Successful Response

403

Forbidden

404

Not Found

422

Validation Error

delete/mf1/receipts/void-with-proof
Request samples
application/json
{
  • "items": [
    ],
  • "proof": "POS",
  • "document_datetime": "2024-03-20T10:00:00"
}
Response samples
application/json
{
  • "type": "/errors/403",
  • "title": "Forbidden",
  • "status": 403,
  • "detail": "A human-readable explanation specific to this occurrence of the problem",
  • "instance": "A URI reference that identifies the specific occurrence of the problem"
}

Get the details or the PDF of a receipt

Retrieve receipt details in JSON format or download as PDF based on the Accept header. Use 'Accept: application/json' for JSON response (default) or 'Accept: application/pdf' for PDF download.

SecurityE-Receipt_IT_API_OAuth2PasswordBearer
Request
path Parameters
receipt_uuid
required
string <uuid> (Receipt Uuid)
header Parameters
Accept (string) or Accept (null) (Accept)

Content type preference. Use 'application/json' for JSON response or 'application/pdf' for PDF download. Defaults to 'application/json' if not specified.

Responses
200

Receipt details in JSON format or PDF file based on Accept header

401

Unauthorized

403

Forbidden - User not authorized to access this receipt

404

Receipt not found

422

Validation Error

get/mf1/receipts/{receipt_uuid}/details
Request samples
Response samples
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "type": "sale",
  • "total_amount": "string",
  • "document_number": "stringstr",
  • "document_datetime": "2025-10-08T16:20:42",
  • "parent_receipt_uuid": "8e47e86b-f4e0-4ed8-a82a-e9c693a00a74",
  • "is_voidable": true,
  • "is_returnable": true,
  • "html_url": "string",
  • "pdf_url": "string",
  • "total_taxable_amount": "7.23",
  • "total_uncollected_amount": "7.23",
  • "deductible_amount": "7.23",
  • "total_vat_amount": "7.23",
  • "total_discount": "7.23",
  • "items": [ ],
  • "customer_lottery_code": "string",
  • "cashier_uuid": "7541da75-91db-4eb9-ad7e-e65d2f127053"
}

Return items from a sale receipt

SecurityE-Receipt_IT_API_OAuth2PasswordBearer
Request
Request Body schema: application/json
required
required
Array of objects (Items)
document_number
required
string (Document Number)

The document number of the original receipt.

Responses
201

Successful Response

403

Forbidden

404

Not Found

422

Validation Error

post/mf1/receipts/return
Request samples
application/json
{
  • "items": [
    ],
  • "document_number": "0001-0001"
}
Response samples
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "type": "sale",
  • "total_amount": "string",
  • "document_number": "stringstr",
  • "document_datetime": "2025-10-08T16:20:42",
  • "parent_receipt_uuid": "8e47e86b-f4e0-4ed8-a82a-e9c693a00a74",
  • "is_voidable": true,
  • "is_returnable": true,
  • "html_url": "string",
  • "pdf_url": "string"
}

Return items from a sale receipt issued by a different Point of Sale

SecurityE-Receipt_IT_API_OAuth2PasswordBearer
Request
Request Body schema: application/json
required
pos_id
required
string (Pos Id)

The ID of the Point of Sale that issued the original receipt.

required
Array of objects (Items)
document_number
required
string (Document Number)

The document number of the original receipt.

document_datetime
required
string (Document Datetime) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

The date and time of the original receipt in ISO format.

Lottery Code (string) or Lottery Code (null) (Lottery Code)

The lottery code of the original receipt, if available.

Responses
201

Successful Response

403

Forbidden

404

Not Found

422

Validation Error

post/mf1/receipts/return-via-different-pos
Request samples
application/json
{
  • "pos_id": "E001-000001",
  • "items": [
    ],
  • "document_number": "0001-0001",
  • "document_datetime": "2024-03-20T10:00:00",
  • "lottery_code": "123456789"
}
Response samples
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "type": "sale",
  • "total_amount": "string",
  • "document_number": "stringstr",
  • "document_datetime": "2025-10-08T16:20:42",
  • "parent_receipt_uuid": "8e47e86b-f4e0-4ed8-a82a-e9c693a00a74",
  • "is_voidable": true,
  • "is_returnable": true,
  • "html_url": "string",
  • "pdf_url": "string"
}

Return items from a receipt identified by a proof of purchase

SecurityE-Receipt_IT_API_OAuth2PasswordBearer
Request
Request Body schema: application/json
required
required
Array of objects (Items)
proof
required
string (E-Receipt_IT_API_ReceiptProofType)

The type of proof of purchase: "POS" for POS receipts, "VR" for "Vuoti a rendere", "ND" for other residual cases. Used in place of device serial number/unique PEM identifier.

Enum: "POS" "VR" "ND"
document_datetime
required
string (Document Datetime) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

The date and time of the proof of purchase in ISO format.

Responses
201

Successful Response

403

Forbidden

404

Not Found

422

Validation Error

post/mf1/receipts/return-with-proof
Request samples
application/json
{
  • "items": [
    ],
  • "proof": "POS",
  • "document_datetime": "2024-03-20T10:00:00"
}
Response samples
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "type": "sale",
  • "total_amount": "string",
  • "document_number": "stringstr",
  • "document_datetime": "2025-10-08T16:20:42",
  • "parent_receipt_uuid": "8e47e86b-f4e0-4ed8-a82a-e9c693a00a74",
  • "is_voidable": true,
  • "is_returnable": true,
  • "html_url": "string",
  • "pdf_url": "string"
}