# API esterna di Invoice Converter

Versione: 1.32.0 · Ultimo aggiornamento: 2026-11-20 · 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 <api_key>` · **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.

## Accesso e prezzi

L'API esterna V1 trasforma fatture PDF o i dati del tuo ERP, software di fatturazione o CRM in file XRechnung, ZUGFeRD/Factur-X, UBL o CII e restituisce un file solo dopo una validazione superata. Una validazione superata dimostra il formato e le regole dello standard, non la corrispondenza dei dati con la fattura originale. Per le eccezioni va previsto un controllo interno.

L'accesso richiede un abbonamento Enterprise: 50 € al mese, oppure 420 € all'anno con fatturazione annuale, imposte escluse. [Attiva Enterprise](https://www.invoice-converter.com/it/pricing)

- [Crea una chiave API](https://www.invoice-converter.com/it/profile#api-access)
- [Guida all'importazione e-mail](https://www.invoice-converter.com/it/developer-api/email-invoices)
- [Guida ai lotti](https://www.invoice-converter.com/it/developer-api/bulk-runs)
- [Confronta tutti i canali di automazione](https://www.invoice-converter.com/it/automation)

## 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 o webhook.** `GET /tasks/{task_id}` finché `status` è `completed` o `failed`, oppure ricevere l’evento di completamento firmato (veda *Webhook*).
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 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 |
| `GET /tasks/{task_id}/correction-result` | Scarica la fattura corretta | 60/min, 1,000/h |
| `POST`, `GET`, `DELETE /webhook-endpoint` | Registrare, leggere o eliminare l’endpoint webhook | 30/min, 300/h |
| `POST /webhook-endpoint:test` | Inviare un evento di test | 5/min, 50/h |

## Autenticazione e accesso

- Header: `Authorization: Bearer <api_key>`.
- 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 <api_key>' \
  -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/<task_id>' \
  -H 'Authorization: Bearer <api_key>'

# 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/<task_id>/result?download=xml' \
  -H 'Authorization: Bearer <api_key>') || { 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 `422 DOCUMENT_NOT_CONVERTIBLE`, `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. Eccezione per XRechnung (profilo `XRECHNUNG` o `ZUGFERD_XRECHNUNG`): se né i dati anagrafici del venditore né il documento indicano l’indirizzo elettronico del venditore (BT-34), e il documento stampa esattamente un indirizzo e-mail del venditore che non è quello dell’acquirente, tale indirizzo diventa BT-34 con lo schema `EM`. Un output Peppol BIS non lo riprende mai. 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: <https://www.invoice-converter.com/developer-api/v1/invoice-data.schema.json>
- Esempio (XRechnung B2G tedesca, supera i controlli EN 16931, XRechnung e ZUGFeRD rigoroso): <https://www.invoice-converter.com/developer-api/v1/invoice-data.example.json>

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`, `business_term`, `rule_id`, `severity`, `source`, `message`, `suggestion`, e `proposal` per una riga che riporta solo un importo).

### 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 con `use_seller_master_data=true`; se il flag manca, vale l’impostazione del conto. Lo schema OpenAPI `SellerMasterData` descrive i campi facoltativi e i relativi termini EN 16931.

Altri campi facoltativi: `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`, `58`), `payment_terms_note`.

- Ogni valore fornito sostituisce il corrispondente valore estratto del venditore o del pagamento. Un elenco `payment_accounts` non vuoto sostituisce tutti i conti per bonifico nell’ordine salvato. IBAN, BIC e nomi dei conti estratti per questi conti vengono ignorati. Gli altri mezzi di pagamento mantengono le regole di selezione esistenti.
- `payment_accounts` contiene al massimo 5 conti con `iban` e, facoltativamente, `bic` e `account_name`. Ogni IBAN deve essere valido e univoco; un BIC fornito deve essere valido. I campi scalari `payment_iban`, `payment_bic` e `payment_account_name` sono rimossi: inviare l’elenco.
- `electronic_address` e `electronic_address_scheme` formano una coppia: inviare entrambi o nessuno.
- Un documento di autofatturazione (codice tipo 261, 389 o 527) resta come è stato letto: lo emette l’acquirente, venditore e beneficiario sono la controparte, e i dati anagrafici del venditore non sostituiscono nulla. La protezione dei conti bancari non rifiuta il suo IBAN quando il documento indica il titolare dell’account come acquirente e un’altra parte come venditore.
- Quando un altro documento indica il titolare dell’account come acquirente e un’altra parte come venditore, le parti restano come sono state lette e la conversione si ferma per la verifica (`party_roles_conflict_with_seller_profile`). Correggere le parti, oppure scegliere il tipo 389 se si tratta di autofatturazione.
- JSON non valido, chiavi sconosciute, conti non validi, più di cinque conti o coppia incompleta: `400 INVALID_SELLER_MASTER_DATA`.

### Valori applicati

Un'attività completata elenca in `applied_values` ogni valore che il servizio ha impostato invece di leggerlo dal documento: i valori presi dai dati anagrafici del venditore e i valori derivati. Ogni voce indica il campo di verifica (`field`), il termine EN 16931 (`business_term`), la fonte `source` (`seller_master_data` o `derived`), un `code`, il valore emesso `value` e, quando un valore del documento è stato sostituito, `previous_value`. Un valore salvato uguale a quello del documento non viene elencato. L'elenco è vuoto quando non è stato impostato nulla. È solo informativo e non fa mai fallire un'attività.

| `code` | Significato |
|---|---|
| `seller_master_data_filled` | Il documento non conteneva alcun valore; è stato usato il valore salvato. |
| `seller_master_data_replaced` | Il valore salvato ha sostituito il valore del documento indicato in `previous_value`. |
| `seller_master_data_removed` | Un conto bancario stampato senza un successore salvato è stato rimosso; `value` è assente. |
| `delivery_country_derived_domestic_touchless`, `delivery_country_derived_from_buyer`, `delivery_country_from_matching_party_address` | Il paese di consegna (BT-80) è stato derivato dagli indirizzi delle parti. |
| `seller_endpoint_derived_from_printed_email_touchless` | L'indirizzo elettronico del venditore (BT-34) è stato preso dall'indirizzo e-mail stampato del venditore. |

Possono essere aggiunti altri codici; trattate un codice sconosciuto come informazione.

## 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). La chiave è già stata usata per una conversione completata e i suoi record di 24 h sono scaduti: `409 IDEMPOTENCY_KEY_ALREADY_USED` (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 oppure attendi il relativo evento webhook; avvia la conversione successiva quando una termina. V1 non offre endpoint batch o elenco delle attività.

## Webhook

Invece del polling, registri un endpoint HTTPS per l’azienda della Sua chiave API. Quando una conversione accettata tramite questa API termina, il servizio invia un `POST` firmato con un piccolo evento JSON. L’evento è una notifica, non il risultato: scarichi il risultato come di consueto con `GET /tasks/{task_id}/result`. Il polling continua a funzionare e resta la soluzione di riserva.

**Registrare.** `POST /webhook-endpoint` con il corpo JSON `{"url": "https://..."}` restituisce `201` (oppure `200` quando sostituisce l’endpoint) con il `secret` di firma. Il secret compare solo in questa risposta; lo conservi sul Suo server. Inviare di nuovo la richiesta sostituisce l’URL e ruota il secret. `GET /webhook-endpoint` mostra l’URL e l’ultima consegna, mai il secret. `DELETE /webhook-endpoint` interrompe tutte le consegne. `POST /webhook-endpoint:test` mette in coda un evento `webhook.test` verso il Suo endpoint.

**Eventi.** `conversion.succeeded` (task `completed`) e `conversion.failed` (task `failed`; `data.error.code` è il codice che restituisce `/result`). Il corpo contiene `id`, `type`, `api_version`, `created_at` e `data` con `task_id`, `status`, `client_reference`, `source_system`, `format`, `profile`, `created_at`, `completed_at` ed `error`. Non contiene dati della fattura né link di download.

```json
{"api_version":"v1","created_at":"2026-11-18T10:00:05+00:00","data":{"client_reference":"ERP-2026-0001","completed_at":"2026-11-18T10:00:04+00:00","created_at":"2026-11-18T09:58:51+00:00","error":null,"format":"XRECHNUNG","profile":"XRECHNUNG","source_system":null,"status":"completed","task_id":"550e8400-e29b-41d4-a716-446655440000"},"id":"evt_9b2f0c1e7a3d4e5f8a6b0c1d2e3f4a5b","type":"conversion.succeeded"}
```

**Verificare la firma.** Ogni richiesta riporta `X-Invoice-Converter-Signature: t=<unix seconds>,v1=<hex>`, `X-Invoice-Converter-Event-Id` e `X-Invoice-Converter-Event-Type`. Calcoli HMAC-SHA256 su `<t>.<raw body>` usando come chiave l’intero secret, compreso il prefisso `whsec_`. Confronti il risultato con `v1` in tempo costante e rifiuti la richiesta quando `t` si discosta di oltre 5 minuti dal Suo orologio. Verifichi i byte grezzi prima di analizzare il JSON.

```python
import hashlib, hmac, time

def verify(secret: str, header: str, raw_body: bytes) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(","))
    timestamp = int(parts["t"])
    signed = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return abs(time.time() - timestamp) <= 300 and hmac.compare_digest(expected, parts["v1"])
```

**Consegna e nuovi tentativi.** Risponda con qualsiasi `2xx` entro 10 secondi; il servizio ignora il corpo della risposta e non segue reindirizzamenti. Qualsiasi altro stato, un timeout o un errore di connessione conta come tentativo fallito. Il servizio prova fino a 8 volte in circa 23 ore (dopo circa 1 min, 5 min, 30 min, 1 h, 3 h, 6 h e 12 h, con variazione casuale) e poi rinuncia. La consegna avviene almeno una volta e senza ordine garantito: deduplichi per `X-Invoice-Converter-Event-Id` e consideri `GET /tasks/{task_id}` la fonte di verità.

**Regole per l’URL.** `https` sulla porta 443 e un nome DNS pubblico, senza indirizzo IP, nome utente, password o frammento. Il nome deve risolversi solo in indirizzi pubblici; il controllo avviene alla registrazione e di nuovo prima di ogni consegna. Un URL rifiutato restituisce `422 INVALID_WEBHOOK_URL` con `details.reason`.

## 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. |
| `API_NOT_ENABLED_FOR_TENANT` | 403 | no | Attivi l’accesso API tramite `details.action_url`. |
| `INSUFFICIENT_API_CREDITS` | 402 | no | Acquisti crediti tramite `details.action_url` o attenda il mese successivo. |
| `IDEMPOTENCY_IN_PROGRESS` | 409 | stessa chiave | Riprovi dopo una breve attesa. |
| `IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_REPLAY_EXPIRED`, `IDEMPOTENCY_KEY_ALREADY_USED` | 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. |
| `DOCUMENT_NOT_CONVERTIBLE` | 422 | no | Corregga il documento sorgente (`details.recovery_hint`), poi converta di nuovo. |
| `TASK_FAILED` | 500 | se `details.retryable` | Legga `details.code`. Se ripetibile: nuova conversione con una nuova chiave. |
| `ARTIFACT_GENERATION_RERUN_REQUIRED`, `EXTRACTION_INCOMPLETE_GROUP_FAILURE` | 409 | nuovo task | Il task non può riprendersi. Avvii una nuova conversione con una nuova chiave. |
| `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`: `SCHEMA_PARSE_FAILED`, `ARTIFACT_PARITY_FAILED` (definitivi); `SOURCE_TEXT_UNAVAILABLE`, `PROVIDER_ERROR` (segua `details.retryable`); `task_interrupted` (ripetibile: il server si è fermato prima della fine della conversione). Motivi di `422 DOCUMENT_NOT_CONVERTIBLE`: `MULTIPLE_INVOICES_IN_DOCUMENT`, `NO_INVOICE_DETECTED`, `INSUFFICIENT_INVOICE_SIGNAL`, `EMBEDDED_INVOICE_XML_INVALID`, `EMBEDDED_INVOICE_XML_UNREPRESENTABLE` e un `SOURCE_TEXT_UNAVAILABLE` non ripetibile o un `PROVIDER_ERROR` con `classification=provider_context_too_large`. `409 ARTIFACT_GENERATION_RERUN_REQUIRED` con `details.code=AUTHORITATIVE_VALIDATION_UNAVAILABLE`: il validatore o un’altra dipendenza dell’artefatto è rimasto non disponibile anche dopo i tentativi lato server. Un task fallito resta fallito. Un nuovo tentativo automatico richiede una nuova conversione e una nuova chiave; una correzione manuale crea un risultato separato e collegato.

Per le attività non riuscite, `review_url` apre una correzione nell’app web per l’azienda interessata. Accedi con un account autorizzato per tale azienda. I dati conservati si aprono nell’editor; altrimenti l’app propone un nuovo caricamento. La correzione completata è collegata in `correction`; l’attività originale e `/result` mantengono lo stato originale. Resta valida la scadenza di conservazione iniziale.

## Risultati, prove e report di validazione

- `/result` esegue solo il recupero. Restituisce `200` solo per un artefatto archiviato con una prova di validazione attuale. Solo i task accettati tramite `POST /invoices:convert` o `POST /invoices:convert-structured` hanno un risultato; per qualsiasi altro task del suo account, `GET /tasks/{task_id}` e `/result` restituiscono `404 TASK_NOT_FOUND`.
- 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.<xml|pdf>.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 una quota condivisa con l’importazione via e-mail e le elaborazioni in blocco: 100 unità per mese di calendario con fatturazione mensile, oppure 1.200 unità per anno contrattuale con fatturazione annuale, disponibili subito dal primo pagamento annuale (100 al mese durante la prova). Le unità non utilizzate scadono alla fine del periodo. 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, tutte le chiamate ai task e i webhook sono gratuiti. 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: <https://www.invoice-converter.com/developer-api/v1/openapi.json>
- Collection Postman: <https://www.invoice-converter.com/developer-api/v1/postman.json> (imposti `base_url`, `api_key`, `idempotency_key`)
- JSON Schema ed esempio della fattura strutturata: veda *Dati fattura strutturati*
- Canale fatture via e-mail: <https://www.invoice-converter.com/it/developer-api/email-invoices>
- Questa documentazione in Markdown (per LLM e lettura offline): <https://www.invoice-converter.com/it/developer-api/md>

## 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 tramite `details.action_url` o attenda il prossimo periodo di quota. 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: attivi un abbonamento Enterprise tramite `details.action_url` o 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`, `IDEMPOTENCY_REPLAY_EXPIRED` e `IDEMPOTENCY_KEY_ALREADY_USED`: 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 tramite `details.action_url` o attenda il prossimo periodo di quota. 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: attivi un abbonamento Enterprise tramite `details.action_url` o 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`, `IDEMPOTENCY_REPLAY_EXPIRED` e `IDEMPOTENCY_KEY_ALREADY_USED`: 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, task non accettato tramite questa API (ad esempio un caricamento web), oppure oltre 24 h dopo la conclusione: `404 TASK_NOT_FOUND`.
- Limite di frequenza: 60/min e 1.500/h per chiave API.

Per le attività non riuscite, `review_url` apre una correzione nell’app web per l’azienda interessata. Accedi con un account autorizzato per tale azienda. I dati conservati si aprono nell’editor; altrimenti l’app propone un nuovo caricamento. La correzione completata è collegata in `correction`; l’attività originale e `/result` mantengono lo stato originale. Resta valida la scadenza di conservazione iniziale.

**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: attivi un abbonamento Enterprise tramite `details.action_url` o contatti il supporto.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `404 TASK_NOT_FOUND`: task sconosciuto, task di un altro tenant, task non accettato tramite questa API 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`.

`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.
- Solo i task accettati tramite i due endpoint di conversione hanno un risultato. Qualsiasi altro task (ad esempio un caricamento web) restituisce `404 TASK_NOT_FOUND`.
- Durante l’elaborazione: `202 TASK_NOT_READY`. Task fallito: il suo errore tipizzato (`409 ARTIFACT_GENERATION_RERUN_REQUIRED`, `422 VALIDATION_FAILED`, `422 DOCUMENT_NOT_CONVERTIBLE`, `500 TASK_FAILED`).
- 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: attivi un abbonamento Enterprise tramite `details.action_url` o contatti il supporto.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `404 TASK_NOT_FOUND`: task sconosciuto, task di un altro tenant, task non accettato tramite questa API 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"
}
```

- `409`: `409`: il task è fallito per un motivo temporaneo e non può riprendersi; ripetere questa richiesta non riesce mai. Avvii una nuova conversione con una nuova Idempotency-Key. Codici: `ARTIFACT_GENERATION_RERUN_REQUIRED` (motivo in `details.code`, per esempio `AUTHORITATIVE_VALIDATION_UNAVAILABLE`), `EXTRACTION_INCOMPLETE_GROUP_FAILURE`.

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

- `422`: La fattura non può essere emessa. Da non ripetere: corregga i dati o il documento sorgente e avvii una nuova conversione. Codici: `VALIDATION_FAILED` (`details.items`), `DOCUMENT_NOT_CONVERTIBLE` (`details.code`, `details.recovery_hint`), `PROFILE_MISMATCH`, `ZUGFERD_SOURCE_PDF_INCOMPATIBLE`, `PROTECTED_BANK_DETAILS_MISMATCH` (`details.items`).

`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`.

`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: attivi un abbonamento Enterprise tramite `details.action_url` o 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"
}
```

- `409`: `409`: il task è fallito per un motivo temporaneo e non può riprendersi; ripetere questa richiesta non riesce mai. Avvii una nuova conversione con una nuova Idempotency-Key. Codici: `ARTIFACT_GENERATION_RERUN_REQUIRED` (motivo in `details.code`, per esempio `AUTHORITATIVE_VALIDATION_UNAVAILABLE`), `EXTRACTION_INCOMPLETE_GROUP_FAILURE`.

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

- `422`: La fattura non può essere emessa. Da non ripetere: corregga i dati o il documento sorgente e avvii una nuova conversione. Codici: `VALIDATION_FAILED` (`details.items`), `DOCUMENT_NOT_CONVERTIBLE` (`details.code`, `details.recovery_hint`), `PROFILE_MISMATCH`, `ZUGFERD_SOURCE_PDF_INCOMPATIBLE`, `PROTECTED_BANK_DETAILS_MISMATCH` (`details.items`).

`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`.

`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}/correction-result — Scarica la fattura corretta

Scarica la correzione collegata dopo che un membro dell’azienda l’ha completata nell’editor web. Si applicano i permessi della chiave API e la scadenza di conservazione originali. Il download non modifica il risultato originale e non consuma un’altra unità. Limite: 60/min e 1,000/h.

**Parametri**

| Nome | Posizione | Tipo | Obbligatorio | Descrizione |
| --- | --- | --- | --- | --- |
| `task_id` | path | string (uuid) | sì | `task_id` della risposta `202`. Non è un UUID → `400 BAD_REQUEST`. |
| `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`: File della fattura corretta e validata.

`application/xml`

```json
{
  "type": "string",
  "format": "binary"
}
```

`application/pdf`

```json
{
  "type": "string",
  "format": "binary"
}
```

- `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: attivi un abbonamento Enterprise tramite `details.action_url` o contatti il supporto.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: Correzione non disponibile, scaduta, incompleta o non più valida. Leggi `code` prima di riprovare.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `409`: Correzione non disponibile, scaduta, incompleta o non più valida. Leggi `code` prima di riprovare.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `410`: Correzione non disponibile, scaduta, incompleta o non più valida. Leggi `code` prima di riprovare.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `422`: Correzione non disponibile, scaduta, incompleta o non più valida. Leggi `code` prima di riprovare.

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

- `503`: Correzione non disponibile, scaduta, incompleta o non più valida. Leggi `code` prima di riprovare.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### GET /webhook-endpoint — Leggere l’endpoint webhook

Restituisce l’URL registrato e l’esito dell’ultimo tentativo di consegna. Il secret non viene mai restituito.

- Limite di frequenza: 30/min e 300/h per chiave API, condiviso da `POST`, `GET`, `DELETE /webhook-endpoint`.

**Parametri**

| Nome | Posizione | Tipo | Obbligatorio | Descrizione |
| --- | --- | --- | --- | --- |
| `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`: L’endpoint registrato.

`application/json`

```json
{
  "$ref": "#/components/schemas/WebhookEndpoint"
}
```

- `401`: Autenticazione non riuscita. Da non ripetere.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Da non ripetere: attivi un abbonamento Enterprise tramite `details.action_url` o contatti il supporto.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `404 WEBHOOK_ENDPOINT_NOT_FOUND`. Nessun endpoint è registrato per l’azienda della chiave API.

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

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

- `503`: Temporaneamente non disponibile. Riprovare con backoff: `WEBHOOK_STORE_UNAVAILABLE`, `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### POST /webhook-endpoint — Registrare o sostituire l’endpoint webhook

Registra l’endpoint HTTPS che riceve gli eventi di completamento dell’azienda della chiave API, oppure lo sostituisce. La risposta contiene il `secret` di firma; non viene mai più mostrato.

- Un nuovo endpoint restituisce `201`, una sostituzione `200`. Una sostituzione ruota subito il secret: gli eventi ancora in attesa vanno al nuovo URL, firmati con il nuovo secret.
- L’URL deve usare `https` sulla porta 443 e indicare un host DNS pubblico (veda *Webhook* nella guida); altrimenti `422 INVALID_WEBHOOK_URL` con `details.reason`.
- Non serve un `Idempotency-Key`. Ripetere la chiamata sostituisce l’endpoint e ruota di nuovo il secret.
- Limite di frequenza: 30/min e 300/h per chiave API, condiviso da `POST`, `GET`, `DELETE /webhook-endpoint`.

**Parametri**

| Nome | Posizione | Tipo | Obbligatorio | Descrizione |
| --- | --- | --- | --- | --- |
| `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`: L’endpoint è stato sostituito e il secret ruotato.

`application/json`

```json
{
  "$ref": "#/components/schemas/WebhookEndpointCreated"
}
```

- `201`: L’endpoint è stato registrato.

`application/json`

```json
{
  "$ref": "#/components/schemas/WebhookEndpointCreated"
}
```

- `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: attivi un abbonamento Enterprise tramite `details.action_url` o contatti il supporto.

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

- `422`: `422 INVALID_WEBHOOK_URL`. Da non ripetere: invii un URL conforme alle regole di *Webhook*. `details.reason` indica la regola: `scheme`, `port`, `userinfo`, `fragment`, `ip_literal`, `host`, `characters`, `length`, `syntax`, `dns_failed` o `address_not_allowed`.

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

- `503`: Temporaneamente non disponibile. Riprovare con backoff: `WEBHOOK_STORE_UNAVAILABLE`, `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### DELETE /webhook-endpoint — Eliminare l’endpoint webhook

Rimuove l’endpoint e ogni evento ancora in attesa di consegna. Il polling non cambia.

- Limite di frequenza: 30/min e 300/h per chiave API, condiviso da `POST`, `GET`, `DELETE /webhook-endpoint`.

**Parametri**

| Nome | Posizione | Tipo | Obbligatorio | Descrizione |
| --- | --- | --- | --- | --- |
| `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**

- `204`: L’endpoint è stato eliminato.
- `401`: Autenticazione non riuscita. Da non ripetere.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Da non ripetere: attivi un abbonamento Enterprise tramite `details.action_url` o contatti il supporto.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `404 WEBHOOK_ENDPOINT_NOT_FOUND`. Nessun endpoint è registrato per l’azienda della chiave API.

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

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

- `503`: Temporaneamente non disponibile. Riprovare con backoff: `WEBHOOK_STORE_UNAVAILABLE`, `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

### POST /webhook-endpoint:test — Inviare un evento di test

Mette in coda un evento `webhook.test` firmato per l’endpoint registrato. La consegna segue le regole e i nuovi tentativi abituali; `GET /webhook-endpoint` ne mostra l’esito.

- Limite di frequenza: 5/min e 50/h per chiave API.

**Parametri**

| Nome | Posizione | Tipo | Obbligatorio | Descrizione |
| --- | --- | --- | --- | --- |
| `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**

- `202`: L’evento di test è stato messo in coda.

`application/json`

```json
{
  "$ref": "#/components/schemas/WebhookTestQueued"
}
```

- `401`: Autenticazione non riuscita. Da non ripetere.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `403`: `403 API_NOT_ENABLED_FOR_TENANT`. Da non ripetere: attivi un abbonamento Enterprise tramite `details.action_url` o contatti il supporto.

`application/json`

```json
{
  "$ref": "#/components/schemas/ErrorEnvelope"
}
```

- `404`: `404 WEBHOOK_ENDPOINT_NOT_FOUND`. Nessun endpoint è registrato per l’azienda della chiave API.

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

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

- `503`: Temporaneamente non disponibile. Riprovare con backoff: `WEBHOOK_STORE_UNAVAILABLE`, `AUTH_SERVICE_UNAVAILABLE`, `PLAN_TIER_CHECK_FAILED`, `RATE_LIMIT_SERVICE_UNAVAILABLE`.

`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"
    },
    "AdvancePaymentSettlement": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/components/schemas/StructuredInvoice_AdvancePaymentSettlementRow"
          },
          "maxItems": 200,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Advancepaymentsettlement"
    },
    "UninvoicedPrepaidAmount": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Pagamento lordo già ricevuto senza fattura di acconto. Incluso in BT-113 oltre alle righe AdvancePaymentSettlement numerate e indicato separatamente nell’allegato di conguaglio. Non includere questo importo anche in una riga di acconto numerata.",
      "title": "Uninvoicedprepaidamount"
    },
    "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"
        },
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "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_accounts": {
      "type": "array",
      "maxItems": 5,
      "description": "Conti del beneficiario salvati, nell’ordine di uscita. Ogni IBAN deve essere valido e univoco. Quando si applicano i dati anagrafici, un elenco non vuoto sostituisce tutti i conti per bonifico estratti (codici 30/42/58); gli altri mezzi di pagamento mantengono le regole di selezione esistenti.",
      "items": {
        "type": "object",
        "required": [
          "iban"
        ],
        "additionalProperties": false,
        "properties": {
          "iban": {
            "type": "string",
            "maxLength": 34,
            "description": "IBAN valido del beneficiario (BT-84), normalizzato senza spazi."
          },
          "bic": {
            "type": "string",
            "maxLength": 11,
            "description": "BIC della banca del beneficiario (BT-86), di 8 o 11 caratteri se indicato."
          },
          "account_name": {
            "type": "string",
            "maxLength": 240,
            "description": "Nome dell’intestatario del conto 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_accounts": [
        {
          "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=<primary_result_format>`."
    },
    "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"
    },
    "review_url": {
      "type": "string",
      "format": "uri",
      "description": "Apri la correzione della fattura nell’app web. Richiede accesso all’azienda."
    },
    "correction": {
      "type": [
        "object",
        "null"
      ],
      "description": "Correzione collegata, se già avviata.",
      "required": [
        "status",
        "run_id",
        "item_id"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "review_required",
            "reviewing",
            "completed",
            "expired"
          ]
        },
        "run_id": {
          "type": "string",
          "format": "uuid"
        },
        "item_id": {
          "type": "string",
          "format": "uuid"
        },
        "result_url": {
          "type": "string",
          "description": "URL relativa per il download, presente solo per una correzione completata e conservata."
        }
      },
      "additionalProperties": false
    },
    "applied_values": {
      "type": "array",
      "description": "Presente per un'attività completata il cui risultato è ancora conservato. Valori che il servizio ha impostato invece di leggerli dal documento: valori dai dati anagrafici del venditore e valori derivati. Vuoto quando non è stato impostato nulla. Vedere *Valori applicati*.",
      "items": {
        "$ref": "#/components/schemas/AppliedValue"
      }
    }
  },
  "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",
        "IDEMPOTENCY_KEY_ALREADY_USED",
        "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",
        "DOCUMENT_NOT_CONVERTIBLE",
        "PROFILE_MISMATCH",
        "ZUGFERD_SOURCE_PDF_INCOMPATIBLE",
        "PROTECTED_BANK_DETAILS_MISMATCH",
        "ZUGFERD_CII_CONVERSION_FAILED",
        "ZUGFERD_PDF_GENERATION_FAILED",
        "XML_GENERATION_FAILED",
        "PDF_GENERATION_FAILED",
        "ARTIFACT_GENERATION_RERUN_REQUIRED",
        "EXTRACTION_INCOMPLETE_GROUP_FAILURE",
        "INTERNAL_ARTIFACT_INVARIANT_FAILED",
        "VALIDATION_REPORT_NOT_FOUND",
        "VALIDATION_REPORT_FAILED",
        "PROXY_ERROR",
        "INVALID_WEBHOOK_URL",
        "WEBHOOK_ENDPOINT_NOT_FOUND",
        "WEBHOOK_STORE_UNAVAILABLE",
        "CORRECTION_RESULT_UNAVAILABLE"
      ],
      "x-enumDescriptions": {
        "AUTHENTICATION_REQUIRED": "401 · no · Invii `Authorization: Bearer <api_key>`.",
        "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. Attivi un abbonamento Enterprise tramite `details.action_url` o 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 tramite `details.action_url` 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.",
        "IDEMPOTENCY_KEY_ALREADY_USED": "409 · no · La chiave è già stata usata per una conversione completata, e i suoi record di replay di 24 h sono scaduti. Usi una nuova chiave per una nuova conversione.",
        "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`, il corpo multipart o un corpo webhook (8 KB) 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, GET sui percorsi dei task e i metodi dei percorsi webhook (veda `Allow`).",
        "NOT_FOUND": "404 · no · Percorso sconosciuto sotto /api/v1.",
        "BAD_REQUEST": "400 · no · `task_id` deve essere un UUID, oppure un corpo webhook non è l’oggetto JSON `{\"url\": \"...\"}`.",
        "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. Su `/tasks/{task_id}` e `/result` anche un task non accettato tramite questa API.",
        "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.",
        "DOCUMENT_NOT_CONVERTIBLE": "422 · no · Il documento sorgente non può essere convertito così com’è (motivo in `details.code`, passo successivo in `details.recovery_hint`). Corregga il documento 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`.",
        "PROTECTED_BANK_DETAILS_MISMATCH": "422 · no · Un IBAN del beneficiario (BT-84) non è tra i conti bancari protetti dall'indirizzo di controllo dell'account. Non è stato emesso alcun file e non è stata usata alcuna unità. Corregga l'IBAN nel documento sorgente o aggiunga il conto nel profilo (l'indirizzo di controllo deve confermarlo), poi avvii una nuova conversione.",
        "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.",
        "ARTIFACT_GENERATION_RERUN_REQUIRED": "409 · nuovo task · Nessun artefatto emesso: generazione o validazione autorevole non riuscita dopo i tentativi del server (motivo in `details.code`, per esempio `AUTHORITATIVE_VALIDATION_UNAVAILABLE`). Avvii una nuova conversione con una nuova Idempotency-Key.",
        "EXTRACTION_INCOMPLETE_GROUP_FAILURE": "409 · nuovo task · Gruppi di estrazione non riusciti (`details.failed_groups`). Avvii una nuova conversione con una nuova Idempotency-Key.",
        "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.",
        "CORRECTION_RESULT_UNAVAILABLE": "400/404/409/410/422/503 · condizionale · Correzione non disponibile o incompleta. Controlla lo stato collegato. Riprova per errori temporanei; i dati scaduti o eliminati richiedono un nuovo invio.",
        "INVALID_WEBHOOK_URL": "422 · no · L’URL del webhook viola una regola di *Webhook*, oppure il suo host si risolve in un indirizzo non pubblico. Veda `details.reason`.",
        "WEBHOOK_ENDPOINT_NOT_FOUND": "404 · no · Nessun endpoint webhook è registrato per l’azienda della chiave.",
        "WEBHOOK_STORE_UNAVAILABLE": "503 · sì · Non è stato possibile leggere o salvare la configurazione del webhook. Riprovare con backoff."
      },
      "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`, `access`, `message`."
    },
    "code": {
      "type": "string",
      "description": "Codice dell’errore sottostante: il motivo con `500 TASK_FAILED`, `422 DOCUMENT_NOT_CONVERTIBLE` e `409 ARTIFACT_GENERATION_RERUN_REQUIRED`; veda `x-enumDescriptions`.",
      "examples": [
        "MULTIPLE_INVOICES_IN_DOCUMENT",
        "NO_INVOICE_DETECTED",
        "INSUFFICIENT_INVOICE_SIGNAL",
        "EMBEDDED_INVOICE_XML_INVALID",
        "EMBEDDED_INVOICE_XML_UNREPRESENTABLE",
        "SOURCE_TEXT_UNAVAILABLE",
        "SCHEMA_PARSE_FAILED",
        "ARTIFACT_PARITY_FAILED",
        "PROVIDER_ERROR",
        "task_interrupted",
        "AUTHORITATIVE_VALIDATION_UNAVAILABLE"
      ],
      "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.",
        "EMBEDDED_INVOICE_XML_INVALID": "Definitivo. Solo con `use_embedded_xml=true`: non è stato possibile leggere l’XML incorporato nel PDF. Correggilo nel sistema emittente oppure invia il PDF senza `use_embedded_xml`.",
        "EMBEDDED_INVOICE_XML_UNREPRESENTABLE": "Definitivo. Solo con `use_embedded_xml=true`: l’XML incorporato contiene un valore che non può essere trasferito senza modifiche, ad esempio una data non nel formato 102 (`YYYYMMDD`). Correggilo nel sistema emittente oppure invia il PDF senza `use_embedded_xml`.",
        "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.",
        "task_interrupted": "Ripetibile. Il server che eseguiva la conversione si è fermato prima della fine. Non è stato emesso alcun artefatto e non è stata usata alcuna unità. Avvii una nuova conversione con una nuova chiave.",
        "AUTHORITATIVE_VALIDATION_UNAVAILABLE": "Con `409 ARTIFACT_GENERATION_RERUN_REQUIRED`: il validatore o un’altra dipendenza dell’artefatto è rimasto non disponibile anche dopo i tentativi lato server. Non è stato emesso alcun artefatto e non è stata usata alcuna unità. Avvii una nuova conversione con una nuova Idempotency-Key."
      }
    },
    "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": "Passo successivo leggibile dalla macchina: `start_new_conversion`, `fix_source_document`, `buy_api_credits` o `activate_api_access`."
    },
    "action_url": {
      "type": "string",
      "format": "uri",
      "description": "Pagina in cui il titolare dell’account risolve `402 INSUFFICIENT_API_CREDITS` (acquistare crediti) o `403 API_NOT_ENABLED_FOR_TENANT` (attivare l’accesso API)."
    },
    "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`."
    },
    "business_term": {
      "type": [
        "string",
        "null"
      ],
      "description": "Termine di business EN 16931 del campo, se noto, per esempio `BT-10`."
    },
    "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. Per una riga che riporta solo un importo, descrive la proposta in `proposal`."
    },
    "proposal": {
      "type": [
        "object",
        "null"
      ],
      "description": "Presente solo nei rilievi di una riga che riporta solo il suo importo netto (BT-131), senza quantità né prezzo unitario: quantità 1, unità `C62` e prezzo unitario = importo netto, corretto per un forfait o un singolo articolo. Una proposta, non una conversione: se la fattura indica quantità e prezzo, invia quei valori; altrimenti conferma la proposta inviando questi valori in una nuova conversione. Assente per una riga con un’unità fisica, uno sconto o una maggiorazione, uno sconto sul prezzo, una quantità di base diversa da 1 o un importo negativo.",
      "properties": {
        "kind": {
          "type": "string",
          "enum": [
            "amount_only_line"
          ]
        },
        "requires_confirmation": {
          "type": "boolean",
          "description": "Sempre `true`: nulla viene applicato finché il chiamante non invia i valori."
        },
        "line_index": {
          "type": "integer",
          "description": "Posizione della riga in `InvoiceLine` (o `CreditNoteLine`), a partire da zero."
        },
        "line_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "L’identificativo della riga (BT-126)."
        },
        "values": {
          "type": "object",
          "description": "Valori proposti per percorso di riga: `InvoicedQuantity` (o `CreditedQuantity`) `1`, il suo `@unitCode` `C62` e `Price.PriceAmount` uguale all’importo netto della riga.",
          "additionalProperties": {
            "type": "string"
          },
          "examples": [
            {
              "InvoicedQuantity": "1",
              "InvoicedQuantity.@unitCode": "C62",
              "Price.PriceAmount": "250"
            }
          ]
        }
      },
      "required": [
        "kind",
        "requires_confirmation",
        "line_index",
        "values"
      ]
    },
    "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",
        "recovery",
        "action_url"
      ],
      "properties": {
        "type": {
          "type": "string",
          "const": "context"
        },
        "remaining": {
          "type": "integer",
          "description": "Crediti prepagati residui."
        },
        "minimum_purchase": {
          "type": "integer",
          "description": "Pacchetto di crediti più piccolo (100)."
        },
        "recovery": {
          "type": "string",
          "const": "buy_api_credits"
        },
        "action_url": {
          "type": "string",
          "format": "uri",
          "description": "Pagina del profilo che vende i pacchetti di crediti API."
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}
```

### `InsufficientApiCreditsAllowanceError`

```json
{
  "type": "object",
  "description": "Struttura del 402 per gli account con una quota inclusa 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",
        "recovery",
        "action_url"
      ],
      "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)."
        },
        "recovery": {
          "type": "string",
          "const": "buy_api_credits"
        },
        "action_url": {
          "type": "string",
          "format": "uri",
          "description": "Pagina del profilo che vende i pacchetti di crediti API."
        }
      },
      "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_AdvancePaymentSettlementRow`

```json
{
  "additionalProperties": false,
  "description": "Un acconto ricevuto che una fattura finale cumulativa detrae in BT-113.\n\nLe righe non sono un gruppo EN 16931: la fattura elettronica le contiene come tabella di liquidazione PDF in allegato\n(BG-24, ID \"advance-settlement\"). Indicare solo i valori stampati sull'acconto;\nl'IVA non viene mai derivata dall'importo lordo. La somma degli importi lordi deve essere pari a BT-113.",
  "properties": {
    "ID": {
      "maxLength": 200,
      "minLength": 1,
      "title": "Id",
      "type": "string"
    },
    "IssueDate": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Issuedate"
    },
    "NetAmount": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Netamount"
    },
    "TaxPercent": {
      "anyOf": [
        {
          "maximum": 100,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Taxpercent"
    },
    "TaxAmount": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Taxamount"
    },
    "GrossAmount": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "title": "Grossamount"
    }
  },
  "required": [
    "ID",
    "GrossAmount"
  ],
  "title": "AdvancePaymentSettlementRow",
  "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": "string"
        },
        {
          "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": [
        {
          "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": "string"
        },
        {
          "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
    },
    "ExternalReference": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/StructuredInvoice_ExternalReference"
        },
        {
          "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": "string"
        },
        {
          "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_ExternalReference`

```json
{
  "additionalProperties": false,
  "properties": {
    "URI": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Uri"
    }
  },
  "title": "ExternalReference",
  "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": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "title": "Invoicedquantity"
    },
    "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": [
        {
          "enum": [
            "3",
            "35",
            "432"
          ],
          "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": "string"
        },
        {
          "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"
    },
    "DiscountDayBasis": {
      "anyOf": [
        {
          "enum": [
            "calendar_days_from_invoice_date",
            "working_days",
            "goods_receipt_or_other_anchor",
            "unknown"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Discountdaybasis"
    },
    "DiscountPercent": {
      "anyOf": [
        {
          "maximum": 100,
          "minimum": 0,
          "type": "number"
        },
        {
          "type": "string"
        },
        {
          "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"
        },
        {
          "type": "string"
        },
        {
          "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": "string"
        },
        {
          "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"
}
```

### `WebhookEndpointRequest`

```json
{
  "type": "object",
  "required": [
    "url"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048,
      "description": "URL `https` sulla porta 443 con un host DNS pubblico. Una query string è consentita; non viene mai registrata nei log."
    }
  },
  "additionalProperties": false
}
```

### `WebhookEndpointCreated`

```json
{
  "type": "object",
  "required": [
    "url",
    "secret",
    "created_at",
    "updated_at",
    "event_types",
    "correlation_id"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    },
    "secret": {
      "type": "string",
      "pattern": "^whsec_[A-Za-z0-9_-]{43}$",
      "description": "Secret di firma: `whsec_` e 32 byte casuali. Visibile solo in questa risposta."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Quando l’endpoint è stato registrato la prima volta (UTC)."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Quando URL e secret sono stati impostati l’ultima volta (UTC)."
    },
    "event_types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "conversion.succeeded",
          "conversion.failed"
        ]
      },
      "description": "I tipi di evento che l’endpoint riceve."
    },
    "correlation_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
```

### `WebhookLastDelivery`

```json
{
  "type": [
    "object",
    "null"
  ],
  "required": [
    "at",
    "outcome",
    "status_code",
    "error",
    "event_id"
  ],
  "description": "L’ultimo tentativo di consegna, oppure `null` prima del primo.",
  "properties": {
    "at": {
      "type": "string",
      "format": "date-time",
      "description": "Quando il tentativo è stato registrato (UTC)."
    },
    "outcome": {
      "type": "string",
      "enum": [
        "delivered",
        "retrying",
        "failed"
      ],
      "description": "`delivered`: una risposta `2xx`. `retrying`: il tentativo è fallito e ne è previsto un altro. `failed`: l’ultimo tentativo è fallito e l’evento è stato abbandonato."
    },
    "status_code": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Stato HTTP della Sua risposta, se è arrivata."
    },
    "error": {
      "type": [
        "string",
        "null"
      ],
      "description": "Perché il tentativo è fallito: `http_status`, `timeout`, `connection_failed`, `request_failed`, `dns_failed`, `address_not_allowed` o un’altra regola URL di `INVALID_WEBHOOK_URL`."
    },
    "event_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "`id` dell’evento di quel tentativo."
    }
  },
  "additionalProperties": false
}
```

### `WebhookEndpoint`

```json
{
  "type": "object",
  "required": [
    "url",
    "created_at",
    "updated_at",
    "event_types",
    "last_delivery",
    "correlation_id"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "event_types": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "conversion.succeeded",
          "conversion.failed"
        ]
      },
      "description": "I tipi di evento che l’endpoint riceve."
    },
    "last_delivery": {
      "$ref": "#/components/schemas/WebhookLastDelivery"
    },
    "correlation_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
```

### `WebhookTestQueued`

```json
{
  "type": "object",
  "required": [
    "event_id",
    "type",
    "correlation_id"
  ],
  "properties": {
    "event_id": {
      "type": "string",
      "description": "`id` dell’evento in coda; la richiesta lo riporta in `X-Invoice-Converter-Event-Id`."
    },
    "type": {
      "type": "string",
      "enum": [
        "webhook.test"
      ]
    },
    "correlation_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": false
}
```

### `WebhookConversionEventData`

```json
{
  "type": "object",
  "required": [
    "task_id",
    "status",
    "created_at",
    "completed_at",
    "client_reference",
    "source_system",
    "format",
    "profile",
    "error"
  ],
  "description": "Gli stessi valori che `GET /tasks/{task_id}` restituisce per il task, più `format` e `profile` richiesti.",
  "properties": {
    "task_id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "type": "string",
      "enum": [
        "completed",
        "failed"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "completed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "client_reference": {
      "type": [
        "string",
        "null"
      ],
      "description": "Eco di `client_reference`."
    },
    "source_system": {
      "type": [
        "string",
        "null"
      ],
      "description": "Eco di `source_system`."
    },
    "format": {
      "type": [
        "string",
        "null"
      ],
      "description": "Il `format` richiesto, per esempio `XRECHNUNG`."
    },
    "profile": {
      "type": [
        "string",
        "null"
      ],
      "description": "Il profilo effettivo, per esempio `XRECHNUNG`."
    },
    "error": {
      "type": [
        "object",
        "null"
      ],
      "required": [
        "code"
      ],
      "description": "`null` per `conversion.succeeded`. Per `conversion.failed`, il `code` che restituisce `GET /tasks/{task_id}/result`; lo chiami per i dettagli.",
      "properties": {
        "code": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}
```

### `WebhookTestEventData`

```json
{
  "type": "object",
  "required": [
    "test"
  ],
  "properties": {
    "test": {
      "type": "boolean",
      "enum": [
        true
      ]
    }
  },
  "additionalProperties": false
}
```

### `WebhookEvent`

```json
{
  "type": "object",
  "required": [
    "id",
    "type",
    "api_version",
    "created_at",
    "data"
  ],
  "description": "Corpo di una richiesta webhook, firmato così come inviato. Recuperi i risultati tramite gli endpoint dei task.",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^evt_[0-9a-f]{32}$",
      "description": "ID dell’evento, anche in `X-Invoice-Converter-Event-Id`. I nuovi tentativi lo mantengono."
    },
    "type": {
      "type": "string",
      "enum": [
        "conversion.succeeded",
        "conversion.failed",
        "webhook.test"
      ]
    },
    "api_version": {
      "type": "string",
      "enum": [
        "v1"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Quando l’evento è stato creato (UTC)."
    },
    "data": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/WebhookConversionEventData"
        },
        {
          "$ref": "#/components/schemas/WebhookTestEventData"
        }
      ]
    }
  },
  "additionalProperties": false
}
```

### `AppliedValue`

```json
{
  "type": "object",
  "required": [
    "field",
    "source",
    "code"
  ],
  "properties": {
    "field": {
      "type": "string",
      "description": "Campo di verifica del valore, ad esempio `Seller.City` o `Payment.Accounts.0.IBAN`."
    },
    "business_term": {
      "type": "string",
      "description": "Termine di business EN 16931, ad esempio `BT-37`. Assente quando il campo non ne ha uno."
    },
    "source": {
      "type": "string",
      "enum": [
        "seller_master_data",
        "derived"
      ],
      "description": "Origine del valore emesso."
    },
    "code": {
      "type": "string",
      "description": "Codice del motivo, vedere *Valori applicati*. Possono essere aggiunti altri codici."
    },
    "previous_value": {
      "type": "string",
      "description": "Il valore del documento che è stato sostituito. Assente quando il documento non ne conteneva."
    },
    "value": {
      "type": "string",
      "description": "Il valore emesso. Assente quando un valore è stato rimosso."
    }
  },
  "additionalProperties": false
}
```

## Codici di errore

| Codice | Descrizione |
| --- | --- |
| `AUTHENTICATION_REQUIRED` | 401 · no · Invii `Authorization: Bearer <api_key>`. |
| `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. Attivi un abbonamento Enterprise tramite `details.action_url` o 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 tramite `details.action_url` 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. |
| `IDEMPOTENCY_KEY_ALREADY_USED` | 409 · no · La chiave è già stata usata per una conversione completata, e i suoi record di replay di 24 h sono scaduti. Usi una nuova chiave per una nuova conversione. |
| `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`, il corpo multipart o un corpo webhook (8 KB) 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, GET sui percorsi dei task e i metodi dei percorsi webhook (veda `Allow`). |
| `NOT_FOUND` | 404 · no · Percorso sconosciuto sotto /api/v1. |
| `BAD_REQUEST` | 400 · no · `task_id` deve essere un UUID, oppure un corpo webhook non è l’oggetto JSON `{"url": "..."}`. |
| `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. Su `/tasks/{task_id}` e `/result` anche un task non accettato tramite questa API. |
| `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. |
| `DOCUMENT_NOT_CONVERTIBLE` | 422 · no · Il documento sorgente non può essere convertito così com’è (motivo in `details.code`, passo successivo in `details.recovery_hint`). Corregga il documento 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`. |
| `PROTECTED_BANK_DETAILS_MISMATCH` | 422 · no · Un IBAN del beneficiario (BT-84) non è tra i conti bancari protetti dall'indirizzo di controllo dell'account. Non è stato emesso alcun file e non è stata usata alcuna unità. Corregga l'IBAN nel documento sorgente o aggiunga il conto nel profilo (l'indirizzo di controllo deve confermarlo), poi avvii una nuova conversione. |
| `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. |
| `ARTIFACT_GENERATION_RERUN_REQUIRED` | 409 · nuovo task · Nessun artefatto emesso: generazione o validazione autorevole non riuscita dopo i tentativi del server (motivo in `details.code`, per esempio `AUTHORITATIVE_VALIDATION_UNAVAILABLE`). Avvii una nuova conversione con una nuova Idempotency-Key. |
| `EXTRACTION_INCOMPLETE_GROUP_FAILURE` | 409 · nuovo task · Gruppi di estrazione non riusciti (`details.failed_groups`). Avvii una nuova conversione con una nuova Idempotency-Key. |
| `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. |
| `CORRECTION_RESULT_UNAVAILABLE` | 400/404/409/410/422/503 · condizionale · Correzione non disponibile o incompleta. Controlla lo stato collegato. Riprova per errori temporanei; i dati scaduti o eliminati richiedono un nuovo invio. |
| `INVALID_WEBHOOK_URL` | 422 · no · L’URL del webhook viola una regola di *Webhook*, oppure il suo host si risolve in un indirizzo non pubblico. Veda `details.reason`. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` | 404 · no · Nessun endpoint webhook è registrato per l’azienda della chiave. |
| `WEBHOOK_STORE_UNAVAILABLE` | 503 · sì · Non è stato possibile leggere o salvare la configurazione del webhook. Riprovare con backoff. |
