{"openapi":"3.0.0","info":{"title":"Invoice","version":"1.0.0","description":"\nComplete API for managing Italian Electronic Invoices (Fatturazione Elettronica) and Digital Receipts (Scontrino Elettronico) in full compliance with tax regulations.\n\n### Core Capabilities\n- **Electronic Invoicing**: Comprehensive management of both Active (outgoing) and Passive (incoming) invoices. Automates transmission to the SDI (Sistema di Interscambio), handles digital signatures, and monitors invoice states in real-time. \n  > **IMPORTANT**: To receive supplier invoices, you need to register our Recipient Code on the Italian Revenue Agency's website. Please follow this [step-by-step guide](https://openapi.it/blog/registrare-codice-destinatario-agenzia-entrate-italiana) and provide the following code when required: **PIC7CPS**\n- **Digital Receipts**: Seamless integration for creating and transmitting Smart Electronic Receipts. Replaces traditional telematic cash registers for online sales, ensuring direct synchronization with the Government Tax Portal (Cassetto Fiscale).\n- **Compliance & Security**: Adheres to Italian Revenue Agency (Agenzia delle Entrate) standards. Supports secure data exchange and flexible configuration management for different business entities.\n\n### 🏪 Stores, Cash Registers & Address Management (NEW)\nThe IT-configuration now supports **multi-store management** through the new `stores`, `cash_registers`, and `merchant_address` fields. These fields allow you to configure:\n- **`merchant_address`**: The legal/registered address of your business (sede legale).\n- **`stores`**: A list of physical points of sale (POS / PEM), each with its own label, address, and associated cash registers.\n- **`cash_registers`**: Individual cash registers within each store, each identified by a unique label.\n\nAll address fields are validated against the Italian CAP (ZIP code) registry to ensure consistency between `zip_code`, `province`, and `city`.\n\n> **NB**: These new fields are required for the upcoming **new RECEIPTS service** for electronic receipt transmission. The new service will be available as soon as the Italian Revenue Agency (Agenzia delle Entrate) APIs are released. We will provide frequent updates to this API as new features become available. The new features will be available shortly in the **test environment** so you can start testing the new functionalities.\n\n**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.\n\n**NB**: To use the receipt transmission service, you must enable your credentials on the Italian Revenue Agency (Agenzia delle Entrate) portal by following the third-party assignment procedure.\nThe same credentials enabled on the portal through this procedure must be entered into your **IT-configuration** (section `receipts_authentication`).\n\n👉 **[CLICK HERE TO DOWNLOAD THE ENABLEMENT PROCEDURE GUIDE](https://docs.openapi.it/Procedura-manuale-per-incarico.pdf)**\n\n*Note: Only companies have the ability to designate a third party for sending receipts. Freelancers (liberi professionisti) and sole proprietorships (aziende individuali) cannot appoint a third-party representative and must manage the transmission directly using their own credentials..*","termsOfService":"https://openapi.it/en/terms-and-conditions","contact":{"url":"https://openapi.it/en/support","name":"Support"},"license":{"name":"Apache 2.0","url":"http://www.apache.org/licenses/LICENSE-2.0.html"}},"servers":[{"url":"https://invoice.openapi.com","description":"Production"},{"url":"https://test.invoice.openapi.com","description":"Sandbox"}],"tags":[{"name":"IT-configuration"},{"name":"IT-invoice","description":"Manage electronic invoices and imports."},{"name":"IT-receipt","description":"Handle receipt processing."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"InvoiceImportRequest":{"type":"object","required":["invoice"],"properties":{"invoice":{"type":"string","description":"The invoice content, either as raw XML or Base64 encoded XML string.","example":"PD94bWwgdmVyc2lvbj0iMS4wIi..."},"details":{"type":"object","description":"Optional SDI details for the imported invoice","properties":{"sdi_id":{"type":"string","description":"The unique SDI identifier. It must be unique within the system; a duplicate check will be performed.","example":"1234567"},"sdi_filename":{"type":"string","example":"IT01234567890_00001.xml"},"sdi_status":{"type":"string","enum":["DELIVERED","ACCEPTED","REJECTED","TERMS_EXPIRED","NOT_DELIVERED"],"description":"Definitive SDI status"},"sdi_message":{"type":"string"},"sdi_update_date":{"type":"string","format":"date-time"},"invoice_date":{"type":"string","format":"date"}}}}},"InvoiceResponse":{"type":"object","description":"Represents the response structure for an invoice, containing status, direction, and detailed entity information.","properties":{"id":{"type":"string","description":"Unique identifier of the invoice."},"state":{"type":"string","description":"Current status of the invoice.","enum":["NEW","SENT","RECEIVED","DONE","ERROR"]},"direction":{"type":"string","description":"Direction of the invoice (incoming or outgoing).","enum":["incoming","outgoing"]},"fiscal_id":{"type":"string","description":"Fiscal ID (VAT number or Tax Code) associated with the invoice context."},"type":{"type":"string","description":"Type of the invoice document (e.g., TD01, TD02)."},"document_number":{"type":"string","description":"Number of the document."},"issue_date":{"type":"string","format":"date","description":"Date of issue of the invoice."},"total_gross_amount":{"type":"number","description":"Total gross amount of the invoice."},"total_amount_excluding_tax":{"type":"number","description":"Total net amount excluding tax."},"total_tax_amount":{"type":"number","description":"Total tax amount."},"total_amount_including_tax":{"type":"number","description":"Total amount including tax."},"total_payable_amount":{"type":"number","description":"Total amount to be paid."},"invoice_lines":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceLine"}},"payment_means":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMeans"}},"transmission_id":{"type":"string","description":"Unique transmission identifier."},"create_at":{"type":"string","description":"Creation timestamp."},"updated_at":{"type":"string","description":"Last update timestamp."},"sender":{"type":"object","description":"Details of the invoice sender.","properties":{"name":{"type":"string","description":"Name or denomination of the sender."},"vat_id":{"type":"string","description":"VAT ID of the sender."},"tax_code":{"type":"string","description":"Tax code of the sender."},"street":{"type":"string","description":"Street address."},"city":{"type":"string","description":"City."},"zip":{"type":"string","description":"ZIP/Postal code."},"province":{"type":"string","description":"Province."},"country_code":{"type":"string","description":"Country code (e.g., IT)."},"phone":{"type":"string","description":"Phone number."},"email":{"type":"string","description":"Email address."}}},"recipient":{"type":"object","description":"Details of the invoice recipient.","properties":{"name":{"type":"string","description":"Name or denomination of the recipient."},"vat_id":{"type":"string","description":"VAT ID of the recipient."},"tax_code":{"type":"string","description":"Tax code of the recipient."},"street":{"type":"string","description":"Street address."},"city":{"type":"string","description":"City."},"zip":{"type":"string","description":"ZIP/Postal code."},"province":{"type":"string","description":"Province."},"country_code":{"type":"string","description":"Country code (e.g., IT)."},"phone":{"type":"string","description":"Phone number."},"email":{"type":"string","description":"Email address."}}},"details":{"type":"object","description":"Additional SDI details and status information.","properties":{"sdi_id":{"type":"string","description":"SDI Identifier assigned by the Revenue Agency."},"sdi_filename":{"type":"string","description":"Name of the file sent/received from SDI."},"sdi_status":{"type":"string","description":"Technical status assigned by the SDI (Sistema di Interscambio). Possible values:\n\n* **BOOKED**: The invoice is queued and waiting to be processed.\n* **SENT**: The invoice has been successfully forwarded to the SDI.\n* **DELIVERED**: The invoice has been successfully delivered to the recipient. **Final State**\n* **NOT_DELIVERED**: The digital address was unreachable; the invoice is available in the recipient's Tax Portal. **Final State**\n* **RECEIVED**: Technical status identifying an incoming (passive) invoice. **Final State**\n* **ACCEPTED**: (PA only) The Public Administration has formally accepted the invoice. **Final State**\n* **REJECTED**: (PA only) The Public Administration has formally rejected the invoice. **Final State**\n* **TERMS_EXPIRED**: (PA only) The 15-day period for PA response has passed. **Final State**\n* **ERROR**: The SDI rejected the file due to formal or validation errors. **Final State**","enum":["BOOKED","SENT","DELIVERED","NOT_DELIVERED","RECEIVED","ACCEPTED","REJECTED","TERMS_EXPIRED","ERROR"],"example":"DELIVERED"},"sdi_message":{"type":"string","description":"Message or error description from SDI."},"sdi_update_date":{"type":"string","description":"Timestamp of the last update from SDI."},"invoice_date":{"type":"string","description":"Formatted date of the invoice."}}}}},"InvoiceLine":{"type":"object","properties":{"description":{"type":"string","description":"Description of the line item."},"quantity":{"type":"number","description":"Quantity of the item."},"unit_of_measure":{"type":"string","nullable":true,"description":"Unit of measure (e.g., KG, copies, etc.)."},"nature":{"type":"string","nullable":true,"description":"VAT nature code (required if VAT rate is 0%)."},"unit_price":{"type":"number","description":"Unit price of the item."},"total_net_amount":{"type":"number","description":"Total net amount for the line."},"tax_rate":{"type":"number","description":"VAT rate percentage."},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceDiscount"},"description":"List of line-level discounts or surcharges."},"item_code":{"type":"string","nullable":true,"description":"Internal item code."}}},"InvoiceDiscount":{"type":"object","properties":{"type":{"type":"string","description":"Type of adjustment (SC = Discount, MG = Surcharge).","enum":["SC","MG"]},"percentage":{"type":"number","description":"Discount percentage."},"amount":{"type":"number","description":"Fixed discount amount."}}},"PaymentMeans":{"type":"object","properties":{"payment_mode":{"type":"string","description":"Code for payment mode (e.g., MP05 for Bank Transfer)."},"due_date":{"type":"string","format":"date","description":"Payment due date."},"amount":{"type":"number","description":"Amount to be paid."},"financial_account":{"type":"string","nullable":true,"description":"IBAN or other financial account."}}},"Callback":{"type":"object","description":"This is our standardized OpenAPI callback system. It enables the configuration of parameters for receiving notifications about status updates of asynchronous requests to this endpoint.","properties":{"method":{"type":"string","description":"Specify the callback method. When set to 'POST', a standard HTTP POST request will be initiated with the Content-Type header set to application/x-www-form-urlencoded. The JSON data will be encoded into a key-value pair named data (customizable using the field parameter) within the request body. If the method is set to 'JSON', a direct HTTP POST request will be made with the Content-Type header set to application/json. The raw JSON data will be directly inserted into the request body without any encoding.","enum":["POST","JSON"],"default":"JSON"},"field":{"type":"string","description":"This parameter works in conjunction with the 'method' parameter set to 'POST'. When provided as a string, it determines the name of the parameter that will be sent in the POST request.","example":"data","default":"data"},"url":{"type":"string","format":"uri","description":"A valid URL capable of handling POST requests must be entered into this parameter. For endpoints requiring authentication, the 'headers' parameter can be used to specify 'basic auth' or 'bearer auth'. The maximum timeout is 30 seconds. If 'retry' is set, the system will retry up to 'retry' times until a 200 status code is received.","example":"https://www.mysite.com/myEndpoint"},"retry":{"type":"integer","description":"The maximum number of attempts is defined by the 'retry' parameter. If the maximum number of attempts is reached without a successful status code (e.g., 200 OK), the request is considered a final failure. A time interval is often introduced between attempts to avoid overloading the server. This interval may increase exponentially with each attempt to reduce the impact on an overloaded server. The 'retry' parameter is configured to retry the request only in case of specific status codes, typically those indicating temporary errors (e.g., 502, 503) or network issues.","example":3,"maximum":5,"minimum":5,"default":0},"headers":{"type":"object","properties":{"key":{"type":"string"}},"description":"A collection of HTTP headers to be sent with the request. Each header is defined as a key-value pair. Headers can be used for various purposes, including authentication, content negotiation, and custom metadata.","example":{"session_id":"9834r5fh589494"}},"custom":{"type":"object","description":"This object can be populated with any additional data you wish to include in the callback response. This data will be accessible within the 'custom' parameter of the callback function. You can use this to store and retrieve any relevant information that you need for your application.","example":{"my_custom_id":"123456789"}}},"required":["url"],"example":{"callback":{"url":"https://your-server.site/123232","custom":123}}},"Address":{"type":"object","description":"Represents a physical address (legal address or point of sale). All fields are required and validated against the Italian CAP registry.\n\n> **NB**: These address fields are required for the upcoming new RECEIPTS service. The `zip_code` is validated against the official Italian CAP registry, and `province` and `city` are cross-checked for consistency.","required":["street_address","street_number","zip_code","city","province"],"properties":{"street_address":{"type":"string","description":"Street name (e.g. 'Via Roma').","maxLength":60,"example":"Via Roma"},"street_number":{"type":"string","description":"Street number (e.g. '10', '10/A').","maxLength":10,"example":"10"},"zip_code":{"type":"string","description":"Italian ZIP code (CAP). Must be exactly 5 digits. Validated against the official Italian CAP registry.","pattern":"^\\d{5}$","minLength":5,"maxLength":5,"example":"00100"},"city":{"type":"string","description":"City name. Must match one of the municipalities associated with the provided ZIP code.","maxLength":60,"example":"Roma"},"province":{"type":"string","description":"Italian province code (2 uppercase letters). Must correspond to the province associated with the provided ZIP code.","pattern":"^[A-Z]{2}$","minLength":2,"maxLength":2,"example":"RM"}}},"CashRegister":{"type":"object","description":"Represents a cash register within a store/point of sale.\n\n> **NB**: Cash registers will be used for the upcoming new RECEIPTS service to identify the device issuing the receipt.","required":["label"],"properties":{"cr_id":{"type":"string","description":"Unique identifier of the cash register. Auto-generated if not provided.","readOnly":true,"example":"665a1b2c3d4e5f6a7b8c9d0e"},"label":{"type":"string","description":"Descriptive label for the cash register (e.g. 'Cassa 1', 'POS Ingresso').","maxLength":50,"example":"Cassa 1"}}},"Store":{"type":"object","description":"Represents a physical point of sale (POS / PEM) with its address and associated cash registers.\n\n> **NB**: Stores represent physical locations where receipts are issued. These fields will be required for the upcoming new RECEIPTS service.","required":["label"],"properties":{"store_id":{"type":"string","description":"Unique identifier of the store. Auto-generated if not provided.","readOnly":true,"example":"665a1b2c3d4e5f6a7b8c9d0e"},"label":{"type":"string","description":"Descriptive label for the store/point of sale (e.g. 'Negozio Centro', 'Punto Vendita Roma').","maxLength":50,"example":"Negozio Centro"},"address":{"$ref":"#/components/schemas/Address"},"cash_registers":{"type":"array","description":"List of cash registers associated with this store.","items":{"$ref":"#/components/schemas/CashRegister"}}}},"IT-configuration":{"type":"object","required":["fiscal_id","name","email"],"properties":{"fiscal_id":{"type":"string","description":"The unique fiscal identifier (VAT number or tax code) of the company registered with the Agenzia delle Entrate.","example":"YourCompanyFiscal_id"},"name":{"type":"string","description":"The company or entity name associated with the fiscal ID.","example":"nameCompany"},"email":{"type":"string","format":"email","description":"The email address used for communication and notifications. Cannot be changed after the configuration is created.","example":"youremail@mail.com"},"receipts":{"type":"boolean","description":"Indicates whether the system should handle digital receipts. When set to `true`, `merchant_address` becomes required.","example":true},"customer_invoice":{"type":"boolean","description":"Indicates whether the system should handle outgoing customer invoices.","example":true},"supplier_invoice":{"type":"boolean","description":"Indicates whether the system should handle incoming supplier invoices. **Note**: To receive these invoices, you must register our Recipient Code (**PIC7CPS**) on the Agenzia delle Entrate portal. Refer to this [registration guide](https://openapi.it/blog/registrare-codice-destinatario-agenzia-entrate-italiana) for details.","example":true},"merchant_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"description":"Legal/registered address of the business (sede legale). Required when `receipts` is set to `true`.\n\n> **NB**: This field is required for the upcoming new RECEIPTS service. It will be used to register your business with the Italian Revenue Agency (Agenzia delle Entrate) for electronic receipt transmission."},"stores":{"type":"array","description":"List of physical points of sale (stores/PEM). Each store can have its own address and cash registers.\n\n> **NB**: Stores and their cash registers are required for the upcoming new RECEIPTS service. They represent the physical locations and devices from which electronic receipts are issued.","items":{"$ref":"#/components/schemas/Store"},"example":[{"label":"Negozio Centro","address":{"street_address":"Via Roma","street_number":"10","zip_code":"00100","city":"Roma","province":"RM"},"cash_registers":[{"label":"Cassa 1"},{"label":"Cassa 2"}]}]},"receipts_authentication":{"type":"object","description":"Authentication credentials required for digital receipt submission.","properties":{"taxCode":{"type":"string","description":"The fiscal code associated with the receipt authentication.","example":"FHHWMF96L52D111B"},"password":{"type":"string","description":"The password for authentication.","example":"1234567891****d"},"pin":{"type":"string","description":"A security PIN associated with the authentication.","example":"1********4"}}},"api_configurations":{"type":"array","description":"Configuration of event-based callbacks for receiving notifications.","items":{"type":"object","properties":{"event":{"type":"string","description":"The type of event for which notifications are configured.","enum":["receipt","receipt-credentials","receipt-retry","receipt-error","customer-invoice","supplier-invoice"],"example":"receipt"},"callback":{"$ref":"#/components/schemas/Callback"}}},"minItems":1,"example":[{"event":"receipt","callback":{"url":"https://your-server.site/123232"}},{"event":"customer_invoice","callback":{"url":"https://your-server.site/123232"}},{"event":"supplier_invoice","callback":{"url":"https://your-server.site/123232"}},{"event":"receipt-error","callback":{"url":"https://your-server.site/error"}}]}}},"IT-configurationPATCH":{"type":"object","description":"Fields available for updating an existing IT-configuration. All fields are optional; only the provided fields will be updated.\n\n> **NB**: You can also perform **granular updates** on individual stores and cash registers using the path-based PATCH endpoints:\n> - `PATCH /IT-configurations/{fiscal_id}/stores/{store_id}` — Update a specific store\n> - `PATCH /IT-configurations/{fiscal_id}/stores/{store_id}/cash_registers/{cr_id}` — Update a specific cash register","properties":{"receipts":{"type":"boolean","description":"Indicates whether the system should handle digital receipts. When set to `true`, `merchant_address` becomes required.","example":true},"merchant_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"description":"Update the legal/registered address of the business. Address fields are merged granularly — you can update individual fields without replacing the entire address.\n\n> **NB**: This field is required for the upcoming new RECEIPTS service."},"stores":{"type":"array","description":"Update or add stores to the configuration. Existing stores are matched by `label` — if a store with the same label exists, it will be updated; otherwise, a new store is created. Stores are never removed via PATCH (additive behavior).\n\n> **NB**: Stores and cash registers are required for the upcoming new RECEIPTS service.","items":{"$ref":"#/components/schemas/Store"},"example":[{"label":"Negozio Centro","address":{"street_address":"Via Nuova","street_number":"15","zip_code":"00100","city":"Roma","province":"RM"}}]},"receipts_authentication":{"type":"object","description":"Authentication credentials required for digital receipt submission.","properties":{"taxCode":{"type":"string","description":"The fiscal code associated with the receipt authentication.","example":"FHHWMF96L52D111B"},"password":{"type":"string","description":"The password for authentication.","example":"1234567891****d"},"pin":{"type":"string","description":"A security PIN associated with the authentication.","example":"1********4"}}},"customer_invoice":{"type":"boolean","description":"Enable or disable outgoing customer invoice management.","example":true},"supplier_invoice":{"type":"boolean","description":"Enable or disable incoming supplier invoice management.","example":true},"api_configurations":{"type":"array","description":"Configuration of event-based callbacks for receiving notifications.","items":{"type":"object","properties":{"event":{"type":"string","description":"The type of event for which notifications are configured.","enum":["receipt","receipt-credentials","receipt-retry","receipt-error","customer-invoice","supplier-invoice"],"example":"receipt"},"callback":{"$ref":"#/components/schemas/Callback"}}},"minItems":1,"example":[{"event":"receipt","callback":{"url":"https://your-server.site/123232"}},{"event":"receipt-error","callback":{"url":"https://your-server.site/error"}}]}}},"ITConfigurationResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"fiscal_id":{"type":"string","example":"YourCompanyFiscal_id"},"name":{"type":"string","example":"nameCompany"},"email":{"type":"string","format":"email","example":"m.amoruso9@openapi.com"},"receipts_authentication":{"type":"object","properties":{"taxCode":{"type":"string","example":"FHHWMF96L52D111B"}}},"api_configurations":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string","example":"receipt"},"callback":{"type":"object","properties":{"method":{"type":"string","enum":["POST","JSON"],"example":"JSON"},"url":{"type":"string","format":"uri","example":"https://www.mysite.com/myEndpoint"},"user_id":{"type":"string","nullable":true},"username":{"type":"string","nullable":true},"field":{"type":"string","example":"data"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"data":{"type":"object","additionalProperties":{"type":"string"}},"retry":{"type":"integer","example":0},"scope":{"type":"string","nullable":true},"domain":{"type":"string","nullable":true},"custom":{"type":"string","nullable":true}}}}}},"receipts":{"type":"boolean","example":true},"customer_invoice":{"type":"boolean","example":true},"supplier_invoice":{"type":"boolean","example":true},"active":{"type":"boolean","example":true},"merchant_address":{"$ref":"#/components/schemas/Address"},"stores":{"type":"array","items":{"$ref":"#/components/schemas/Store"}},"create_timestamp":{"type":"integer","example":1738318895},"id":{"type":"string","example":"679ca42e**********016df7"}}},"success":{"type":"boolean","example":true},"message":{"type":"string","example":""},"error":{"type":"string","nullable":true}}},"ITConfigurationResponseArray":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ITConfigurationResponse"}}}},"ITInvoiceResponseArray":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceResponse"}}}},"ITReceiptResponseArray":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ResponseReceipts"}}}},"POSTReceipt":{"type":"object","required":["fiscal_id","items","cash_payment_amount"],"properties":{"fiscal_id":{"type":"string","description":"The VAT number of the company issuing the receipt (without country prefix). Must match the registered tax ID with the tax authority.","example":"YourCompanyFiscal_id"},"items":{"type":"array","description":"List of items being sold or services provided. Minimum 1 item required.","minItems":1,"items":{"type":"object","required":["quantity","description","unit_price","vat_rate_code"],"properties":{"quantity":{"type":"number","format":"double","description":"Item quantity with exactly 2 decimal places. For services, use 1.00.","example":2},"description":{"type":"string","description":"Clear item description (max 1000 chars).  Avoid special characters except commas and periods.","example":"Premium consulting service","maxLength":1000},"unit_price":{"type":"number","format":"double","description":"Gross unit price (VAT included) with up to 8 decimal digits. Must be positive.","example":59.99},"vat_rate_code":{"type":"string","description":"Applicable VAT rate code. Use 'N' codes for non-taxable items. Confirm correct rate with your accountant.","enum":["4","5","10","22","2","6.4","7","7.3","7.5","7.65","7.95","8.3","8.5","8.8","9.5","12.3","N1","N2","N3","N4","N5","N6"],"example":"22"},"discount":{"type":"number","description":"Item-level discount in EUR (VAT included).  Deducted from taxable amount. Cannot be used with 'complimentary'.","example":5,"minimum":0,"default":0},"complimentary":{"type":"boolean","description":"Marks item as free gift. VAT still applies. Set unit_price to normal price, system will zero it.","example":false,"default":false},"sku":{"type":"string","description":"Internal product identifier for inventory tracking. Not reported to tax authority.","example":"PROD-1002-XL"}}}},"cash_payment_amount":{"type":"number","description":"Amount paid in physical cash. Must equal sum of items minus discounts if no other payment methods used.","example":50,"minimum":0},"electronic_payment_amount":{"type":"number","description":"Amount paid via card/bancomat. Required when cash_payment_amount doesn't cover total. Must match actual transaction amount.","example":34.5,"minimum":0,"default":0},"ticket_restaurant_payment_amount":{"type":"number","description":"Total paid with meal vouchers. Requires corresponding ticket_restaurant_quantity. Not applicable for non-food items.","example":15,"minimum":0,"default":0},"ticket_restaurant_quantity":{"type":"integer","description":"Number of meal vouchers used. Multiply by voucher face value should equal ticket_restaurant_payment_amount.","example":2,"minimum":0,"default":0},"goods_uncollected_amount":{"type":"number","description":"[FOR DELIVERED GOODS ONLY] Amount of goods delivered but not yet paid. Triggers 'credit note' in tax reporting. Requires invoice_issuing=true.","example":250,"minimum":0,"default":0},"services_uncollected_amount":{"type":"number","description":"[FOR SERVICES ONLY] Value of services rendered but not yet paid. Reported as account receivable. Requires invoice_issuing=true.","example":1200,"minimum":0,"default":0},"invoice_issuing":{"type":"boolean","description":"Set to true when payment will be collected later via invoice. Requires either goods_uncollected_amount or services_uncollected_amount.","example":true,"default":false},"linked_receipt":{"type":"string","description":"Reference to related documents. Format: \"TYPE-YEAR-NUMBER\" (e.g. \"INV-2023-1001\"). Used for: 1. Subsequent invoices 2. Credit notes 3. Order references","example":"ORD-2023-456","maxLength":50},"discount":{"type":"number","description":"Global discount (doesn't affect taxable amount). Typically used for: 1. Rounding adjustments 2. Loyalty discounts","example":2.5,"minimum":0,"default":0},"lottery_code":{"type":"string","description":"8-character alphanumeric code for receipt lottery participation. Requirements: 1. Total ≥ €1.00 2. Fully electronic payment 3. Valid Italian receipt","example":"A1B2C3D4","pattern":"^[a-zA-Z0-9]{8}$"},"tags":{"type":"array","description":"Internal tracking tags (not fiscal-relevant). Max 10 tags allowed.","items":{"type":"string","example":"seasonal-promo"},"maxItems":10}}},"ReceiptResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"fiscal_id":{"type":"string","description":"The VAT number of the company issuing the receipt.","example":"YourCompanyFiscal_id"},"items":{"type":"array","description":"List of items in the receipt.","items":{"type":"object","properties":{"quantity":{"type":"number","description":"Quantity of the item.","example":11},"description":{"type":"string","description":"Description of the item.","example":"test ultimate"},"unit_price":{"type":"number","description":"Unit price of the item, including VAT.","example":10},"vat_rate_code":{"type":"string","description":"VAT rate code for the item.","example":"22"},"complimentary":{"type":"boolean","description":"Indicates if the item is complimentary (free).","example":true},"discount":{"type":"number","description":"Discount amount applied to the item in EUR.","example":0},"sku":{"type":"string","description":"You can set a number that is assigned to a product for the purpose of inventory management and ease of tracking.","example":"product1"}}}},"cash_payment_amount":{"type":"number","description":"Amount paid in cash in EUR.","example":4.5},"id":{"type":"string","description":"Unique identifier for the receipt.","example":"679cd95***************23"},"invoice_issuing":{"type":"boolean","description":"Flag indicating whether an invoice will be issued.","example":false},"services_uncollected_amount":{"type":"number","description":"Uncollected amount in EUR for services.","example":0},"goods_uncollected_amount":{"type":"number","description":"Uncollected amount in EUR for delivered goods.","example":0},"electronic_payment_amount":{"type":"number","description":"Amount paid electronically in EUR.","example":0},"ticket_restaurant_payment_amount":{"type":"number","description":"Amount paid using ticket restaurant in EUR.","example":0},"ticket_restaurant_quantity":{"type":"integer","description":"Number of ticket restaurant vouchers used.","example":0},"discount":{"type":"number","description":"Discount applied at payment time but does not alter taxable amount.","example":0},"linked_receipt":{"type":"string","description":"Reference to a linked receipt, if applicable.","example":"string"},"lottery_code":{"type":"string","nullable":true,"description":"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\"","example":null},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the document was created.","example":"2025-01-31T14:08:20.000Z"},"error_message":{"type":"string","nullable":true,"description":"Error message if communication with the Tax Authority fails.","example":null},"error_code":{"type":"string","nullable":true,"description":"Error code if communication with the Tax Authority fails.","example":null},"total_amount":{"type":"number","description":"Total amount for the receipt, including VAT.","example":0},"document_number":{"type":"string","description":"Document number assigned by the Tax Authority.","example":""},"document_date":{"type":"string","format":"date-time","nullable":true,"description":"Date of document issuance.","example":null},"transaction_id":{"type":"string","nullable":true,"description":"Identifier assigned to the document by the Tax Authority.","example":null},"create_timestamp":{"type":"integer","description":"Unix timestamp when the document was created.","example":1738332500},"status":{"type":"string","description":"new: The receipt has been created but not yet processed.\nretry: The receipt encountered an issue during submission and will be retried.\nsubmitted: The receipt has been sent for processing but is not yet finalized.\nready: The receipt has been successfully processed and is ready for use.\nfailed: The receipt processing has failed, requiring manual intervention.\nvoided: The receipt has been canceled and is no longer valid.\n","enum":["new","retry","submitted","ready","failed","voided"],"example":"new"},"type":{"type":"string","description":"Type of document issued.","enum":["sale","return","void"],"example":"sale"},"deductible_amount":{"type":"number","description":"Deductible amount for the return receipt, if applicable.","example":0},"total_discount":{"type":"number","description":"Total discount applied to the return receipt.","example":0},"total_gross_discount":{"type":"number","description":"Total gross discount applied to the return receipt.","example":0},"total_taxable_amount":{"type":"number","description":"Total taxable amount for the return receipt, before VAT.","example":0},"total_uncollected_amount":{"type":"number","description":"Total uncollected amount for the return receipt.","example":0},"total_vat_amount":{"type":"number","description":"Total VAT amount for the return receipt.","example":0},"update_timestamp":{"type":"integer","description":"Timestamp for when the return receipt was last updated, in Unix format.","example":1738341000},"tags":{"type":"array","description":"You can insert details for you receipt.","items":{"type":"object","example":["store1","store2"]}}}},"success":{"type":"boolean","description":"Indicates if the operation was successful.","example":true},"message":{"type":"string","description":"Additional message related to the operation.","example":""},"error":{"type":"string","nullable":true,"description":"Error message if applicable.","example":null}}},"ReceiptReturn":{"type":"object","properties":{"items":{"type":"array","description":"List of items to be returned.","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the item.","example":"374813"},"quantity":{"type":"number","description":"Quantity of the item to be returned.","example":2}}}}}},"ResponseCallbackReceipts":{"type":"object","properties":{"data":{"type":"object","properties":{"fiscal_id":{"type":"string","description":"The VAT number of the company that issued the receipt, without the country prefix.","example":"YourCompanyFiscal_id"},"items":{"type":"array","description":"List of items in the receipt.","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the item.","example":"'200170'"},"quantity":{"type":"number","description":"Quantity of the item, expressed with 2 decimal digits.","example":10},"description":{"type":"string","description":"Description of the item.","example":"product"},"gross_price":{"type":"number","description":"Gross price of the item, including VAT.","example":10},"vat_rate":{"type":"string","description":"VAT rate code for the item.","enum":["4","5","10","22","2","6.4","7","7.3","7.5","7.65","7.95","8.3","8.5","8.8","9.5","12.3","N1","N2","N3","N4","N5","N6"],"example":"'22'"},"gross_discount":{"type":"number","description":"Gross discount applied to the item.","example":0},"complimentary":{"type":"boolean","description":"Set to true if the item is complimentary (free).","example":true},"unit_price":{"type":"number","description":"Unit price of the item, expressed with up to 8 decimal digits.","example":8.19672131},"return":{"type":"number","description":"Return amount for the item, if applicable.","example":0},"taxable_amount":{"type":"number","description":"Taxable amount for the item.","example":90.16393442},"net_taxable_amount":{"type":"number","description":"Net taxable amount after discounts.","example":90.16393442},"vat_amount":{"type":"number","description":"VAT amount applied to the item.","example":19.83606558},"total_amount":{"type":"number","description":"Total amount for the item including VAT.","example":110},"unit_discount":{"type":"number","description":"Unit discount amount, expressed in EUR.","example":0},"sku":{"type":"string","description":"You can set a number that is assigned to a product for the purpose of inventory management and ease of tracking.","example":"product1"}}}},"cash_payment_amount":{"type":"number","description":"Cash payment amount in EUR.","example":100},"invoice_issuing":{"type":"boolean","description":"Flag for invoice issuance. Set to true for uncollected amounts invoiced at the end of the period.","example":false},"services_uncollected_amount":{"type":"number","description":"Uncollected amount in EUR for services.","example":0},"goods_uncollected_amount":{"type":"number","description":"Uncollected amount in EUR for delivered goods.","example":0},"electronic_payment_amount":{"type":"number","description":"Electronic payment amount in EUR.","example":0},"ticket_restaurant_payment_amount":{"type":"number","description":"Ticket restaurant payment amount in EUR.","example":0},"ticket_restaurant_quantity":{"type":"integer","description":"Number of Ticket Restaurants used.","example":0},"discount":{"type":"number","description":"Discount amount in EUR, applied at payment time but does not change the taxable amount.","example":0},"linked_receipt":{"type":"string","description":"Linked receipt reference, if applicable.","example":"string"},"lottery_code":{"type":"string","description":"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\"","example":null},"created_at":{"type":"string","description":"Timestamp when the document was created.","example":"2025-01-31T14:08:20.000Z"},"error_message":{"type":"string","description":"The error message in case the communication with the Tax Authority failed.","example":null},"error_code":{"type":"string","description":"The error code in case the communication with the Tax Authority failed.","example":null},"total_amount":{"type":"number","description":"Total amount for the receipt, including VAT.","example":110},"document_number":{"type":"string","description":"The document number assigned to the receipt by the Tax Authority.","example":"OPENAPI2025/0000-4706"},"document_date":{"type":"string","description":"The date of the document issuance.","example":"2025-01-31T14:08:28.000Z"},"transaction_id":{"type":"string","description":"The identifier assigned to the document by the Tax Authority.","example":"4706"},"create_timestamp":{"type":"integer","description":"Timestamp for when the document was created, in Unix format.","example":1738332500},"status":{"type":"string","description":"Current status of the document.","enum":["new","retry","submitted","ready","failed","voided"],"example":"ready"},"type":{"type":"string","description":"Type of document issued.","enum":["sale","return","void"],"example":"sale"},"deductible_amount":{"type":"number","description":"Deductible amount for the receipt, if applicable.","example":0},"total_discount":{"type":"number","description":"Total discount applied to the document.","example":0},"total_gross_discount":{"type":"number","description":"Total gross discount applied to the document.","example":0},"total_taxable_amount":{"type":"number","description":"Total taxable amount for the document, before VAT.","example":90.16393442},"total_uncollected_amount":{"type":"number","description":"Total uncollected amount for the document.","example":0},"total_vat_amount":{"type":"number","description":"Total VAT amount for the document.","example":19.83606558},"update_timestamp":{"type":"integer","description":"Timestamp for when the document was last updated, in Unix format.","example":1738332518},"tags":{"type":"array","description":"You can insert details for you receipt.","items":{"type":"object","example":["store1","store2"]}},"id":{"type":"string","description":"Unique identifier for the document.","example":"679c**********1111111111"},"custom":{"type":"object","description":"Custom fields for the document, if any.","example":null}}}}},"ResponseReceipts":{"properties":{"fiscal_id":{"type":"string","description":"The VAT number of the company that issued the receipt, without the country prefix.","example":"YourCompanyFiscal_id"},"items":{"type":"array","description":"List of items in the receipt.","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the item.","example":"'200170'"},"quantity":{"type":"number","description":"Quantity of the item, expressed with 2 decimal digits.","example":10},"description":{"type":"string","description":"Description of the item.","example":"product"},"gross_price":{"type":"number","description":"Gross price of the item, including VAT.","example":10},"vat_rate":{"type":"string","description":"VAT rate code for the item.","enum":["4","5","10","22","2","6.4","7","7.3","7.5","7.65","7.95","8.3","8.5","8.8","9.5","12.3","N1","N2","N3","N4","N5","N6"],"example":"'22'"},"gross_discount":{"type":"number","description":"Gross discount applied to the item.","example":0},"complimentary":{"type":"boolean","description":"Set to true if the item is complimentary (free).","example":true},"unit_price":{"type":"number","description":"Unit price of the item, expressed with up to 8 decimal digits.","example":8.19672131},"return":{"type":"number","description":"Return amount for the item, if applicable.","example":0},"taxable_amount":{"type":"number","description":"Taxable amount for the item.","example":90.16393442},"net_taxable_amount":{"type":"number","description":"Net taxable amount after discounts.","example":90.16393442},"vat_amount":{"type":"number","description":"VAT amount applied to the item.","example":19.83606558},"total_amount":{"type":"number","description":"Total amount for the item including VAT.","example":110},"unit_discount":{"type":"number","description":"Unit discount amount, expressed in EUR.","example":0},"sku":{"type":"string","description":"You can set a number that is assigned to a product for the purpose of inventory management and ease of tracking.","example":"product1"}}}},"cash_payment_amount":{"type":"number","description":"Cash payment amount in EUR.","example":100},"invoice_issuing":{"type":"boolean","description":"Flag for invoice issuance. Set to true for uncollected amounts invoiced at the end of the period.","example":false},"services_uncollected_amount":{"type":"number","description":"Uncollected amount in EUR for services.","example":0},"goods_uncollected_amount":{"type":"number","description":"Uncollected amount in EUR for delivered goods.","example":0},"electronic_payment_amount":{"type":"number","description":"Electronic payment amount in EUR.","example":0},"ticket_restaurant_payment_amount":{"type":"number","description":"Ticket restaurant payment amount in EUR.","example":0},"ticket_restaurant_quantity":{"type":"integer","description":"Number of Ticket Restaurants used.","example":0},"discount":{"type":"number","description":"Discount amount in EUR, applied at payment time but does not change the taxable amount.","example":0},"linked_receipt":{"type":"string","description":"Linked receipt reference, if applicable.","example":"string"},"lottery_code":{"type":"string","description":"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\"","example":null},"created_at":{"type":"string","description":"Timestamp when the document was created.","example":"2025-01-31T14:08:20.000Z"},"error_message":{"type":"string","description":"The error message in case the communication with the Tax Authority failed.","example":null},"error_code":{"type":"string","description":"The error code in case the communication with the Tax Authority failed.","example":null},"total_amount":{"type":"number","description":"Total amount for the receipt, including VAT.","example":110},"document_number":{"type":"string","description":"The document number assigned to the receipt by the Tax Authority.","example":"OPENAPI2025/0000-4706"},"document_date":{"type":"string","description":"The date of the document issuance.","example":"2025-01-31T14:08:28.000Z"},"transaction_id":{"type":"string","description":"The identifier assigned to the document by the Tax Authority.","example":"4706"},"create_timestamp":{"type":"integer","description":"Timestamp for when the document was created, in Unix format.","example":1738332500},"status":{"type":"string","description":"Current status of the document.","enum":["new","retry","submitted","ready","failed","voided"],"example":"ready"},"type":{"type":"string","description":"Type of document issued.","enum":["sale","return","void"],"example":"sale"},"deductible_amount":{"type":"number","description":"Deductible amount for the receipt, if applicable.","example":0},"total_discount":{"type":"number","description":"Total discount applied to the document.","example":0},"total_gross_discount":{"type":"number","description":"Total gross discount applied to the document.","example":0},"total_taxable_amount":{"type":"number","description":"Total taxable amount for the document, before VAT.","example":90.16393442},"total_uncollected_amount":{"type":"number","description":"Total uncollected amount for the document.","example":0},"total_vat_amount":{"type":"number","description":"Total VAT amount for the document.","example":19.83606558},"update_timestamp":{"type":"integer","description":"Timestamp for when the document was last updated, in Unix format.","example":1738332518},"id":{"type":"string","description":"Unique identifier for the document.","example":"679c**********1111111111"}}},"ResponseReceiptsPdf":{"type":"string","description":"When the Content-Type header is set to application/pdf, the API returns the receipt as a downloadable PDF file instead of the default JSON response.","example":"download PDF"},"ResponseReturnReceipt":{"type":"object","properties":{"data":{"type":"object","properties":{"fiscal_id":{"type":"string","description":"The VAT number of the company that issued the return receipt, without the country prefix.","example":"YourCompanyFiscal_id"},"items":{"type":"array","description":"List of items in the return receipt.","items":{"type":"object"}},"cash_payment_amount":{"type":"number","description":"Cash payment amount in EUR for the return receipt.","example":0},"id":{"type":"string","description":"Unique identifier for the return receipt.","example":"112ss95***************2"},"invoice_issuing":{"type":"boolean","description":"Flag for invoice issuance. Set to true for uncollected amounts invoiced at the end of the period.","example":false},"services_uncollected_amount":{"type":"number","description":"Uncollected amount in EUR for services in the return receipt.","example":0},"goods_uncollected_amount":{"type":"number","description":"Uncollected amount in EUR for returned goods.","example":0},"electronic_payment_amount":{"type":"number","description":"Electronic payment amount in EUR for the return receipt.","example":0},"ticket_restaurant_payment_amount":{"type":"number","description":"Ticket restaurant payment amount in EUR for the return receipt.","example":0},"ticket_restaurant_quantity":{"type":"integer","description":"Number of Ticket Restaurants used in the return receipt.","example":0},"discount":{"type":"number","description":"Discount amount in EUR, applied at return time but does not change the taxable amount.","example":0},"linked_receipt":{"type":"string","description":"Linked receipt reference, if applicable. This would be the original receipt from which the return was made.","example":null},"lottery_code":{"type":"string","description":"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\"","example":null},"created_at":{"type":"string","description":"Timestamp when the return receipt was created.","example":"2025-01-31T16:29:52.000Z"},"error_message":{"type":"string","description":"The error message in case the communication with the Tax Authority failed.","example":null},"error_code":{"type":"string","description":"The error code in case the communication with the Tax Authority failed.","example":null},"total_amount":{"type":"number","description":"Total amount for the return receipt, including VAT.","example":null},"document_number":{"type":"string","description":"The document number assigned to the return receipt by the Tax Authority.","example":""},"document_date":{"type":"string","description":"The date of the return receipt issuance.","example":null},"transaction_id":{"type":"string","description":"The identifier assigned to the return receipt by the Tax Authority.","example":null},"create_timestamp":{"type":"integer","description":"Timestamp for when the return receipt was created, in Unix format.","example":1738340991},"parent_receipt_id":{"type":"string","description":"ID of the original receipt to which this return is linked.","example":"679cf5377be****b540a2b52"},"status":{"type":"string","description":"Current status of the return receipt.","enum":["new","retry","submitted","ready","failed","voided"],"example":"new"},"type":{"type":"string","description":"Type of document issued, in this case, 'return'.","enum":["sale","return","void"],"example":"return"},"deductible_amount":{"type":"number","description":"Deductible amount for the return receipt, if applicable.","example":0},"total_discount":{"type":"number","description":"Total discount applied to the return receipt.","example":0},"total_gross_discount":{"type":"number","description":"Total gross discount applied to the return receipt.","example":0},"total_taxable_amount":{"type":"number","description":"Total taxable amount for the return receipt, before VAT.","example":0},"total_uncollected_amount":{"type":"number","description":"Total uncollected amount for the return receipt.","example":0},"total_vat_amount":{"type":"number","description":"Total VAT amount for the return receipt.","example":0},"update_timestamp":{"type":"integer","description":"Timestamp for when the return receipt was last updated, in Unix format.","example":1738341000},"tags":{"type":"array","description":"You can insert details for you receipt.","items":{"type":"object"},"example":["store1","store2"]}}}}},"ResponseVoidReceipt":{"type":"object","properties":{"data":{"type":"object","properties":{"fiscal_id":{"type":"string","description":"The VAT number of the company that issued the return receipt, without the country prefix.","example":"YourCompanyFiscal_id"},"items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the item.","example":"'200170'"},"quantity":{"type":"number","description":"Quantity of the item, expressed with 2 decimal digits.","example":10},"description":{"type":"string","description":"Description of the item.","example":"product"},"gross_price":{"type":"number","description":"Gross price of the item, including VAT.","example":10},"vat_rate":{"type":"string","description":"VAT rate code for the item.","enum":["4","5","10","22","2","6.4","7","7.3","7.5","7.65","7.95","8.3","8.5","8.8","9.5","12.3","N1","N2","N3","N4","N5","N6"],"example":"'22'"},"gross_discount":{"type":"number","description":"Gross discount applied to the item.","example":0},"complimentary":{"type":"boolean","description":"Set to true if the item is complimentary (free).","example":true},"unit_price":{"type":"number","description":"Unit price of the item, expressed with up to 8 decimal digits.","example":8.19672131},"return":{"type":"number","description":"Return amount for the item, if applicable.","example":0},"taxable_amount":{"type":"number","description":"Taxable amount for the item.","example":90.16393442},"net_taxable_amount":{"type":"number","description":"Net taxable amount after discounts.","example":90.16393442},"vat_amount":{"type":"number","description":"VAT amount applied to the item.","example":19.83606558},"total_amount":{"type":"number","description":"Total amount for the item including VAT.","example":110},"unit_discount":{"type":"number","description":"Unit discount amount, expressed in EUR.","example":0},"sku":{"type":"string","description":"You can set a number that is assigned to a product for the purpose of inventory management and ease of tracking.","example":"product1"}}},"cash_payment_amount":{"type":"number","description":"Cash payment amount in EUR for the return receipt.","example":4.5},"id":{"type":"string","description":"Unique identifier for the return receipt.","example":"6b7****************03b8d2"},"invoice_issuing":{"type":"boolean","description":"Flag for invoice issuance. Set to true for uncollected amounts invoiced at the end of the period.","example":false},"services_uncollected_amount":{"type":"number","description":"Uncollected amount in EUR for services in the return receipt.","example":0},"goods_uncollected_amount":{"type":"number","description":"Uncollected amount in EUR for returned goods.","example":0},"electronic_payment_amount":{"type":"number","description":"Electronic payment amount in EUR for the return receipt.","example":0},"ticket_restaurant_payment_amount":{"type":"number","description":"Ticket restaurant payment amount in EUR for the return receipt.","example":0},"ticket_restaurant_quantity":{"type":"integer","description":"Number of Ticket Restaurants used in the return receipt.","example":0},"discount":{"type":"number","description":"Discount amount in EUR, applied at return time but does not change the taxable amount.","example":0},"linked_receipt":{"type":"string","description":"Linked receipt reference, if applicable. This would be the original receipt from which the return was made.","example":null},"lottery_code":{"type":"string","description":"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\"","example":null},"created_at":{"type":"string","description":"Timestamp when the return receipt was created.","example":"2025-01-31T16:29:52.000Z"},"error_message":{"type":"string","description":"The error message in case the communication with the Tax Authority failed.","example":null},"error_code":{"type":"string","description":"The error code in case the communication with the Tax Authority failed.","example":null},"total_amount":{"type":"number","description":"Total amount for the return receipt, including VAT.","example":null},"document_number":{"type":"string","description":"The document number assigned to the return receipt by the Tax Authority.","example":""},"document_date":{"type":"string","description":"The date of the return receipt issuance.","example":null},"transaction_id":{"type":"string","description":"The identifier assigned to the return receipt by the Tax Authority.","example":null},"create_timestamp":{"type":"integer","description":"Timestamp for when the return receipt was created, in Unix format.","example":1738340991},"parent_receipt_id":{"type":"string","description":"ID of the original receipt to which this return is linked.","example":"6a9**************d077b23"},"status":{"type":"string","description":"Current status of the voided receipt.","enum":["new","retry","submitted","ready","failed","voided"],"example":"new"},"type":{"type":"string","description":"Type of document issued, in this case, 'void'.","enum":["sale","return","void"],"example":"void"},"deductible_amount":{"type":"number","description":"Deductible amount for the return receipt, if applicable.","example":0},"total_discount":{"type":"number","description":"Total discount applied to the return receipt.","example":0},"total_gross_discount":{"type":"number","description":"Total gross discount applied to the return receipt.","example":0},"total_taxable_amount":{"type":"number","description":"Total taxable amount for the return receipt, before VAT.","example":0},"total_uncollected_amount":{"type":"number","description":"Total uncollected amount for the return receipt.","example":0},"total_vat_amount":{"type":"number","description":"Total VAT amount for the return receipt.","example":0},"update_timestamp":{"type":"integer","description":"Timestamp for when the return receipt was last updated, in Unix format.","example":1738341000},"tags":{"description":"You can insert details for you receipt.","example":null}}},"message":{"type":"string","description":"Confirmation message for the voided receipt.","example":"voided receipt: 6a9**************d077b23"},"success":{"type":"boolean","description":"Indicates whether the void operation was successful.","example":true},"error":{"type":"string","nullable":true,"description":"Error message in case of failure, null if successful.","example":null}}},"ResponseVoidReceiptCallback":{"type":"object","properties":{"data":{"type":"object","properties":{"fiscal_id":{"type":"string","description":"The VAT number of the company that issued the return receipt, without the country prefix.","example":"YourCompanyFiscal_id"},"items":{"type":"array","description":"List of items in the return receipt.","items":{"type":"object","properties":{"quantity":{"type":"number","description":"Quantity of the returned item, expressed with 2 decimal digits.","example":11},"description":{"type":"string","description":"Description of the returned item.","example":"test ultimate"},"unit_price":{"type":"number","description":"Unit price of the returned item, expressed with up to 8 decimal digits.","example":8.19672131},"vat_rate_code":{"type":"string","description":"VAT rate code for the returned item.","example":"22"},"complimentary":{"type":"boolean","description":"Set to true if the item is complimentary (free).","example":true}}}},"cash_payment_amount":{"type":"number","description":"Cash payment amount in EUR for the return receipt.","example":4.5},"id":{"type":"string","description":"Unique identifier for the return receipt.","example":"6a9**************d077b23"},"invoice_issuing":{"type":"boolean","description":"Flag for invoice issuance. Set to true for uncollected amounts invoiced at the end of the period.","example":false},"services_uncollected_amount":{"type":"number","description":"Uncollected amount in EUR for services in the return receipt.","example":0},"goods_uncollected_amount":{"type":"number","description":"Uncollected amount in EUR for returned goods.","example":0},"electronic_payment_amount":{"type":"number","description":"Electronic payment amount in EUR for the return receipt.","example":0},"ticket_restaurant_payment_amount":{"type":"number","description":"Ticket restaurant payment amount in EUR for the return receipt.","example":0},"ticket_restaurant_quantity":{"type":"integer","description":"Number of Ticket Restaurants used in the return receipt.","example":0},"discount":{"type":"number","description":"Discount amount in EUR, applied at return time but does not change the taxable amount.","example":0},"linked_receipt":{"type":"string","description":"Linked receipt reference, if applicable. This would be the original receipt from which the return was made.","example":null},"lottery_code":{"type":"string","description":"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\"","example":null},"created_at":{"type":"string","description":"Timestamp when the return receipt was created.","example":"2025-01-31T16:29:52.000Z"},"error_message":{"type":"string","description":"The error message in case the communication with the Tax Authority failed.","example":null},"error_code":{"type":"string","description":"The error code in case the communication with the Tax Authority failed.","example":null},"total_amount":{"type":"number","description":"Total amount for the return receipt, including VAT.","example":null},"document_number":{"type":"string","description":"The document number assigned to the return receipt by the Tax Authority.","example":""},"document_date":{"type":"string","description":"The date of the return receipt issuance.","example":null},"transaction_id":{"type":"string","description":"The identifier assigned to the return receipt by the Tax Authority.","example":null},"create_timestamp":{"type":"integer","description":"Timestamp for when the return receipt was created, in Unix format.","example":1738340991},"parent_receipt_id":{"type":"string","description":"ID of the original receipt to which this voided is linked.","example":"679ca42e**********016f18"},"status":{"type":"string","description":"Current status of the return receipt.","enum":["new","retry","submitted","ready","failed","voided"],"example":"new"},"type":{"type":"string","description":"Type of document issued, in this case, 'return'.","enum":["sale","return","void"],"example":"return"},"deductible_amount":{"type":"number","description":"Deductible amount for the return receipt, if applicable.","example":0},"total_discount":{"type":"number","description":"Total discount applied to the return receipt.","example":0},"total_gross_discount":{"type":"number","description":"Total gross discount applied to the return receipt.","example":0},"total_taxable_amount":{"type":"number","description":"Total taxable amount for the return receipt, before VAT.","example":0},"total_uncollected_amount":{"type":"number","description":"Total uncollected amount for the return receipt.","example":0},"total_vat_amount":{"type":"number","description":"Total VAT amount for the return receipt.","example":0},"update_timestamp":{"type":"integer","description":"Timestamp for when the return receipt was last updated, in Unix format.","example":1738341000},"tags":{"type":"array","description":"You can insert details for you receipt.","items":{"type":"object","example":["store1","store2"]}},"custom":{"type":"object","description":"Custom fields for the return receipt, if any.","example":null}}}}},"ResponseReturnReceiptCallback":{"type":"object","properties":{"data":{"type":"object","properties":{"fiscal_id":{"type":"string","description":"The VAT number of the company that issued the return receipt, without the country prefix.","example":"YourCompanyFiscal_id"},"items":{"type":"array","description":"List of items in the return receipt.","items":{"type":"object","properties":{"quantity":{"type":"number","description":"Quantity of the returned item, expressed with 2 decimal digits.","example":11},"description":{"type":"string","description":"Description of the returned item.","example":"test ultimate"},"unit_price":{"type":"number","description":"Unit price of the returned item, expressed with up to 8 decimal digits.","example":8.19672131},"vat_rate_code":{"type":"string","description":"VAT rate code for the returned item.","example":"22"},"complimentary":{"type":"boolean","description":"Set to true if the item is complimentary (free).","example":true},"sku":{"type":"string","description":"You can set a number that is assigned to a product for the purpose of inventory management and ease of tracking.","example":"product1"}}}},"cash_payment_amount":{"type":"number","description":"Cash payment amount in EUR for the return receipt.","example":4.5},"id":{"type":"string","description":"Unique identifier for the return receipt.","example":"679cfa81a4e83682b7097b92"},"invoice_issuing":{"type":"boolean","description":"Flag for invoice issuance. Set to true for uncollected amounts invoiced at the end of the period.","example":false},"services_uncollected_amount":{"type":"number","description":"Uncollected amount in EUR for services in the return receipt.","example":0},"goods_uncollected_amount":{"type":"number","description":"Uncollected amount in EUR for returned goods.","example":0},"electronic_payment_amount":{"type":"number","description":"Electronic payment amount in EUR for the return receipt.","example":0},"ticket_restaurant_payment_amount":{"type":"number","description":"Ticket restaurant payment amount in EUR for the return receipt.","example":0},"ticket_restaurant_quantity":{"type":"integer","description":"Number of Ticket Restaurants used in the return receipt.","example":0},"discount":{"type":"number","description":"Discount amount in EUR, applied at return time but does not change the taxable amount.","example":0},"linked_receipt":{"type":"string","description":"Linked receipt reference, if applicable. This would be the original receipt from which the return was made.","example":null},"lottery_code":{"type":"string","description":"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\"","example":null},"created_at":{"type":"string","description":"Timestamp when the return receipt was created.","example":"2025-01-31T16:29:52.000Z"},"error_message":{"type":"string","description":"The error message in case the communication with the Tax Authority failed.","example":null},"error_code":{"type":"string","description":"The error code in case the communication with the Tax Authority failed.","example":null},"total_amount":{"type":"number","description":"Total amount for the return receipt, including VAT.","example":null},"document_number":{"type":"string","description":"The document number assigned to the return receipt by the Tax Authority.","example":""},"document_date":{"type":"string","description":"The date of the return receipt issuance.","example":null},"transaction_id":{"type":"string","description":"The identifier assigned to the return receipt by the Tax Authority.","example":null},"create_timestamp":{"type":"integer","description":"Timestamp for when the return receipt was created, in Unix format.","example":1738340991},"parent_receipt_id":{"type":"string","description":"ID of the original receipt to which this return is linked.","example":"679ca42e**********016f18"},"status":{"type":"string","description":"Current status of the return receipt.","enum":["new","retry","submitted","ready","failed","voided"],"example":"new"},"type":{"type":"string","description":"Type of document issued, in this case, 'return'.","enum":["sale","return","void"],"example":"return"},"deductible_amount":{"type":"number","description":"Deductible amount for the return receipt, if applicable.","example":0},"total_discount":{"type":"number","description":"Total discount applied to the return receipt.","example":0},"total_gross_discount":{"type":"number","description":"Total gross discount applied to the return receipt.","example":0},"total_taxable_amount":{"type":"number","description":"Total taxable amount for the return receipt, before VAT.","example":0},"total_uncollected_amount":{"type":"number","description":"Total uncollected amount for the return receipt.","example":0},"total_vat_amount":{"type":"number","description":"Total VAT amount for the return receipt.","example":0},"update_timestamp":{"type":"integer","description":"Timestamp for when the return receipt was last updated, in Unix format.","example":1738341000},"tags":{"type":"array","description":"You can insert details for you receipt.","items":{"type":"object","example":["store1","store2"]}},"custom":{"type":"object","description":"Custom fields for the return receipt, if any.","example":null}}}}}}},"paths":{"/IT-invoices":{"get":{"tags":["IT-invoice"],"summary":"Retrieve all IT-invoices.","description":"Retrieve a list of IT invoices with optional filtering and pagination. \n\nUsers can filter results by `fiscal_id`, `state`, `direction`, `type`, `document_number`, and `issue_date`.\n\nPagination options include `skip` to specify the number of records to omit and `limit` to define the maximum number of records returned (capped at 100).\n\n`fiscal_id`, `state`, and `direction` support multiple values by separating them with a comma.\n\n`issue_date` must follow the YYYY-MM-DD format.\n\nThis endpoint returns a structured JSON response containing the matching invoices.","parameters":[{"name":"fiscal_id","in":"query","description":"Filter invoices by fiscal ID.","schema":{"type":"string"}},{"name":"document_number","in":"query","description":"Filter invoices by document number.","schema":{"type":"string"}},{"name":"state","in":"query","description":"Filter invoices by state. Multiple values can be provided, separated by commas.","schema":{"type":"array","items":{"type":"string","enum":["NEW","SENT","RECEIVED","DONE","ERROR"]}},"style":"form","explode":false},{"name":"direction","in":"query","description":"Filter invoices by direction. Multiple values can be provided, separated by commas.","schema":{"type":"array","items":{"type":"string","enum":["incoming","outgoing"]}},"style":"form","explode":false},{"name":"type","in":"query","description":"Filter invoices by type (e.g., TD01).","schema":{"type":"string"}},{"name":"issue_date","in":"query","description":"Filter invoices by issue date (YYYY-MM-DD format).\nYou can also filter for documents before or after a specific date using parameters:\n- issue_date[before]=YYYY-MM-DD (for documents before the specified date)\n- issue_date[after]=YYYY-MM-DD (for documents after the specified date)\n","schema":{"type":"string","format":"date"}},{"name":"skip","in":"query","description":"Number of records to skip for pagination.","schema":{"type":"integer","minimum":0}},{"name":"limit","in":"query","description":"Number of records to return (max 100).","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"List of IT-invoices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITInvoiceResponseArray"}}}}}},"post":{"tags":["IT-invoice"],"summary":"Create/Send an invoice.","description":"Send an electronic invoice (XML format) to the SDI.\n\n**Requirements**:\nTo use this service, you must enable the `customer_invoice` option in your `IT-configuration`.\n\n**Invoice Flow and Notification States**:\nAfter submission, the system sends a **Webhook notification** to your configured endpoint at every status change. The main states you will receive are:\n* **NEW**: Invoice created system-side.\n* **SENT**: Invoice transmitted to the SDI (intermediary state).\n* **RECEIVED**: Used exclusively for the passive invoice flow (inbound invoices).\n* **ERROR**: **Final State** indicating a transmission failure or rejection (triggered by `ERROR` or `REJECTED` SDI statuses).\n* **DONE**: **Final State** indicating the process was completed successfully (triggered by `DELIVERED`, `ACCEPTED`, `TERMS_EXPIRED`, or `NOT_DELIVERED` SDI statuses).\n\n**SDI Status Details (`details.sdi_status`)**:\nThe `details.sdi_status` field in the notification payload provides the video technical status from the Revenue Agency:\n* **BOOKED**: The invoice is queued and waiting to be processed.\n* **SENT**: The invoice has been successfully forwarded to the SDI.\n* **DELIVERED**: The invoice has been successfully delivered to the recipient's digital address. **Final State**\n* **NOT_DELIVERED**: The invoice is available in the recipient's Tax Portal (*Cassetto Fiscale*) because the digital address was unreachable or missing. **Final State**\n* **RECEIVED**: Technical status identifying an incoming (passive) invoice. **Final State**\n* **ACCEPTED**: (PA only) The Public Administration has formally accepted the invoice. **Final State**\n* **REJECTED**: (PA only) The Public Administration has rejected the invoice. **Final State**\n* **TERMS_EXPIRED**: (PA only) The 15-day period for PA acceptance has passed; the invoice is now legally considered accepted. **Final State**\n* **ERROR**: The SDI rejected the file due to formal or validation errors. **Final State**\n\n**Special Case: PA Invoices**:\nFor invoices addressed to the **Public Administration (FPA12)**, the status **DELIVERED** is **not final**. The system will keep the invoice in the **SENT** state until a formal response is received (**ACCEPTED**, **REJECTED**, or **TERMS_EXPIRED**). Only these outcomes will trigger the final **DONE** or **ERROR** state.\n\n**Sandbox Environment & Timing**:\n* **Processing Time**: In both test and production, the status transitions from **BOOKED** to **SENT** within 60 seconds.\n* **Webhook Notifications**: Webhooks are triggered every 60 seconds. Expect a total delay of approximately 120 seconds from the initial booking to receive the first notification.\n\n**Digital Signature & PA Invoices**:\n* **Mandatory Signing**: Invoices addressed to the **Public Administration (FPA12)** MUST be digitally signed.\n* **Automatic Signing**: Openapi applies its digital signature automatically if no custom credentials are provided.\n* **Custom Signing**: Provide your own certificate credentials in the request headers if you wish to use a custom signature.\n\n**Price esignature**: The invoice is signed via our signing system using EU-QES_automatic. Any applicable costs or subscriptions are automatically deducted if the service is active for your account. You can view the full signature details by clicking [EU-QES_automatic](https://console.openapi.com/it/apis/esignature/documentation#scope=POST:esignature.openapi.com/EU-QES_automatic) \n\n**Reliability & SDI Availability**:\nIn the rare event of SDI temporary unavailability, the system will automatically retry the transmission after 5 minutes, then 10, then 15, and so on.\n\n**Note**: The `DatiTrasmissione` block in the uploaded XML will be automatically updated by our system to ensure correct routing.","parameters":[{"name":"X-Signature-User","in":"header","description":"Your digital signature service username. Required only for custom signing.","required":false,"schema":{"type":"string"}},{"name":"X-Signature-Password","in":"header","description":"Your digital signature service password. Required only for custom signing.","required":false,"schema":{"type":"string"}}],"callbacks":{"callback":{"{your_url}":{"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceResponse"},"examples":{"SENT":{"description":"Status **SENT**: The outgoing invoice has been successfully transmitted to the SDI (Sistema di Interscambio). It is now being processed or has been delivered to the recipient.\n\n- **Direction**: outgoing\n- **Technical Context**: Matches `sdi_status` like 'SENT'.","value":{"data":{"id":"697b0f1234dc0831bb0xxxx1","state":"SENT","direction":"outgoing","document_number":"101/2026","currency":"EUR","total_amount_excluding_tax":100,"total_tax_amount":22,"total_amount_including_tax":122,"total_payable_amount":122,"type":"TD01","invoice_lines":[{"description":"Example Product","quantity":1,"unit_of_measure":"Pezzo","nature":null,"unit_price":100,"total_net_amount":100,"tax_rate":22,"discounts":[],"item_code":"P01"}],"payment_means":[{"payment_mode":"MP05","due_date":"2026-03-11","amount":122,"financial_account":"IT00X0000000000000000000000"}],"transmission_id":"1","details":{"sdi_id":"12345678","sdi_filename":"IT01234567890_00001.xml","sdi_status":"SENT","sdi_message":"Ricevuta di consegna","sdi_update_date":"2026-02-11 10:00:00","invoice_date":"2026-02-11"},"sender":{"name":"My Business SpA","vat_id":"IT01234567890","tax_code":"01234567890","street":"Via Roma, 1","zip":"00100","city":"Roma","province":"RM","country_code":"IT","phone":null,"email":"billing@mybusiness.it"},"recipient":{"name":"Customer Srl","vat_id":"IT09876543210","tax_code":"09876543210","street":"Via Milano, 10","zip":"20100","city":"Milano","province":"MI","country_code":"IT","phone":null,"email":null},"create_at":"2026-02-11 09:00:00 +00:00","updated_at":"2026-02-11 10:00:00 +00:00"}}},"RECEIVED":{"description":"Status **RECEIVED**: A passive (incoming) invoice from a supplier has been received by the platform and is available for your company.\n\n- **Direction**: incoming\n- **Technical Context**: Triggers when a supplier sends an invoice to your Recipient Code (PIC7CPS).","value":{"data":{"id":"697b0f5678dc0831bb0xxxx2","state":"RECEIVED","direction":"incoming","document_number":"SUP-2026-01","currency":"EUR","total_amount_excluding_tax":500,"total_tax_amount":110,"total_amount_including_tax":610,"total_payable_amount":610,"type":"TD01","invoice_lines":[{"description":"Consulting Services","quantity":1,"unit_of_measure":"H","nature":null,"unit_price":500,"total_net_amount":500,"tax_rate":22,"discounts":[{"type":"SC","percentage":10,"amount":50}],"item_code":"S01"}],"payment_means":[],"transmission_id":"99","details":{"sdi_id":"87654321","sdi_filename":"IT09876543210_55555.xml","sdi_status":"","sdi_message":"","sdi_update_date":"2026-02-11 11:00:00","invoice_date":"2026-02-10"},"sender":{"name":"Supplier Inc","vat_id":"IT09876543210","tax_code":"09876543210","street":"Industrial Way, 5","zip":"50100","city":"Firenze","province":"FI","country_code":"IT","phone":null,"email":null},"recipient":{"name":"My Business SpA","vat_id":"IT01234567890","tax_code":"01234567890","street":"Via Roma, 1","zip":"00100","city":"Roma","province":"RM","country_code":"IT","phone":null,"email":"billing@mybusiness.it"},"create_at":"2026-02-11 11:05:00 +00:00","updated_at":"2026-02-11 11:05:00 +00:00"}}},"ERROR":{"description":"Status **ERROR**: The transmission to the SDI failed or the invoice was rejected by the tax authority due to formal errors (Scarto).\n\n- **Direction**: outgoing\n- **Technical Context**: Matches `sdi_status` like 'REJECTED' or 'ERROR'. See `sdi_message` for error details.","value":{"data":{"id":"697b0f9012dc0831bb0xxxx3","state":"ERROR","direction":"outgoing","document_number":"102/2026","currency":"EUR","total_amount_excluding_tax":200,"total_tax_amount":44,"total_amount_including_tax":244,"total_payable_amount":244,"type":"TD01","invoice_lines":[{"description":"Consulting Services","quantity":1,"unit_of_measure":"H","nature":null,"unit_price":500,"total_net_amount":500,"tax_rate":22,"discounts":[],"item_code":"S01"}],"payment_means":[{"payment_mode":"MP05","due_date":"2026-03-11","amount":122,"financial_account":"IT00X0000000000000000000000"}],"transmission_id":"2","details":{"sdi_id":"12345000","sdi_filename":"IT01234567890_00002.xml","sdi_status":"REJECTED","sdi_message":"Errore 00404: Fattura duplicata","sdi_update_date":"2026-02-11 11:30:00","invoice_date":"2026-02-11"},"sender":{"name":"Supplier Inc","vat_id":"IT09876543210","tax_code":"09876543210","street":"Industrial Way, 5","zip":"50100","city":"Firenze","province":"FI","country_code":"IT","phone":null,"email":null},"recipient":{"name":"My Business SpA","vat_id":"IT01234567890","tax_code":"01234567890","street":"Via Roma, 1","zip":"00100","city":"Roma","province":"RM","country_code":"IT","phone":null,"email":"billing@mybusiness.it"},"create_at":"2026-02-11 11:05:00 +00:00","updated_at":"2026-02-11 11:05:00 +00:00"}}},"DONE":{"description":"Status **DONE**: The transmission process is considered complete. For outgoing invoices, this often corresponds to 'NOT_DELIVERED','RECEIVED', 'ACCEPTED',  'TERMS_EXPIRED'.\n\n- **Direction**: outgoing\n- **Technical Context**: Indicates no further statuses are expected for this invoice from SDI.","value":{"data":{"id":"697b0f3456dc0831bb0xxxx4","state":"DONE","direction":"outgoing","document_number":"099/2026","currency":"EUR","total_amount_excluding_tax":300,"total_tax_amount":66,"total_amount_including_tax":366,"total_payable_amount":366,"type":"TD01","invoice_lines":[{"description":"Consulting Services","quantity":1,"unit_of_measure":"H","nature":null,"unit_price":500,"total_net_amount":500,"tax_rate":22,"discounts":[],"item_code":"S01"}],"payment_means":[{"payment_mode":"MP05","due_date":"2026-03-11","amount":122,"financial_account":"IT00X0000000000000000000000"}],"transmission_id":"0","details":{"sdi_id":"11112222","sdi_filename":"IT01234567890_99999.xml","sdi_status":"TERMS_EXPIRED","sdi_message":"Processo completato per decorrenza termini","sdi_update_date":"2026-02-10 15:00:00","invoice_date":"2026-01-20"},"sender":{"name":"Supplier Inc","vat_id":"IT09876543210","tax_code":"09876543210","street":"Industrial Way, 5","zip":"50100","city":"Firenze","province":"FI","country_code":"IT","phone":null,"email":null},"recipient":{"name":"My Business SpA","vat_id":"IT01234567890","tax_code":"01234567890","street":"Via Roma, 1","zip":"00100","city":"Roma","province":"RM","country_code":"IT","phone":null,"email":"billing@mybusiness.it"},"create_at":"2026-02-11 11:05:00 +00:00","updated_at":"2026-02-11 11:05:00 +00:00"}}}}}}},"responses":{"200":{"description":"ok"}}}}}},"requestBody":{"required":true,"content":{"application/xml":{"schema":{"type":"object","xml":{"name":"FatturaElettronica"},"description":"The XML file content of the invoice."},"examples":{"FatturaEsempio":{"summary":"Exemple Invoice TD01","value":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<p:FatturaElettronica xmlns:p=\"http://ivaservizi.agenziaentrate.gov.it/docs/xsd/fatture/v1.2\" xmlns:ds=\"http://www.w3.org/2000/09/xmldsig#\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:schemaLocation=\"http://ivaservizi.agenziaentrate.gov.it/docs/xsd/fatture/v1.2 http://www.fatturapa.gov.it/export/fatturazione/sdi/fatturapa/v1.2/Schema_del_file_xml_FatturaPA_versione_1.2.xsd\" versione=\"FPR12\">\n  <FatturaElettronicaHeader>\n    <DatiTrasmissione>\n      <IdTrasmittente>\n        <IdPaese>IT</IdPaese>\n        <IdCodice>CODICE_TRASMITTENTE_ANONIMO</IdCodice>\n      </IdTrasmittente>\n      <ProgressivoInvio>12</ProgressivoInvio>\n      <FormatoTrasmissione>FPR12</FormatoTrasmissione>\n      <CodiceDestinatario>0000000</CodiceDestinatario>\n      <ContattiTrasmittente>\n        <Email>info@openapi.com</Email>\n      </ContattiTrasmittente>\n    </DatiTrasmissione>\n    <CedentePrestatore>\n      <DatiAnagrafici>\n        <IdFiscaleIVA>\n          <IdPaese>IT</IdPaese>\n          <IdCodice>PIVA_MITTENTE_ANONIMO</IdCodice>\n        </IdFiscaleIVA>\n        <CodiceFiscale>CODICE_FISCALE_ANONIMO</CodiceFiscale>\n        <Anagrafica>\n          <Denominazione>Openapi SpA</Denominazione>\n        </Anagrafica>\n        <RegimeFiscale>RF01</RegimeFiscale>\n      </DatiAnagrafici>\n      <Sede>\n        <Indirizzo>Viale Filippo Tommaso Marinetti, 221</Indirizzo>\n        <CAP>00143</CAP>\n        <Comune>Roma</Comune>\n        <Provincia>RM</Provincia>\n        <Nazione>IT</Nazione>\n      </Sede>\n      <IscrizioneREA>\n        <Ufficio>RM</Ufficio>\n        <NumeroREA>1377241</NumeroREA>\n        <CapitaleSociale>10000.00</CapitaleSociale>\n        <SocioUnico>SM</SocioUnico>\n        <StatoLiquidazione>LN</StatoLiquidazione>\n      </IscrizioneREA>\n    </CedentePrestatore>\n    <CessionarioCommittente>\n      <DatiAnagrafici>\n        <IdFiscaleIVA>\n          <IdPaese>IT</IdPaese>\n          <IdCodice>PIVA_CLIENTE_ANONIMO</IdCodice>\n        </IdFiscaleIVA>\n        <Anagrafica>\n          <Denominazione>O.M.Z. Srl</Denominazione>\n        </Anagrafica>\n      </DatiAnagrafici>\n      <Sede>\n        <Indirizzo>Via N. Strampelli, 22</Indirizzo>\n        <CAP>00040</CAP>\n        <Comune>Ardea</Comune>\n        <Provincia>RM</Provincia>\n        <Nazione>IT</Nazione>\n      </Sede>\n    </CessionarioCommittente>\n  </FatturaElettronicaHeader>\n  <FatturaElettronicaBody>\n    <DatiGenerali>\n      <DatiGeneraliDocumento>\n        <TipoDocumento>TD01</TipoDocumento>\n        <Divisa>EUR</Divisa>\n        <Data>2025-10-01</Data>\n        <Numero>1637/2025</Numero>\n        <ImportoTotaleDocumento>307.44</ImportoTotaleDocumento>\n        <Causale>Periodo fatturazione: 01/10/2025 - 30/09/2026 Rif. Ord. 257 del 01/10/2025</Causale>\n      </DatiGeneraliDocumento>\n      <DatiOrdineAcquisto>\n        <IdDocumento>257</IdDocumento>\n        <Data>2025-10-01</Data>\n      </DatiOrdineAcquisto>\n    </DatiGenerali>\n    <DatiBeniServizi>\n      <DettaglioLinee>\n        <NumeroLinea>1</NumeroLinea>\n        <Descrizione>Hosting gestito professionale</Descrizione>\n        <Quantita>1.00</Quantita>\n        <PrezzoUnitario>120.00</PrezzoUnitario>\n        <PrezzoTotale>120.00</PrezzoTotale>\n        <AliquotaIVA>22.00</AliquotaIVA>\n      </DettaglioLinee>\n      <DatiRiepilogo>\n        <AliquotaIVA>22.00</AliquotaIVA>\n        <ImponibileImporto>252.00</ImponibileImporto>\n        <Imposta>55.44</Imposta>\n      </DatiRiepilogo>\n    </DatiBeniServizi>\n    <DatiPagamento>\n      <CondizioniPagamento>TP02</CondizioniPagamento>\n      <DettaglioPagamento>\n        <ModalitaPagamento>MP05</ModalitaPagamento>\n        <ImportoPagamento>307.44</ImportoPagamento>\n        <IBAN>IT00X0000000000000000000000</IBAN>\n      </DettaglioPagamento>\n    </DatiPagamento>\n  </FatturaElettronicaBody>\n</p:FatturaElettronica>"}}}}},"responses":{"200":{"description":"Invoice created/sent successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InvoiceResponse"}}}}}},"400":{"description":"Invalid input data","content":{"application/json":{"example":{"data":"null","success":false,"message":"Invalid XML structure","error":400}}}},"403":{"description":"Permission denied for this fiscal_id","content":{"application/json":{"example":{"data":"null","success":false,"message":"Unauthorized access","error":403}}}},"422":{"description":"Unproccessable Entity","content":{"application/json":{"example":{"data":"null","success":false,"message":"Validation Error: Missing required field","error":422}}}}}}},"/IT-invoices/{id}":{"get":{"tags":["IT-invoice"],"summary":"Retrieve a specific invoice.","description":"Retrieve the details of a specific invoice using its unique ID.","parameters":[{"name":"id","in":"path","required":true,"description":"The unique identifier of the invoice.","schema":{"type":"string"}}],"responses":{"200":{"description":"Invoice details.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InvoiceResponse"}}}}}},"404":{"description":"Invoice not found."}}}},"/IT-invoices_import":{"post":{"tags":["IT-invoice"],"summary":"Import external invoice.","description":"Import invoices that were sent/received via other systems. Accepts both raw XML and Base64 encoded XML formats. Automatically detects direction based on fiscal IDs. A duplicate check is performed based on SDI ID (if provided) and business keys (fiscal ID, document number, date, and direction).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceImportRequest"}}}},"responses":{"200":{"description":"Invoice imported successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InvoiceResponse"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid input data","content":{"application/json":{"example":{"data":"null","success":false,"message":"Invalid input data","error":400}}}},"403":{"description":"Permission denied for this fiscal_id","content":{"application/json":{"example":{"data":"null","success":false,"message":"Unauthorized access","error":403}}}},"404":{"description":"404 Not Found","content":{"application/json":{"example":{"data":"null","success":true,"message":"Fiscal ID not found or not registered","error":111}}}}}}},"/IT-invoices_validate":{"post":{"tags":["IT-invoice"],"summary":"Validate invoice structure.","description":"Validate the XML structure of an Italian electronic invoice according to official SDI (Sistema di Interscambio) XSD schemas. This endpoint performs structure and formal validation without actually transmitting the invoice.","requestBody":{"required":true,"content":{"application/xml":{"schema":{"type":"object","xml":{"name":"FatturaElettronica"},"description":"The XML file content of the invoice."},"examples":{"FatturaEsempio":{"summary":"Exemple Invoice TD01","value":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<p:FatturaElettronica xmlns:p=\"http://ivaservizi.agenziaentrate.gov.it/docs/xsd/fatture/v1.2\" xmlns:ds=\"http://www.w3.org/2000/09/xmldsig#\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xsi:schemaLocation=\"http://ivaservizi.agenziaentrate.gov.it/docs/xsd/fatture/v1.2 http://www.fatturapa.gov.it/export/fatturazione/sdi/fatturapa/v1.2/Schema_del_file_xml_FatturaPA_versione_1.2.xsd\" versione=\"FPR12\">\n  <FatturaElettronicaHeader>\n    <DatiTrasmissione>\n      <IdTrasmittente>\n        <IdPaese>IT</IdPaese>\n        <IdCodice>CODICE_TRASMITTENTE_ANONIMO</IdCodice>\n      </IdTrasmittente>\n      <ProgressivoInvio>12</ProgressivoInvio>\n      <FormatoTrasmissione>FPR12</FormatoTrasmissione>\n      <CodiceDestinatario>0000000</CodiceDestinatario>\n      <ContattiTrasmittente>\n        <Email>info@openapi.com</Email>\n      </ContattiTrasmittente>\n    </DatiTrasmissione>\n    <CedentePrestatore>\n      <DatiAnagrafici>\n        <IdFiscaleIVA>\n          <IdPaese>IT</IdPaese>\n          <IdCodice>PIVA_MITTENTE_ANONIMO</IdCodice>\n        </IdFiscaleIVA>\n        <CodiceFiscale>CODICE_FISCALE_ANONIMO</CodiceFiscale>\n        <Anagrafica>\n          <Denominazione>Openapi SpA</Denominazione>\n        </Anagrafica>\n        <RegimeFiscale>RF01</RegimeFiscale>\n      </DatiAnagrafici>\n      <Sede>\n        <Indirizzo>Viale Filippo Tommaso Marinetti, 221</Indirizzo>\n        <CAP>00143</CAP>\n        <Comune>Roma</Comune>\n        <Provincia>RM</Provincia>\n        <Nazione>IT</Nazione>\n      </Sede>\n      <IscrizioneREA>\n        <Ufficio>RM</Ufficio>\n        <NumeroREA>1377241</NumeroREA>\n        <CapitaleSociale>10000.00</CapitaleSociale>\n        <SocioUnico>SM</SocioUnico>\n        <StatoLiquidazione>LN</StatoLiquidazione>\n      </IscrizioneREA>\n    </CedentePrestatore>\n    <CessionarioCommittente>\n      <DatiAnagrafici>\n        <IdFiscaleIVA>\n          <IdPaese>IT</IdPaese>\n          <IdCodice>PIVA_CLIENTE_ANONIMO</IdCodice>\n        </IdFiscaleIVA>\n        <Anagrafica>\n          <Denominazione>O.M.Z. Srl</Denominazione>\n        </Anagrafica>\n      </DatiAnagrafici>\n      <Sede>\n        <Indirizzo>Via N. Strampelli, 22</Indirizzo>\n        <CAP>00040</CAP>\n        <Comune>Ardea</Comune>\n        <Provincia>RM</Provincia>\n        <Nazione>IT</Nazione>\n      </Sede>\n    </CessionarioCommittente>\n  </FatturaElettronicaHeader>\n  <FatturaElettronicaBody>\n    <DatiGenerali>\n      <DatiGeneraliDocumento>\n        <TipoDocumento>TD01</TipoDocumento>\n        <Divisa>EUR</Divisa>\n        <Data>2025-10-01</Data>\n        <Numero>1637/2025</Numero>\n        <ImportoTotaleDocumento>307.44</ImportoTotaleDocumento>\n        <Causale>Periodo fatturazione: 01/10/2025 - 30/09/2026 Rif. Ord. 257 del 01/10/2025</Causale>\n      </DatiGeneraliDocumento>\n      <DatiOrdineAcquisto>\n        <IdDocumento>257</IdDocumento>\n        <Data>2025-10-01</Data>\n      </DatiOrdineAcquisto>\n    </DatiGenerali>\n    <DatiBeniServizi>\n      <DettaglioLinee>\n        <NumeroLinea>1</NumeroLinea>\n        <Descrizione>Hosting gestito professionale</Descrizione>\n        <Quantita>1.00</Quantita>\n        <PrezzoUnitario>120.00</PrezzoUnitario>\n        <PrezzoTotale>120.00</PrezzoTotale>\n        <AliquotaIVA>22.00</AliquotaIVA>\n      </DettaglioLinee>\n      <DatiRiepilogo>\n        <AliquotaIVA>22.00</AliquotaIVA>\n        <ImponibileImporto>252.00</ImponibileImporto>\n        <Imposta>55.44</Imposta>\n      </DatiRiepilogo>\n    </DatiBeniServizi>\n    <DatiPagamento>\n      <CondizioniPagamento>TP02</CondizioniPagamento>\n      <DettaglioPagamento>\n        <ModalitaPagamento>MP05</ModalitaPagamento>\n        <ImportoPagamento>307.44</ImportoPagamento>\n        <IBAN>IT00X0000000000000000000000</IBAN>\n      </DettaglioPagamento>\n    </DatiPagamento>\n  </FatturaElettronicaBody>\n</p:FatturaElettronica>"}}}}},"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"valid":{"type":"boolean","example":true},"message":{"type":"string","example":"XML structure is valid."}}}}}}}},"400":{"description":"Request body is empty","content":{"application/json":{"example":{"data":"null","success":false,"message":"Request body is empty","error":400}}}},"422":{"description":"XML Validation Failed","content":{"application/json":{"example":{"data":"null","success":false,"message":"XML Validation Failed: [Error details...]","error":422}}}}}}},"/IT-configurations":{"get":{"tags":["IT-configuration"],"summary":"Retrieve all IT-configurations.","description":"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.\n  \n","responses":{"200":{"description":"List of IT-configurations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITConfigurationResponseArray"},"example":{"data":[{"fiscal_id":"YourCompanyFiscal_id","name":"nameCompany","email":"youremail@mail.com","receipts_authentication":null,"taxCode":"FHHWMF96L52D111B","api_configurations":[{"event":"receipt","callback":{"method":"JSON","url":"https://www.mysite.com/myEndpoint","user_id":"","username":"","field":"data","headers":{},"data":{},"retry":0,"scope":null,"domain":null,"custom":null}},{"event":"receipt-error","callback":{"method":"JSON","url":"https://www.mysite.com/myEndpoint","user_id":"","username":"","field":"data","headers":{},"data":{},"retry":0,"scope":null,"domain":null,"custom":null}}],"receipts":true,"active":true,"create_timestamp":1738323790,"id":"679ca42e**********016f18"},{"fiscal_id":"YourCompanyFiscal_id2","name":"nameCompany2","email":"youremail@mail.com2","receipts_authentication":{"taxCode":"FHHWMF96L52D111B"},"api_configurations":[{"event":"receipt","callback":{"method":"JSON","url":"https://www.mysite.com/myEndpoint","user_id":"","username":"","field":"data","headers":{},"data":{},"retry":0,"scope":null,"domain":null,"custom":null}},{"event":"receipt-credentials","callback":{"method":"JSON","url":"https://www.mysite.com/myEndpoint","user_id":"","username":"","field":"data","headers":{},"data":{},"retry":0,"scope":null,"domain":null,"custom":null}},{"event":"receipt-retry","callback":{"method":"JSON","url":"https://www.mysite.com/myEndpoint","user_id":"","username":"","field":"data","headers":{},"data":{},"retry":0,"scope":null,"domain":null,"custom":null}},{"event":"receipt-error","callback":{"method":"JSON","url":"https://www.mysite.com/myEndpoint","user_id":"","username":"","field":"data","headers":{},"data":{},"retry":0,"scope":null,"domain":null,"custom":null}}],"receipts":true,"active":true,"create_timestamp":1738318895,"id":"679ca42e**********016df7"}],"success":true,"message":"","error":null}}}}}},"post":{"tags":["IT-configuration"],"summary":"Create a new IT-configuration.","description":"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\n\n   **IMPORTANT**: To receive notification, it is necessary to insert the api_configurations and set the event as indicated in the schemas.\n   It will always be possible to update the data with the PATCH IT-configuration\n   \n   For sending receipts, it is necessary to enable the `receipts` option to true.\n   \n   To use the **invoice sending service**, you must enable the `customer_invoice` option.\n   \n   To receive **incoming invoices** (passive invoices), you must enable the `supplier_invoice` option and follow the [registration guide](https://openapi.it/blog/registrare-codice-destinatario-agenzia-entrate-italiana).\n   \n   By default, all will be set to false.\n   \n   ### 🏪 New Fields: Stores, Cash Registers & Addresses\n   You can now configure `merchant_address` (legal address), `stores` (physical points of sale), and `cash_registers` (devices within each store). All address fields are validated against the Italian CAP registry.\n   \n   > **NB**: These new fields are required for the upcoming **new RECEIPTS service** for electronic receipt transmission, which will be available as soon as the Italian Revenue Agency (Agenzia delle Entrate) APIs are released. The new features will be available shortly in the **test environment** for early testing. We will provide frequent updates to this API.\n   \n   \n   *It will be possible to configure up to 10 companies per day for free, subsequently the indicated price will be applied*\n   \n   \n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IT-configuration"}}}},"responses":{"200":{"description":"IT-configuration created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITConfigurationResponse"},"example":{"data":{"fiscal_id":"YourCompanyFiscal_id","name":"nameCompany","email":"youremail@mail.com","receipts_authentication":{"taxCode":"FHHWMF96L52D111B"},"api_configurations":[{"event":"receipt","callback":{"method":"JSON","url":"https://www.mysite.com/myEndpoint","user_id":"","username":"","field":"data","headers":{},"data":{},"retry":0,"scope":null,"domain":null,"custom":null}},{"event":"receipt-credentials","callback":{"method":"JSON","url":"https://www.mysite.com/myEndpoint","user_id":"","username":"","field":"data","headers":{},"data":{},"retry":0,"scope":null,"domain":null,"custom":null}},{"event":"receipt-retry","callback":{"method":"JSON","url":"https://www.mysite.com/myEndpoint","user_id":"","username":"","field":"data","headers":{},"data":{},"retry":0,"scope":null,"domain":null,"custom":null}},{"event":"receipt-error","callback":{"method":"JSON","url":"https://www.mysite.com/myEndpoint","user_id":"","username":"","field":"data","headers":{},"data":{},"retry":0,"scope":null,"domain":null,"custom":null}}],"receipts":true,"active":true,"create_timestamp":1738318895,"id":"679ca42e**********016df7"},"success":true,"message":"","error":null}}}},"404":{"description":"404 Not Found","content":{"application/json":{"example":{"data":"null","success":true,"message":"Fiscal ID not found or not registered","error":111}}}}}}},"/IT-configurations/{fiscal_id}":{"get":{"tags":["IT-configuration"],"summary":"Retrieve a single IT-configuration by fiscal_id.","description":"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\n  \n","parameters":[{"name":"fiscal_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of IT-configurations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITConfigurationResponse"},"example":{"data":{"fiscal_id":"YourCompanyFiscal_id2","name":"nameCompany2","email":"youremail@mail.com2","receipts_authentication":{"taxCode":"FHHWMF96L52D111B"},"api_configurations":[{"event":"receipt","callback":{"method":"JSON","url":"https://www.mysite.com/myEndpoint","user_id":"","username":"","field":"data","headers":{},"data":{},"retry":0,"scope":null,"domain":null,"custom":null}},{"event":"receipt-credentials","callback":{"method":"JSON","url":"https://www.mysite.com/myEndpoint","user_id":"","username":"","field":"data","headers":{},"data":{},"retry":0,"scope":null,"domain":null,"custom":null}},{"event":"receipt-retry","callback":{"method":"JSON","url":"https://www.mysite.com/myEndpoint","user_id":"","username":"","field":"data","headers":{},"data":{},"retry":0,"scope":null,"domain":null,"custom":null}},{"event":"receipt-error","callback":{"method":"JSON","url":"https://www.mysite.com/myEndpoint","user_id":"","username":"","field":"data","headers":{},"data":{},"retry":0,"scope":null,"domain":null,"custom":null}}],"receipts":true,"active":true,"create_timestamp":1738318895,"id":"679ca42e**********016df7"},"success":true,"message":"","error":null}}}},"404":{"description":"404 Not Found","content":{"application/json":{"example":{"data":"null","success":true,"message":"Fiscal ID not found or not registered","error":111}}}}}},"patch":{"tags":["IT-configuration"],"summary":"Update an existing IT-configuration.","description":"This service allows you to modify or update authentication data in case they have expired. You can also update the API configurations, stores, cash registers, and addresses. If you no longer wish to receive notifications for a specific event, simply set the `callback` to `null`.\n\n  **NB**: The credentials in the *receipts_authentication* have to be updated every 90 days (for the Agenzia delle Entrate).\n\n  ### 🏪 Granular Patching for Stores & Cash Registers\n  You can update specific stores and cash registers using path-based granular PATCH:\n  - **Update a store**: `PATCH /IT-configurations/{fiscal_id}/stores/{store_id}` — Send the fields to update (e.g. `label`, `address`)\n  - **Update a cash register**: `PATCH /IT-configurations/{fiscal_id}/stores/{store_id}/cash_registers/{cr_id}` — Send the fields to update (e.g. `label`)\n\n  When updating the `merchant_address` or store `address`, all address fields are validated against the Italian CAP registry to ensure `zip_code`, `province`, and `city` are consistent.\n\n  > **NB**: These new fields (`merchant_address`, `stores`, `cash_registers`) are required for the upcoming **new RECEIPTS service** that will be available as soon as the Italian Revenue Agency (Agenzia delle Entrate) APIs are released. The new features will be available shortly in the **test environment** so you can start testing. We will provide frequent updates to this API.\n","parameters":[{"name":"fiscal_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IT-configurationPATCH"}}}},"responses":{"200":{"description":"IT-configuration created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITConfigurationResponse"},"example":{"data":{"fiscal_id":"YourCompanyFiscal_id","name":"nameCompany","email":"youremail@mail.com","receipts_authentication":{"taxCode":"FHHWMF96L52D111B"},"api_configurations":[{"event":"receipt","callback":{"method":"JSON","url":"https://www.mysite.com/myEndpoint","user_id":"","username":"","field":"data","headers":{},"data":{},"retry":0,"scope":null,"domain":null,"custom":null}},{"event":"receipt-credentials","callback":{"method":"JSON","url":"https://www.mysite.com/myEndpoint","user_id":"","username":"","field":"data","headers":{},"data":{},"retry":0,"scope":null,"domain":null,"custom":null}},{"event":"receipt-retry","callback":{"method":"JSON","url":"https://www.mysite.com/myEndpoint","user_id":"","username":"","field":"data","headers":{},"data":{},"retry":0,"scope":null,"domain":null,"custom":null}},{"event":"receipt-error","callback":{"method":"JSON","url":"https://www.mysite.com/myEndpoint","user_id":"","username":"","field":"data","headers":{},"data":{},"retry":0,"scope":null,"domain":null,"custom":null}}],"receipts":true,"active":true,"create_timestamp":1738318895,"id":"679ca42e**********016df7"},"success":true,"message":"","error":null}}}},"400":{"description":"400 Bad Request","content":{"application/json":{"example":{"data":"null","success":true,"message":"Invalid field: email. Fields fiscal_id, name, email are not editable.","error":670}}}},"404":{"description":"404 Not Found","content":{"application/json":{"example":{"data":"null","success":true,"message":"Fiscal ID not found or not registered","error":111}}}}}},"delete":{"tags":["IT-configuration"],"summary":"Delete a IT-configuration by fiscal_id.","description":"This service allows you to delete the configuration. \n\n  **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.\n\n  \n","parameters":[{"name":"fiscal_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"IT-configuration deleted.","content":{"application/json":{"example":{"data":"null","success":true,"message":"Deleted configuration for id: YourCompanyFiscal_id","error":null}}}},"404":{"description":"404 Not Found","content":{"application/json":{"example":{"data":"null","success":true,"message":"Fiscal ID not found or not registered","error":111}}}}}}},"/IT-receipts":{"get":{"tags":["IT-receipt"],"summary":"Retrieve all IT-receipts.","description":"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.\n\n  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).\n  \n  fiscal_id, status, and type support multiple values by separating them with a comma (e.g., fiscal_id_1,fiscal_id_2).\n  \n  **status** valid values: new, retry, submitted, ready, failed, voided.\n  \n  **type** valid values: sale, return, void.\n  \n  **created_at** and **document_date** must follow the YYYY-MM-DD format.\n  \n  This endpoint returns a structured JSON response containing the matching receipts.\n","parameters":[{"name":"fiscal_id","in":"query","description":"Filter receipts by fiscal ID.","schema":{"type":"string"}},{"name":"document_number","in":"query","description":"Filter receipts by document number.","schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter receipts by status. Multiple values can be provided, separated by commas.","schema":{"type":"array","items":{"type":"string","enum":["new","retry","submitted","ready","failed","voided"]}},"style":"form","explode":false},{"name":"type","in":"query","description":"Filter receipts by type. Multiple values can be provided, separated by commas.","schema":{"type":"array","items":{"type":"string","enum":["sale","return","void"]}},"style":"form","explode":false},{"name":"created_at","in":"query","description":"Filter receipts by creation date (YYYY-MM-DD format).\nYou can also filter for documents before or after a specific date using parameters:\n- created_at[before]=YYYY-MM-DD (for documents before the specified date)\n- created_at[after]=YYYY-MM-DD (for documents after the specified date).\n","schema":{"type":"string","format":"date"}},{"name":"document_date","in":"query","description":"Filter receipts by document date (YYYY-MM-DD format).\nYou can also filter for documents before or after a specific date using parameters:\n- created_at[before]=YYYY-MM-DD (for documents before the specified date)\n- created_at[after]=YYYY-MM-DD (for documents after the specified date)\n","schema":{"type":"string","format":"date"}},{"name":"parent_receipt_id","in":"query","description":"Filter receipts by parent receipt ID.","schema":{"type":"string"}},{"name":"skip","in":"query","description":"Number of records to skip for pagination.","schema":{"type":"integer","minimum":0}},{"name":"limit","in":"query","description":"Number of records to return (max 100).","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"List of IT-configurations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ITReceiptResponseArray"},"example":{"data":[{"fiscal_id":"YourCompanyFiscal_id","items":[{"id":"489432","quantity":11,"description":"test ultimate","gross_price":10,"vat_rate":"22","gross_discount":0,"complimentary":true,"unit_price":8.19672131,"return":1,"taxable_amount":8.19672131,"net_taxable_amount":8.19672131,"vat_amount":1.80327868,"total_amount":10,"unit_discount":0,"sku":"product1"}],"cash_payment_amount":4.5,"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,"linked_receipt":null,"lottery_code":null,"created_at":"2025-01-31T16:29:52.000Z","error_message":null,"error_code":null,"total_amount":10,"document_number":"OPENAPI2025/0000-4712","document_date":"2025-01-31T16:30:00.000Z","transaction_id":"4712","create_timestamp":1738340991,"parent_receipt_id":"6as******************b52","status":"ready","type":"return","deductible_amount":0,"total_discount":0,"total_gross_discount":0,"total_taxable_amount":8.19672132,"total_uncollected_amount":0,"total_vat_amount":1.80327868,"update_timestamp":1738341005,"id":"679ca42e**********016f18","tags":["es1","es2"]},{"fiscal_id":"YourCompanyFiscal_id","items":[{"id":"250652","quantity":11,"description":"test ultimate","gross_price":10,"vat_rate":"22","gross_discount":0,"complimentary":true,"unit_price":8.19672131,"return":0,"taxable_amount":90.16393442,"net_taxable_amount":90.16393442,"vat_amount":19.83606558,"total_amount":110,"unit_discount":0,"sku":"product2"}],"cash_payment_amount":4.5,"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,"linked_receipt":"string","lottery_code":null,"created_at":"2025-01-31T16:07:19.000Z","error_message":null,"error_code":null,"total_amount":110,"document_number":"OPENAPI2025/0000-4711","document_date":"2025-01-31T16:07:26.000Z","transaction_id":"4711","create_timestamp":1738339638,"status":"ready","type":"sale","deductible_amount":0,"total_discount":0,"total_gross_discount":0,"total_taxable_amount":90.16393442,"total_uncollected_amount":0,"total_vat_amount":19.83606558,"update_timestamp":1738341005,"id":"6as******************b52"},{"fiscal_id":"YourCompanyFiscal_id","items":[{"id":"200170","quantity":11,"description":"test ultimate","gross_price":10,"vat_rate":"22","gross_discount":0,"complimentary":true,"unit_price":8.19672131,"return":0,"taxable_amount":90.16393442,"net_taxable_amount":90.16393442,"vat_amount":19.83606558,"total_amount":110,"unit_discount":0,"sku":"product3"}],"cash_payment_amount":4.5,"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,"linked_receipt":"string","lottery_code":null,"created_at":"2025-01-31T14:08:20.000Z","error_message":null,"error_code":null,"total_amount":110,"document_number":"OPENAPI2025/0000-4706","document_date":"2025-01-31T14:08:28.000Z","transaction_id":"4706","create_timestamp":1738332500,"status":"ready","type":"sale","deductible_amount":0,"total_discount":0,"total_gross_discount":0,"total_taxable_amount":90.16393442,"total_uncollected_amount":0,"total_vat_amount":19.83606558,"update_timestamp":1738332518,"id":"671skdjapsj78*********23"}],"success":true,"message":"","error":null}}}}}},"post":{"tags":["IT-receipt"],"summary":"Create a new receipt.","description":"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.\n\nUnlike 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.\n\n**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.\n\n**Sandbox Environment**:\nThe 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.\n\n**NB**: \n  It is important to set the following events for the callbacks: \n  - `receipt`: *This event is triggered when a new receipt is submitted and ready*\n  - `receipt-credentials`: This event is triggered when there are update about credentials\n  - `receipt-retry`:*This event is triggered when the communication with the Tax Authority portal failed, and we will retry to send the receipt again*\n  - `receipt-error` *This event is triggered when the Tax Authority portal reports an error*\n  \n  \n  This is because the receipt details will be updated based on the event type.\n  \n  \n  \n  Before sending a document to the Tax Authority Portal, OpenaApi will perform some checks on the data you sent.\n  \n  \n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/POSTReceipt"}}}},"callbacks":{"callback":{"{your_url}":{"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseCallbackReceipts"},"examples":{"ready-sale":{"description":"In the callback, the various types and statuses of the receipt will be returned.\nThis is the response where the receipt has been successfully issued and is ready.\n","value":{"data":{"data":{"fiscal_id":"YourCompanyFiscal_id","items":[{"id":"200170","quantity":10,"description":"product","gross_price":10,"vat_rate":"22","gross_discount":0,"complimentary":true,"unit_price":8.19672131,"return":0,"taxable_amount":90.16393442,"net_taxable_amount":90.16393442,"vat_amount":19.83606558,"total_amount":110,"unit_discount":0}],"cash_payment_amount":100,"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,"linked_receipt":"string","lottery_code":null,"created_at":"2025-01-31T14:08:20.000Z","error_message":null,"error_code":null,"total_amount":110,"document_number":"OPENAPI2025/0000-4706","document_date":"2025-01-31T14:08:28.000Z","transaction_id":"4706","create_timestamp":1738332500,"status":"ready","type":"sale","deductible_amount":0,"total_discount":0,"total_gross_discount":0,"total_taxable_amount":90.16393442,"total_uncollected_amount":0,"total_vat_amount":19.83606558,"update_timestamp":1738332518,"id":"679c**********1111111111"},"custom":null}}}}}}},"responses":{"200":{"description":"ok"}}}}}},"responses":{"200":{"description":"Receipt created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiptResponse"}}}},"400":{"description":"400 Bad Request","content":{"application/json":{"example":{"data":"null","success":false,"message":"Missing fiscal_id","error":423}}}}}}},"/IT-receipts/{id}":{"get":{"tags":["IT-receipt"],"summary":"Retrieve a single receipt by ID.","description":"Retrieves the details of a single receipt using its unique identifier. The receipt ID must be provided in the request path.\n\n  When the **Content-Type Header** is set to **application/pdf**, the API returns the receipt as a downloadable PDF file instead of the default JSON response.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"679cd95***************23"}}],"responses":{"200":{"description":"Receipt Found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ResponseReceipts"}}}},"application/pdf":{"schema":{"$ref":"#/components/schemas/ResponseReceiptsPdf"}}}}}},"patch":{"tags":["IT-receipt"],"summary":"Return one or more items from a receipt.","description":"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.\n\n**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.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier of the receipt to be updated.","example":"679c***6d00d0***b23"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiptReturn"}}}},"callbacks":{"callback":{"{your_url}":{"post":{"operationId":"postReceiptCallbackPatch","description":"Callback for receipt updates.","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ResponseCallbackReceipts"},{"$ref":"#/components/schemas/ResponseReturnReceiptCallback"}]},"examples":{"ready-sale":{"description":"In the callback, the various types and statuses of the receipt will be returned.\nThis is the response where the receipt has been successfully issued and is ready.\n","value":{"data":{"fiscal_id":"YourCompanyFiscal_id","items":[{"id":"250652","quantity":1,"description":"product","gross_price":10,"vat_rate":"22","gross_discount":0,"complimentary":true,"unit_price":8.19672131,"return":1,"taxable_amount":90.16393442,"net_taxable_amount":90.16393442,"vat_amount":19.83606558,"total_amount":110,"unit_discount":0}],"cash_payment_amount":0,"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,"linked_receipt":"string","lottery_code":null,"created_at":"2025-01-31T16:07:19.000Z","error_message":null,"error_code":null,"total_amount":110,"document_number":"OPENAPI2025/0000-4711","document_date":"2025-01-31T16:07:26.000Z","transaction_id":"4711","create_timestamp":1738339638,"status":"ready","type":"sale","tags":[],"deductible_amount":0,"total_discount":0,"total_gross_discount":0,"total_taxable_amount":90.16393442,"total_uncollected_amount":0,"total_vat_amount":19.83606558,"update_timestamp":1738341005,"id":"679cf5377be****b540a2b52"},"custom":null}},"ready-return":{"description":"This callback notifies the updated returned receipt, which includes the parent ID.\n","value":{"data":{"fiscal_id":"YourCompanyFiscal_id","items":[{"id":"489432","quantity":11,"description":"product","gross_price":10,"vat_rate":"22","gross_discount":0,"complimentary":true,"unit_price":8.19672131,"return":1,"taxable_amount":8.19672131,"net_taxable_amount":8.19672131,"vat_amount":1.80327868,"total_amount":10,"unit_discount":0}],"cash_payment_amount":4.5,"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,"linked_receipt":null,"lottery_code":null,"created_at":"2025-01-31T16:29:52.000Z","error_message":null,"error_code":null,"total_amount":10,"document_number":"OPENAPI2025/0000-4712","document_date":"2025-01-31T16:30:00.000Z","transaction_id":"4712","create_timestamp":1738340991,"parent_receipt_id":"679cf5377be****b540a2b52","status":"ready","type":"return","tags":null,"deductible_amount":0,"total_discount":0,"total_gross_discount":0,"total_taxable_amount":8.19672132,"total_uncollected_amount":0,"total_vat_amount":1.80327868,"update_timestamp":1738341005,"id":"a********4e83682b7097b92"},"custom":null}}}}}},"responses":{"200":{"description":"ok"}}}}}},"responses":{"200":{"description":"Receipt created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseReturnReceipt"}}}}}},"delete":{"tags":["IT-receipt"],"summary":"Delete a receipt by ID.","description":"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.\n\nThe void receipt will reflect the cancellation of the original transaction while maintaining traceability.\n\nUpon success, the response will include the newly created void receipt details.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"6a9**************d077b23"}}],"callbacks":{"callback":{"{your_url}":{"post":{"operationId":"postReceiptCallbackDelete","description":"Callback for receipt updates.","requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ResponseCallbackReceipts"},{"$ref":"#/components/schemas/ResponseVoidReceiptCallback"}]},"examples":{"voided-sale":{"description":"In the callback, the various types and statuses of the receipt will be returned.\nThis is the response where the receipt has been successfully voided.\n","value":{"data":{"fiscal_id":"YourCompanyFiscal_id","items":[{"id":"250652","quantity":11,"description":"product","gross_price":10,"vat_rate":"22","gross_discount":0,"complimentary":true,"unit_price":8.19672131,"return":0,"taxable_amount":90.16393442,"net_taxable_amount":90.16393442,"vat_amount":19.83606558,"total_amount":110,"unit_discount":0}],"cash_payment_amount":4.5,"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,"linked_receipt":"string","lottery_code":null,"created_at":"2025-01-31T16:07:19.000Z","error_message":null,"error_code":null,"total_amount":110,"document_number":"OPENAPI2025/0000-4711","document_date":"2025-01-31T16:07:26.000Z","transaction_id":"4711","create_timestamp":1738339638,"status":"voided","type":"sale","deductible_amount":0,"total_discount":0,"total_gross_discount":0,"total_taxable_amount":90.16393442,"total_uncollected_amount":0,"tags":[],"total_vat_amount":19.83606558,"update_timestamp":1738341005,"id":"679cf5377be****b540a2b52"},"custom":null}},"ready-void":{"description":"This callback notifies the updated void receipt, which includes the parent ID.\n","value":{"data":{"fiscal_id":"YourCompanyFiscal_id","items":[{"id":"489432","quantity":11,"description":"product","gross_price":10,"vat_rate":"22","gross_discount":0,"complimentary":true,"unit_price":8.19672131,"return":1,"taxable_amount":8.19672131,"net_taxable_amount":8.19672131,"vat_amount":1.80327868,"total_amount":10,"unit_discount":0}],"cash_payment_amount":4.5,"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,"linked_receipt":null,"lottery_code":null,"created_at":"2025-01-31T16:29:52.000Z","error_message":null,"error_code":null,"total_amount":10,"document_number":"OPENAPI2025/0000-4712","document_date":"2025-01-31T16:30:00.000Z","transaction_id":"4712","create_timestamp":1738340991,"parent_receipt_id":"6a9**************d077b23","status":"ready","type":"void","tags":null,"deductible_amount":0,"total_discount":0,"total_gross_discount":0,"total_taxable_amount":8.19672132,"total_uncollected_amount":0,"total_vat_amount":1.80327868,"update_timestamp":1738341005,"id":"6b7****************03b8d2"},"custom":null}}}}}},"responses":{"200":{"description":"ok"}}}}}},"responses":{"200":{"description":"Receipt created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseVoidReceipt"}}}}}}}},"externalDocs":{"description":"First time here? Generate a new access token","url":"https://console.openapi.com/oauth"},"security":[{"bearerAuth":[]}]}