{ "openapi": "3.0.4", "info": { "title": "Invoicetronic API", "description": "The [Invoicetronic API][2] is a RESTful service that allows you to send and receive invoices through the Italian [Servizio di Interscambio (SDI)][1], or Interchange Service. The API is designed to be simple and easy to use, abstracting away SDI complexity while providing complete control over the invoice send/receive process. It provides advanced features as encryption at rest, multi-language pre-flight invoice validation, multiple upload formats, webhooks, event logging, client SDKs, and CLI tools.\n\nFor more information, see [Invoicetronic website][2]\n\n[1]: https://www.fatturapa.gov.it/it/sistemainterscambio/cose-il-sdi/\n[2]: https://invoicetronic.com/", "termsOfService": "https://invoicetronic.com/tos", "contact": { "name": "Invoicetronic", "url": "https://invoicetronic.com/en/contact/", "email": "info@invoicetronic.com" }, "license": { "name": "MIT", "url": "https://github.com/invoicetronic/openapi/blob/main/LICENSE" }, "version": "1.9.1" }, "servers": [ { "url": "https://api.invoicetronic.com/v1/" } ], "paths": { "/company/{id}": { "get": { "tags": [ "company" ], "summary": "Get a company by id", "description": "Retrieve a company by its internal id.\n\n**Companies** are the entities that send and receive invoices. They are automatically created from invoice data when invoices are sent or received.", "parameters": [ { "name": "id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "404": { "description": "Not Found" } } }, "delete": { "tags": [ "company" ], "summary": "Delete a company", "description": "Delete a company by its internal id.\n\n**Companies** are the entities that send and receive invoices. They are automatically created from invoice data when invoices are sent or received.\n\n**Warning:** Deleting a company will permanently remove all associated data, including sent invoices, received invoices, invoice updates from SDI, logs, and webhooks.\n\nIf the company has any linked invoices, you must explicitly confirm deletion by adding `?force=true` to the request. Without this parameter, the API will return `409 Conflict` with details about the linked data.", "parameters": [ { "name": "id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "force", "in": "query", "description": "Force delete including all related data.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "404": { "description": "Not Found" } } } }, "/company/{vat}": { "get": { "tags": [ "company" ], "summary": "Get a company by vat number", "description": "Retrieve a company by its VAT number.\n\n**Companies** are the entities that send and receive invoices. They are automatically created from invoice data when invoices are sent or received.", "parameters": [ { "name": "vat", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "404": { "description": "Not Found" } } } }, "/company": { "get": { "tags": [ "company" ], "summary": "List companies", "description": "Retrieve a paginated list of companies. Results can be filtered by free-text search (`q`) across name, VAT number, and fiscal code.\n\n**Companies** are the entities that send and receive invoices. They are automatically created from invoice data when invoices are sent or received.", "parameters": [ { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "page_size", "in": "query", "description": "Items per page. Cannot be greater than 200.", "schema": { "type": "integer", "format": "int32", "default": 100 } }, { "name": "sort", "in": "query", "description": "Sort by field. Prefix with '-' for descending order.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Full-text search across committente, prestatore, identifier, and file name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } } } } }, "404": { "description": "Not Found" } } }, "post": { "tags": [ "company" ], "summary": "Add a company", "description": "Add a new company.\n\n**Companies** are the entities that send and receive invoices. They are automatically created from invoice data when invoices are sent or received.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "company" ], "summary": "Update a company", "description": "Update an existing company.\n\n**Companies** are the entities that send and receive invoices. They are automatically created from invoice data when invoices are sent or received.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/export": { "get": { "tags": [ "export" ], "summary": "Export invoices as a ZIP archive", "description": "Export invoices as a ZIP archive of FatturaPA XML files, suitable for import into accounting software (TeamSystem, Zucchetti, etc.).\n\n**Sent invoices** are only included when they have reached a definitive state (e.g., `Consegnato` for private recipients, `AccettatoDalDestinatario`, `DecorrenzaTermini`, etc.). Invoices still being processed by SDI are excluded.\n\n**Received invoices** are always included. Unread invoices are automatically marked as read and counted as operations.\n\n### Period filters\n\nYou can filter by period using either:\n- `year` + `month` (e.g., `year=2026&month=3` for March 2026)\n- `year` + `quarter` (e.g., `year=2026&quarter=1` for Q1 Jan-Mar)\n- `document_date_from` / `document_date_to` for a custom date range\n\nThese options are mutually exclusive. The `year` parameter alone is not valid and requires either `month` or `quarter`.\n\n### Response\n\nReturns `200` with a ZIP archive, or `204 No Content` if no invoices match the given filters. Files in the archive are organized by company VAT number (`{vat}/send/`, `{vat}/receive/`).\n\n### Rate limiting\n\nThis endpoint has a dedicated rate limit: only one export request per user can be processed at a time. Concurrent requests will receive a `429 Too Many Requests` response.", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "company_id", "in": "query", "description": "Company id", "schema": { "type": "integer", "format": "int32" } }, { "name": "year", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "month", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "quarter", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "document_date_from", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "document_date_to", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK" }, "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/health": { "get": { "tags": [ "health" ], "summary": "Health check", "description": "Returns the health status of the API and its dependencies. No authentication required. Rate limited to 12 requests per minute.", "responses": { "200": { "description": "OK" }, "429": { "description": "Too Many Requests" }, "503": { "description": "Service Unavailable" } } } }, "/log/{id}": { "get": { "tags": [ "log" ], "summary": "Get an event by id", "description": "Retrieve a log event by its internal id.\n\n**Logs** record every API request. They are preserved for 15 days.\n\nYou can also view logs in the Events section of the [Dashboard](https://dashboard.invoicetronic.com).", "parameters": [ { "name": "id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "404": { "description": "Not Found" } } } }, "/log": { "get": { "tags": [ "log" ], "summary": "List events", "description": "Retrieve a paginated list of log events. Results can be filtered by various criteria such as endpoint, method, status code, and date ranges.\n\n**Logs** record every API request. They are preserved for 15 days.\n\nYou can also view logs in the Events section of the [Dashboard](https://dashboard.invoicetronic.com).", "parameters": [ { "name": "company_id", "in": "query", "description": "Company id", "schema": { "type": "integer", "format": "int32" } }, { "name": "endpoint", "in": "query", "schema": { "type": "string" } }, { "name": "method", "in": "query", "schema": { "type": "string" } }, { "name": "api_verion", "in": "query", "description": "Api version", "schema": { "type": "integer", "format": "int32" } }, { "name": "status_code", "in": "query", "description": "Response status code", "schema": { "type": "integer", "format": "int32" } }, { "name": "date_created_from", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "date_created_to", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "page_size", "in": "query", "description": "Items per page. Cannot be greater than 200.", "schema": { "type": "integer", "format": "int32", "default": 100 } }, { "name": "sort", "in": "query", "description": "Sort by field. Prefix with '-' for descending order.", "schema": { "type": "string" } }, { "name": "query", "in": "query", "schema": { "type": "string" } }, { "name": "success", "in": "query", "schema": { "type": "boolean" } }, { "name": "date_time_from", "in": "query", "description": "Date and time of the event", "schema": { "type": "string", "format": "date-time" } }, { "name": "date_time_to", "in": "query", "description": "Date and time of the event", "schema": { "type": "string", "format": "date-time" } }, { "name": "user_agent", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } }, "404": { "description": "Not Found" } } } }, "/receive/{id}": { "get": { "tags": [ "receive" ], "summary": "Get an incoming invoice by id", "description": "Retrieve an incoming invoice by its internal id. The `id` is unique and assigned by the system when the invoice is received. Returns invoice metadata; set `include_payload` to true to include the full invoice content. The invoice is marked as read (`is_read` = true) only when `include_payload` is true.\n\n**Receive** invoices are inbound purchase invoices received from suppliers through Italy's SDI (Sistema di Interscambio). Preserved for two years in the live environment and 24 hours in the [Sandbox](https://invoicetronic.com/en/docs/sandbox/).\n\nInbound invoices are routed to your account via the recipient VAT number, so the recipient company must exist in Invoicetronic for the invoice to be matched. If an invoice arrives before its company has been registered, it is held by our SDI infrastructure and automatically re-processed once the company is created—no invoice is lost. See [Prerequisites](https://invoicetronic.com/en/docs/prerequisites/) for the recommended setup order.", "parameters": [ { "name": "id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "include_payload", "in": "query", "description": "Include payload in the response. Defaults to false.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receive" } } } }, "404": { "description": "Not Found" } } }, "delete": { "tags": [ "receive" ], "summary": "Delete an incoming invoice by id", "description": "Permanently delete a receive invoice by its internal id. This action cannot be undone.\n\n**Receive** invoices are inbound purchase invoices received from suppliers through Italy's SDI (Sistema di Interscambio). Preserved for two years in the live environment and 24 hours in the [Sandbox](https://invoicetronic.com/en/docs/sandbox/).\n\nInbound invoices are routed to your account via the recipient VAT number, so the recipient company must exist in Invoicetronic for the invoice to be matched. If an invoice arrives before its company has been registered, it is held by our SDI infrastructure and automatically re-processed once the company is created—no invoice is lost. See [Prerequisites](https://invoicetronic.com/en/docs/prerequisites/) for the recommended setup order.", "parameters": [ { "name": "id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receive" } } } }, "404": { "description": "Not Found" } } } }, "/receive/{id}/payload": { "get": { "tags": [ "receive" ], "summary": "Get a receive invoice payload by id", "description": "Retrieve only the payload of a receive invoice, without the full invoice metadata.\nThis is useful when you already have the invoice metadata and only need the XML content.\n\nThe response is a `text/plain` string, identical to the `payload` field returned\nby the standard GET endpoint with `include_payload=true`.\n\nThe invoice is marked as read (`is_read` = true) and counted as an operation, same as when\nretrieving the full invoice with `include_payload=true`.\n", "parameters": [ { "name": "id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/receive": { "get": { "tags": [ "receive" ], "summary": "List incoming invoices", "description": "Retrieve a paginated list of receive invoices. Results can be filtered by various criteria such as company, date ranges, sender, document number, and free-text search (`q`). Returns invoice metadata; set `include_payload` to true to include the full invoice content. Invoices are marked as read (`is_read` = true) only when `include_payload` is true.\n\n**Receive** invoices are inbound purchase invoices received from suppliers through Italy's SDI (Sistema di Interscambio). Preserved for two years in the live environment and 24 hours in the [Sandbox](https://invoicetronic.com/en/docs/sandbox/).\n\nInbound invoices are routed to your account via the recipient VAT number, so the recipient company must exist in Invoicetronic for the invoice to be matched. If an invoice arrives before its company has been registered, it is held by our SDI infrastructure and automatically re-processed once the company is created—no invoice is lost. See [Prerequisites](https://invoicetronic.com/en/docs/prerequisites/) for the recommended setup order.", "parameters": [ { "name": "company_id", "in": "query", "description": "Company id", "schema": { "type": "integer", "format": "int32" } }, { "name": "identifier", "in": "query", "description": "SDI identifier.", "schema": { "type": "string" } }, { "name": "unread", "in": "query", "description": "Unread items only.", "schema": { "type": "boolean" } }, { "name": "committente", "in": "query", "description": "Vat number or fiscal code.", "schema": { "type": "string" } }, { "name": "prestatore", "in": "query", "description": "Vat number or fiscal code.", "schema": { "type": "string" } }, { "name": "file_name", "in": "query", "description": "File name.", "schema": { "type": "string" } }, { "name": "last_update_from", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "last_update_to", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "date_sent_from", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "date_sent_to", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "document_date_from", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "document_date_to", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "document_number", "in": "query", "description": "Document number.", "schema": { "type": "string" } }, { "name": "include_payload", "in": "query", "description": "Include payload in the response. Defaults to false.", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "page_size", "in": "query", "description": "Items per page. Cannot be greater than 200.", "schema": { "type": "integer", "format": "int32", "default": 100 } }, { "name": "sort", "in": "query", "description": "Sort by field. Prefix with '-' for descending order.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Full-text search across committente, prestatore, identifier, and file name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Receive" } } } } }, "404": { "description": "Not Found" } } } }, "/send/{id}": { "get": { "tags": [ "send" ], "summary": "Get a invoice by id", "description": "Retrieve a send invoice by its internal id. The `id` is unique and assigned by the system when the invoice is created. Returns invoice metadata; set `include_payload` to true to include the full invoice content.\n\n**Send** invoices are outbound sales invoices transmitted to customers through Italy's SDI (Sistema di Interscambio). Preserved for two years in the live environment and 15 days in the [Sandbox](https://invoicetronic.com/en/docs/sandbox/).", "parameters": [ { "name": "id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "include_payload", "in": "query", "description": "Include payload in the response. Defaults to false.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Send" } } } }, "404": { "description": "Not Found" } } } }, "/send/{identifier}": { "get": { "tags": [ "send" ], "summary": "Get a invoice by identifier", "description": "Retrieve a send invoice by its SDI identifier. The `identifier` is assigned by the SDI and becomes available after the invoice has been accepted. Returns invoice metadata; set `include_payload` to true to include the full invoice content.\n\n**Send** invoices are outbound sales invoices transmitted to customers through Italy's SDI (Sistema di Interscambio). Preserved for two years in the live environment and 15 days in the [Sandbox](https://invoicetronic.com/en/docs/sandbox/).", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include_payload", "in": "query", "description": "Include payload in the response. Defaults to false.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Send" } } } }, "404": { "description": "Not Found" } } } }, "/send/{id}/payload": { "get": { "tags": [ "send" ], "summary": "Get a send invoice payload by id", "description": "Retrieve only the payload of a send invoice, without the full invoice metadata.\nThis is useful when you already have the invoice metadata and only need the XML content.\n\nThe response is a `text/plain` string, identical to the `payload` field returned\nby the standard GET endpoint with `include_payload=true`. Depending on how the invoice\nwas originally submitted, the payload may be Base64-encoded or plain XML.\n", "parameters": [ { "name": "id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Not Found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/send": { "get": { "tags": [ "send" ], "summary": "List invoices", "description": "Retrieve a paginated list of send invoices. Results can be filtered by various criteria such as company, date ranges, document number, and free-text search (`q`). Returns invoice metadata; set `include_payload` to true to include the full invoice content.\n\n**Send** invoices are outbound sales invoices transmitted to customers through Italy's SDI (Sistema di Interscambio). Preserved for two years in the live environment and 15 days in the [Sandbox](https://invoicetronic.com/en/docs/sandbox/).", "parameters": [ { "name": "company_id", "in": "query", "description": "Company id", "schema": { "type": "integer", "format": "int32" } }, { "name": "identifier", "in": "query", "description": "SDI identifier.", "schema": { "type": "string" } }, { "name": "committente", "in": "query", "description": "Vat number or fiscal code.", "schema": { "type": "string" } }, { "name": "prestatore", "in": "query", "description": "Vat number or fiscal code.", "schema": { "type": "string" } }, { "name": "file_name", "in": "query", "description": "File name.", "schema": { "type": "string" } }, { "name": "last_update_from", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "last_update_to", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "date_sent_from", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "date_sent_to", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "document_date_from", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "document_date_to", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "document_number", "in": "query", "description": "Document number.", "schema": { "type": "string" } }, { "name": "include_payload", "in": "query", "description": "Include payload in the response. Defaults to false.", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "page_size", "in": "query", "description": "Items per page. Cannot be greater than 200.", "schema": { "type": "integer", "format": "int32", "default": 100 } }, { "name": "sort", "in": "query", "description": "Sort by field. Prefix with '-' for descending order.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "description": "Full-text search across committente, prestatore, identifier, and file name.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Send" } } } } }, "404": { "description": "Not Found" } } }, "post": { "tags": [ "send" ], "summary": "Add an invoice", "description": "Add a new invoice using a structured Send object. The invoice will be signed (if requested), validated (if requested), and queued for delivery to SDI. Status updates from SDI will be available in the `update` endpoint.\n\n**Send** invoices are outbound sales invoices transmitted to customers through Italy's SDI (Sistema di Interscambio). Preserved for two years in the live environment and 15 days in the [Sandbox](https://invoicetronic.com/en/docs/sandbox/).\n\nYou can also upload invoices via the [Dashboard](https://dashboard.invoicetronic.com).", "parameters": [ { "name": "validate", "in": "query", "description": "Validate the document first, and reject it on failure.", "schema": { "type": "boolean", "default": false } }, { "name": "signature", "in": "query", "description": "Whether to digitally sign the document.", "schema": { "enum": [ "None", "Apply", "Force", "Auto" ], "type": "string", "description": "Definisce le modalità di firma per le fatture.", "default": "Auto" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Send" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Send" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/send/xml": { "post": { "tags": [ "send" ], "summary": "Add an invoice by xml", "description": "Add a new invoice using a raw XML document in FatturaPA format. The invoice will be signed (if requested), validated (if requested), and queued for delivery to SDI. Status updates from SDI will be available in the `update` endpoint.\n\n**Send** invoices are outbound sales invoices transmitted to customers through Italy's SDI (Sistema di Interscambio). Preserved for two years in the live environment and 15 days in the [Sandbox](https://invoicetronic.com/en/docs/sandbox/).\n\nYou can also upload invoices via the [Dashboard](https://dashboard.invoicetronic.com).", "parameters": [ { "name": "validate", "in": "query", "description": "Validate the document first, and reject it on failure.", "schema": { "type": "boolean", "default": false } }, { "name": "signature", "in": "query", "description": "Whether to digitally sign the document.", "schema": { "enum": [ "None", "Apply", "Force", "Auto" ], "type": "string", "description": "Definisce le modalità di firma per le fatture.", "default": "Auto" } } ], "requestBody": { "content": { "application/xml": { "schema": { "$ref": "#/components/schemas/FatturaOrdinaria" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Send" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/send/file": { "post": { "tags": [ "send" ], "summary": "Add an invoice by file", "description": "Add a new invoice by uploading a file. Supported formats are XML (FatturaPA) and P7M (signed). The invoice will be signed (if requested), validated (if requested), and queued for delivery to SDI. Status updates from SDI will be available in the `update` endpoint.\n\n**Send** invoices are outbound sales invoices transmitted to customers through Italy's SDI (Sistema di Interscambio). Preserved for two years in the live environment and 15 days in the [Sandbox](https://invoicetronic.com/en/docs/sandbox/).\n\nYou can also upload invoices via the [Dashboard](https://dashboard.invoicetronic.com).", "parameters": [ { "name": "validate", "in": "query", "description": "Validate the document first, and reject it on failure.", "schema": { "type": "boolean", "default": false } }, { "name": "signature", "in": "query", "description": "Whether to digitally sign the document.", "schema": { "enum": [ "None", "Apply", "Force", "Auto" ], "type": "string", "description": "Definisce le modalità di firma per le fatture.", "default": "Auto" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } }, "encoding": { "file": { "style": "form" } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Send" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/send/json": { "post": { "tags": [ "send" ], "summary": "Add an invoice by json", "description": "Add a new invoice using a FatturaPA JSON representation. The invoice will be signed (if requested), validated (if requested), and queued for delivery to SDI. Status updates from SDI will be available in the `update` endpoint.\n\n**Send** invoices are outbound sales invoices transmitted to customers through Italy's SDI (Sistema di Interscambio). Preserved for two years in the live environment and 15 days in the [Sandbox](https://invoicetronic.com/en/docs/sandbox/).\n\nYou can also upload invoices via the [Dashboard](https://dashboard.invoicetronic.com).", "parameters": [ { "name": "validate", "in": "query", "description": "Validate the document first, and reject it on failure.", "schema": { "type": "boolean", "default": false } }, { "name": "signature", "in": "query", "description": "Whether to digitally sign the document.", "schema": { "enum": [ "None", "Apply", "Force", "Auto" ], "type": "string", "description": "Definisce le modalità di firma per le fatture.", "default": "Auto" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FatturaOrdinaria" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Send" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/send/validate": { "post": { "tags": [ "send" ], "summary": "Validate an invoice", "description": "Validate an invoice without sending it to SDI. Use this to check for errors before actual submission. Returns validation results with any errors found.\n\n**Send** invoices are outbound sales invoices transmitted to customers through Italy's SDI (Sistema di Interscambio). Preserved for two years in the live environment and 15 days in the [Sandbox](https://invoicetronic.com/en/docs/sandbox/).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Send" } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/send/validate/xml": { "post": { "tags": [ "send" ], "summary": "Validate an invoice by xml", "description": "Validate an XML invoice document without sending it to SDI. Use this to check for errors before actual submission. Returns validation results with any errors found.\n\n**Send** invoices are outbound sales invoices transmitted to customers through Italy's SDI (Sistema di Interscambio). Preserved for two years in the live environment and 15 days in the [Sandbox](https://invoicetronic.com/en/docs/sandbox/).", "requestBody": { "content": { "application/xml": { "schema": { "$ref": "#/components/schemas/FatturaOrdinaria" } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/send/validate/file": { "post": { "tags": [ "send" ], "summary": "Validate an invoice file", "description": "Validate an invoice file without sending it to SDI. Supported formats are XML (FatturaPA) and P7M (signed). Use this to check for errors before actual submission. Returns validation results with any errors found.\n\n**Send** invoices are outbound sales invoices transmitted to customers through Italy's SDI (Sistema di Interscambio). Preserved for two years in the live environment and 15 days in the [Sandbox](https://invoicetronic.com/en/docs/sandbox/).", "requestBody": { "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } }, "encoding": { "file": { "style": "form" } } } } }, "responses": { "204": { "description": "No Content" }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/send/validate/json": { "post": { "tags": [ "send" ], "summary": "Validate an invoice by json", "description": "Validate a JSON invoice without sending it to SDI. Use this to check for errors before actual submission. Returns validation results with any errors found.\n\n**Send** invoices are outbound sales invoices transmitted to customers through Italy's SDI (Sistema di Interscambio). Preserved for two years in the live environment and 15 days in the [Sandbox](https://invoicetronic.com/en/docs/sandbox/).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FatturaOrdinaria" } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/status": { "get": { "tags": [ "status" ], "summary": "Account status", "description": "Retrieve the number of operations (invoices + validations) and signatures left on your account.\n\nWhen `signature_left` is 0, you will receive a `403 Forbidden` response when trying to sign an invoice. Likewise, if `operation_left` is 0, you will receive a `403 Forbidden` response when storing or validating an invoice.\n\nYou can also check your account status from the [Dashboard](https://dashboard.invoicetronic.com), where you can purchase additional operations and/or signatures.\n\n**Please note** that these values are not enforced if you are on the [Sandbox](https://invoicetronic.com/en/docs/sandbox/).", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } } } }, "/update/{id}": { "get": { "tags": [ "update" ], "summary": "Get an update by id", "description": "Retrieve an update by its internal id.\n\n**Updates** are status notifications from Italy's SDI (Sistema di Interscambio) about invoices you sent. Multiple updates can exist for the same send item as the invoice progresses through the SDI workflow.\n\nThe `state` field is the most important property and can have the following values:\n\n| Value | Name | Description |\n|-------|------|-------------|\n| 2 | `Inviato` | Sent to the SDI. |\n| 5 | `Consegnato` | Delivered to the recipient. |\n| 6 | `NonConsegnato` | Not delivered to the recipient. Only relevant for public administration entities. |\n| 7 | `Scartato` | Rejected by the SDI. |\n| 8 | `AccettatoDalDestinatario` | Accepted by the recipient. Only relevant for public administration entities. |\n| 9 | `RifiutatoDalDestinatario` | Rejected by the recipient. Only relevant for public administration entities. |\n| 10 | `ImpossibilitaDiRecapito` | Available on the recipient's tax drawer, but it was not possible to deliver it to the recipient's reception system. |\n| 11 | `DecorrenzaTermini` | A public administration entity has not responded for more than 15 days. The document is considered delivered. |\n| 12 | `AttestazioneTrasmissioneFattura` | A public administration entity has received the document, but has not yet processed it. |\n\n**Cost:** Querying this endpoint is free and does not count as an operation against your plan limits.\n\n**Important:** Always monitor the state of your sent invoices. A state of `Inviato` only means the invoice has been submitted to SDI, not that it has been delivered. A state like `Scartato` indicates that the invoice was **not** successfully delivered and may require corrective action, such as fixing validation errors and resubmitting. In that case, `description` contains the reason for the rejection.", "parameters": [ { "name": "id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Update" } } } }, "404": { "description": "Not Found" } } } }, "/update": { "get": { "tags": [ "update" ], "summary": "List updates", "description": "Retrieve a paginated list of updates. Results can be filtered by various criteria such as company, send item, SDI state, and date ranges.\n\n**Updates** are status notifications from Italy's SDI (Sistema di Interscambio) about invoices you sent. Multiple updates can exist for the same send item as the invoice progresses through the SDI workflow.\n\nThe `state` field is the most important property and can have the following values:\n\n| Value | Name | Description |\n|-------|------|-------------|\n| 2 | `Inviato` | Sent to the SDI. |\n| 5 | `Consegnato` | Delivered to the recipient. |\n| 6 | `NonConsegnato` | Not delivered to the recipient. Only relevant for public administration entities. |\n| 7 | `Scartato` | Rejected by the SDI. |\n| 8 | `AccettatoDalDestinatario` | Accepted by the recipient. Only relevant for public administration entities. |\n| 9 | `RifiutatoDalDestinatario` | Rejected by the recipient. Only relevant for public administration entities. |\n| 10 | `ImpossibilitaDiRecapito` | Available on the recipient's tax drawer, but it was not possible to deliver it to the recipient's reception system. |\n| 11 | `DecorrenzaTermini` | A public administration entity has not responded for more than 15 days. The document is considered delivered. |\n| 12 | `AttestazioneTrasmissioneFattura` | A public administration entity has received the document, but has not yet processed it. |\n\n**Cost:** Querying this endpoint is free and does not count as an operation against your plan limits.\n\n**Important:** Always monitor the state of your sent invoices. A state of `Inviato` only means the invoice has been submitted to SDI, not that it has been delivered. A state like `Scartato` indicates that the invoice was **not** successfully delivered and may require corrective action, such as fixing validation errors and resubmitting. In that case, `description` contains the reason for the rejection.", "parameters": [ { "name": "company_id", "in": "query", "description": "Company id", "schema": { "type": "integer", "format": "int32" } }, { "name": "identifier", "in": "query", "description": "SDI identifier.", "schema": { "type": "string" } }, { "name": "prestatore", "in": "query", "description": "Vat number or fiscal code.", "schema": { "type": "string" } }, { "name": "unread", "in": "query", "description": "Unread items only.", "schema": { "type": "boolean" } }, { "name": "send_id", "in": "query", "description": "Send item's id.", "schema": { "type": "integer", "format": "int32" } }, { "name": "state", "in": "query", "description": "SDI state", "schema": { "enum": [ "Inviato", "Consegnato", "NonConsegnato", "Scartato", "AccettatoDalDestinatario", "RifiutatoDalDestinatario", "ImpossibilitaDiRecapito", "DecorrenzaTermini", "AttestazioneTrasmissioneFattura" ], "type": "string" } }, { "name": "last_update_from", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "last_update_to", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "date_sent_from", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "date_sent_to", "in": "query", "description": "UTC ISO 8601 (2024-11-29T12:34:56Z)", "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "page_size", "in": "query", "description": "Items per page. Cannot be greater than 200.", "schema": { "type": "integer", "format": "int32", "default": 100 } }, { "name": "sort", "in": "query", "description": "Sort by field. Prefix with '-' for descending order.", "schema": { "type": "string", "default": "last_update" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Update" } } } } }, "404": { "description": "Not Found" } } } }, "/webhook/{id}": { "get": { "tags": [ "webhook" ], "summary": "Get a webhook by id", "description": "Retrieve a webhook by its internal id.\n\n**Webhooks** allow you to receive notifications to an external service when specific events occur, such as invoice creation or status updates. You can subscribe to specific events and receive a notification when they occur.\n\nYou can also manage webhooks via the [Dashboard](https://dashboard.invoicetronic.com).\n\nFor more information, see the **[Webhooks documentation page](https://invoicetronic.com/en/docs/webhooks/)**.", "parameters": [ { "name": "id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebHook" } } } }, "404": { "description": "Not Found" } } }, "delete": { "tags": [ "webhook" ], "summary": "Delete a webhook by id", "description": "Delete a webhook subscription by its internal id.\n\n**Webhooks** allow you to receive notifications to an external service when specific events occur, such as invoice creation or status updates. You can subscribe to specific events and receive a notification when they occur.\n\nYou can also manage webhooks via the [Dashboard](https://dashboard.invoicetronic.com).\n\nFor more information, see the **[Webhooks documentation page](https://invoicetronic.com/en/docs/webhooks/)**.", "parameters": [ { "name": "id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebHook" } } } }, "404": { "description": "Not Found" } } } }, "/webhook": { "get": { "tags": [ "webhook" ], "summary": "List webhooks", "description": "Retrieve a paginated list of webhooks. Results can be filtered by company, description, enabled status, events, and URL.\n\n**Webhooks** allow you to receive notifications to an external service when specific events occur, such as invoice creation or status updates. You can subscribe to specific events and receive a notification when they occur.\n\nYou can also manage webhooks via the [Dashboard](https://dashboard.invoicetronic.com).\n\nFor more information, see the **[Webhooks documentation page](https://invoicetronic.com/en/docs/webhooks/)**.", "parameters": [ { "name": "company_id", "in": "query", "description": "Company id", "schema": { "type": "integer", "format": "int32" } }, { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "page_size", "in": "query", "description": "Items per page. Cannot be greater than 200.", "schema": { "type": "integer", "format": "int32", "default": 100 } }, { "name": "sort", "in": "query", "description": "Sort by field. Prefix with '-' for descending order.", "schema": { "type": "string" } }, { "name": "description", "in": "query", "schema": { "type": "string" } }, { "name": "enabled", "in": "query", "schema": { "type": "boolean" } }, { "name": "events", "in": "query", "schema": { "type": "string" } }, { "name": "url", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebHook" } } } } }, "404": { "description": "Not Found" } } }, "post": { "tags": [ "webhook" ], "summary": "Add a webhook", "description": "Create a new webhook subscription.\n\n**Webhooks** allow you to receive notifications to an external service when specific events occur, such as invoice creation or status updates. You can subscribe to specific events and receive a notification when they occur.\n\nYou can also manage webhooks via the [Dashboard](https://dashboard.invoicetronic.com).\n\nFor more information, see the **[Webhooks documentation page](https://invoicetronic.com/en/docs/webhooks/)**.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebHook" } } }, "required": true }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebHook" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "put": { "tags": [ "webhook" ], "summary": "Update a webhook", "description": "Update an existing webhook subscription.\n\n**Webhooks** allow you to receive notifications to an external service when specific events occur, such as invoice creation or status updates. You can subscribe to specific events and receive a notification when they occur.\n\nYou can also manage webhooks via the [Dashboard](https://dashboard.invoicetronic.com).\n\nFor more information, see the **[Webhooks documentation page](https://invoicetronic.com/en/docs/webhooks/)**.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebHook" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebHook" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/webhookhistory/{id}": { "get": { "tags": [ "webhook" ], "summary": "Get a webhook history item by id", "description": "Webhook history items are stored in the database and can be accessed via the API. They are preserved for 15 in both the live and sandbox environments.", "parameters": [ { "name": "id", "in": "path", "description": "Item id", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebHookHistory" } } } }, "404": { "description": "Not Found" } } } }, "/webhookhistory": { "get": { "tags": [ "webhook" ], "summary": "List webhook history items", "description": "Webhook history items are stored in the database and can be accessed via the API. They are preserved for 15 in both the live and sandbox environments.", "parameters": [ { "name": "page", "in": "query", "description": "Page number.", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "page_size", "in": "query", "description": "Items per page. Cannot be greater than 200.", "schema": { "type": "integer", "format": "int32", "default": 100 } }, { "name": "sort", "in": "query", "description": "Sort by field. Prefix with '-' for descending order.", "schema": { "type": "string" } }, { "name": "webhook_id", "in": "query", "description": "WebHook id", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebHookHistory" } } } } }, "404": { "description": "Not Found" } } } } }, "components": { "schemas": { "Allegati": { "type": "object", "properties": { "nome_attachment": { "type": "string", "nullable": true }, "algoritmo_compressione": { "type": "string", "nullable": true }, "formato_attachment": { "type": "string", "nullable": true }, "descrizione_attachment": { "type": "string", "nullable": true }, "attachment": { "type": "string", "format": "byte", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "AltriDatiGestionali": { "type": "object", "properties": { "tipo_dato": { "type": "string", "nullable": true }, "riferimento_testo": { "type": "string", "nullable": true }, "riferimento_numero": { "type": "number", "format": "double", "nullable": true }, "riferimento_data": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "Anagrafica": { "type": "object", "properties": { "denominazione": { "type": "string", "nullable": true }, "nome": { "type": "string", "nullable": true }, "cognome": { "type": "string", "nullable": true }, "titolo": { "type": "string", "nullable": true }, "cod_eori": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "CedentePrestatore": { "type": "object", "properties": { "dati_anagrafici": { "$ref": "#/components/schemas/DatiAnagraficiCedentePrestatore" }, "sede": { "$ref": "#/components/schemas/SedeCedentePrestatore" }, "stabile_organizzazione": { "$ref": "#/components/schemas/StabileOrganizzazione" }, "iscrizione_rea": { "$ref": "#/components/schemas/IscrizioneREA" }, "contatti": { "$ref": "#/components/schemas/Contatti" }, "riferimento_amministrazione": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "CessionarioCommittente": { "type": "object", "properties": { "dati_anagrafici": { "$ref": "#/components/schemas/DatiAnagraficiCessionarioCommittente" }, "sede": { "$ref": "#/components/schemas/SedeCessionarioCommittente" }, "stabile_organizzazione": { "$ref": "#/components/schemas/StabileOrganizzazione" }, "rappresentante_fiscale": { "$ref": "#/components/schemas/RappresentanteFiscaleCessionarioCommittente" } }, "additionalProperties": false, "x-internal": true }, "CodiceArticolo": { "type": "object", "properties": { "codice_tipo": { "type": "string", "nullable": true }, "codice_valore": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "Company": { "required": [ "fiscal_code", "name", "vat" ], "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier. For POST requests, leave it at `0` — the server will assign one automatically.\nFor PUT requests, set it to the id of the record you want to update.", "format": "int32", "example": 0 }, "created": { "type": "string", "description": "Creation date. It is set automatically.", "format": "date-time", "readOnly": true }, "version": { "type": "integer", "description": "Row version, for optimistic concurrency. It is set automatically.", "format": "int32", "readOnly": true }, "user_id": { "type": "integer", "description": "User id. It is set automatically based on the authenticated user.", "format": "int32", "readOnly": true }, "vat": { "minLength": 1, "type": "string", "description": "Vat number. Must include the country code.", "example": "IT01234567891" }, "fiscal_code": { "minLength": 1, "type": "string", "description": "Fiscal code. In most cases it's the same as the vat number.", "example": "RSSMRA70A01F205V" }, "name": { "minLength": 1, "type": "string", "description": "Name", "example": "Mario Rossi Srl" } }, "additionalProperties": false, "description": "A company model." }, "Contatti": { "type": "object", "properties": { "telefono": { "type": "string", "nullable": true }, "fax": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "ContattiTrasmittente": { "type": "object", "properties": { "telefono": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DatiAnagrafici": { "type": "object", "properties": { "id_fiscale_iva": { "$ref": "#/components/schemas/IdFiscaleIVA" }, "codice_fiscale": { "type": "string", "nullable": true }, "anagrafica": { "$ref": "#/components/schemas/Anagrafica" } }, "additionalProperties": false, "x-internal": true }, "DatiAnagraficiCedentePrestatore": { "type": "object", "properties": { "id_fiscale_iva": { "$ref": "#/components/schemas/IdFiscaleIVA" }, "codice_fiscale": { "type": "string", "nullable": true }, "anagrafica": { "$ref": "#/components/schemas/Anagrafica" }, "albo_professionale": { "type": "string", "nullable": true }, "provincia_albo": { "type": "string", "nullable": true }, "numero_iscrizione_albo": { "type": "string", "nullable": true }, "data_iscrizione_albo": { "type": "string", "format": "date-time", "nullable": true }, "regime_fiscale": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DatiAnagraficiCessionarioCommittente": { "type": "object", "properties": { "id_fiscale_iva": { "$ref": "#/components/schemas/IdFiscaleIVA" }, "codice_fiscale": { "type": "string", "nullable": true }, "anagrafica": { "$ref": "#/components/schemas/Anagrafica" } }, "additionalProperties": false, "x-internal": true }, "DatiAnagraficiVettore": { "type": "object", "properties": { "id_fiscale_iva": { "$ref": "#/components/schemas/IdFiscaleIVA" }, "codice_fiscale": { "type": "string", "nullable": true }, "anagrafica": { "$ref": "#/components/schemas/Anagrafica" }, "numero_licenza_guida": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DatiBeniServizi": { "type": "object", "properties": { "dettaglio_linee": { "type": "array", "items": { "$ref": "#/components/schemas/DettaglioLinee" }, "nullable": true }, "dati_riepilogo": { "type": "array", "items": { "$ref": "#/components/schemas/DatiRiepilogo" }, "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DatiBollo": { "type": "object", "properties": { "bollo_virtuale": { "type": "string", "nullable": true }, "importo_bollo": { "type": "number", "format": "double", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DatiCassaPrevidenziale": { "type": "object", "properties": { "tipo_cassa": { "type": "string", "nullable": true }, "al_cassa": { "type": "number", "format": "double" }, "importo_contributo_cassa": { "type": "number", "format": "double" }, "imponibile_cassa": { "type": "number", "format": "double" }, "aliquota_iva": { "type": "number", "format": "double" }, "ritenuta": { "type": "string", "nullable": true }, "natura": { "type": "string", "nullable": true }, "riferimento_amministrazione": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DatiContratto": { "type": "object", "properties": { "riferimento_numero_linea": { "type": "array", "items": { "type": "integer", "format": "int32" }, "nullable": true }, "id_documento": { "type": "string", "nullable": true }, "data": { "type": "string", "format": "date-time", "nullable": true }, "num_item": { "type": "string", "nullable": true }, "codice_commessa_convenzione": { "type": "string", "nullable": true }, "codice_cup": { "type": "string", "nullable": true }, "codice_cig": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DatiConvenzione": { "type": "object", "properties": { "riferimento_numero_linea": { "type": "array", "items": { "type": "integer", "format": "int32" }, "nullable": true }, "id_documento": { "type": "string", "nullable": true }, "data": { "type": "string", "format": "date-time", "nullable": true }, "num_item": { "type": "string", "nullable": true }, "codice_commessa_convenzione": { "type": "string", "nullable": true }, "codice_cup": { "type": "string", "nullable": true }, "codice_cig": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DatiDDT": { "type": "object", "properties": { "numero_ddt": { "type": "string", "nullable": true }, "data_ddt": { "type": "string", "format": "date-time" }, "riferimento_numero_linea": { "type": "array", "items": { "type": "integer", "format": "int32" }, "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DatiFattureCollegate": { "type": "object", "properties": { "riferimento_numero_linea": { "type": "array", "items": { "type": "integer", "format": "int32" }, "nullable": true }, "id_documento": { "type": "string", "nullable": true }, "data": { "type": "string", "format": "date-time", "nullable": true }, "num_item": { "type": "string", "nullable": true }, "codice_commessa_convenzione": { "type": "string", "nullable": true }, "codice_cup": { "type": "string", "nullable": true }, "codice_cig": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DatiGenerali": { "type": "object", "properties": { "dati_generali_documento": { "$ref": "#/components/schemas/DatiGeneraliDocumento" }, "dati_ordine_acquisto": { "type": "array", "items": { "$ref": "#/components/schemas/DatiOrdineAcquisto" }, "nullable": true }, "dati_contratto": { "type": "array", "items": { "$ref": "#/components/schemas/DatiContratto" }, "nullable": true }, "dati_convenzione": { "type": "array", "items": { "$ref": "#/components/schemas/DatiConvenzione" }, "nullable": true }, "dati_ricezione": { "type": "array", "items": { "$ref": "#/components/schemas/DatiRicezione" }, "nullable": true }, "dati_fatture_collegate": { "type": "array", "items": { "$ref": "#/components/schemas/DatiFattureCollegate" }, "nullable": true }, "dati_sal": { "type": "array", "items": { "$ref": "#/components/schemas/DatiSAL" }, "nullable": true }, "dati_ddt": { "type": "array", "items": { "$ref": "#/components/schemas/DatiDDT" }, "nullable": true }, "dati_trasporto": { "$ref": "#/components/schemas/DatiTrasporto" }, "fattura_principale": { "$ref": "#/components/schemas/FatturaPrincipale" } }, "additionalProperties": false, "x-internal": true }, "DatiGeneraliDocumento": { "type": "object", "properties": { "tipo_documento": { "type": "string", "nullable": true }, "divisa": { "type": "string", "nullable": true }, "data": { "type": "string", "format": "date-time" }, "numero": { "type": "string", "nullable": true }, "dati_ritenuta": { "type": "array", "items": { "$ref": "#/components/schemas/DatiRitenuta" }, "nullable": true }, "dati_bollo": { "$ref": "#/components/schemas/DatiBollo" }, "dati_cassa_previdenziale": { "type": "array", "items": { "$ref": "#/components/schemas/DatiCassaPrevidenziale" }, "nullable": true }, "sconto_maggiorazione": { "type": "array", "items": { "$ref": "#/components/schemas/ScontoMaggiorazione" }, "nullable": true }, "importo_totale_documento": { "type": "number", "format": "double", "nullable": true }, "arrotondamento": { "type": "number", "format": "double", "nullable": true }, "causale": { "type": "array", "items": { "type": "string" }, "nullable": true }, "art73": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DatiOrdineAcquisto": { "type": "object", "properties": { "riferimento_numero_linea": { "type": "array", "items": { "type": "integer", "format": "int32" }, "nullable": true }, "id_documento": { "type": "string", "nullable": true }, "data": { "type": "string", "format": "date-time", "nullable": true }, "num_item": { "type": "string", "nullable": true }, "codice_commessa_convenzione": { "type": "string", "nullable": true }, "codice_cup": { "type": "string", "nullable": true }, "codice_cig": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DatiPagamento": { "type": "object", "properties": { "condizioni_pagamento": { "type": "string", "nullable": true }, "dettaglio_pagamento": { "type": "array", "items": { "$ref": "#/components/schemas/DettaglioPagamento" }, "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DatiRicezione": { "type": "object", "properties": { "riferimento_numero_linea": { "type": "array", "items": { "type": "integer", "format": "int32" }, "nullable": true }, "id_documento": { "type": "string", "nullable": true }, "data": { "type": "string", "format": "date-time", "nullable": true }, "num_item": { "type": "string", "nullable": true }, "codice_commessa_convenzione": { "type": "string", "nullable": true }, "codice_cup": { "type": "string", "nullable": true }, "codice_cig": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DatiRiepilogo": { "type": "object", "properties": { "aliquota_iva": { "type": "number", "format": "double" }, "natura": { "type": "string", "nullable": true }, "spese_accessorie": { "type": "number", "format": "double", "nullable": true }, "arrotondamento": { "type": "number", "format": "double", "nullable": true }, "imponibile_importo": { "type": "number", "format": "double" }, "imposta": { "type": "number", "format": "double" }, "esigibilita_iva": { "type": "string", "nullable": true }, "riferimento_normativo": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DatiRitenuta": { "type": "object", "properties": { "tipo_ritenuta": { "type": "string", "nullable": true }, "importo_ritenuta": { "type": "number", "format": "double" }, "aliquota_ritenuta": { "type": "number", "format": "double" }, "causale_pagamento": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DatiSAL": { "type": "object", "properties": { "riferimento_fase": { "type": "integer", "format": "int32" } }, "additionalProperties": false, "x-internal": true }, "DatiTrasmissione": { "type": "object", "properties": { "id_trasmittente": { "$ref": "#/components/schemas/IdTrasmittente" }, "progressivo_invio": { "type": "string", "nullable": true }, "formato_trasmissione": { "type": "string", "nullable": true }, "codice_destinatario": { "type": "string", "nullable": true }, "contatti_trasmittente": { "$ref": "#/components/schemas/ContattiTrasmittente" }, "pec_destinatario": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DatiTrasporto": { "type": "object", "properties": { "dati_anagrafici_vettore": { "$ref": "#/components/schemas/DatiAnagraficiVettore" }, "mezzo_trasporto": { "type": "string", "nullable": true }, "causale_trasporto": { "type": "string", "nullable": true }, "numero_colli": { "type": "integer", "format": "int32", "nullable": true }, "descrizione": { "type": "string", "nullable": true }, "unita_misura_peso": { "type": "string", "nullable": true }, "peso_lordo": { "type": "number", "format": "double", "nullable": true }, "peso_netto": { "type": "number", "format": "double", "nullable": true }, "data_ora_ritiro": { "type": "string", "format": "date-time", "nullable": true }, "data_inizio_trasporto": { "type": "string", "format": "date-time", "nullable": true }, "tipo_resa": { "type": "string", "nullable": true }, "indirizzo_resa": { "$ref": "#/components/schemas/IndirizzoResa" }, "data_ora_consegna": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DatiVeicoli": { "type": "object", "properties": { "data": { "type": "string", "format": "date-time", "nullable": true }, "totale_percorso": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DettaglioLinee": { "type": "object", "properties": { "numero_linea": { "type": "integer", "format": "int32" }, "tipo_cessione_prestazione": { "type": "string", "nullable": true }, "codice_articolo": { "type": "array", "items": { "$ref": "#/components/schemas/CodiceArticolo" }, "nullable": true }, "descrizione": { "type": "string", "nullable": true }, "quantita": { "type": "number", "format": "double", "nullable": true }, "unita_misura": { "type": "string", "nullable": true }, "data_inizio_periodo": { "type": "string", "format": "date-time", "nullable": true }, "data_fine_periodo": { "type": "string", "format": "date-time", "nullable": true }, "prezzo_unitario": { "type": "number", "format": "double" }, "sconto_maggiorazione": { "type": "array", "items": { "$ref": "#/components/schemas/ScontoMaggiorazione" }, "nullable": true }, "prezzo_totale": { "type": "number", "format": "double" }, "aliquota_iva": { "type": "number", "format": "double" }, "ritenuta": { "type": "string", "nullable": true }, "natura": { "type": "string", "nullable": true }, "riferimento_amministrazione": { "type": "string", "nullable": true }, "altri_dati_gestionali": { "type": "array", "items": { "$ref": "#/components/schemas/AltriDatiGestionali" }, "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DettaglioPagamento": { "type": "object", "properties": { "beneficiario": { "type": "string", "nullable": true }, "modalita_pagamento": { "type": "string", "nullable": true }, "data_riferimento_termini_pagamento": { "type": "string", "format": "date-time", "nullable": true }, "giorni_termini_pagamento": { "type": "integer", "format": "int32", "nullable": true }, "data_scadenza_pagamento": { "type": "string", "format": "date-time", "nullable": true }, "importo_pagamento": { "type": "number", "format": "double" }, "cod_ufficio_postale": { "type": "string", "nullable": true }, "cognome_quietanzante": { "type": "string", "nullable": true }, "nome_quietanzante": { "type": "string", "nullable": true }, "cf_quietanzante": { "type": "string", "nullable": true }, "titolo_quietanzante": { "type": "string", "nullable": true }, "istituto_finanziario": { "type": "string", "nullable": true }, "iban": { "type": "string", "nullable": true }, "abi": { "type": "string", "nullable": true }, "cab": { "type": "string", "nullable": true }, "bic": { "type": "string", "nullable": true }, "sconto_pagamento_anticipato": { "type": "number", "format": "double", "nullable": true }, "data_limite_pagamento_anticipato": { "type": "string", "format": "date-time", "nullable": true }, "penalita_pagamenti_ritardati": { "type": "number", "format": "double", "nullable": true }, "data_decorrenza_penale": { "type": "string", "format": "date-time", "nullable": true }, "codice_pagamento": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "DocumentData": { "type": "object", "properties": { "number": { "type": "string", "nullable": true }, "date": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "x-internal": true }, "Error": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code.", "nullable": true }, "description": { "type": "string", "description": "Error description.", "nullable": true }, "hint": { "type": "string", "description": "Hint on how to solve the issue.", "nullable": true } }, "additionalProperties": false, "description": "Validation error from the SDI.", "x-internal": true }, "Event": { "required": [ "endpoint", "method" ], "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier. For POST requests, leave it at `0` — the server will assign one automatically.\nFor PUT requests, set it to the id of the record you want to update.", "format": "int32", "example": 0 }, "created": { "type": "string", "description": "Creation date. It is set automatically.", "format": "date-time", "readOnly": true }, "version": { "type": "integer", "description": "Row version, for optimistic concurrency. It is set automatically.", "format": "int32", "readOnly": true }, "user_id": { "type": "integer", "description": "User id.", "format": "int32" }, "api_key_id": { "type": "integer", "description": "Api key id.", "format": "int32" }, "company_id": { "type": "integer", "description": "Company id.", "format": "int32", "nullable": true }, "method": { "minLength": 1, "type": "string", "description": "Request method." }, "endpoint": { "minLength": 1, "type": "string", "description": "API endpoint." }, "api_version": { "type": "integer", "description": "Api version.", "format": "int32" }, "status_code": { "type": "integer", "description": "Status code returned by the API.", "format": "int32" }, "date_time": { "type": "string", "description": "Date and time of the request.", "format": "date-time" }, "error": { "type": "string", "description": "Response error.", "nullable": true }, "resource_id": { "type": "integer", "description": "ID of the resource created or modified by this request.", "format": "int32", "nullable": true }, "user_agent": { "maxLength": 512, "type": "string", "description": "User-Agent header from the HTTP request.", "nullable": true }, "success": { "type": "boolean", "description": "Whether the request was successful.", "readOnly": true }, "query": { "type": "string", "description": "Request query. Only used for internal logging, not sent to webhooks.", "nullable": true }, "response_body": { "type": "string", "description": "Response payload. It is guaranteed to be encrypted at rest.", "nullable": true } }, "additionalProperties": false, "description": "An API request log entry." }, "FatturaElettronicaBody": { "type": "object", "properties": { "dati_generali": { "$ref": "#/components/schemas/DatiGenerali" }, "dati_beni_servizi": { "$ref": "#/components/schemas/DatiBeniServizi" }, "dati_veicoli": { "$ref": "#/components/schemas/DatiVeicoli" }, "dati_pagamento": { "type": "array", "items": { "$ref": "#/components/schemas/DatiPagamento" }, "nullable": true }, "allegati": { "type": "array", "items": { "$ref": "#/components/schemas/Allegati" }, "nullable": true } }, "additionalProperties": false, "x-internal": true }, "FatturaElettronicaHeader": { "type": "object", "properties": { "dati_trasmissione": { "$ref": "#/components/schemas/DatiTrasmissione" }, "cedente_prestatore": { "$ref": "#/components/schemas/CedentePrestatore" }, "RappresentanteFiscale": { "$ref": "#/components/schemas/RappresentanteFiscale" }, "cessionario_committente": { "$ref": "#/components/schemas/CessionarioCommittente" }, "terzo_intermediario_o_soggetto_emittente": { "$ref": "#/components/schemas/TerzoIntermediarioOSoggettoEmittente" }, "soggetto_emittente": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "FatturaOrdinaria": { "type": "object", "properties": { "sistema_emittente": { "type": "string", "nullable": true }, "fattura_elettronica_header": { "$ref": "#/components/schemas/FatturaElettronicaHeader" }, "fattura_elettronica_body": { "type": "array", "items": { "$ref": "#/components/schemas/FatturaElettronicaBody" }, "nullable": true } }, "additionalProperties": false, "x-internal": true }, "FatturaPrincipale": { "type": "object", "properties": { "numero_fattura_principale": { "type": "string", "nullable": true }, "data_fattura_principale": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "IdFiscaleIVA": { "type": "object", "properties": { "id_paese": { "type": "string", "nullable": true }, "id_codice": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "IdTrasmittente": { "type": "object", "properties": { "id_paese": { "type": "string", "nullable": true }, "id_codice": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "IndirizzoResa": { "type": "object", "properties": { "indirizzo": { "type": "string", "nullable": true }, "numero_civico": { "type": "string", "nullable": true }, "cap": { "type": "string", "nullable": true }, "comune": { "type": "string", "nullable": true }, "provincia": { "type": "string", "nullable": true }, "nazione": { "type": "string", "default": "IT", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "IscrizioneREA": { "type": "object", "properties": { "ufficio": { "type": "string", "nullable": true }, "numero_rea": { "type": "string", "nullable": true }, "capitale_sociale": { "type": "number", "format": "double", "nullable": true }, "socio_unico": { "type": "string", "nullable": true }, "stato_liquidazione": { "type": "string", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32", "nullable": true }, "detail": { "type": "string", "nullable": true }, "instance": { "type": "string", "nullable": true } }, "additionalProperties": { }, "x-internal": true }, "RappresentanteFiscale": { "type": "object", "properties": { "dati_anagrafici": { "$ref": "#/components/schemas/DatiAnagrafici" } }, "additionalProperties": false, "x-internal": true }, "RappresentanteFiscaleCessionarioCommittente": { "type": "object", "properties": { "denominazione": { "type": "string", "nullable": true }, "nome": { "type": "string", "nullable": true }, "cognome": { "type": "string", "nullable": true }, "id_fiscale_iva": { "$ref": "#/components/schemas/IdFiscaleIVA" } }, "additionalProperties": false, "x-internal": true }, "Receive": { "required": [ "payload" ], "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier. For POST requests, leave it at `0` — the server will assign one automatically.\nFor PUT requests, set it to the id of the record you want to update.", "format": "int32", "example": 0 }, "created": { "type": "string", "description": "Creation date. It is set automatically.", "format": "date-time", "readOnly": true }, "version": { "type": "integer", "description": "Row version, for optimistic concurrency. It is set automatically.", "format": "int32", "readOnly": true }, "user_id": { "type": "integer", "description": "User id. It is set automatically based on the authenticated user.", "format": "int32", "readOnly": true }, "company_id": { "type": "integer", "description": "Company id. It is set automatically based on the VAT number extracted from the invoice payload (the sender for `send`, the recipient for `receive`).", "format": "int32", "readOnly": true }, "committente": { "type": "string", "description": "VAT number of the Cessionario/Committente (customer). This is automatically set based on the recipient's VAT number.", "nullable": true, "readOnly": true }, "prestatore": { "type": "string", "description": "VAT number of the Cedente/Prestatore (vendor). This is automatically set based on the sender's VAT number.", "nullable": true, "readOnly": true }, "identifier": { "type": "string", "description": "SDI identifier. This is set by the SDI and is guaranteed to be unique within the SDI system.", "nullable": true, "readOnly": true }, "file_name": { "type": "string", "description": "Xml file name. If not provided on send, it will be auto-generated.", "nullable": true, "example": "IT01180680397ITRON_00001.xml" }, "format": { "type": "string", "description": "SDI format (FPA12, FPR12, FSM10, ...)", "nullable": true, "example": "FPR12" }, "payload": { "minLength": 1, "type": "string", "description": "Xml payload. This is the actual xml content, as string. On send, it can be base64 encoded. If it's not, it will be encoded before sending. It is guaranteed to be encrypted at rest.", "example": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48cDpGYXR0dXJhRWxldHRyb25pY2EgLi4uPjwvcDpGYXR0dXJhRWxldHRyb25pY2E+" }, "last_update": { "type": "string", "description": "Last update from SDI.", "format": "date-time", "nullable": true, "readOnly": true }, "date_sent": { "type": "string", "description": "When the invoice was sent to SDI.", "format": "date-time", "nullable": true, "readOnly": true }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentData" }, "description": "The invoices included in the payload. This is set by the system, based on the xml content.", "nullable": true, "readOnly": true }, "encoding": { "enum": [ "Xml", "Base64" ], "type": "string", "description": "Whether the payload is Base64 encoded or a plain XML (text)." }, "nome_prestatore": { "type": "string", "description": "Business name of the prestatore (supplier/seller) extracted from the invoice XML.", "nullable": true }, "is_read": { "type": "boolean", "description": "Whether the invoice has been read at least once. Set to true only when the invoice is requested with include_payload=true." }, "message_id": { "type": "string", "description": "SDI message id.", "nullable": true } }, "additionalProperties": false, "description": "A received invoice." }, "ScontoMaggiorazione": { "type": "object", "properties": { "tipo": { "type": "string", "nullable": true }, "percentuale": { "type": "number", "format": "double", "nullable": true }, "importo": { "type": "number", "format": "double", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "SedeCedentePrestatore": { "type": "object", "properties": { "indirizzo": { "type": "string", "nullable": true }, "numero_civico": { "type": "string", "nullable": true }, "cap": { "type": "string", "nullable": true }, "comune": { "type": "string", "nullable": true }, "provincia": { "type": "string", "nullable": true }, "nazione": { "type": "string", "default": "IT", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "SedeCessionarioCommittente": { "type": "object", "properties": { "indirizzo": { "type": "string", "nullable": true }, "numero_civico": { "type": "string", "nullable": true }, "cap": { "type": "string", "nullable": true }, "comune": { "type": "string", "nullable": true }, "provincia": { "type": "string", "nullable": true }, "nazione": { "type": "string", "default": "IT", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "Send": { "required": [ "payload" ], "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier. For POST requests, leave it at `0` — the server will assign one automatically.\nFor PUT requests, set it to the id of the record you want to update.", "format": "int32", "example": 0 }, "created": { "type": "string", "description": "Creation date. It is set automatically.", "format": "date-time", "readOnly": true }, "version": { "type": "integer", "description": "Row version, for optimistic concurrency. It is set automatically.", "format": "int32", "readOnly": true }, "user_id": { "type": "integer", "description": "User id. It is set automatically based on the authenticated user.", "format": "int32", "readOnly": true }, "company_id": { "type": "integer", "description": "Company id. It is set automatically based on the VAT number extracted from the invoice payload (the sender for `send`, the recipient for `receive`).", "format": "int32", "readOnly": true }, "committente": { "type": "string", "description": "VAT number of the Cessionario/Committente (customer). This is automatically set based on the recipient's VAT number.", "nullable": true, "readOnly": true }, "prestatore": { "type": "string", "description": "VAT number of the Cedente/Prestatore (vendor). This is automatically set based on the sender's VAT number.", "nullable": true, "readOnly": true }, "identifier": { "type": "string", "description": "SDI identifier. This is set by the SDI and is guaranteed to be unique within the SDI system.", "nullable": true, "readOnly": true }, "file_name": { "type": "string", "description": "Xml file name. If not provided on send, it will be auto-generated.", "nullable": true, "example": "IT01180680397ITRON_00001.xml" }, "format": { "type": "string", "description": "SDI format (FPA12, FPR12, FSM10, ...)", "nullable": true, "example": "FPR12" }, "payload": { "minLength": 1, "type": "string", "description": "Xml payload. This is the actual xml content, as string. On send, it can be base64 encoded. If it's not, it will be encoded before sending. It is guaranteed to be encrypted at rest.", "example": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48cDpGYXR0dXJhRWxldHRyb25pY2EgLi4uPjwvcDpGYXR0dXJhRWxldHRyb25pY2E+" }, "last_update": { "type": "string", "description": "Last update from SDI.", "format": "date-time", "nullable": true, "readOnly": true }, "date_sent": { "type": "string", "description": "When the invoice was sent to SDI.", "format": "date-time", "nullable": true, "readOnly": true }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentData" }, "description": "The invoices included in the payload. This is set by the system, based on the xml content.", "nullable": true, "readOnly": true }, "encoding": { "enum": [ "Xml", "Base64" ], "type": "string", "description": "Whether the payload is Base64 encoded or a plain XML (text)." }, "nome_committente": { "type": "string", "description": "Business name of the committente (client/buyer) extracted from the invoice XML.", "nullable": true, "readOnly": true }, "meta_data": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional metadata, as json.", "nullable": true, "example": { "order_id": "ORD-123" } }, "company": { "$ref": "#/components/schemas/Company" } }, "additionalProperties": false, "description": "A sent invoice." }, "SendReduced": { "type": "object", "properties": { "identifier": { "type": "string", "description": "SDI identifier.", "nullable": true }, "prestatore": { "type": "string", "description": "VAT number of the Cedente/Prestatore (vendor).", "nullable": true }, "meta_data": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional metadata, as json.", "nullable": true }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentData" }, "description": "The invoices included in the payload.", "nullable": true }, "date_sent": { "type": "string", "description": "When the invoice was sent to SDI.", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "Reduced Send data for Update responses, containing only the essential fields.", "x-internal": true }, "StabileOrganizzazione": { "type": "object", "properties": { "indirizzo": { "type": "string", "nullable": true }, "numero_civico": { "type": "string", "nullable": true }, "cap": { "type": "string", "nullable": true }, "comune": { "type": "string", "nullable": true }, "provincia": { "type": "string", "nullable": true }, "nazione": { "type": "string", "default": "IT", "nullable": true } }, "additionalProperties": false, "x-internal": true }, "Status": { "type": "object", "properties": { "operation_left": { "type": "integer", "description": "Operations (invoices and validations) left.", "format": "int32" }, "signature_left": { "type": "integer", "description": "Signatures left.", "format": "int32" }, "has_active_seat": { "type": "boolean", "description": "Whether the current API key has an active Desk seat." }, "is_sub_key": { "type": "boolean", "description": "Whether the current API key is a sub-key (restricted key)." } }, "additionalProperties": false, "description": "Account status with remaining operations and signatures." }, "TerzoIntermediarioOSoggettoEmittente": { "type": "object", "properties": { "dati_anagrafici": { "$ref": "#/components/schemas/DatiAnagrafici" } }, "additionalProperties": false, "x-internal": true }, "Update": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier. For POST requests, leave it at `0` — the server will assign one automatically.\nFor PUT requests, set it to the id of the record you want to update.", "format": "int32", "example": 0 }, "created": { "type": "string", "description": "Creation date. It is set automatically.", "format": "date-time", "readOnly": true }, "version": { "type": "integer", "description": "Row version, for optimistic concurrency. It is set automatically.", "format": "int32", "readOnly": true }, "user_id": { "type": "integer", "description": "User id.", "format": "int32" }, "company_id": { "type": "integer", "description": "Company id.", "format": "int32" }, "send_id": { "type": "integer", "description": "Send id. This is the id of the sent invoice to which this update refers to.", "format": "int32" }, "last_update": { "type": "string", "description": "Last update from SDI.", "format": "date-time" }, "state": { "enum": [ "Inviato", "Consegnato", "NonConsegnato", "Scartato", "AccettatoDalDestinatario", "RifiutatoDalDestinatario", "ImpossibilitaDiRecapito", "DecorrenzaTermini", "AttestazioneTrasmissioneFattura" ], "type": "string", "description": "State of the document. These are the possible values, as per the SDI documentation:" }, "description": { "type": "string", "description": "Description for the state.", "nullable": true }, "message_id": { "type": "string", "description": "SDI message id.", "nullable": true }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Error" }, "description": "SDI errors, if any.", "nullable": true }, "is_read": { "type": "boolean", "description": "Whether the item has been read at least once." }, "send": { "$ref": "#/components/schemas/SendReduced" } }, "additionalProperties": false, "description": "An SDI status update for a sent invoice." }, "WebHook": { "required": [ "url" ], "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier. For POST requests, leave it at `0` — the server will assign one automatically.\nFor PUT requests, set it to the id of the record you want to update.", "format": "int32", "example": 0 }, "created": { "type": "string", "description": "Creation date. It is set automatically.", "format": "date-time", "readOnly": true }, "version": { "type": "integer", "description": "Row version, for optimistic concurrency. It is set automatically.", "format": "int32", "readOnly": true }, "user_id": { "type": "integer", "description": "User id. It is set automatically based on the authenticated user.", "format": "int32", "readOnly": true }, "company_id": { "type": "integer", "description": "Optional company id. If set, the webhook is restricted to events for that company; if omitted, it fires for all companies on the account.", "format": "int32", "nullable": true, "example": 1 }, "url": { "minLength": 1, "type": "string", "description": "The url of your application's endpoint that will receive a POST request when the webhook is fired.", "example": "https://example.com/webhooks/invoicetronic" }, "enabled": { "type": "boolean", "description": "Whether the webhook is enabled. On creation, this is set to `true`." }, "secret": { "type": "string", "description": "The secret used to generate webhook signatures, only returned on creation. You should store this value securely and validate it on every call, to ensure that the caller is InvoicetronicApi.", "nullable": true, "example": "wh_sec_1a2b3c4d5e6f7g8h9i0j" }, "description": { "type": "string", "description": "An optional description.", "nullable": true, "example": "Production webhook" }, "events": { "type": "array", "items": { "type": "string" }, "description": "List of events that trigger the webhook.\nSee Invoicetronic.SupportedEvents.Available for a list of valid event names.", "nullable": true, "example": [ "send.add", "receive.add" ] }, "failure_notified_at": { "type": "string", "description": "Timestamp of the last failure notification email sent for this webhook. Set by the notifier service; reset to null on successful delivery.", "format": "date-time", "nullable": true, "readOnly": true } }, "additionalProperties": false, "description": "A webhook subscription." }, "WebHookHistory": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier. For POST requests, leave it at `0` — the server will assign one automatically.\nFor PUT requests, set it to the id of the record you want to update.", "format": "int32", "example": 0 }, "created": { "type": "string", "description": "Creation date. It is set automatically.", "format": "date-time", "readOnly": true }, "version": { "type": "integer", "description": "Row version, for optimistic concurrency. It is set automatically.", "format": "int32", "readOnly": true }, "web_hook_id": { "type": "integer", "description": "Webhook id.", "format": "int32" }, "user_id": { "type": "integer", "description": "User id.", "format": "int32" }, "event": { "type": "string", "description": "Event name.", "nullable": true }, "status_code": { "type": "integer", "description": "HTTP status code returned by the webhook endpoint. A value of 0 means the request could not be completed due to a network error (e.g., DNS resolution failure, connection refused, or timeout). This typically indicates that the endpoint URL is misconfigured or no longer exists.", "format": "int32" }, "error": { "type": "string", "description": "Error description, if any. Null when the delivery is successful (2xx). Contains the exception message for network errors (status code 0) or the response body for non-2xx HTTP responses.", "nullable": true }, "date_time": { "type": "string", "description": "Date and time of the request.", "format": "date-time" }, "success": { "type": "boolean", "description": "Whether the request was successful.", "readOnly": true } }, "additionalProperties": false, "description": "Webhook history." } }, "securitySchemes": { "Basic": { "type": "http", "description": "Use your API key as the basic auth username, and an empty password. If you don't have an API key, you can get one by signing up at [Invoicetronic](https://invoicetronic.com).", "scheme": "basic" } } }, "security": [ { "Basic": [ ] } ], "tags": [ { "name": "company" }, { "name": "export" }, { "name": "health" }, { "name": "log" }, { "name": "receive" }, { "name": "send" }, { "name": "status" }, { "name": "update" }, { "name": "webhook" } ] }