# API esterna di Invoice Converter Versione: 1.20.0 · Ultimo aggiornamento: 2026-10-02 · URL di base: `https://www.invoice-converter.com/api/v1` Converta documenti fattura (PDF, DOCX, TXT) o dati fattura strutturati provenienti dal Suo sistema ERP, di fatturazione o CRM in fatture elettroniche XRechnung, ZUGFeRD/Factur-X, EN 16931, UBL o CII validate. **URL di base** `https://www.invoice-converter.com/api/v1` · **Autenticazione** `Authorization: Bearer ` · **Contratto** OpenAPI 3.1 (questo documento) Questa pagina è la documentazione completa: le sezioni della guida qui sotto spiegano il flusso, mentre le sezioni su endpoint e schemi elencano ogni campo, valore e risposta. ## Panoramica L’API converte una fattura per richiesta in una fattura elettronica validata. Ogni conversione è asincrona: 1. **Conversione.** `POST /invoices:convert` (documento PDF, DOCX o TXT) oppure `POST /invoices:convert-structured` (i Suoi dati fattura più un PDF di supporto). Risposta: `202` con `task_id`. 2. **Polling.** `GET /tasks/{task_id}` finché `status` è `completed` o `failed`. 3. **Download.** `GET /tasks/{task_id}/result?download=xml|pdf`. Facoltativo: `GET /tasks/{task_id}/validation-report?download=html|xml`. Un task si completa solo quando l’artefatto ha superato la validazione per il profilo richiesto. Non esiste un output in bozza né la possibilità di ignorare gli avvisi. La V1 non offre webhook, endpoint batch né un endpoint per elencare i task. | Endpoint | Scopo | Limite di frequenza per chiave API | |---|---|---| | `POST /invoices:convert` | Convertire un documento | 30/min, 500/h | | `POST /invoices:convert-structured` | Convertire dati strutturati | 30/min, 500/h | | `GET /tasks/{task_id}` | Stato del task | 60/min, 1.500/h | | `GET /tasks/{task_id}/result` | Scaricare l’artefatto | 60/min, 1.000/h | | `GET /tasks/{task_id}/validation-report` | Scaricare il report di validazione | 30/min, 500/h | ## Autenticazione e accesso - Header: `Authorization: Bearer `. - Le chiavi sono credenziali live legate al tenant, con il prefisso `icp_...`. Le crei, le ruoti e le revochi nella pagina del profilo con un abbonamento Enterprise attivo. Non serve un’approvazione separata. - Conservi le chiavi sul proprio server. Non le inserisca mai in codice browser o mobile, nei log o nei ticket. - Token mancante: `401 AUTHENTICATION_REQUIRED`. Chiave sconosciuta o revocata: `401 INVALID_API_KEY`. Chiave valida senza accesso API: `403 API_NOT_ENABLED_FOR_TENANT`. Chiave di un account eliminato: `410 ACCOUNT_DELETED` (l’eliminazione è definitiva; non riprovi). ## Guida rapida ```bash # 1. Convert curl -X POST 'https://www.invoice-converter.com/api/v1/invoices:convert' \ -H 'Authorization: Bearer ' \ -H 'Idempotency-Key: erp-inv-2026-0001' \ -F 'file=@invoice.pdf' \ -F 'format=XRECHNUNG' \ -F 'client_reference=ERP-2026-0001' # 2. Poll (first call about 20 s later) curl 'https://www.invoice-converter.com/api/v1/tasks/' \ -H 'Authorization: Bearer ' # 3. Download download_tmp=$(mktemp) || exit 1 download_meta=$(curl --silent --show-error --output "$download_tmp" \ --write-out '%{http_code} %{content_type}' --dump-header headers.txt \ 'https://www.invoice-converter.com/api/v1/tasks//result?download=xml' \ -H 'Authorization: Bearer ') || { rm -f "$download_tmp"; exit 1; } case "$download_meta" in '200 application/xml'|'200 application/xml;'*|'200 text/xml'|'200 text/xml;'*) mv "$download_tmp" invoice.xml ;; *) rm -f "$download_tmp" printf 'Download not saved (%s). Continue polling on 202.\n' "$download_meta" >&2 exit 1 ;; esac ``` Il corpo della risposta `202` contiene `task_id`, `status` (`pending` o `processing`), `status_url` e `primary_result_url`. Basi la logica su `status`, non su `message`. Salvi l’`X-Correlation-ID` di ogni risposta; il supporto ne ha bisogno. Una risposta di stato completata (abbreviata): ```json { "task_id": "550e8400-e29b-41d4-a716-446655440000", "status": "completed", "progress": 100, "created_at": "2026-09-30T08:00:00+00:00", "completed_at": "2026-09-30T08:01:12+00:00", "error": null, "client_reference": "ERP-2026-0001", "primary_result_url": "/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/result?download=xml", "result_artifacts": { "xml": { "state": "cached", "artifact_state": "compliant", "validation_state": "passed" } } } ``` Per `failed`, `error` contiene un riepilogo (stringa o oggetto); chiami `/result` per ottenere l’errore tipizzato. ## Formati e profili `format` è obbligatorio e sceglie la sintassi e il contenitore. `profile` è facoltativo e sceglie il set di regole. Se omette `profile`, si applica il valore predefinito del formato. | `format` | `profile` consentiti | Predefinito | `download=xml` | `download=pdf` | |---|---|---|---|---| | `XRECHNUNG` | `XRECHNUNG` | `XRECHNUNG` | UBL | PDF renderizzato (best effort) | | `EN16931` | `EN16931` | `EN16931` | UBL | PDF renderizzato (best effort) | | `UBL` | `XRECHNUNG`, `PEPPOL`, `EN16931` | `EN16931` | UBL | PDF renderizzato (best effort) | | `CII` | `XRECHNUNG`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `EN16931` | CII | PDF renderizzato (best effort) | | `ZUGFERD` | `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `ZUGFERD_EN16931` | CII | PDF ibrido ZUGFeRD/Factur-X | - `format` e `profile` non distinguono maiuscole e minuscole. Alias: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`. - Un profilo non elencato per il formato: `422 OUTPUT_PROFILE_CONFLICT`. Un nome di profilo sconosciuto: `422 INVALID_PROFILE` con `details.allowed_profiles`. - Per i formati XML, `download=xml` è l’artefatto principale. Il rendering PDF è una comodità e può non essere disponibile. - `format=ZUGFERD` richiede un PDF come sorgente. Un upload DOCX o TXT viene rifiutato già al caricamento con `422 ZUGFERD_SOURCE_PDF_REQUIRED`. - `jurisdiction` (ISO 3166-1 alpha-2), `transaction_scope` (`B2B`, `B2G`, `B2C`) e `delivery_channel` (`PEPPOL`, `DIRECT_XML`, `PORTAL`, `EMAIL_PDF`, `UNKNOWN`) sono indicazioni di contesto facoltative. Per i flussi B2G tedeschi o Peppol, fornisca il contesto del chiamante al caricamento. Un valore non valido restituisce `422 UPLOAD_FAILED`. ## Conversione di documenti `POST /invoices:convert`, `multipart/form-data`: - `file` (obbligatorio): `.pdf`, `.docx` o `.txt`. Una fattura per file. Un documento con più fatture fallisce con `500 TASK_FAILED`, `details.code=MULTIPLE_INVOICES_IN_DOCUMENT`. - `format` (obbligatorio), `profile`, campi di contesto come sopra. - `client_reference` (≤ 200 caratteri) o il suo alias `external_invoice_id`, e `source_system` (≤ 100 caratteri): restituiti nella risposta `202` e nello stato del task. - `use_embedded_xml` (predefinito `false`): l’XML Factur-X/ZUGFeRD/XRechnung incorporato in un PDF viene ignorato, salvo che questo valore sia `true`. - `email_input`: istruzioni facoltative in testo libero per l’estrazione (solo PDF, ≤ 10.000 caratteri, non insieme a `use_embedded_xml=true`). - `use_seller_master_data` e `seller_master_data`: veda *Dati anagrafici del venditore*. L’estrazione legge il documento. Non inventa dati legali, fiscali, di instradamento, bancari o il riferimento dell’acquirente. Se mancano dati obbligatori, il task fallisce e `/result` restituisce `422 VALIDATION_FAILED`. ## Dati fattura strutturati `POST /invoices:convert-structured` converte dati provenienti dal Suo sistema ERP, di fatturazione o CRM (per esempio Salesforce). - `pdf_file` (obbligatorio): il PDF di supporto. Per `ZUGFERD` l’XML validato viene incorporato in esso; per i formati XML viene archiviato come PDF originale. **Non fornisce mai dati della fattura.** - `data_file` (obbligatorio, ripetibile; alias `data_files`, `data_files[]`): `.json`, `.csv`, `.xml`, `.xlsx` o `.txt`, in totale ≤ 2 MB. - Campi `format`, `profile`, di contesto, di riferimento cliente e di dati anagrafici del venditore come per la conversione di documenti. `email_input` e `use_embedded_xml` non sono accettati. ### Mappatura deterministica e interpretata | Input | Mappatura | Risultato | |---|---|---| | **Un solo** `data_file` JSON nel formato JSON canonico della fattura, al livello superiore o racchiuso in `invoice_data` | Deterministica, senza IA | Stesso input, stesso output | | Un file XML UBL 2.1 Invoice o CII D16B | Deterministica, senza IA | Parser XML di fattura esistente | | Più parti JSON canoniche `data_file` coerenti | Unione deterministica, senza IA | Campi e righe distinti vengono combinati | | CSV, XLSX, TXT, altro XML, JSON personalizzato o piatto, o parti in formati misti | Mappatura con IA | Funziona con etichette chiare; non deterministica | Per un’integrazione ripetibile, invii un solo file JSON canonico: - JSON Schema: - Esempio (XRechnung B2G tedesca, supera i controlli EN 16931, XRechnung e ZUGFeRD rigoroso): Il formato usa i nomi degli elementi UBL 2.1 / EN 16931. Il percorso canonico viene riconosciuto quando sono presenti almeno 3 delle chiavi di primo livello `ID`, `IssueDate`, `InvoiceTypeCode`, `DocumentCurrencyCode`, `AccountingSupplierParty`, `AccountingCustomerParty`, `TaxTotal`, `LegalMonetaryTotal`, `InvoiceLine`, tra cui `ID`, `InvoiceLine` o `LegalMonetaryTotal`. I campi sconosciuti nel JSON canonico restituiscono `400 INVALID_UPLOAD` prima della creazione del task. `details.unknown_paths` elenca fino a 100 percorsi JSON interessati; `details.unknown_path_count` indica il totale. Rimuova i campi non dichiarati invece di fare affidamento sulla loro eliminazione silenziosa. La mappatura con IA ha l’istruzione di non inventare campi mancanti. I dati mancanti fanno quindi fallire la validazione invece di essere dedotti. **Export suddivisi.** Per una fattura suddivisa in più file (per esempio testata e righe), ripeta `data_file`. Invii una richiesta per fattura. - Ogni parte deve contenere lo stesso numero di fattura in una colonna o chiave chiamata `invoice number`, `invoice no`, `invoice no.`, `invoice id`, `rechnungsnr`, `rechnungsnr.`, `rechnung nr`, `rechnung nr.`, `belegnr` o `belegnr.`. - I nomi non distinguono maiuscole e minuscole, e `_` e `-` valgono come spazi, quindi `Invoice_Number` funziona. `document no` e `document number` sono un’alternativa meno affidabile. - Nomi in camelCase come `invoiceNumber` e nomi API di Salesforce come `Invoice_Number__c` vengono riconosciuti. - Un numero mancante o in conflitto restituisce `400 INVALID_UPLOAD` con `details.reason` `bundle_invoice_id_missing` o `bundle_invoice_id_mismatch`. Le parti JSON canoniche usano lo stesso `ID` al livello superiore. Ogni parte deve soddisfare la regola di rilevamento canonico sopra indicata. Le righe richiedono valori `InvoiceLine[].ID` espliciti e univoci in ogni parte. Le righe identiche ripetute tra parti vengono deduplicate; valori in conflitto o righe diverse con lo stesso ID restituiscono `400 INVALID_UPLOAD`, `details.reason=canonical_bundle_conflict` e `details.path`. Il server non sceglie tra valori in conflitto e non ricalcola i totali. Un valore null è considerato assente quando un’altra parte fornisce il dato. ### Dati obbligatori | Sempre | Per XRechnung (anche `UBL`/`CII` con profilo `XRECHNUNG`, e `ZUGFERD_XRECHNUNG`) | Per ZUGFeRD rigoroso | |---|---|---| | `ID`, `IssueDate`, `InvoiceTypeCode`, `DocumentCurrencyCode`, nome del venditore e dell’acquirente, riepilogo IVA, totali, almeno una riga | `BuyerReference` (Leitweg-ID, BR-DE-15); `PaymentMeans` (BR-DE-1); nome, telefono ed e-mail del referente del venditore (BR-DE-2/5/6/7); città e CAP di venditore e acquirente; `EndpointID` di venditore e acquirente con `@schemeID`; `Percent` IVA per ogni subtotale; partita IVA o numero fiscale del venditore | Una data di consegna, un periodo di fatturazione o periodi di riga; un paese di consegna, ove applicabile | I dati mancanti chiudono il task come `failed`; `/result` restituisce `422 VALIDATION_FAILED` con `details.items[]` (`field`, `rule_id`, `severity`, `source`, `suggestion`). ### Percorsi JSON più usati `AccountingSupplierParty.Party` è abbreviato in `Seller`, `AccountingCustomerParty.Party` in `Buyer`. XR = obbligatorio per XRechnung. | Percorso JSON | EN 16931 | XR | |---|---|---| | `ID` | BT-1 | sì | | `IssueDate` | BT-2 | sì | | `InvoiceTypeCode` (per esempio `380` fattura commerciale) | BT-3 | sì | | `DocumentCurrencyCode` | BT-5 | sì | | `DueDate` | BT-9 | – | | `BuyerReference` | BT-10 | sì | | `OrderReference.ID` | BT-13 | – | | `InvoicePeriod.StartDate` / `.EndDate` | BT-73 / BT-74 | – | | `PaymentTerms.Note` | BT-20 | – | | `Seller.PartyLegalEntity.RegistrationName` | BT-27 | sì | | `Seller.PartyTaxScheme.CompanyID` (partita IVA) | BT-31 | sì¹ | | `Seller.EndpointID` (`#text`, `@schemeID`) | BT-34 | sì | | `Seller.PostalAddress.StreetName` | BT-35 | – | | `Seller.PostalAddress.CityName` / `.PostalZone` | BT-37 / BT-38 | sì | | `Seller.PostalAddress.Country.IdentificationCode` | BT-40 | sì | | `Seller.Contact.Name` / `.Telephone` / `.ElectronicMail` | BT-41 / BT-42 / BT-43 | sì | | `Buyer.PartyLegalEntity.RegistrationName` | BT-44 | sì | | `Buyer.EndpointID` (`#text`, `@schemeID`) | BT-49 | sì | | `Buyer.PostalAddress.CityName` / `.PostalZone` | BT-52 / BT-53 | sì | | `Buyer.PostalAddress.Country.IdentificationCode` | BT-55 | sì | | `Delivery.ActualDeliveryDate` | BT-72 | – | | `PaymentMeans.PaymentMeansCode` | BT-81 | sì | | `PaymentMeans.PayeeFinancialAccount.ID` (IBAN) | BT-84 | per bonifico | | `TaxTotal.TaxAmount` | BT-110 | sì | | `TaxTotal.TaxSubtotal[].TaxableAmount` / `.TaxAmount` | BT-116 / BT-117 | sì | | `TaxTotal.TaxSubtotal[].TaxCategory.ID` / `.Percent` | BT-118 / BT-119 | sì | | `LegalMonetaryTotal.LineExtensionAmount` / `.TaxExclusiveAmount` | BT-106 / BT-109 | sì | | `LegalMonetaryTotal.TaxInclusiveAmount` / `.PayableAmount` | BT-112 / BT-115 | sì | | `InvoiceLine[].ID` / `.InvoicedQuantity` / `.unitCode` | BT-126 / BT-129 / BT-130 | sì | | `InvoiceLine[].LineExtensionAmount` | BT-131 | sì | | `InvoiceLine[].Price.PriceAmount` | BT-146 | sì | | `InvoiceLine[].Item.Name` | BT-153 | sì | | `InvoiceLine[].Item.ClassifiedTaxCategory.ID` / `.Percent` | BT-151 / BT-152 | sì | ¹ Partita IVA del venditore (BT-31) o numero fiscale (BT-32, `PartyTaxScheme` con `TaxScheme.ID` `FC`). ## Dati anagrafici del venditore `seller_master_data` è una stringa contenente un oggetto JSON. Si applica solo quando `use_seller_master_data=true`; se il flag è omesso, si applica l’impostazione predefinita dell’account. Chiavi: `business_name`, `trading_name`, `street`, `additional_address`, `postal_code`, `city`, `country`, `vat_id`, `tax_number`, `electronic_address`, `electronic_address_scheme`, `contact_name`, `contact_email`, `contact_phone`, `payment_means_code` (`30`, `42` o `58`), `payment_iban`, `payment_bic`, `payment_account_name`, `payment_terms_note`. Lo schema OpenAPI `SellerMasterData` indica il termine EN 16931 di ogni chiave. - Ogni valore fornito sostituisce il valore estratto del venditore o del pagamento. Le chiavi assenti lasciano la fattura invariata. - `electronic_address` e `electronic_address_scheme` formano una coppia: invii entrambi o nessuno dei due. - JSON non valido, chiavi sconosciute o una coppia incompleta: `400 INVALID_SELLER_MASTER_DATA`. ## Idempotenza e nuovi tentativi - `Idempotency-Key` è obbligatorio su entrambi gli endpoint POST. Formato: 1–200 caratteri, il primo è una lettera o una cifra, poi lettere, cifre, `.`, `_`, `:` o `-` (`^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$`). Una buona chiave è l’ID della Sua fattura più una versione, per esempio `sf-a0B5g00000XyZ12-v1`. - Ambito: tenant ed endpoint, non la singola chiave API. I record vengono conservati 24 ore. - A ogni nuovo tentativo riutilizzi la stessa chiave **e** lo stesso payload. Una ripetizione restituisce la risposta `202` originale con `Idempotency-Replayed: true` e senza un secondo addebito. - **Una chiave, un task.** Una volta accettato un upload, ogni nuovo tentativo con la stessa chiave e lo stesso payload restituisce quel task: lo stesso `task_id` e lo stesso corpo `202`. Questo vale anche se non ha ricevuto la prima risposta o se ha ricevuto un `5xx` dopo l’accettazione del task. Un nuovo tentativo non avvia mai un secondo task e non riserva né addebita mai una seconda unità. - Le richieste con la stessa chiave vengono eseguite una alla volta: le altre ricevono `409 IDEMPOTENCY_IN_PROGRESS`. Un nuovo tentativo dopo il fallimento del task restituisce quel task fallito; per riprovare, usi una nuova chiave. - La stessa chiave con un payload diverso: `409 IDEMPOTENCY_CONFLICT`. La prima richiesta ancora in corso: `409 IDEMPOTENCY_IN_PROGRESS` (riprovi più tardi con la stessa chiave). Il task originale già eliminato: `409 IDEMPOTENCY_REPLAY_EXPIRED` (nuova chiave). - Ripetere un `429` o un `5xx` con la stessa chiave è sicuro: queste risposte non bloccano la chiave. Un nuovo tentativo con la stessa chiave non addebita mai due volte: se un task era già stato accettato, restituisce quel task; altrimenti esegue di nuovo l’upload. Un `5xx` da solo non indica se un task è stato accettato, quindi riprovi sempre con la stessa chiave. ## Limiti, polling e picchi I **limiti di frequenza** valgono per chiave API, con un contingente per endpoint (tabella in *Panoramica*), in finestre fisse di minuto e ora di calendario. Una richiesta rifiutata non viene conteggiata. `429 RATE_LIMITED` contiene `Retry-After`, `X-RateLimit-Limit-Minute`, `X-RateLimit-Limit-Hour` e `details.minute_count`, `hour_count`, `limit_minute`, `limit_hour`. Le risposte riuscite non contengono header di quota. **Polling.** Prima chiamata di stato circa 20 s dopo il `202`, poi dopo 20, 30, 45 e 60 s, poi ogni 60 s. Si fermi a `completed` o `failed`. La maggior parte delle conversioni termina entro due minuti. Il server fa fallire un task dopo 5 minuti senza avanzamento o dopo 15 minuti in totale, quindi imposti il timeout del client a circa 16 minuti. **Dimensione.** I due percorsi di upload su `www.invoice-converter.com` inoltrano direttamente al backend, senza Vercel Function. Limiti predefiniti: file sorgente `file` o supporto `pdf_file` ≤ 20.000.000 byte (20 MB); parti `data_file` ≤ 2.000.000 byte (2 MB) in totale. Il corpo multipart dispone di 1.000.000 byte aggiuntivi: 21 MB per documenti, 23 MB per upload strutturati. Al massimo 20 parti file e 50 campi di testo (`400 INVALID_UPLOAD`). Il superamento di un limite di file o corpo restituisce JSON `413 PAYLOAD_TOO_LARGE` con `details.limit_bytes`. L’autenticazione precede l’ammissione del corpo. Gli errori di infrastruttura possono ancora restituire risposte non JSON. **Picchi** (per esempio centinaia di fatture ricorrenti il primo del mese): le attività accettate attendono in una coda di elaborazione condivisa. Gli upload API usano complessivamente al massimo metà dei posti configurati per processo backend, arrotondata per difetto. La coda predefinita di otto posti ammette quattro attività API e lascia quattro posti ai canali web o ad altri canali. Questo protegge la capacità di ammissione; non garantisce velocità o priorità. Una coda o quota API piena restituisce `503 SERVER_BUSY` con `Retry-After: 15` prima di consumare un posto del limite di conversione o prenotare un’unità. Ripetere un’attività accettata non richiede un altro posto. Schema client consigliato: 1. Mantieni una coda lato client con circa 2–4 conversioni in corso; adattala a `SERVER_BUSY`. 2. Su `429` e `503 SERVER_BUSY`, attendi `Retry-After`, poi riprova con **la stessa** `Idempotency-Key`. 3. Interroga ogni attività con il backoff indicato sopra; avvia la conversione successiva quando una termina. V1 non offre webhook di completamento, endpoint batch o elenco delle attività. ## Errori Ogni errore JSON contiene `code`, `message`, `correlation_id` e di solito `details`. Basi la logica su `code`; per `500 TASK_FAILED` anche su `details.code` e `details.retryable`. `details.type` è di solito presente, ma non sempre. Non basi mai la logica solo sullo stato HTTP o su `message`. Il catalogo completo (ogni codice con stato HTTP, regola di ripetizione e azione) è `ErrorEnvelope.code` nel riferimento OpenAPI. I codici più frequenti: | Codice | HTTP | Riprovare? | Azione | |---|---|---|---| | `AUTHENTICATION_REQUIRED`, `INVALID_API_KEY` | 401 | no | Corregga la chiave. | | `ACCOUNT_DELETED` | 410 | no | L’account di questa chiave è stato eliminato. L’eliminazione è definitiva. | | `IDEMPOTENCY_KEY_REQUIRED`, `INVALID_IDEMPOTENCY_KEY` | 400 | no | Invii un `Idempotency-Key` valido. | | `FORMAT_REQUIRED` / `INVALID_FORMAT` | 400 / 422 | no | Invii un `format` supportato. | | `OUTPUT_PROFILE_CONFLICT`, `INVALID_PROFILE` | 422 | no | Usi un profilo della tabella o lo ometta. | | `INVALID_UPLOAD` | 400 / 415 | no | Corregga il corpo multipart, il tipo di file o i numeri di fattura dell’export suddiviso. | | `FUNCTION_PAYLOAD_TOO_LARGE` (testo semplice) / `PAYLOAD_TOO_LARGE` | 413 | no | Invii una richiesta più piccola. | | `INSUFFICIENT_API_CREDITS` | 402 | no | Acquisti crediti o attenda il mese successivo. | | `IDEMPOTENCY_IN_PROGRESS` | 409 | stessa chiave | Riprovi dopo una breve attesa. | | `IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_REPLAY_EXPIRED` | 409 | no | Usi una nuova chiave. | | `RATE_LIMITED` | 429 | stessa chiave | Attenda `Retry-After`. | | `SERVER_BUSY` | 503 | stessa chiave | Coda di elaborazione piena. Attenda `Retry-After`. | | `UPLOAD_FAILED` | 503 / 500 | stessa chiave | L’upload non è stato accettato, oppure è stato accettato ma non è stato possibile ricostruire la prima risposta. Riprovi con backoff e la stessa chiave. | | `UPLOAD_FAILED` | 422 | no | `jurisdiction`, `transaction_scope` o `delivery_channel` non valido. | | `TASK_NOT_READY` | 202 | polling | Continui a interrogare lo stato. | | `VALIDATION_FAILED` | 422 | no | Corregga i dati (`details.items`), poi converta di nuovo. | | `TASK_FAILED` | 500 | se `details.retryable` | Legga `details.code`. Se ripetibile: nuova conversione con una nuova chiave. | | `AUTHORITATIVE_VALIDATION_UNAVAILABLE` | 503 | sì | Ripeta lo stesso download più tardi. | | `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE` | 503 | nuovo task | Avvii una nuova conversione. | | `INTERNAL_ARTIFACT_INVARIANT_FAILED` | 500 | no | Contatti il supporto indicando l’ID di correlazione. | | `TASK_NOT_FOUND` | 404 | no | Task sconosciuto, task di un altro tenant o eliminato dopo 24 h. | | `PROXY_ERROR` | 502 / 504 | stessa chiave | Riprovi con backoff. | Motivi di `500 TASK_FAILED` in `details.code`: `MULTIPLE_INVOICES_IN_DOCUMENT`, `NO_INVOICE_DETECTED`, `INSUFFICIENT_INVOICE_SIGNAL`, `SCHEMA_PARSE_FAILED`, `ARTIFACT_PARITY_FAILED` (definitivi); `SOURCE_TEXT_UNAVAILABLE`, `PROVIDER_ERROR` (segua `details.retryable`). Un task fallito resta fallito: lo recuperi solo con una nuova conversione e una nuova chiave. ## Risultati, prove e report di validazione - `/result` esegue solo il recupero. Restituisce `200` solo per un artefatto archiviato con una prova di validazione attuale. - Registri gli header della risposta: `X-Correlation-ID`, `X-Artifact-Sha256` (hash dei byte consegnati), `X-Validation-Proof-Id`, `X-Artifact-State` (`compliant`), `X-Validation-State` (`passed`). - `/validation-report?download=html|xml` (parametro obbligatorio) restituisce il report legato all’artefatto consegnato: il report KoSIT oppure, per Factur-X, un XML `validation-evidence` con `source="facturx_php"`. L’evidenza Factur-X prova solo la validazione dell’XML archiviato, non la fedeltà alla sorgente né la conformità PDF/A. Su questo endpoint `X-Artifact-Sha256` è l’hash dell’artefatto di risultato validato, non del report. Nessun report per l’artefatto attuale: `404 VALIDATION_REPORT_NOT_FOUND`. - `result_artifacts..state` nello stato del task: `cached`, `not_ready`, `validation_failed`, `dependency_failed`, `artifact_generation_rerun_required`, `artifact_invariant_failed`. ## Conservazione, fatturazione e archiviazione - **Conservazione.** Task, artefatti e record di idempotenza vengono eliminati 24 ore dopo la conclusione del task. In seguito ogni endpoint dei task restituisce `404 TASK_NOT_FOUND`. Le evidenze di controllo qualità seguono i tempi di conservazione indicati nella sezione 9 dell’[Accordo sul trattamento dei dati](https://www.invoice-converter.com/it/dpa). - **Fatturazione.** Ogni conversione accettata usa un’unità. Enterprise include 100 unità per mese di calendario, condivise con l’importazione via e-mail. Le unità aggiuntive usano crediti prepagati: 100 per 50 EUR, 200 per 100 EUR, 500 per 250 EUR, 1.000 per 400 EUR. Ripetizioni, conversioni fallite e tutte le chiamate ai task sono gratuite. Quando nessuna copertura è disponibile per un’unità: `402 INSUFFICIENT_API_CREDITS` (due strutture di `details`, veda la risposta OpenAPI `PaymentRequired`). - **Archiviazione.** Costruisca il pacchetto di archiviazione durante il flusso, non dopo: PDF originale, XML generato o PDF ibrido, report di validazione e un record di metadati con `task_id`, `client_reference`, formato/profilo, `X-Artifact-Sha256`, `X-Validation-Proof-Id`, `X-Validation-Report-Proof-Id`, `created_at`/`completed_at` e gli ID di correlazione. ## Supporto e contratto - Contatto: `contact@invoice-converter.com`. Indichi l’`X-Correlation-ID`. - L’API è fornita secondo i Termini standard e il DPA e un eventuale order form Enterprise. Non si applica alcuno SLA su disponibilità, tempi di elaborazione o supporto, salvo diversa indicazione in un order form. - Documenti sorgente di scarsa qualità e casi limite richiedono una revisione umana. Mantenga un proprio processo per eccezioni, correzioni, recapito e archiviazione. - L’accesso API è destinato all’uso nella propria attività. Rivendita, uso white-label o come service bureau richiedono un accordo di partnership. ## Artefatti di riferimento - OpenAPI 3.1: - Collection Postman: (imposti `base_url`, `api_key`, `idempotency_key`) - JSON Schema ed esempio della fattura strutturata: veda *Dati fattura strutturati* - Canale fatture via e-mail: - Questa documentazione in Markdown (per LLM e lettura offline): ## Endpoint ### POST /invoices:convert — Convertire un documento fattura Carichi un documento fattura e avvii una conversione rigorosa. - `file`: `.pdf`, `.docx` o `.txt`, una fattura per file. File sorgente ≤ 20 MB (20.000.000 byte); corpo multipart completo ≤ 21 MB. - `format` è obbligatorio; `profile` è facoltativo (valore predefinito per formato qui sotto). - L’XML incorporato in un PDF viene ignorato, salvo `use_embedded_xml=true`. - Limite di frequenza: 30/min e 500/h per chiave API. | `format` | `profile` consentiti | Predefinito | `download=xml` | `download=pdf` | |---|---|---|---|---| | `XRECHNUNG` | `XRECHNUNG` | `XRECHNUNG` | UBL | PDF renderizzato (best effort) | | `EN16931` | `EN16931` | `EN16931` | UBL | PDF renderizzato (best effort) | | `UBL` | `XRECHNUNG`, `PEPPOL`, `EN16931` | `EN16931` | UBL | PDF renderizzato (best effort) | | `CII` | `XRECHNUNG`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `EN16931` | CII | PDF renderizzato (best effort) | | `ZUGFERD` | `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | `ZUGFERD_EN16931` | CII | PDF ibrido ZUGFeRD/Factur-X | **Parametri** | Nome | Posizione | Tipo | Obbligatorio | Descrizione | | --- | --- | --- | --- | --- | | `Idempotency-Key` | header | string | sì | Obbligatorio su entrambi gli endpoint POST. Riutilizzi la stessa chiave con lo stesso payload a ogni nuovo tentativo; una ripetizione restituisce il `202` originale senza un secondo addebito. Ambito: tenant + endpoint, conservato 24 h. Mancante → `400 IDEMPOTENCY_KEY_REQUIRED`; malformato → `400 INVALID_IDEMPOTENCY_KEY`; stessa chiave con un altro payload → `409 IDEMPOTENCY_CONFLICT`. | | `X-Correlation-ID` | header | string (uuid) | | UUID facoltativo per il tracciamento. Un valore mancante o non UUID viene sostituito da un UUID generato dal server. Restituito nell’header di risposta `X-Correlation-ID`; lo indichi al supporto. | **Corpo della richiesta** (`multipart/form-data`) | Nome | Tipo | Obbligatorio | Descrizione | | --- | --- | --- | --- | | `file` | string (binary) | sì | Il documento fattura: `.pdf`, `.docx` o `.txt`, una fattura per file. `.doc`, `.rtf` e immagini vengono rifiutati (`400 INVALID_UPLOAD`). `format=ZUGFERD` richiede un PDF (`422 ZUGFERD_SOURCE_PDF_REQUIRED`). | | `format` | string: `XRECHNUNG`, `ZUGFERD`, `EN16931`, `UBL`, `CII` | sì | Formato di output di destinazione. Obbligatorio; non esiste un valore predefinito. Non distingue maiuscole e minuscole. Mancante → `400 FORMAT_REQUIRED`; sconosciuto → `422 INVALID_FORMAT`. | | `profile` | string: `XRECHNUNG`, `PEPPOL`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | | Set di regole rispetto al quale viene validato l’artefatto. Facoltativo: ogni `format` ha un valore predefinito (veda la tabella dell’operazione). Non distingue maiuscole e minuscole. Alias: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`; `ZUGFERD-XRECHNUNG` → `ZUGFERD_XRECHNUNG`. Non consentito per questo formato → `422 OUTPUT_PROFILE_CONFLICT`; nome sconosciuto → `422 INVALID_PROFILE`. | | `jurisdiction` | string | | Paese della transazione secondo ISO 3166-1 alpha-2, per esempio `DE`. Contesto facoltativo. Non valido → `422 UPLOAD_FAILED`. | | `transaction_scope` | string: `B2B`, `B2G`, `B2C` | | Indicazione di contesto facoltativa. Non valida → `422 UPLOAD_FAILED`. | | `delivery_channel` | string: `PEPPOL`, `DIRECT_XML`, `PORTAL`, `EMAIL_PDF`, `UNKNOWN` | | Indicazione di contesto facoltativa: `EMAIL_PDF` per la consegna di PDF ibridi, `DIRECT_XML` per l’integrazione XML diretta, `PEPPOL` per la consegna tramite rete. Non valida → `422 UPLOAD_FAILED`. | | `client_reference` | string | | Il Suo riferimento di fattura o di job. Restituito nella risposta 202 e nello stato del task. Nessun carattere di controllo. `external_invoice_id` è accettato come alias; se vengono inviati entrambi, devono coincidere, altrimenti `400 CLIENT_REFERENCE_CONFLICT`. | | `source_system` | string | | Etichetta del sistema ERP o di fatturazione chiamante. Restituita nella risposta 202 e nello stato del task. | | `use_embedded_xml` | boolean | | Usa come fonte di estrazione l’XML Factur-X/ZUGFeRD/XRechnung incorporato nel PDF. Predefinito `false`: l’XML incorporato viene ignorato e viene letto il documento visibile. | | `email_input` | string | | Istruzioni in testo libero per l’estrazione, in qualsiasi lingua (solo sorgente PDF). Non combinabile con `use_embedded_xml=true`. Fa parte dell’identità di idempotenza. Non valido → `400 INVALID_EMAIL_INPUT`. | | `use_seller_master_data` | boolean | | Applica i dati anagrafici del venditore. Omesso: si applica l’impostazione predefinita dell’account. `false`: ignora i dati del venditore salvati per questa richiesta. `true`: applica i dati salvati e `seller_master_data`. | | `seller_master_data` | string | | Stringa con un oggetto JSON (schema: `SellerMasterData`). Applicata solo con `use_seller_master_data=true`. Ogni valore fornito sostituisce il valore estratto del venditore o del pagamento; le chiavi assenti lasciano la fattura invariata. Non valida → `400 INVALID_SELLER_MASTER_DATA`. | ```json { "$ref": "#/components/schemas/ConvertInvoiceRequest" } ``` **Risposte** - `202`: Accettata. Interroghi `status_url`. Un nuovo tentativo con lo stesso Idempotency-Key e lo stesso payload restituisce il task già accettato: lo stesso task_id e lo stesso corpo 202, con l’header Idempotency-Replayed: true. Questo vale anche quando la prima risposta è andata persa o era un 5xx dopo l’accettazione del task, e dopo il fallimento del task. Non avvia mai un secondo task e non riserva né addebita mai una seconda unità. `application/json` ```json { "$ref": "#/components/schemas/ConvertAcceptedResponse" } ``` - `400`: Richiesta non valida. Da non ripetere: corregga la richiesta. Veda `ErrorEnvelope.code` per tutti i codici 400. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `401`: Autenticazione non riuscita. Da non ripetere. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `402`: `402 INSUFFICIENT_API_CREDITS`. Da non ripetere: acquisti un pacchetto di crediti prepagati o attenda la prossima quota mensile. Due strutture di `details`; legga le chiavi presenti. `application/json` ```json { "oneOf": [ { "$ref": "#/components/schemas/InsufficientApiCreditsPrepaidError" }, { "$ref": "#/components/schemas/InsufficientApiCreditsAllowanceError" } ] } ``` - `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Da non ripetere: contatti il supporto. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `405`: `405 METHOD_NOT_ALLOWED`: i percorsi di conversione accettano POST; OPTIONS restituisce 204. Il backend restituisce un errore JSON con `correlation_id` per i metodi non supportati. HEAD non restituisce un corpo. `application/json` ```json { "$ref": "#/components/schemas/EdgeError" } ``` - `409`: Conflitto di idempotenza. `IDEMPOTENCY_IN_PROGRESS`: riprovi con la stessa chiave dopo una breve attesa (una richiesta bloccata viene rilasciata dopo 15 min). `IDEMPOTENCY_CONFLICT` e `IDEMPOTENCY_REPLAY_EXPIRED`: usi una nuova chiave. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `410`: 410 ACCOUNT_DELETED. La chiave API si autentica ancora, ma il relativo account è stato eliminato. L’eliminazione è definitiva, quindi la risposta è 410 Gone su ogni percorso che la segnala. Da non ripetere. Una chiave revocata restituisce invece 401 INVALID_API_KEY. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `413`: Richiesta troppo grande. Non riprovabile: inviare una richiesta più piccola. Gli upload vanno direttamente al backend. I limiti di file e corpo multipart restituiscono JSON `413 PAYLOAD_TOO_LARGE` con `details.limit_bytes`. Limiti predefiniti: file sorgente o supporto 20 MB, parti di dati strutturati 2 MB in totale; corpo multipart completo 21 MB per documenti o 23 MB per upload strutturati (incluso 1 MB aggiuntivo). `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` `text/plain` ```json { "type": "string" } ``` - `415`: `415 INVALID_UPLOAD`: invii `multipart/form-data`. Da non ripetere. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `422`: Validazione dell’upload o delle opzioni della richiesta non riuscita. Da non ripetere: corregga la richiesta. Codici: `INVALID_FORMAT`, `INVALID_PROFILE`, `OUTPUT_PROFILE_CONFLICT`, `OUTPUT_PROFILE_REQUIRED`, `UPLOAD_FAILED` (valore di contesto non valido), `ZUGFERD_SOURCE_PDF_REQUIRED`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `429`: `429 RATE_LIMITED`. Ripetibile: attenda `Retry-After` secondi e riprovi con lo stesso Idempotency-Key. I limiti valgono per chiave API ed endpoint, in finestre fisse di minuto e ora di calendario. Le richieste rifiutate non vengono conteggiate. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `500`: Errore lato server. Per impostazione predefinita un 500 non è ripetibile. `TASK_FAILED`: legga `details.code`; solo `details.retryable: true` consente un nuovo tentativo, e solo come NUOVA conversione con un nuovo Idempotency-Key. `INTERNAL_ARTIFACT_INVARIANT_FAILED`: contatti il supporto. `UPLOAD_FAILED` all’upload: riprovi con la stessa chiave. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `502`: `502 PROXY_ERROR`: l’edge non ha raggiunto il backend. Riprovi con backoff e lo stesso Idempotency-Key. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `503`: Temporaneamente non disponibile. Riprovi con lo stesso Idempotency-Key. `SERVER_BUSY`: la coda di elaborazione è piena; attenda `Retry-After` secondi. `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `API_CREDIT_SERVICE_UNAVAILABLE`, `UPLOAD_FAILED` (altro errore di accettazione): riprovi con backoff. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `504`: `504 PROXY_ERROR`: il backend non ha risposto in tempo. Riprovi con backoff e lo stesso Idempotency-Key. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` ### POST /invoices:convert-structured — Convertire dati fattura strutturati Converta i dati fattura del Suo sistema. `data_file` è l’unica fonte dei dati; `pdf_file` è solo il supporto (incorporato per ZUGFeRD, altrimenti archiviato come PDF originale). - **Deterministica:** un JSON `data_file` nel formato `StructuredInvoiceData`, parti JSON canoniche coerenti o un file XML UBL 2.1 Invoice / CII D16B vengono mappati senza IA ([schema](https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json), [esempio](https://www.invoice-converter.com/developer-api/v1/invoice-data.example.json)). - **Interpretata:** CSV, XLSX, TXT, altro XML, JSON personalizzato e parti in formati misti usano la mappatura con IA, che lascia vuoti i campi mancanti. - Export suddivisi: ripeta `data_file`; tutte le parti richiedono lo stesso numero di fattura. Colonne come `Invoice Number`, `Rechnungsnr`, `invoiceNumber` e `Invoice_Number__c` vengono riconosciute; il JSON canonico usa `ID`. - JSON canonico: i campi sconosciuti restituiscono `400 INVALID_UPLOAD` con `details.unknown_paths`; i valori in conflitto dell’insieme restituiscono `details.reason=canonical_bundle_conflict` e `details.path`. Le righe richiedono valori `InvoiceLine[].ID` espliciti e univoci in ogni parte. - Limiti: `pdf_file` ≤ 20 MB, parti `data_file` ≤ 2 MB in totale, corpo multipart completo ≤ 23 MB. Limite di frequenza: 30/min e 500/h per chiave API. - Le regole per `format` e `profile` sono le stesse di `POST /invoices:convert`. **Parametri** | Nome | Posizione | Tipo | Obbligatorio | Descrizione | | --- | --- | --- | --- | --- | | `Idempotency-Key` | header | string | sì | Obbligatorio su entrambi gli endpoint POST. Riutilizzi la stessa chiave con lo stesso payload a ogni nuovo tentativo; una ripetizione restituisce il `202` originale senza un secondo addebito. Ambito: tenant + endpoint, conservato 24 h. Mancante → `400 IDEMPOTENCY_KEY_REQUIRED`; malformato → `400 INVALID_IDEMPOTENCY_KEY`; stessa chiave con un altro payload → `409 IDEMPOTENCY_CONFLICT`. | | `X-Correlation-ID` | header | string (uuid) | | UUID facoltativo per il tracciamento. Un valore mancante o non UUID viene sostituito da un UUID generato dal server. Restituito nell’header di risposta `X-Correlation-ID`; lo indichi al supporto. | **Corpo della richiesta** (`multipart/form-data`) | Nome | Tipo | Obbligatorio | Descrizione | | --- | --- | --- | --- | | `pdf_file` | string (binary) | sì | PDF di supporto. Per `ZUGFERD` l’XML validato viene incorporato in esso; per i formati XML viene archiviato come PDF originale. Non fornisce mai dati della fattura. | | `data_file` | oneOf(string (binary), array of string (binary)) | sì | Dati fattura: `.json`, `.csv`, `.xml`, `.xlsx` o `.txt` (≤ 2 MB in totale). Il JSON canonico (al livello superiore o racchiuso in `invoice_data`), le parti JSON canoniche coerenti e un file XML UBL 2.1 Invoice / CII D16B vengono mappati senza IA; gli altri formati usano la mappatura con IA. I campi canonici sconosciuti e i dati in conflitto dell’insieme restituiscono `400 INVALID_UPLOAD`. Ripeta la parte per una fattura suddivisa in più file; tutte le parti richiedono lo stesso numero di fattura e le righe canoniche richiedono ID espliciti e univoci. Schema: https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json. I nomi dei campi `data_files` e `data_files[]` sono accettati come alias. | | `format` | string: `XRECHNUNG`, `ZUGFERD`, `EN16931`, `UBL`, `CII` | sì | Formato di output di destinazione. Obbligatorio; non esiste un valore predefinito. Non distingue maiuscole e minuscole. Mancante → `400 FORMAT_REQUIRED`; sconosciuto → `422 INVALID_FORMAT`. | | `profile` | string: `XRECHNUNG`, `PEPPOL`, `EN16931`, `ZUGFERD_EN16931`, `ZUGFERD_FACTURX_EXTENDED`, `ZUGFERD_XRECHNUNG` | | Set di regole rispetto al quale viene validato l’artefatto. Facoltativo: ogni `format` ha un valore predefinito (veda la tabella dell’operazione). Non distingue maiuscole e minuscole. Alias: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`; `ZUGFERD-XRECHNUNG` → `ZUGFERD_XRECHNUNG`. Non consentito per questo formato → `422 OUTPUT_PROFILE_CONFLICT`; nome sconosciuto → `422 INVALID_PROFILE`. | | `jurisdiction` | string | | Paese della transazione secondo ISO 3166-1 alpha-2, per esempio `DE`. Contesto facoltativo. Non valido → `422 UPLOAD_FAILED`. | | `transaction_scope` | string: `B2B`, `B2G`, `B2C` | | Indicazione di contesto facoltativa. Non valida → `422 UPLOAD_FAILED`. | | `delivery_channel` | string: `PEPPOL`, `DIRECT_XML`, `PORTAL`, `EMAIL_PDF`, `UNKNOWN` | | Indicazione di contesto facoltativa: `EMAIL_PDF` per la consegna di PDF ibridi, `DIRECT_XML` per l’integrazione XML diretta, `PEPPOL` per la consegna tramite rete. Non valida → `422 UPLOAD_FAILED`. | | `client_reference` | string | | Il Suo riferimento di fattura o di job. Restituito nella risposta 202 e nello stato del task. Nessun carattere di controllo. `external_invoice_id` è accettato come alias; se vengono inviati entrambi, devono coincidere, altrimenti `400 CLIENT_REFERENCE_CONFLICT`. | | `source_system` | string | | Etichetta del sistema ERP o di fatturazione chiamante. Restituita nella risposta 202 e nello stato del task. | | `use_seller_master_data` | boolean | | Applica i dati anagrafici del venditore. Omesso: si applica l’impostazione predefinita dell’account. `false`: ignora i dati del venditore salvati per questa richiesta. `true`: applica i dati salvati e `seller_master_data`. | | `seller_master_data` | string | | Stringa con un oggetto JSON (schema: `SellerMasterData`). Applicata solo con `use_seller_master_data=true`. Ogni valore fornito sostituisce il valore estratto del venditore o del pagamento; le chiavi assenti lasciano la fattura invariata. Non valida → `400 INVALID_SELLER_MASTER_DATA`. | ```json { "$ref": "#/components/schemas/ConvertStructuredInvoiceRequest" } ``` **Risposte** - `202`: Accettata. Interroghi `status_url`. Un nuovo tentativo con lo stesso Idempotency-Key e lo stesso payload restituisce il task già accettato: lo stesso task_id e lo stesso corpo 202, con l’header Idempotency-Replayed: true. Questo vale anche quando la prima risposta è andata persa o era un 5xx dopo l’accettazione del task, e dopo il fallimento del task. Non avvia mai un secondo task e non riserva né addebita mai una seconda unità. `application/json` ```json { "$ref": "#/components/schemas/ConvertAcceptedResponse" } ``` - `400`: Richiesta non valida. Da non ripetere: corregga la richiesta. Veda `ErrorEnvelope.code` per tutti i codici 400. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `401`: Autenticazione non riuscita. Da non ripetere. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `402`: `402 INSUFFICIENT_API_CREDITS`. Da non ripetere: acquisti un pacchetto di crediti prepagati o attenda la prossima quota mensile. Due strutture di `details`; legga le chiavi presenti. `application/json` ```json { "oneOf": [ { "$ref": "#/components/schemas/InsufficientApiCreditsPrepaidError" }, { "$ref": "#/components/schemas/InsufficientApiCreditsAllowanceError" } ] } ``` - `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Da non ripetere: contatti il supporto. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `405`: `405 METHOD_NOT_ALLOWED`: i percorsi di conversione accettano POST; OPTIONS restituisce 204. Il backend restituisce un errore JSON con `correlation_id` per i metodi non supportati. HEAD non restituisce un corpo. `application/json` ```json { "$ref": "#/components/schemas/EdgeError" } ``` - `409`: Conflitto di idempotenza. `IDEMPOTENCY_IN_PROGRESS`: riprovi con la stessa chiave dopo una breve attesa (una richiesta bloccata viene rilasciata dopo 15 min). `IDEMPOTENCY_CONFLICT` e `IDEMPOTENCY_REPLAY_EXPIRED`: usi una nuova chiave. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `410`: 410 ACCOUNT_DELETED. La chiave API si autentica ancora, ma il relativo account è stato eliminato. L’eliminazione è definitiva, quindi la risposta è 410 Gone su ogni percorso che la segnala. Da non ripetere. Una chiave revocata restituisce invece 401 INVALID_API_KEY. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `413`: Richiesta troppo grande. Non riprovabile: inviare una richiesta più piccola. Gli upload vanno direttamente al backend. I limiti di file e corpo multipart restituiscono JSON `413 PAYLOAD_TOO_LARGE` con `details.limit_bytes`. Limiti predefiniti: file sorgente o supporto 20 MB, parti di dati strutturati 2 MB in totale; corpo multipart completo 21 MB per documenti o 23 MB per upload strutturati (incluso 1 MB aggiuntivo). `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` `text/plain` ```json { "type": "string" } ``` - `415`: `415 INVALID_UPLOAD`: invii `multipart/form-data`. Da non ripetere. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `422`: Validazione dell’upload o delle opzioni della richiesta non riuscita. Da non ripetere: corregga la richiesta. Codici: `INVALID_FORMAT`, `INVALID_PROFILE`, `OUTPUT_PROFILE_CONFLICT`, `OUTPUT_PROFILE_REQUIRED`, `UPLOAD_FAILED` (valore di contesto non valido), `ZUGFERD_SOURCE_PDF_REQUIRED`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `429`: `429 RATE_LIMITED`. Ripetibile: attenda `Retry-After` secondi e riprovi con lo stesso Idempotency-Key. I limiti valgono per chiave API ed endpoint, in finestre fisse di minuto e ora di calendario. Le richieste rifiutate non vengono conteggiate. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `500`: Errore lato server. Per impostazione predefinita un 500 non è ripetibile. `TASK_FAILED`: legga `details.code`; solo `details.retryable: true` consente un nuovo tentativo, e solo come NUOVA conversione con un nuovo Idempotency-Key. `INTERNAL_ARTIFACT_INVARIANT_FAILED`: contatti il supporto. `UPLOAD_FAILED` all’upload: riprovi con la stessa chiave. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `502`: `502 PROXY_ERROR`: l’edge non ha raggiunto il backend. Riprovi con backoff e lo stesso Idempotency-Key. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `503`: Temporaneamente non disponibile. Riprovi con lo stesso Idempotency-Key. `SERVER_BUSY`: la coda di elaborazione è piena; attenda `Retry-After` secondi. `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `API_CREDIT_SERVICE_UNAVAILABLE`, `UPLOAD_FAILED` (altro errore di accettazione): riprovi con backoff. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `504`: `504 PROXY_ERROR`: il backend non ha risposto in tempo. Riprovi con backoff e lo stesso Idempotency-Key. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` ### GET /tasks/{task_id} — Leggere lo stato del task Restituisce lo stato del task. Interroghi finché `status` è `completed` o `failed`. - Backoff: prima chiamata ~20 s dopo il `202`, poi 20, 30, 45, 60 s, poi ogni 60 s. Si fermi dopo ~16 min. - `completed`: scarichi da `primary_result_url`. `failed`: chiami `/result` per l’errore tipizzato. - Task sconosciuto, oppure oltre 24 h dopo la conclusione: `404 TASK_NOT_FOUND`. - Limite di frequenza: 60/min e 1.500/h per chiave API. **Parametri** | Nome | Posizione | Tipo | Obbligatorio | Descrizione | | --- | --- | --- | --- | --- | | `task_id` | path | string (uuid) | sì | `task_id` della risposta `202`. Non è un UUID → `400 BAD_REQUEST`. | | `include_validation_report_html` | query | string: `true`, `false` | | `true` aggiunge l’HTML sanificato del report di validazione come `validation_report_html`. Valori diversi da `true`/`false` → `400 INVALID_QUERY_PARAMETER`. | | `X-Correlation-ID` | header | string (uuid) | | UUID facoltativo per il tracciamento. Un valore mancante o non UUID viene sostituito da un UUID generato dal server. Restituito nell’header di risposta `X-Correlation-ID`; lo indichi al supporto. | **Risposte** - `200`: Stato attuale del task. `application/json` ```json { "$ref": "#/components/schemas/TaskStatusResponse" } ``` - `400`: Richiesta non valida. Da non ripetere: corregga la richiesta. Veda `ErrorEnvelope.code` per tutti i codici 400. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `401`: Autenticazione non riuscita. Da non ripetere. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Da non ripetere: contatti il supporto. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `404`: `404 TASK_NOT_FOUND`: task sconosciuto, task di un altro tenant o eliminato 24 h dopo la conclusione. Da non ripetere. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `405`: `405 METHOD_NOT_ALLOWED`: i percorsi dei task accettano solo GET. Inviato dal proxy edge, quindi il corpo non contiene `correlation_id`. `application/json` ```json { "$ref": "#/components/schemas/EdgeError" } ``` - `410`: 410 ACCOUNT_DELETED. La chiave API si autentica ancora, ma il relativo account è stato eliminato. L’eliminazione è definitiva, quindi la risposta è 410 Gone su ogni percorso che la segnala. Da non ripetere. Una chiave revocata restituisce invece 401 INVALID_API_KEY. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `429`: `429 RATE_LIMITED`. Ripetibile: attenda `Retry-After` secondi e riprovi con lo stesso Idempotency-Key. I limiti valgono per chiave API ed endpoint, in finestre fisse di minuto e ora di calendario. Le richieste rifiutate non vengono conteggiate. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `500`: Errore lato server. Per impostazione predefinita un 500 non è ripetibile. `TASK_FAILED`: legga `details.code`; solo `details.retryable: true` consente un nuovo tentativo, e solo come NUOVA conversione con un nuovo Idempotency-Key. `INTERNAL_ARTIFACT_INVARIANT_FAILED`: contatti il supporto. `UPLOAD_FAILED` all’upload: riprovi con la stessa chiave. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `502`: `502 PROXY_ERROR`: l’edge non ha raggiunto il backend. Riprovi con backoff e lo stesso Idempotency-Key. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `503`: Temporaneamente non disponibile. Riprovi con backoff: `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `AUTHORITATIVE_VALIDATION_UNAVAILABLE`. Avvii invece una NUOVA conversione: `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `504`: `504 PROXY_ERROR`: il backend non ha risposto in tempo. Riprovi con backoff e lo stesso Idempotency-Key. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` ### GET /tasks/{task_id}/result — Scaricare il risultato Scarichi l’artefatto validato. Solo recupero: questa chiamata non genera, corregge né valida nulla. - `download=xml`: UBL (`XRECHNUNG`, `EN16931`, `UBL`) o CII (`CII`, `ZUGFERD`). Sempre l’artefatto principale per i formati XML. - `download=pdf`: PDF ibrido ZUGFeRD/Factur-X per `ZUGFERD`; un rendering best effort per gli altri formati. - Durante l’elaborazione: `202 TASK_NOT_READY`. Task fallito: il suo errore tipizzato (`422 VALIDATION_FAILED`, `500 TASK_FAILED`, `503 ...`). - Limite di frequenza: 60/min e 1.000/h per chiave API. **Parametri** | Nome | Posizione | Tipo | Obbligatorio | Descrizione | | --- | --- | --- | --- | --- | | `task_id` | path | string (uuid) | sì | `task_id` della risposta `202`. Non è un UUID → `400 BAD_REQUEST`. | | `download` | query | string: `xml`, `pdf` | sì | Artefatto da scaricare (senza distinzione tra maiuscole e minuscole). Mancante → `400 DOWNLOAD_FORMAT_REQUIRED`; altri valori → `400 INVALID_DOWNLOAD_FORMAT`. | | `X-Correlation-ID` | header | string (uuid) | | UUID facoltativo per il tracciamento. Un valore mancante o non UUID viene sostituito da un UUID generato dal server. Restituito nell’header di risposta `X-Correlation-ID`; lo indichi al supporto. | **Risposte** - `200`: I byte dell’artefatto. Gli header `X-*` descrivono i byte consegnati; li registri per il Suo archivio. `application/xml` ```json { "type": "string" } ``` `application/pdf` ```json { "type": "string", "format": "binary" } ``` - `202`: `202 TASK_NOT_READY`: elaborazione in corso. Il corpo è un envelope di errore, non un file. Continui a interrogare lo stato del task. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `400`: Richiesta non valida. Da non ripetere: corregga la richiesta. Veda `ErrorEnvelope.code` per tutti i codici 400. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `401`: Autenticazione non riuscita. Da non ripetere. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Da non ripetere: contatti il supporto. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `404`: `404 TASK_NOT_FOUND`: task sconosciuto, task di un altro tenant o eliminato 24 h dopo la conclusione. `404 TASK_RESULT_FAILED`: il task esiste, ma i dati del risultato non sono disponibili; contatti il supporto indicando l’ID di correlazione. Da non ripetere. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `405`: `405 METHOD_NOT_ALLOWED`: i percorsi dei task accettano solo GET. Inviato dal proxy edge, quindi il corpo non contiene `correlation_id`. `application/json` ```json { "$ref": "#/components/schemas/EdgeError" } ``` - `410`: 410 ACCOUNT_DELETED. La chiave API si autentica ancora, ma il relativo account è stato eliminato. L’eliminazione è definitiva, quindi la risposta è 410 Gone su ogni percorso che la segnala. Da non ripetere. Una chiave revocata restituisce invece 401 INVALID_API_KEY. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `422`: La fattura non può essere emessa. Da non ripetere: corregga i dati e avvii una nuova conversione. Codici: `VALIDATION_FAILED` (`details.items`), `PROFILE_MISMATCH`, `ZUGFERD_SOURCE_PDF_INCOMPATIBLE`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `429`: `429 RATE_LIMITED`. Ripetibile: attenda `Retry-After` secondi e riprovi con lo stesso Idempotency-Key. I limiti valgono per chiave API ed endpoint, in finestre fisse di minuto e ora di calendario. Le richieste rifiutate non vengono conteggiate. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `500`: Errore lato server. Per impostazione predefinita un 500 non è ripetibile. `TASK_FAILED`: legga `details.code`; solo `details.retryable: true` consente un nuovo tentativo, e solo come NUOVA conversione con un nuovo Idempotency-Key. `INTERNAL_ARTIFACT_INVARIANT_FAILED`: contatti il supporto. `UPLOAD_FAILED` all’upload: riprovi con la stessa chiave. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `502`: `502 PROXY_ERROR`: l’edge non ha raggiunto il backend. Riprovi con backoff e lo stesso Idempotency-Key. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `503`: Temporaneamente non disponibile. Riprovi con backoff: `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `AUTHORITATIVE_VALIDATION_UNAVAILABLE`. Avvii invece una NUOVA conversione: `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `504`: `504 PROXY_ERROR`: il backend non ha risposto in tempo. Riprovi con backoff e lo stesso Idempotency-Key. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` ### GET /tasks/{task_id}/validation-report — Scaricare il report di validazione Scarichi il report di validazione legato all’artefatto consegnato. - `download=html` per le persone; `download=xml` per il report KoSIT, oppure l’XML `validation-evidence` di Factur-X (`source="facturx_php"`, non in formato KoSIT). - Gli header `X-Artifact-*` descrivono l’artefatto di risultato validato, non i byte del report. - L’evidenza Factur-X prova solo la validazione dell’XML archiviato, non la fedeltà alla sorgente né la conformità PDF/A. - Limite di frequenza: 30/min e 500/h per chiave API. **Parametri** | Nome | Posizione | Tipo | Obbligatorio | Descrizione | | --- | --- | --- | --- | --- | | `task_id` | path | string (uuid) | sì | `task_id` della risposta `202`. Non è un UUID → `400 BAD_REQUEST`. | | `download` | query | string: `html`, `xml` | sì | `html` per un report leggibile, `xml` per il report leggibile da una macchina. Mancante → `400 DOWNLOAD_FORMAT_REQUIRED`; altri valori → `400 INVALID_DOWNLOAD_FORMAT`. | | `X-Correlation-ID` | header | string (uuid) | | UUID facoltativo per il tracciamento. Un valore mancante o non UUID viene sostituito da un UUID generato dal server. Restituito nell’header di risposta `X-Correlation-ID`; lo indichi al supporto. | **Risposte** - `200`: Il report. `text/html` ```json { "type": "string" } ``` `application/xml` ```json { "type": "string" } ``` - `202`: `202 TASK_NOT_READY`: elaborazione in corso. Il corpo è un envelope di errore, non un file. Continui a interrogare lo stato del task. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `400`: Richiesta non valida. Da non ripetere: corregga la richiesta. Veda `ErrorEnvelope.code` per tutti i codici 400. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `401`: Autenticazione non riuscita. Da non ripetere. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Da non ripetere: contatti il supporto. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `404`: `404 TASK_NOT_FOUND` (task sconosciuto o scaduto) o `404 VALIDATION_REPORT_NOT_FOUND` (nessun report legato all’artefatto attuale; `details.reason`). Da non ripetere. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `405`: `405 METHOD_NOT_ALLOWED`: i percorsi dei task accettano solo GET. Inviato dal proxy edge, quindi il corpo non contiene `correlation_id`. `application/json` ```json { "$ref": "#/components/schemas/EdgeError" } ``` - `410`: 410 ACCOUNT_DELETED. La chiave API si autentica ancora, ma il relativo account è stato eliminato. L’eliminazione è definitiva, quindi la risposta è 410 Gone su ogni percorso che la segnala. Da non ripetere. Una chiave revocata restituisce invece 401 INVALID_API_KEY. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `422`: La fattura non può essere emessa. Da non ripetere: corregga i dati e avvii una nuova conversione. Codici: `VALIDATION_FAILED` (`details.items`), `PROFILE_MISMATCH`, `ZUGFERD_SOURCE_PDF_INCOMPATIBLE`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `429`: `429 RATE_LIMITED`. Ripetibile: attenda `Retry-After` secondi e riprovi con lo stesso Idempotency-Key. I limiti valgono per chiave API ed endpoint, in finestre fisse di minuto e ora di calendario. Le richieste rifiutate non vengono conteggiate. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `500`: Errore lato server. Per impostazione predefinita un 500 non è ripetibile. `TASK_FAILED`: legga `details.code`; solo `details.retryable: true` consente un nuovo tentativo, e solo come NUOVA conversione con un nuovo Idempotency-Key. `INTERNAL_ARTIFACT_INVARIANT_FAILED`: contatti il supporto. `UPLOAD_FAILED` all’upload: riprovi con la stessa chiave. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `502`: `502 PROXY_ERROR`: l’edge non ha raggiunto il backend. Riprovi con backoff e lo stesso Idempotency-Key. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `503`: Temporaneamente non disponibile. Riprovi con backoff: `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`, `AUTHORITATIVE_VALIDATION_UNAVAILABLE`. Avvii invece una NUOVA conversione: `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE`. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` - `504`: `504 PROXY_ERROR`: il backend non ha risposto in tempo. Riprovi con backoff e lo stesso Idempotency-Key. `application/json` ```json { "$ref": "#/components/schemas/ErrorEnvelope" } ``` ## Schemi ### `ConvertInvoiceRequest` ```json { "type": "object", "required": [ "file", "format" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Il documento fattura: `.pdf`, `.docx` o `.txt`, una fattura per file. `.doc`, `.rtf` e immagini vengono rifiutati (`400 INVALID_UPLOAD`). `format=ZUGFERD` richiede un PDF (`422 ZUGFERD_SOURCE_PDF_REQUIRED`)." }, "format": { "type": "string", "enum": [ "XRECHNUNG", "ZUGFERD", "EN16931", "UBL", "CII" ], "description": "Formato di output di destinazione. Obbligatorio; non esiste un valore predefinito. Non distingue maiuscole e minuscole. Mancante → `400 FORMAT_REQUIRED`; sconosciuto → `422 INVALID_FORMAT`.", "examples": [ "XRECHNUNG" ] }, "profile": { "type": "string", "enum": [ "XRECHNUNG", "PEPPOL", "EN16931", "ZUGFERD_EN16931", "ZUGFERD_FACTURX_EXTENDED", "ZUGFERD_XRECHNUNG" ], "description": "Set di regole rispetto al quale viene validato l’artefatto. Facoltativo: ogni `format` ha un valore predefinito (veda la tabella dell’operazione). Non distingue maiuscole e minuscole. Alias: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`; `ZUGFERD-XRECHNUNG` → `ZUGFERD_XRECHNUNG`. Non consentito per questo formato → `422 OUTPUT_PROFILE_CONFLICT`; nome sconosciuto → `422 INVALID_PROFILE`.", "examples": [ "XRECHNUNG" ] }, "jurisdiction": { "type": "string", "description": "Paese della transazione secondo ISO 3166-1 alpha-2, per esempio `DE`. Contesto facoltativo. Non valido → `422 UPLOAD_FAILED`.", "examples": [ "DE" ] }, "transaction_scope": { "type": "string", "enum": [ "B2B", "B2G", "B2C" ], "description": "Indicazione di contesto facoltativa. Non valida → `422 UPLOAD_FAILED`." }, "delivery_channel": { "type": "string", "enum": [ "PEPPOL", "DIRECT_XML", "PORTAL", "EMAIL_PDF", "UNKNOWN" ], "description": "Indicazione di contesto facoltativa: `EMAIL_PDF` per la consegna di PDF ibridi, `DIRECT_XML` per l’integrazione XML diretta, `PEPPOL` per la consegna tramite rete. Non valida → `422 UPLOAD_FAILED`." }, "client_reference": { "type": "string", "maxLength": 200, "description": "Il Suo riferimento di fattura o di job. Restituito nella risposta 202 e nello stato del task. Nessun carattere di controllo. `external_invoice_id` è accettato come alias; se vengono inviati entrambi, devono coincidere, altrimenti `400 CLIENT_REFERENCE_CONFLICT`.", "examples": [ "ERP-2026-0001" ] }, "source_system": { "type": "string", "maxLength": 100, "description": "Etichetta del sistema ERP o di fatturazione chiamante. Restituita nella risposta 202 e nello stato del task.", "examples": [ "salesforce" ] }, "use_embedded_xml": { "type": "boolean", "default": false, "description": "Usa come fonte di estrazione l’XML Factur-X/ZUGFeRD/XRechnung incorporato nel PDF. Predefinito `false`: l’XML incorporato viene ignorato e viene letto il documento visibile." }, "email_input": { "type": "string", "maxLength": 10000, "description": "Istruzioni in testo libero per l’estrazione, in qualsiasi lingua (solo sorgente PDF). Non combinabile con `use_embedded_xml=true`. Fa parte dell’identità di idempotenza. Non valido → `400 INVALID_EMAIL_INPUT`.", "examples": [ "Use purchase order number PO-42." ] }, "use_seller_master_data": { "type": "boolean", "description": "Applica i dati anagrafici del venditore. Omesso: si applica l’impostazione predefinita dell’account. `false`: ignora i dati del venditore salvati per questa richiesta. `true`: applica i dati salvati e `seller_master_data`." }, "seller_master_data": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/SellerMasterData" }, "description": "Stringa con un oggetto JSON (schema: `SellerMasterData`). Applicata solo con `use_seller_master_data=true`. Ogni valore fornito sostituisce il valore estratto del venditore o del pagamento; le chiavi assenti lasciano la fattura invariata. Non valida → `400 INVALID_SELLER_MASTER_DATA`.", "examples": [ "{\"business_name\":\"Seller GmbH\",\"vat_id\":\"DE123456789\",\"city\":\"Berlin\",\"country\":\"DE\"}" ] } }, "additionalProperties": false } ``` ### `ConvertStructuredInvoiceRequest` ```json { "type": "object", "required": [ "pdf_file", "data_file", "format" ], "properties": { "pdf_file": { "type": "string", "format": "binary", "description": "PDF di supporto. Per `ZUGFERD` l’XML validato viene incorporato in esso; per i formati XML viene archiviato come PDF originale. Non fornisce mai dati della fattura." }, "data_file": { "oneOf": [ { "type": "string", "format": "binary" }, { "type": "array", "minItems": 1, "items": { "type": "string", "format": "binary" } } ], "description": "Dati fattura: `.json`, `.csv`, `.xml`, `.xlsx` o `.txt` (≤ 2 MB in totale). Il JSON canonico (al livello superiore o racchiuso in `invoice_data`), le parti JSON canoniche coerenti e un file XML UBL 2.1 Invoice / CII D16B vengono mappati senza IA; gli altri formati usano la mappatura con IA. I campi canonici sconosciuti e i dati in conflitto dell’insieme restituiscono `400 INVALID_UPLOAD`. Ripeta la parte per una fattura suddivisa in più file; tutte le parti richiedono lo stesso numero di fattura e le righe canoniche richiedono ID espliciti e univoci. Schema: https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json. I nomi dei campi `data_files` e `data_files[]` sono accettati come alias." }, "format": { "type": "string", "enum": [ "XRECHNUNG", "ZUGFERD", "EN16931", "UBL", "CII" ], "description": "Formato di output di destinazione. Obbligatorio; non esiste un valore predefinito. Non distingue maiuscole e minuscole. Mancante → `400 FORMAT_REQUIRED`; sconosciuto → `422 INVALID_FORMAT`.", "examples": [ "XRECHNUNG" ] }, "profile": { "type": "string", "enum": [ "XRECHNUNG", "PEPPOL", "EN16931", "ZUGFERD_EN16931", "ZUGFERD_FACTURX_EXTENDED", "ZUGFERD_XRECHNUNG" ], "description": "Set di regole rispetto al quale viene validato l’artefatto. Facoltativo: ogni `format` ha un valore predefinito (veda la tabella dell’operazione). Non distingue maiuscole e minuscole. Alias: `EXTENDED` → `ZUGFERD_FACTURX_EXTENDED`; `ZUGFERD`, `FACTURX`, `FACTUR-X`, `FACTUR_X` → `ZUGFERD_EN16931`; `ZUGFERD-XRECHNUNG` → `ZUGFERD_XRECHNUNG`. Non consentito per questo formato → `422 OUTPUT_PROFILE_CONFLICT`; nome sconosciuto → `422 INVALID_PROFILE`.", "examples": [ "XRECHNUNG" ] }, "jurisdiction": { "type": "string", "description": "Paese della transazione secondo ISO 3166-1 alpha-2, per esempio `DE`. Contesto facoltativo. Non valido → `422 UPLOAD_FAILED`.", "examples": [ "DE" ] }, "transaction_scope": { "type": "string", "enum": [ "B2B", "B2G", "B2C" ], "description": "Indicazione di contesto facoltativa. Non valida → `422 UPLOAD_FAILED`." }, "delivery_channel": { "type": "string", "enum": [ "PEPPOL", "DIRECT_XML", "PORTAL", "EMAIL_PDF", "UNKNOWN" ], "description": "Indicazione di contesto facoltativa: `EMAIL_PDF` per la consegna di PDF ibridi, `DIRECT_XML` per l’integrazione XML diretta, `PEPPOL` per la consegna tramite rete. Non valida → `422 UPLOAD_FAILED`." }, "client_reference": { "type": "string", "maxLength": 200, "description": "Il Suo riferimento di fattura o di job. Restituito nella risposta 202 e nello stato del task. Nessun carattere di controllo. `external_invoice_id` è accettato come alias; se vengono inviati entrambi, devono coincidere, altrimenti `400 CLIENT_REFERENCE_CONFLICT`.", "examples": [ "ERP-2026-0001" ] }, "source_system": { "type": "string", "maxLength": 100, "description": "Etichetta del sistema ERP o di fatturazione chiamante. Restituita nella risposta 202 e nello stato del task.", "examples": [ "salesforce" ] }, "use_seller_master_data": { "type": "boolean", "description": "Applica i dati anagrafici del venditore. Omesso: si applica l’impostazione predefinita dell’account. `false`: ignora i dati del venditore salvati per questa richiesta. `true`: applica i dati salvati e `seller_master_data`." }, "seller_master_data": { "type": "string", "contentMediaType": "application/json", "contentSchema": { "$ref": "#/components/schemas/SellerMasterData" }, "description": "Stringa con un oggetto JSON (schema: `SellerMasterData`). Applicata solo con `use_seller_master_data=true`. Ogni valore fornito sostituisce il valore estratto del venditore o del pagamento; le chiavi assenti lasciano la fattura invariata. Non valida → `400 INVALID_SELLER_MASTER_DATA`.", "examples": [ "{\"business_name\":\"Seller GmbH\",\"vat_id\":\"DE123456789\",\"city\":\"Berlin\",\"country\":\"DE\"}" ] } }, "additionalProperties": false } ``` ### `StructuredInvoiceData` ```json { "additionalProperties": false, "properties": { "CustomizationID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Customizationid" }, "ProfileID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Profileid" }, "ID": { "title": "Id", "type": "string" }, "IssueDate": { "title": "Issuedate", "type": "string" }, "DueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Duedate" }, "TaxCurrencyCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxcurrencycode" }, "TaxPointDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxpointdate" }, "InvoicePeriod": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_InvoicePeriod" }, { "type": "null" } ], "default": null }, "InvoiceTypeCode": { "title": "Invoicetypecode", "type": "string" }, "DocumentCurrencyCode": { "title": "Documentcurrencycode", "type": "string" }, "OrderReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_OrderReference" }, { "type": "null" } ], "default": null }, "SalesOrderReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_SalesOrderReference" }, { "type": "null" } ], "default": null }, "ContractDocumentReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_ContractDocumentReference" }, { "type": "null" } ], "default": null }, "ProjectReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_ProjectReference" }, { "type": "null" } ], "default": null }, "TenderOrLotReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_TenderOrLotReference" }, { "type": "null" } ], "default": null }, "DespatchDocumentReference": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_DespatchDocumentReference" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_DespatchDocumentReference" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Despatchdocumentreference" }, "PrecedingInvoiceReference": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StructuredInvoice_PrecedingInvoiceReference" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Precedinginvoicereference" }, "AdditionalDocumentReference": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StructuredInvoice_AdditionalDocumentReference" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Additionaldocumentreference" }, "AllowanceCharge": { "anyOf": [ { "items": { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Allowancecharge" }, "AccountingSupplierParty": { "$ref": "#/components/schemas/StructuredInvoice_AccountingSupplierParty" }, "AccountingCustomerParty": { "$ref": "#/components/schemas/StructuredInvoice_AccountingCustomerParty" }, "PayeeParty": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PayeeParty" }, { "type": "null" } ], "default": null }, "TaxRepresentativeParty": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_TaxRepresentativeParty" }, { "type": "null" } ], "default": null }, "Delivery": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Delivery" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_Delivery" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Delivery" }, "DeliveryTerms": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_DeliveryTerms" }, { "type": "null" } ], "default": null }, "PaymentMeans": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PaymentMeans" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_PaymentMeans" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Paymentmeans" }, "PaymentTerms": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PaymentTerms" }, { "type": "null" } ], "default": null }, "TaxTotal": { "$ref": "#/components/schemas/StructuredInvoice_TaxTotal" }, "LegalMonetaryTotal": { "$ref": "#/components/schemas/StructuredInvoice_LegalMonetaryTotal" }, "InvoiceLine": { "items": { "$ref": "#/components/schemas/StructuredInvoice_InvoiceLine" }, "title": "Invoiceline", "type": "array" }, "Note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Note" }, "BuyerReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Buyerreference" }, "BuyerAccountingReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Buyeraccountingreference" } }, "required": [ "ID", "IssueDate", "InvoiceTypeCode", "DocumentCurrencyCode", "AccountingSupplierParty", "AccountingCustomerParty", "TaxTotal", "LegalMonetaryTotal", "InvoiceLine" ], "title": "Invoice Converter structured invoice JSON", "type": "object", "description": "JSON canonico della fattura per POST /api/v1/invoices:convert-structured. I nomi degli elementi seguono UBL 2.1 / EN 16931. Invii una fattura come un solo data_file JSON, al livello superiore o racchiusa in un oggetto 'invoice_data'; questo formato viene mappato senza interpretazione IA. Il riconoscimento richiede almeno 3 delle chiavi di primo livello ID, IssueDate, InvoiceTypeCode, DocumentCurrencyCode, AccountingSupplierParty, AccountingCustomerParty, TaxTotal, LegalMonetaryTotal, InvoiceLine, tra cui ID, InvoiceLine o LegalMonetaryTotal. Scaricabile: https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json", "examples": [ { "ID": "RE-2026-00123", "IssueDate": "2026-09-30", "DueDate": "2026-10-30", "InvoiceTypeCode": "380", "DocumentCurrencyCode": "EUR", "BuyerReference": "04011000-1234512345-06", "OrderReference": { "ID": "PO-4711" }, "InvoicePeriod": { "StartDate": "2026-09-01", "EndDate": "2026-09-30" }, "Note": "Monthly subscription September 2026", "AccountingSupplierParty": { "Party": { "EndpointID": { "#text": "billing@seller.example", "@schemeID": "EM" }, "PartyName": { "Name": "Seller GmbH" }, "PostalAddress": { "StreetName": "Hauptstraße 1", "CityName": "Berlin", "PostalZone": "10115", "Country": { "IdentificationCode": "DE" } }, "PartyTaxScheme": { "CompanyID": "DE123456789", "TaxScheme": { "ID": "VAT" } }, "PartyLegalEntity": { "RegistrationName": "Seller GmbH", "CompanyID": "HRB 12345" }, "Contact": { "Name": "Erika Muster", "Telephone": "+49 30 123456", "ElectronicMail": "erika@seller.example" } } }, "AccountingCustomerParty": { "Party": { "EndpointID": { "#text": "04011000-1234512345-06", "@schemeID": "0204" }, "PartyName": { "Name": "Buyer AG" }, "PostalAddress": { "StreetName": "Marktplatz 5", "CityName": "München", "PostalZone": "80331", "Country": { "IdentificationCode": "DE" } }, "PartyTaxScheme": { "CompanyID": "DE987654321", "TaxScheme": { "ID": "VAT" } }, "PartyLegalEntity": { "RegistrationName": "Buyer AG" } } }, "Delivery": { "ActualDeliveryDate": "2026-09-30", "DeliveryLocation": { "Address": { "StreetName": "Marktplatz 5", "CityName": "München", "PostalZone": "80331", "Country": { "IdentificationCode": "DE" } } } }, "PaymentMeans": { "PaymentMeansCode": "58", "PaymentID": "RE-2026-00123", "PayeeFinancialAccount": { "ID": "DE02120300000000202051", "Name": "Seller GmbH", "FinancialInstitutionBranch": { "ID": "BYLADEM1001" } } }, "PaymentTerms": { "Note": "Zahlbar innerhalb von 30 Tagen ohne Abzug", "NetDays": 30 }, "TaxTotal": { "TaxAmount": "285.00", "TaxSubtotal": [ { "TaxableAmount": "1500.00", "TaxAmount": "285.00", "TaxCategory": { "ID": "S", "Percent": 19, "TaxScheme": { "ID": "VAT" } } } ] }, "LegalMonetaryTotal": { "LineExtensionAmount": "1500.00", "TaxExclusiveAmount": "1500.00", "TaxInclusiveAmount": "1785.00", "PayableAmount": "1785.00" }, "InvoiceLine": [ { "ID": "1", "InvoicedQuantity": 10, "unitCode": "HUR", "LineExtensionAmount": "1200.00", "Item": { "Name": "Consulting", "SellersItemIdentification": { "ID": "SRV-01" }, "ClassifiedTaxCategory": { "ID": "S", "Percent": 19, "TaxScheme": { "ID": "VAT" } } }, "Price": { "PriceAmount": "120.00" } }, { "ID": "2", "InvoicedQuantity": 2, "unitCode": "C62", "LineExtensionAmount": "300.00", "Item": { "Name": "Software licence", "ClassifiedTaxCategory": { "ID": "S", "Percent": 19, "TaxScheme": { "ID": "VAT" } } }, "Price": { "PriceAmount": "150.00" } } ] } ] } ``` ### `SellerMasterData` ```json { "type": "object", "description": "Valori predefiniti del venditore, inviati come campo modulo stringa JSON `seller_master_data`. Ogni chiave è facoltativa. `electronic_address` e `electronic_address_scheme` formano una coppia: invii entrambi o nessuno dei due.", "properties": { "business_name": { "type": "string", "maxLength": 240, "description": "Ragione sociale (BT-27)." }, "trading_name": { "type": "string", "maxLength": 240, "description": "Nome commerciale (BT-28)." }, "street": { "type": "string", "description": "Via e numero civico (BT-35)." }, "additional_address": { "type": "string", "description": "Riga aggiuntiva dell’indirizzo (BT-36)." }, "postal_code": { "type": "string", "description": "CAP (BT-38)." }, "city": { "type": "string", "description": "Città (BT-37)." }, "country": { "type": "string", "description": "Codice paese ISO 3166-1 alpha-2 (BT-40).", "examples": [ "DE" ] }, "vat_id": { "type": "string", "description": "Partita IVA (BT-31).", "examples": [ "DE123456789" ] }, "tax_number": { "type": "string", "description": "Numero fiscale (BT-32)." }, "electronic_address": { "type": "string", "description": "Indirizzo elettronico (BT-34). Richiede `electronic_address_scheme`." }, "electronic_address_scheme": { "type": "string", "description": "Schema EAS dell’indirizzo elettronico, per esempio `EM` o `0204`." }, "contact_name": { "type": "string", "description": "Referente (BT-41)." }, "contact_email": { "type": "string", "description": "E-mail del referente (BT-43)." }, "contact_phone": { "type": "string", "description": "Telefono del referente (BT-42)." }, "payment_means_code": { "type": "string", "enum": [ "30", "42", "58" ], "description": "Codice del mezzo di pagamento per bonifico (BT-81): 30 bonifico, 42 pagamento su conto bancario, 58 bonifico SEPA." }, "payment_iban": { "type": "string", "description": "IBAN del conto del beneficiario (BT-84)." }, "payment_bic": { "type": "string", "description": "BIC della banca del beneficiario (BT-86)." }, "payment_account_name": { "type": "string", "description": "Intestatario del conto del beneficiario (BT-85)." }, "payment_terms_note": { "type": "string", "description": "Testo delle condizioni di pagamento (BT-20)." } }, "additionalProperties": false, "examples": [ { "business_name": "Seller GmbH", "street": "Hauptstraße 1", "postal_code": "10115", "city": "Berlin", "country": "DE", "vat_id": "DE123456789", "electronic_address": "billing@seller.example", "electronic_address_scheme": "EM", "contact_name": "Erika Muster", "contact_email": "erika@seller.example", "contact_phone": "+49 30 123456", "payment_means_code": "58", "payment_iban": "DE02120300000000202051" } ] } ``` ### `ConvertAcceptedResponse` ```json { "type": "object", "required": [ "task_id", "status", "correlation_id" ], "properties": { "task_id": { "type": "string", "format": "uuid", "description": "Lo usi per tutte le chiamate ai task." }, "status": { "type": "string", "enum": [ "pending", "processing" ], "description": "`pending`: in coda. `processing`: avviato." }, "message": { "type": "string", "description": "Conferma leggibile. Non basi la logica su questo valore." }, "filename": { "type": [ "string", "null" ], "description": "Nome file del documento caricato (o del PDF di supporto)." }, "pdf_filename": { "type": [ "string", "null" ], "description": "Nome file del PDF di supporto (endpoint strutturato)." }, "data_filename": { "type": [ "string", "null" ], "description": "Nome del primo file di dati (endpoint strutturato)." }, "data_filenames": { "type": "array", "items": { "type": "string" }, "description": "Nomi di tutti i file di dati (endpoint strutturato)." }, "data_file_count": { "type": "integer", "minimum": 1, "description": "Numero di file di dati (endpoint strutturato)." }, "file_size": { "type": "integer", "minimum": 0, "description": "Byte accettati in totale." }, "pdf_file_size": { "type": "integer", "minimum": 0, "description": "Byte del PDF di supporto (endpoint strutturato)." }, "data_file_size": { "type": "integer", "minimum": 0, "description": "Byte dei file di dati in totale (endpoint strutturato)." }, "correlation_id": { "type": "string", "format": "uuid" }, "status_url": { "type": "string", "description": "URL relativo da interrogare." }, "primary_result_format": { "type": "string", "enum": [ "xml", "pdf" ], "description": "Download abituale per il formato richiesto: `pdf` per ZUGFERD, altrimenti `xml`." }, "primary_result_url": { "type": "string", "description": "URL relativo del risultato con `download=`." }, "client_reference": { "type": "string", "description": "Eco di `client_reference`." }, "source_system": { "type": "string", "description": "Eco di `source_system`." } }, "additionalProperties": false } ``` ### `TaskStatusResponse` ```json { "type": "object", "required": [ "task_id", "status", "correlation_id" ], "properties": { "task_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "description": "`pending`: in coda. `processing`: in esecuzione. `completed`: esiste un artefatto validato. `failed`: definitivo, nessun artefatto." }, "progress": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100, "description": "Avanzamento approssimativo in percentuale. Non lo usi per stimare i tempi." }, "created_at": { "type": "string", "format": "date-time", "description": "Momento in cui il task è stato accettato (UTC)." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Momento in cui il task ha raggiunto `completed` o `failed` (UTC)." }, "filename": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "object", "null" ], "additionalProperties": true, "description": "Riepilogo dell’errore quando `status=failed`: un messaggio o un oggetto con `code`, `message`, `retryable`. Solo informativo; `/result` restituisce l’envelope di errore tipizzato." }, "correlation_id": { "type": "string", "format": "uuid", "description": "ID di tracciamento di questa chiamata di stato." }, "client_reference": { "type": [ "string", "null" ], "description": "Eco di `client_reference`." }, "source_system": { "type": [ "string", "null" ], "description": "Eco di `source_system`." }, "primary_result_format": { "type": "string", "enum": [ "xml", "pdf" ], "description": "Download abituale per il formato richiesto." }, "primary_result_url": { "type": "string", "description": "URL relativo del risultato." }, "result_artifacts": { "$ref": "#/components/schemas/ResultArtifacts" }, "validation_report_html": { "$ref": "#/components/schemas/ValidationReportHtmlStatus" } }, "additionalProperties": false } ``` ### `ResultArtifacts` ```json { "type": "object", "description": "Disponibilità al download per ogni artefatto.", "properties": { "xml": { "$ref": "#/components/schemas/ResultArtifactStatus" }, "pdf": { "$ref": "#/components/schemas/ResultArtifactStatus" } }, "additionalProperties": false } ``` ### `ResultArtifactStatus` ```json { "type": "object", "required": [ "state", "download_url" ], "properties": { "state": { "type": "string", "enum": [ "cached", "not_ready", "validation_failed", "dependency_failed", "artifact_generation_rerun_required", "artifact_invariant_failed" ], "description": "`cached`: scaricabile. `not_ready`: non ancora prodotto. `validation_failed`: problema bloccante nei dati o nel PDF sorgente. `dependency_failed`: interruzione del validatore o dell’archiviazione. `artifact_generation_rerun_required`: avvii una nuova conversione. `artifact_invariant_failed`: contatti il supporto indicando l’ID di correlazione." }, "download_url": { "type": "string", "description": "URL di download relativo." }, "content_type": { "type": "string" }, "filename": { "type": "string" }, "bytes": { "type": "integer", "minimum": 0 }, "artifact_state": { "type": "string", "enum": [ "compliant", "warning_only", "cannot_guarantee", "blocked" ], "description": "Stato di conformità. `compliant` per ogni artefatto API consegnato." }, "validation_state": { "type": "string", "enum": [ "passed", "failed_overridable", "failed_blocking", "not_validated" ], "description": "Esito della validazione. `passed` per ogni artefatto API consegnato." } }, "additionalProperties": false } ``` ### `ValidationReportHtmlStatus` ```json { "type": "object", "description": "Presente solo con `include_validation_report_html=true`.", "required": [ "available" ], "properties": { "available": { "type": "boolean" }, "content_type": { "type": "string", "enum": [ "text/html; charset=utf-8" ] }, "html": { "type": "string", "description": "HTML sanificato del report; i percorsi del server sono oscurati." }, "source": { "type": "string", "description": "Per esempio `artifact`, `embedded_xml` o `source_xml`." }, "source_result_format": { "type": "string", "enum": [ "xml", "pdf" ] }, "reason": { "type": "string", "description": "Motivo per cui nessun report è disponibile, per esempio `task_not_completed`, `proof_not_found`, `artifact_not_current`." } }, "additionalProperties": false } ``` ### `ErrorEnvelope` ```json { "type": "object", "description": "Ogni errore JSON. Basi la logica su `code`; per `500 TASK_FAILED` anche su `details.code` e `details.retryable`. Ripeta una scrittura solo con lo stesso Idempotency-Key.", "required": [ "code", "message", "correlation_id" ], "properties": { "code": { "type": "string", "enum": [ "AUTHENTICATION_REQUIRED", "INVALID_API_KEY", "API_NOT_ENABLED_FOR_TENANT", "ACCOUNT_DELETED", "INSUFFICIENT_API_CREDITS", "AUTH_SERVICE_UNAVAILABLE", "PLAN_TIER_CHECK_FAILED", "RATE_LIMIT_SERVICE_UNAVAILABLE", "API_CREDIT_SERVICE_UNAVAILABLE", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_IN_PROGRESS", "IDEMPOTENCY_CONFLICT", "IDEMPOTENCY_REPLAY_EXPIRED", "FORMAT_REQUIRED", "INVALID_FORMAT", "INVALID_PROFILE", "OUTPUT_PROFILE_CONFLICT", "OUTPUT_PROFILE_REQUIRED", "CLIENT_REFERENCE_CONFLICT", "INVALID_CLIENT_METADATA", "INVALID_SELLER_MASTER_DATA", "INVALID_EMBEDDED_XML_POLICY", "INVALID_EMAIL_INPUT", "INVALID_UPLOAD", "PAYLOAD_TOO_LARGE", "UPLOAD_FAILED", "SERVER_BUSY", "ZUGFERD_SOURCE_PDF_REQUIRED", "METHOD_NOT_ALLOWED", "NOT_FOUND", "BAD_REQUEST", "INVALID_QUERY_PARAMETER", "DOWNLOAD_FORMAT_REQUIRED", "INVALID_DOWNLOAD_FORMAT", "TASK_NOT_READY", "TASK_NOT_FOUND", "TASK_STATUS_FAILED", "TASK_RESULT_FAILED", "TASK_FAILED", "VALIDATION_FAILED", "PROFILE_MISMATCH", "ZUGFERD_SOURCE_PDF_INCOMPATIBLE", "ZUGFERD_CII_CONVERSION_FAILED", "ZUGFERD_PDF_GENERATION_FAILED", "XML_GENERATION_FAILED", "PDF_GENERATION_FAILED", "AUTHORITATIVE_VALIDATION_UNAVAILABLE", "ARTIFACT_GENERATION_RERUN_REQUIRED", "EXTRACTION_INCOMPLETE_GROUP_FAILURE", "INTERNAL_ARTIFACT_INVARIANT_FAILED", "VALIDATION_REPORT_NOT_FOUND", "VALIDATION_REPORT_FAILED", "PROXY_ERROR" ], "x-enumDescriptions": { "AUTHENTICATION_REQUIRED": "401 · no · Invii `Authorization: Bearer `.", "INVALID_API_KEY": "401 · no · La chiave è sconosciuta, revocata o malformata. La corregga o la ruoti.", "API_NOT_ENABLED_FOR_TENANT": "403 · no · La chiave è valida, ma l’account non ha accesso alla External API. Contatti il supporto.", "ACCOUNT_DELETED": "410 · no · L’account di questa chiave API è stato eliminato. L’eliminazione è definitiva. Una chiave revocata restituisce `INVALID_API_KEY`.", "INSUFFICIENT_API_CREDITS": "402 · no · Quota inclusa e crediti prepagati esauriti. Acquisti un pacchetto di crediti o attenda il mese successivo. Due strutture di `details`.", "AUTH_SERVICE_UNAVAILABLE": "503 · sì · L’autenticazione è temporaneamente non disponibile. Riprovi con backoff e lo stesso Idempotency-Key.", "PLAN_TIER_CHECK_FAILED": "503 · sì · Non è stato possibile verificare il piano o l’accesso API. Riprovi con backoff e lo stesso Idempotency-Key.", "RATE_LIMIT_SERVICE_UNAVAILABLE": "503 · sì · Il servizio dei limiti di frequenza non è disponibile. Riprovi con backoff e lo stesso Idempotency-Key.", "API_CREDIT_SERVICE_UNAVAILABLE": "503 · sì · La verifica di crediti e quota non è disponibile. Ripeta l’upload con lo stesso Idempotency-Key.", "RATE_LIMITED": "429 · sì · Attenda `Retry-After` secondi, poi riprovi con lo stesso Idempotency-Key.", "IDEMPOTENCY_KEY_REQUIRED": "400 · no · Invii un header `Idempotency-Key` su entrambi gli endpoint POST.", "INVALID_IDEMPOTENCY_KEY": "400 · no · Usi 1–200 caratteri conformi a `^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$`.", "IDEMPOTENCY_IN_PROGRESS": "409 · sì · La prima richiesta con questa chiave è ancora in corso. Riprovi con la stessa chiave dopo una breve attesa.", "IDEMPOTENCY_CONFLICT": "409 · no · La chiave è stata usata con un payload diverso. Usi una nuova chiave per un nuovo payload.", "IDEMPOTENCY_REPLAY_EXPIRED": "409 · no · Il task originale ha superato la conservazione di 24 h. Avvii una nuova conversione con una nuova chiave.", "FORMAT_REQUIRED": "400 · no · Invii `format` in ogni richiesta di conversione.", "INVALID_FORMAT": "422 · no · Invii uno tra XRECHNUNG, ZUGFERD, EN16931, UBL, CII.", "INVALID_PROFILE": "422 · no · Nome di profilo sconosciuto. `details.allowed_profiles` elenca i valori consentiti.", "OUTPUT_PROFILE_CONFLICT": "422 · no · Il profilo non è consentito per questo `format`. Invii un profilo compatibile o lo ometta.", "OUTPUT_PROFILE_REQUIRED": "422 · no · Difensivo; la V1 imposta un profilo predefinito per ogni formato, quindi non è previsto.", "CLIENT_REFERENCE_CONFLICT": "400 · no · `client_reference` e `external_invoice_id` sono diversi. Ne invii uno solo, oppure lo stesso valore in entrambi.", "INVALID_CLIENT_METADATA": "400 · no · Mantenga `client_reference`/`external_invoice_id` ≤ 200 e `source_system` ≤ 100 caratteri, senza caratteri di controllo.", "INVALID_SELLER_MASTER_DATA": "400 · no · Invii `seller_master_data` come stringa con un oggetto JSON e chiavi supportate; invii `electronic_address` e `electronic_address_scheme` insieme.", "INVALID_EMBEDDED_XML_POLICY": "400 · no · Invii `use_embedded_xml` come `true` o `false`, oppure lo ometta.", "INVALID_EMAIL_INPUT": "400 · no · Invii `email_input` una sola volta, ≤ 10.000 caratteri, solo con sorgente PDF, non con `use_embedded_xml=true`, mai su convert-structured.", "INVALID_UPLOAD": "400/415 · no · Corregga l’upload: multipart/form-data, tipo di file supportato, ≤ 20 parti file e 50 campi, un solo numero di fattura in tutte le parti `data_file` (`details.reason`).", "PAYLOAD_TOO_LARGE": "413 · no · Un file, il totale di `data_file` o il corpo multipart supera il proprio limite backend. Verificare `details.limit_bytes`; inviare una richiesta più piccola.", "UPLOAD_FAILED": "422 · no: valore `jurisdiction`/`transaction_scope`/`delivery_channel` non valido. 500/503 · sì: l’upload non è stato accettato, oppure è stato accettato ma non è stato possibile ricostruire la prima risposta. Riprovi con backoff e lo stesso Idempotency-Key; il nuovo tentativo restituisce il task accettato.", "SERVER_BUSY": "503 · sì · La coda di elaborazione è piena. Attenda `Retry-After` secondi (15), poi riprovi con lo stesso Idempotency-Key.", "ZUGFERD_SOURCE_PDF_REQUIRED": "422 · no · `format=ZUGFERD` richiede un PDF come sorgente. Carichi un PDF o scelga un formato XML.", "METHOD_NOT_ALLOWED": "405 · no · Usi POST sui percorsi di conversione e GET sui percorsi dei task (veda `Allow`).", "NOT_FOUND": "404 · no · Percorso sconosciuto sotto /api/v1.", "BAD_REQUEST": "400 · no · `task_id` deve essere un UUID.", "INVALID_QUERY_PARAMETER": "400 · no · Invii `include_validation_report_html` come `true` o `false`.", "DOWNLOAD_FORMAT_REQUIRED": "400 · no · Invii il parametro di query obbligatorio `download`.", "INVALID_DOWNLOAD_FORMAT": "400 · no · Usi `download=xml|pdf` su /result e `download=html|xml` su /validation-report.", "TASK_NOT_READY": "202 · polling · Il task è ancora in esecuzione. Continui a interrogare lo stato del task con backoff.", "TASK_NOT_FOUND": "404 · no · Task sconosciuto, task di un altro tenant o eliminato 24 h dopo la conclusione. Tutti gli endpoint dei task.", "TASK_STATUS_FAILED": "5xx · sì · Non è stato possibile leggere lo stato. Ripeta il polling con backoff.", "TASK_RESULT_FAILED": "404/5xx · solo 5xx · Non è stato possibile leggere il risultato (per esempio metadati del task mancanti). Ripeta i 5xx con backoff; per un 404 contatti il supporto indicando l’ID di correlazione.", "TASK_FAILED": "500 · solo se `details.retryable` è true · Legga `details.code`. Gli errori ripetibili richiedono una NUOVA conversione con un nuovo Idempotency-Key.", "VALIDATION_FAILED": "422 · no · Errori di validazione bloccanti. Corregga i dati (`details.items`) e avvii una nuova conversione.", "PROFILE_MISMATCH": "422 · no · Il documento archiviato dichiara un altro profilo. Avvii una nuova conversione con il profilo corretto.", "ZUGFERD_SOURCE_PDF_INCOMPATIBLE": "422 · no · Il PDF sorgente non può contenere un ibrido PDF/A-3 rigoroso. Normalizzi il PDF o usi `download=xml`.", "ZUGFERD_CII_CONVERSION_FAILED": "422/500 · no · Conversione CII ibrida non riuscita. Contatti il supporto indicando l’ID di correlazione.", "ZUGFERD_PDF_GENERATION_FAILED": "500 · no · Generazione del PDF ibrido non riuscita. Contatti il supporto indicando l’ID di correlazione.", "XML_GENERATION_FAILED": "500 · sì, con backoff · Percorso di generazione su richiesta legacy; non previsto per i task API rigorosi.", "PDF_GENERATION_FAILED": "500 · sì, con backoff · Percorso di generazione su richiesta legacy; non previsto per i task API rigorosi.", "AUTHORITATIVE_VALIDATION_UNAVAILABLE": "503 · sì · Il validatore è temporaneamente non disponibile. Ripeta lo stesso download più tardi.", "ARTIFACT_GENERATION_RERUN_REQUIRED": "503 · nuovo task · Generazione dell’artefatto non riuscita dopo i tentativi del server. Avvii una nuova conversione.", "EXTRACTION_INCOMPLETE_GROUP_FAILURE": "503 · nuovo task · Gruppi di estrazione non riusciti (`details.failed_groups`). Avvii una nuova conversione.", "INTERNAL_ARTIFACT_INVARIANT_FAILED": "500 · no · Task completato senza un artefatto archiviato sicuro. Contatti il supporto indicando l’ID di correlazione.", "VALIDATION_REPORT_NOT_FOUND": "404 · no · Nessun report è legato all’artefatto attuale (`details.reason`).", "VALIDATION_REPORT_FAILED": "4xx/5xx · solo 5xx · Recupero del report non riuscito. Ripeta i 5xx temporanei con backoff.", "PROXY_ERROR": "502/504 · sì · Errore di trasporto tra edge e backend. Riprovi con backoff e lo stesso Idempotency-Key." }, "description": "Codice di errore leggibile da una macchina. Formato di ogni descrizione: stato HTTP · riprovare? · azione." }, "message": { "type": "string", "description": "Testo leggibile. Non lo analizzi." }, "correlation_id": { "type": "string", "format": "uuid", "description": "Lo indichi al supporto." }, "details": { "$ref": "#/components/schemas/ErrorDetails" } }, "additionalProperties": false } ``` ### `EdgeError` ```json { "type": "object", "description": "Errore inviato dal proxy edge prima che la richiesta raggiunga l’API (`404 NOT_FOUND`, `405 METHOD_NOT_ALLOWED`). Senza `correlation_id`.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "NOT_FOUND", "METHOD_NOT_ALLOWED" ] }, "message": { "type": "string" } } } ``` ### `ErrorDetails` ```json { "type": "object", "description": "Contesto strutturato. Le chiavi dipendono dal codice; possono comparire chiavi sconosciute. `type` è di solito presente, ma non sempre (per esempio `{\"field\": \"download\"}`, `INVALID_UPLOAD`, `413`), quindi basi la logica sul `code` dell’envelope.", "properties": { "type": { "type": "string", "description": "Famiglia del dettaglio, per esempio `validation`, `rate_limit`, `idempotency_conflict`, `idempotency_in_progress`, `profile_mismatch`, `context`, `dependency`, `artifact_generation`, `validation_report`, `message`." }, "code": { "type": "string", "description": "Codice dell’errore sottostante. Con `500 TASK_FAILED` indica il motivo; veda `x-enumDescriptions`.", "examples": [ "MULTIPLE_INVOICES_IN_DOCUMENT", "NO_INVOICE_DETECTED", "INSUFFICIENT_INVOICE_SIGNAL", "SOURCE_TEXT_UNAVAILABLE", "SCHEMA_PARSE_FAILED", "ARTIFACT_PARITY_FAILED", "PROVIDER_ERROR" ], "x-enumDescriptions": { "MULTIPLE_INVOICES_IN_DOCUMENT": "Definitivo. Il documento contiene più di una fattura. Lo suddivida e converta ogni fattura separatamente.", "NO_INVOICE_DETECTED": "Definitivo. Il documento non è una fattura. Lo inoltri a una persona.", "INSUFFICIENT_INVOICE_SIGNAL": "Definitivo. Dati di fattura insufficienti. Invii una sorgente migliore o usi convert-structured.", "SOURCE_TEXT_UNAVAILABLE": "Veda `retryable`. false: nessun testo leggibile (carichi un PDF con testo o una scansione più nitida). true: l’OCR era temporaneamente non disponibile; avvii una nuova conversione.", "SCHEMA_PARSE_FAILED": "Definitivo per questo tentativo. Avvii una nuova conversione; se si ripete, contatti il supporto.", "ARTIFACT_PARITY_FAILED": "Definitivo. L’artefatto non corrispondeva ai dati finali della fattura. Contatti il supporto indicando l’ID di correlazione.", "PROVIDER_ERROR": "Veda `retryable`. true: avvii una nuova conversione dopo un’attesa. `classification=provider_context_too_large`: invii un documento più piccolo." } }, "retryable": { "type": "boolean", "description": "Vincolante, se presente. `true` su `TASK_FAILED`: avvii una NUOVA conversione con un nuovo Idempotency-Key." }, "can_review": { "type": "boolean" }, "classification": { "type": "string", "description": "Per esempio `multiple_invoices`, `not_invoice`, `provider_context_too_large`." }, "category": { "type": "string" }, "recovery_hint": { "type": "string", "description": "Passo successivo leggibile." }, "same_task_retryable": { "type": "boolean", "description": "`false`: lo stesso task non può essere recuperato; avvii una nuova conversione." }, "recovery": { "type": "string", "description": "Per esempio `start_new_conversion`." }, "dependency": { "type": "string" }, "stage": { "type": "string" }, "failed_groups": { "type": "array", "items": { "type": "string" }, "description": "Gruppi di estrazione non riusciti con `EXTRACTION_INCOMPLETE_GROUP_FAILURE`." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationDetail" }, "description": "Problemi bloccanti con `VALIDATION_FAILED`." }, "field": { "type": "string", "description": "Campo della richiesta che causa l’errore, per esempio `download` o `file`." }, "reason": { "type": "string", "description": "Motivo specifico, per esempio `bundle_invoice_id_missing`, `bundle_invoice_id_mismatch`, `different_payload_for_same_key`." }, "profile": { "type": "string" }, "format": { "type": "string" }, "allowed_profiles": { "type": "array", "items": { "type": "string" }, "description": "Profili consentiti negli errori di profilo." }, "minute_count": { "type": "integer" }, "hour_count": { "type": "integer" }, "limit_minute": { "type": "integer" }, "limit_hour": { "type": "integer" }, "limit_bytes": { "type": "integer", "description": "Limite di dimensione con `413 PAYLOAD_TOO_LARGE`." }, "declared_size": { "type": "integer" }, "received_bytes": { "type": "integer" }, "remaining": { "type": "integer" }, "included_remaining": { "type": "integer" }, "credit_remaining": { "type": [ "integer", "null" ] }, "shortfall": { "type": "integer" }, "minimum_purchase": { "type": "integer" }, "bridge_status": { "type": "integer" } }, "additionalProperties": true } ``` ### `ValidationDetail` ```json { "type": "object", "description": "Un problema di validazione bloccante.", "properties": { "field": { "type": [ "string", "null" ], "description": "Percorso del campo della fattura, per esempio `BuyerReference`." }, "rule_id": { "type": [ "string", "null" ], "description": "ID della regola, per esempio `BR-DE-15`." }, "severity": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "suggestion": { "type": [ "string", "null" ], "description": "Cosa correggere." }, "message": { "type": [ "string", "null" ] } }, "additionalProperties": true } ``` ### `InsufficientApiCreditsPrepaidError` ```json { "type": "object", "description": "Struttura del 402 per gli account solo prepagati.", "required": [ "code", "message", "correlation_id", "details" ], "properties": { "code": { "type": "string", "const": "INSUFFICIENT_API_CREDITS" }, "message": { "type": "string" }, "correlation_id": { "type": "string", "format": "uuid" }, "details": { "type": "object", "required": [ "type", "remaining", "minimum_purchase" ], "properties": { "type": { "type": "string", "const": "context" }, "remaining": { "type": "integer", "description": "Crediti prepagati residui." }, "minimum_purchase": { "type": "integer", "description": "Pacchetto di crediti più piccolo (100)." } }, "additionalProperties": true } }, "additionalProperties": false } ``` ### `InsufficientApiCreditsAllowanceError` ```json { "type": "object", "description": "Struttura del 402 per gli account con una quota mensile applicata.", "required": [ "code", "message", "correlation_id", "details" ], "properties": { "code": { "type": "string", "const": "INSUFFICIENT_API_CREDITS" }, "message": { "type": "string" }, "correlation_id": { "type": "string", "format": "uuid" }, "details": { "type": "object", "required": [ "type", "included_remaining", "credit_remaining", "shortfall", "minimum_purchase" ], "properties": { "type": { "type": "string", "const": "context" }, "included_remaining": { "type": "integer", "description": "Quota residua di questo mese." }, "credit_remaining": { "type": [ "integer", "null" ], "description": "Crediti prepagati residui, oppure null." }, "shortfall": { "type": "integer", "description": "Unità non coperte." }, "minimum_purchase": { "type": "integer", "description": "Pacchetto di crediti più piccolo (100)." } }, "additionalProperties": true } }, "additionalProperties": false } ``` ### `StructuredInvoice_AccountingCustomerParty` ```json { "additionalProperties": false, "properties": { "Party": { "$ref": "#/components/schemas/StructuredInvoice_Party" } }, "required": [ "Party" ], "title": "AccountingCustomerParty", "type": "object" } ``` ### `StructuredInvoice_AccountingSupplierParty` ```json { "additionalProperties": false, "properties": { "Party": { "$ref": "#/components/schemas/StructuredInvoice_Party" } }, "required": [ "Party" ], "title": "AccountingSupplierParty", "type": "object" } ``` ### `StructuredInvoice_AdditionalDocumentReference` ```json { "additionalProperties": false, "properties": { "ID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "DocumentTypeCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Documenttypecode" }, "DocumentDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Documentdescription" }, "Attachment": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Attachment" }, { "type": "null" } ], "default": null } }, "title": "AdditionalDocumentReference", "type": "object" } ``` ### `StructuredInvoice_AllowanceCharge` ```json { "additionalProperties": false, "description": "Sconto o maggiorazione a livello di documento (BG-20/BG-21)", "properties": { "ChargeIndicator": { "title": "Chargeindicator", "type": "boolean" }, "AllowanceChargeReasonCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Allowancechargereasoncode" }, "AllowanceChargeReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Allowancechargereason" }, "MultiplierFactorNumeric": { "anyOf": [ { "maximum": 100, "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "description": "Punti percentuali della sorgente, esattamente come stampati. 30% è 30, mai 0.3; 0.3% resta 0.3. Non converta mai i punti percentuali in fattori decimali.", "title": "Multiplierfactornumeric" }, "BaseAmount": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Baseamount" }, "Amount": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "string" } ], "title": "Amount" }, "TaxCategory": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_AllowanceChargeTaxCategory" }, { "type": "null" } ], "default": null } }, "required": [ "ChargeIndicator", "Amount" ], "title": "AllowanceCharge", "type": "object" } ``` ### `StructuredInvoice_AllowanceChargeTaxCategory` ```json { "additionalProperties": false, "description": "Categoria IVA per sconto/maggiorazione a livello di documento (BG-21)", "properties": { "ID": { "title": "Id", "type": "string" }, "Percent": { "anyOf": [ { "maximum": 100, "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Percent" }, "TaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_TaxScheme" } }, "required": [ "ID", "TaxScheme" ], "title": "AllowanceChargeTaxCategory", "type": "object" } ``` ### `StructuredInvoice_Attachment` ```json { "additionalProperties": false, "properties": { "EmbeddedDocumentBinaryObject": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_EmbeddedDocumentBinaryObject" }, { "type": "null" } ], "default": null } }, "title": "Attachment", "type": "object" } ``` ### `StructuredInvoice_BuyersItemIdentification` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "BuyersItemIdentification", "type": "object" } ``` ### `StructuredInvoice_CardAccount` ```json { "additionalProperties": false, "properties": { "PrimaryAccountNumberID": { "title": "Primaryaccountnumberid", "type": "string" }, "NetworkID": { "title": "Networkid", "type": "string" }, "HolderName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Holdername" } }, "required": [ "PrimaryAccountNumberID", "NetworkID" ], "title": "CardAccount", "type": "object" } ``` ### `StructuredInvoice_ClassifiedTaxCategory` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "Percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Percent" }, "TaxExemptionReasonCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxexemptionreasoncode" }, "TaxExemptionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxexemptionreason" }, "TaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_TaxScheme" } }, "required": [ "ID", "TaxScheme" ], "title": "ClassifiedTaxCategory", "type": "object" } ``` ### `StructuredInvoice_CommodityClassification` ```json { "additionalProperties": false, "properties": { "ItemClassificationCode": { "$ref": "#/components/schemas/StructuredInvoice_ItemClassificationCode" } }, "required": [ "ItemClassificationCode" ], "title": "CommodityClassification", "type": "object" } ``` ### `StructuredInvoice_Contact` ```json { "additionalProperties": false, "properties": { "Name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "Telephone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Telephone" }, "ElectronicMail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Electronicmail" } }, "title": "Contact", "type": "object" } ``` ### `StructuredInvoice_ContractDocumentReference` ```json { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "ContractDocumentReference", "type": "object" } ``` ### `StructuredInvoice_Country` ```json { "additionalProperties": false, "properties": { "IdentificationCode": { "title": "Identificationcode", "type": "string" } }, "required": [ "IdentificationCode" ], "title": "Country", "type": "object" } ``` ### `StructuredInvoice_Delivery` ```json { "additionalProperties": false, "properties": { "ActualDeliveryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Actualdeliverydate" }, "DeliveryLocation": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_DeliveryLocation" }, { "type": "null" } ], "default": null }, "DeliveryParty": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Party" }, { "type": "null" } ], "default": null } }, "title": "Delivery", "type": "object" } ``` ### `StructuredInvoice_DeliveryAddress` ```json { "additionalProperties": false, "properties": { "StreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Streetname" }, "AdditionalStreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Additionalstreetname" }, "CityName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cityname" }, "PostalZone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Postalzone" }, "CountrySubentity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Countrysubentity" }, "Country": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Country" }, { "type": "null" } ], "default": null } }, "title": "DeliveryAddress", "type": "object" } ``` ### `StructuredInvoice_DeliveryLocation` ```json { "additionalProperties": false, "properties": { "ID": { "anyOf": [ { "type": "string" }, { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Id" }, "schemeID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Schemeid" }, "Address": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_DeliveryAddress" }, { "type": "null" } ], "default": null } }, "title": "DeliveryLocation", "type": "object" } ``` ### `StructuredInvoice_DeliveryTerms` ```json { "additionalProperties": false, "properties": { "ID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Id" }, "SpecialTerms": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Specialterms" } }, "title": "DeliveryTerms", "type": "object" } ``` ### `StructuredInvoice_DespatchDocumentReference` ```json { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "DespatchDocumentReference", "type": "object" } ``` ### `StructuredInvoice_EmbeddedDocumentBinaryObject` ```json { "additionalProperties": false, "properties": { "#text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "#Text" }, "mimeCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mimecode" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Filename" } }, "title": "EmbeddedDocumentBinaryObject", "type": "object" } ``` ### `StructuredInvoice_EndpointID` ```json { "additionalProperties": false, "properties": { "#text": { "title": "#Text", "type": "string" }, "@schemeID": { "title": "@Schemeid", "type": "string" } }, "required": [ "#text", "@schemeID" ], "title": "EndpointID", "type": "object" } ``` ### `StructuredInvoice_FinancialInstitutionBranch` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "FinancialInstitutionBranch", "type": "object" } ``` ### `StructuredInvoice_InvoiceLine` ```json { "additionalProperties": false, "properties": { "ID": { "description": "Identificativo della riga: usi il numero di posizione esatto della fattura originale (per esempio '1.1.30', '10', '001'). Usi una numerazione progressiva '1', '2', '3' solo se non esistono identificativi espliciti. NON il nome dell’articolo.", "title": "Id", "type": "string" }, "Note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Note" }, "InvoicedQuantity": { "title": "Invoicedquantity", "type": "number" }, "unitCode": { "title": "Unitcode", "type": "string" }, "LineExtensionAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Lineextensionamount" }, "PeriodStart": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Periodstart" }, "PeriodEnd": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Periodend" }, "InvoicePeriod": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_InvoicePeriod" }, { "type": "null" } ], "default": null }, "OrderLineReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Orderlinereference" }, "Item": { "$ref": "#/components/schemas/StructuredInvoice_Item" }, "Price": { "$ref": "#/components/schemas/StructuredInvoice_Price" }, "AllowanceCharge": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Allowancecharge" } }, "required": [ "ID", "InvoicedQuantity", "unitCode", "LineExtensionAmount", "Item", "Price" ], "title": "InvoiceLine", "type": "object" } ``` ### `StructuredInvoice_InvoicePeriod` ```json { "additionalProperties": false, "properties": { "StartDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Startdate" }, "EndDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Enddate" }, "DescriptionCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Descriptioncode" } }, "title": "InvoicePeriod", "type": "object" } ``` ### `StructuredInvoice_Item` ```json { "additionalProperties": false, "properties": { "Description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "Name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "BuyersItemIdentification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_BuyersItemIdentification" }, { "type": "null" } ], "default": null }, "SellersItemIdentification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_SellersItemIdentification" }, { "type": "null" } ], "default": null }, "StandardItemIdentification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_StandardItemIdentification" }, { "type": "null" } ], "default": null }, "OriginCountry": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_OriginCountry" }, { "type": "null" } ], "default": null }, "CommodityClassification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_CommodityClassification" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_CommodityClassification" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Commodityclassification" }, "ClassifiedTaxCategory": { "$ref": "#/components/schemas/StructuredInvoice_ClassifiedTaxCategory" } }, "required": [ "ClassifiedTaxCategory" ], "title": "Item", "type": "object" } ``` ### `StructuredInvoice_ItemClassificationCode` ```json { "additionalProperties": false, "properties": { "#text": { "title": "#Text", "type": "string" }, "listID": { "title": "Listid", "type": "string" }, "listVersionID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Listversionid" } }, "required": [ "#text", "listID" ], "title": "ItemClassificationCode", "type": "object" } ``` ### `StructuredInvoice_LegalMonetaryTotal` ```json { "additionalProperties": false, "properties": { "LineExtensionAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Lineextensionamount" }, "AllowanceTotalAmount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Allowancetotalamount" }, "ChargeTotalAmount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Chargetotalamount" }, "TaxExclusiveAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxexclusiveamount" }, "TaxInclusiveAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxinclusiveamount" }, "PrepaidAmount": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Prepaidamount" }, "PayableRoundingAmount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Payableroundingamount" }, "PayableAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Payableamount" } }, "required": [ "LineExtensionAmount", "TaxExclusiveAmount", "TaxInclusiveAmount", "PayableAmount" ], "title": "LegalMonetaryTotal", "type": "object" } ``` ### `StructuredInvoice_OrderReference` ```json { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" }, "IssueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Issuedate" } }, "required": [ "ID" ], "title": "OrderReference", "type": "object" } ``` ### `StructuredInvoice_OriginCountry` ```json { "additionalProperties": false, "properties": { "IdentificationCode": { "title": "Identificationcode", "type": "string" } }, "required": [ "IdentificationCode" ], "title": "OriginCountry", "type": "object" } ``` ### `StructuredInvoice_Party` ```json { "additionalProperties": false, "properties": { "EndpointID": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_EndpointID" }, { "type": "null" } ], "default": null }, "PartyIdentification": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PartyIdentification" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_PartyIdentification" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Partyidentification" }, "PartyName": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Partyname" }, "PostalAddress": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PostalAddress" }, { "type": "null" } ], "default": null }, "PartyTaxScheme": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PartyTaxScheme" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_PartyTaxScheme" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Partytaxscheme" }, "PartyLegalEntity": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PartyLegalEntity" }, { "type": "null" } ], "default": null }, "Contact": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_Contact" }, { "type": "null" } ], "default": null } }, "title": "Party", "type": "object" } ``` ### `StructuredInvoice_PartyIdentification` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "schemeID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Schemeid" } }, "required": [ "ID" ], "title": "PartyIdentification", "type": "object" } ``` ### `StructuredInvoice_PartyLegalEntity` ```json { "additionalProperties": false, "properties": { "RegistrationName": { "title": "Registrationname", "type": "string" }, "CompanyID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Companyid" }, "CompanyLegalForm": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Companylegalform" } }, "required": [ "RegistrationName" ], "title": "PartyLegalEntity", "type": "object" } ``` ### `StructuredInvoice_PartyTaxScheme` ```json { "additionalProperties": false, "properties": { "CompanyID": { "title": "Companyid", "type": "string" }, "TaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_TaxScheme" } }, "required": [ "CompanyID", "TaxScheme" ], "title": "PartyTaxScheme", "type": "object" } ``` ### `StructuredInvoice_PayeeFinancialAccount` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "Name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "FinancialInstitutionBranch": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_FinancialInstitutionBranch" }, { "type": "null" } ], "default": null } }, "required": [ "ID" ], "title": "PayeeFinancialAccount", "type": "object" } ``` ### `StructuredInvoice_PayeeParty` ```json { "additionalProperties": false, "properties": { "Party": { "$ref": "#/components/schemas/StructuredInvoice_Party" } }, "required": [ "Party" ], "title": "PayeeParty", "type": "object" } ``` ### `StructuredInvoice_PaymentMandate` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "PayerFinancialAccount": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PayeeFinancialAccount" }, { "type": "null" } ], "default": null } }, "required": [ "ID" ], "title": "PaymentMandate", "type": "object" } ``` ### `StructuredInvoice_PaymentMeans` ```json { "additionalProperties": false, "properties": { "PaymentMeansCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Paymentmeanscode" }, "PaymentID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Paymentid" }, "PaymentChannelCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Paymentchannelcode" }, "InstructionID": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Instructionid" }, "InstructionNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Instructionnote" }, "PayeeFinancialAccount": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PayeeFinancialAccount" }, { "type": "null" } ], "default": null }, "CardAccount": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_CardAccount" }, { "type": "null" } ], "default": null }, "PaymentMandate": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_PaymentMandate" }, { "type": "null" } ], "default": null } }, "title": "PaymentMeans", "type": "object" } ``` ### `StructuredInvoice_PaymentTerms` ```json { "additionalProperties": false, "properties": { "Note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Note" }, "PenaltySurchargePercent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Penaltysurchargepercent" }, "Amount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Amount" }, "NetDays": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Netdays" }, "DiscountDays": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Discountdays" }, "DiscountPercent": { "anyOf": [ { "maximum": 100, "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Discountpercent" }, "DiscountBaseAmount": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "default": null, "title": "Discountbaseamount" }, "ExplicitDueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Explicitduedate" } }, "title": "PaymentTerms", "type": "object" } ``` ### `StructuredInvoice_PostalAddress` ```json { "additionalProperties": false, "properties": { "StreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Streetname" }, "CityName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cityname" }, "PostalZone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Postalzone" }, "Country": { "$ref": "#/components/schemas/StructuredInvoice_Country" }, "AdditionalStreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Additionalstreetname" }, "CountrySubentity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Countrysubentity" } }, "required": [ "Country" ], "title": "PostalAddress", "type": "object" } ``` ### `StructuredInvoice_PrecedingInvoiceReference` ```json { "additionalProperties": false, "description": "BG-3: riferimento a una fattura precedente (per esempio una fattura finale, Schlussrechnung, che richiama fatture di acconto, Abschlagsrechnungen)", "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" }, "IssueDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Issuedate" } }, "required": [ "ID" ], "title": "PrecedingInvoiceReference", "type": "object" } ``` ### `StructuredInvoice_Price` ```json { "additionalProperties": false, "properties": { "PriceAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Priceamount" }, "BaseQuantity": { "anyOf": [ { "type": "number" }, { "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "type": "object" }, { "type": "null" } ], "default": null, "title": "Basequantity" }, "AllowanceCharge": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_AllowanceCharge" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Allowancecharge" } }, "required": [ "PriceAmount" ], "title": "Price", "type": "object" } ``` ### `StructuredInvoice_ProjectReference` ```json { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "ProjectReference", "type": "object" } ``` ### `StructuredInvoice_SalesOrderReference` ```json { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "SalesOrderReference", "type": "object" } ``` ### `StructuredInvoice_SellersItemIdentification` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "SellersItemIdentification", "type": "object" } ``` ### `StructuredInvoice_StandardItemIdentification` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "schemeID": { "default": "0160", "title": "Schemeid", "type": "string" } }, "required": [ "ID" ], "title": "StandardItemIdentification", "type": "object" } ``` ### `StructuredInvoice_TaxCategory` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" }, "Percent": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Percent" }, "TaxExemptionReasonCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxexemptionreasoncode" }, "TaxExemptionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Taxexemptionreason" }, "TaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_TaxScheme" } }, "required": [ "ID", "TaxScheme" ], "title": "TaxCategory", "type": "object" } ``` ### `StructuredInvoice_TaxRepresentativeParty` ```json { "additionalProperties": false, "description": "BG-11: rappresentante fiscale del venditore\nObbligatorio quando si usano i codici IVA S, Z, E, AE, K, G, L, M\ne non sono indicati né BT-31 né BT-32 (BR-DE-16)", "properties": { "PartyName": { "minLength": 1, "title": "Partyname", "type": "string" }, "PostalAddress": { "$ref": "#/components/schemas/StructuredInvoice_TaxRepresentativePostalAddress" }, "PartyTaxScheme": { "$ref": "#/components/schemas/StructuredInvoice_PartyTaxScheme" } }, "required": [ "PartyName", "PostalAddress", "PartyTaxScheme" ], "title": "TaxRepresentativeParty", "type": "object" } ``` ### `StructuredInvoice_TaxRepresentativePostalAddress` ```json { "additionalProperties": false, "description": "BG-12: indirizzo postale del rappresentante fiscale del venditore", "properties": { "StreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Streetname" }, "AdditionalStreetName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Additionalstreetname" }, "CityName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cityname" }, "PostalZone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Postalzone" }, "CountrySubentity": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Countrysubentity" }, "Country": { "$ref": "#/components/schemas/StructuredInvoice_Country" } }, "required": [ "Country" ], "title": "TaxRepresentativePostalAddress", "type": "object" } ``` ### `StructuredInvoice_TaxScheme` ```json { "additionalProperties": false, "properties": { "ID": { "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "TaxScheme", "type": "object" } ``` ### `StructuredInvoice_TaxSubtotal` ```json { "additionalProperties": false, "properties": { "TaxableAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxableamount" }, "TaxAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxamount" }, "TaxCategory": { "$ref": "#/components/schemas/StructuredInvoice_TaxCategory" } }, "required": [ "TaxableAmount", "TaxAmount", "TaxCategory" ], "title": "TaxSubtotal", "type": "object" } ``` ### `StructuredInvoice_TaxTotal` ```json { "additionalProperties": false, "properties": { "TaxAmount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "title": "Taxamount" }, "TaxSubtotal": { "anyOf": [ { "$ref": "#/components/schemas/StructuredInvoice_TaxSubtotal" }, { "items": { "$ref": "#/components/schemas/StructuredInvoice_TaxSubtotal" }, "type": "array" } ], "title": "Taxsubtotal" } }, "required": [ "TaxAmount", "TaxSubtotal" ], "title": "TaxTotal", "type": "object" } ``` ### `StructuredInvoice_TenderOrLotReference` ```json { "additionalProperties": false, "properties": { "ID": { "minLength": 1, "title": "Id", "type": "string" } }, "required": [ "ID" ], "title": "TenderOrLotReference", "type": "object" } ``` ## Codici di errore | Codice | Descrizione | | --- | --- | | `AUTHENTICATION_REQUIRED` | 401 · no · Invii `Authorization: Bearer `. | | `INVALID_API_KEY` | 401 · no · La chiave è sconosciuta, revocata o malformata. La corregga o la ruoti. | | `API_NOT_ENABLED_FOR_TENANT` | 403 · no · La chiave è valida, ma l’account non ha accesso alla External API. Contatti il supporto. | | `ACCOUNT_DELETED` | 410 · no · L’account di questa chiave API è stato eliminato. L’eliminazione è definitiva. Una chiave revocata restituisce `INVALID_API_KEY`. | | `INSUFFICIENT_API_CREDITS` | 402 · no · Quota inclusa e crediti prepagati esauriti. Acquisti un pacchetto di crediti o attenda il mese successivo. Due strutture di `details`. | | `AUTH_SERVICE_UNAVAILABLE` | 503 · sì · L’autenticazione è temporaneamente non disponibile. Riprovi con backoff e lo stesso Idempotency-Key. | | `PLAN_TIER_CHECK_FAILED` | 503 · sì · Non è stato possibile verificare il piano o l’accesso API. Riprovi con backoff e lo stesso Idempotency-Key. | | `RATE_LIMIT_SERVICE_UNAVAILABLE` | 503 · sì · Il servizio dei limiti di frequenza non è disponibile. Riprovi con backoff e lo stesso Idempotency-Key. | | `API_CREDIT_SERVICE_UNAVAILABLE` | 503 · sì · La verifica di crediti e quota non è disponibile. Ripeta l’upload con lo stesso Idempotency-Key. | | `RATE_LIMITED` | 429 · sì · Attenda `Retry-After` secondi, poi riprovi con lo stesso Idempotency-Key. | | `IDEMPOTENCY_KEY_REQUIRED` | 400 · no · Invii un header `Idempotency-Key` su entrambi gli endpoint POST. | | `INVALID_IDEMPOTENCY_KEY` | 400 · no · Usi 1–200 caratteri conformi a `^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$`. | | `IDEMPOTENCY_IN_PROGRESS` | 409 · sì · La prima richiesta con questa chiave è ancora in corso. Riprovi con la stessa chiave dopo una breve attesa. | | `IDEMPOTENCY_CONFLICT` | 409 · no · La chiave è stata usata con un payload diverso. Usi una nuova chiave per un nuovo payload. | | `IDEMPOTENCY_REPLAY_EXPIRED` | 409 · no · Il task originale ha superato la conservazione di 24 h. Avvii una nuova conversione con una nuova chiave. | | `FORMAT_REQUIRED` | 400 · no · Invii `format` in ogni richiesta di conversione. | | `INVALID_FORMAT` | 422 · no · Invii uno tra XRECHNUNG, ZUGFERD, EN16931, UBL, CII. | | `INVALID_PROFILE` | 422 · no · Nome di profilo sconosciuto. `details.allowed_profiles` elenca i valori consentiti. | | `OUTPUT_PROFILE_CONFLICT` | 422 · no · Il profilo non è consentito per questo `format`. Invii un profilo compatibile o lo ometta. | | `OUTPUT_PROFILE_REQUIRED` | 422 · no · Difensivo; la V1 imposta un profilo predefinito per ogni formato, quindi non è previsto. | | `CLIENT_REFERENCE_CONFLICT` | 400 · no · `client_reference` e `external_invoice_id` sono diversi. Ne invii uno solo, oppure lo stesso valore in entrambi. | | `INVALID_CLIENT_METADATA` | 400 · no · Mantenga `client_reference`/`external_invoice_id` ≤ 200 e `source_system` ≤ 100 caratteri, senza caratteri di controllo. | | `INVALID_SELLER_MASTER_DATA` | 400 · no · Invii `seller_master_data` come stringa con un oggetto JSON e chiavi supportate; invii `electronic_address` e `electronic_address_scheme` insieme. | | `INVALID_EMBEDDED_XML_POLICY` | 400 · no · Invii `use_embedded_xml` come `true` o `false`, oppure lo ometta. | | `INVALID_EMAIL_INPUT` | 400 · no · Invii `email_input` una sola volta, ≤ 10.000 caratteri, solo con sorgente PDF, non con `use_embedded_xml=true`, mai su convert-structured. | | `INVALID_UPLOAD` | 400/415 · no · Corregga l’upload: multipart/form-data, tipo di file supportato, ≤ 20 parti file e 50 campi, un solo numero di fattura in tutte le parti `data_file` (`details.reason`). | | `PAYLOAD_TOO_LARGE` | 413 · no · Un file, il totale di `data_file` o il corpo multipart supera il proprio limite backend. Verificare `details.limit_bytes`; inviare una richiesta più piccola. | | `UPLOAD_FAILED` | 422 · no: valore `jurisdiction`/`transaction_scope`/`delivery_channel` non valido. 500/503 · sì: l’upload non è stato accettato, oppure è stato accettato ma non è stato possibile ricostruire la prima risposta. Riprovi con backoff e lo stesso Idempotency-Key; il nuovo tentativo restituisce il task accettato. | | `SERVER_BUSY` | 503 · sì · La coda di elaborazione è piena. Attenda `Retry-After` secondi (15), poi riprovi con lo stesso Idempotency-Key. | | `ZUGFERD_SOURCE_PDF_REQUIRED` | 422 · no · `format=ZUGFERD` richiede un PDF come sorgente. Carichi un PDF o scelga un formato XML. | | `METHOD_NOT_ALLOWED` | 405 · no · Usi POST sui percorsi di conversione e GET sui percorsi dei task (veda `Allow`). | | `NOT_FOUND` | 404 · no · Percorso sconosciuto sotto /api/v1. | | `BAD_REQUEST` | 400 · no · `task_id` deve essere un UUID. | | `INVALID_QUERY_PARAMETER` | 400 · no · Invii `include_validation_report_html` come `true` o `false`. | | `DOWNLOAD_FORMAT_REQUIRED` | 400 · no · Invii il parametro di query obbligatorio `download`. | | `INVALID_DOWNLOAD_FORMAT` | 400 · no · Usi `download=xml\|pdf` su /result e `download=html\|xml` su /validation-report. | | `TASK_NOT_READY` | 202 · polling · Il task è ancora in esecuzione. Continui a interrogare lo stato del task con backoff. | | `TASK_NOT_FOUND` | 404 · no · Task sconosciuto, task di un altro tenant o eliminato 24 h dopo la conclusione. Tutti gli endpoint dei task. | | `TASK_STATUS_FAILED` | 5xx · sì · Non è stato possibile leggere lo stato. Ripeta il polling con backoff. | | `TASK_RESULT_FAILED` | 404/5xx · solo 5xx · Non è stato possibile leggere il risultato (per esempio metadati del task mancanti). Ripeta i 5xx con backoff; per un 404 contatti il supporto indicando l’ID di correlazione. | | `TASK_FAILED` | 500 · solo se `details.retryable` è true · Legga `details.code`. Gli errori ripetibili richiedono una NUOVA conversione con un nuovo Idempotency-Key. | | `VALIDATION_FAILED` | 422 · no · Errori di validazione bloccanti. Corregga i dati (`details.items`) e avvii una nuova conversione. | | `PROFILE_MISMATCH` | 422 · no · Il documento archiviato dichiara un altro profilo. Avvii una nuova conversione con il profilo corretto. | | `ZUGFERD_SOURCE_PDF_INCOMPATIBLE` | 422 · no · Il PDF sorgente non può contenere un ibrido PDF/A-3 rigoroso. Normalizzi il PDF o usi `download=xml`. | | `ZUGFERD_CII_CONVERSION_FAILED` | 422/500 · no · Conversione CII ibrida non riuscita. Contatti il supporto indicando l’ID di correlazione. | | `ZUGFERD_PDF_GENERATION_FAILED` | 500 · no · Generazione del PDF ibrido non riuscita. Contatti il supporto indicando l’ID di correlazione. | | `XML_GENERATION_FAILED` | 500 · sì, con backoff · Percorso di generazione su richiesta legacy; non previsto per i task API rigorosi. | | `PDF_GENERATION_FAILED` | 500 · sì, con backoff · Percorso di generazione su richiesta legacy; non previsto per i task API rigorosi. | | `AUTHORITATIVE_VALIDATION_UNAVAILABLE` | 503 · sì · Il validatore è temporaneamente non disponibile. Ripeta lo stesso download più tardi. | | `ARTIFACT_GENERATION_RERUN_REQUIRED` | 503 · nuovo task · Generazione dell’artefatto non riuscita dopo i tentativi del server. Avvii una nuova conversione. | | `EXTRACTION_INCOMPLETE_GROUP_FAILURE` | 503 · nuovo task · Gruppi di estrazione non riusciti (`details.failed_groups`). Avvii una nuova conversione. | | `INTERNAL_ARTIFACT_INVARIANT_FAILED` | 500 · no · Task completato senza un artefatto archiviato sicuro. Contatti il supporto indicando l’ID di correlazione. | | `VALIDATION_REPORT_NOT_FOUND` | 404 · no · Nessun report è legato all’artefatto attuale (`details.reason`). | | `VALIDATION_REPORT_FAILED` | 4xx/5xx · solo 5xx · Recupero del report non riuscito. Ripeta i 5xx temporanei con backoff. | | `PROXY_ERROR` | 502/504 · sì · Errore di trasporto tra edge e backend. Riprovi con backoff e lo stesso Idempotency-Key. |