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