Validare fatture elettroniche via API

Invia una fattura elettronica (ad esempio una XRechnung in UBL o CII, oppure un PDF ZUGFeRD) a POST /v1/validate. La risposta è JSON con un esito e tutti i rilievi, così il tuo processo per le fatture in entrata può individuare automaticamente le fatture difettose.

Controllare una fattura

curl

curl -s -X POST 'https://api.electronic-invoice.app/v1/validate' \
  -H 'Authorization: Bearer eia_live_YOUR_KEY' \
  -H 'Content-Type: application/xml' \
  --data-binary @invoice.xml

Python (requests)

import requests

with open("invoice.xml", "rb") as f:
    r = requests.post(
        "https://api.electronic-invoice.app/v1/validate",
        headers={"Authorization": "Bearer eia_live_YOUR_KEY", "Content-Type": "application/xml"},
        data=f.read(),
        timeout=60,
    )
result = r.json()
print(result["verdict"])
for finding in result["findings"]:
    print(finding["severity"], finding["ruleId"], finding["message"])

La risposta

Anche una fattura non valida restituisce lo stato 200; l'esito si trova in verdict: valid, warnings o invalid. Qui manca il riferimento dell'acquirente BT-10:

{
  "verdict": "invalid",
  "country": "DE",
  "detected": {
    "container": "xml",
    "syntax": "UBL-Invoice",
    "guidelineId": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
    "profile": "XRECHNUNG",
    "scenario": "EN16931 XRechnung (UBL Invoice)"
  },
  "summary": { "errors": 1, "warnings": 0, "infos": 0 },
  "findings": [
    {
      "ruleId": "BR-DE-15",
      "severity": "error",
      "source": "schematron",
      "location": "/Invoice[1]",
      "message": "[BR-DE-15] Das Element \"Buyer reference\" (BT-10) muss übermittelt werden.",
      "explanation": {
        "de": "XRechnung: Die Käuferreferenz (BT-10, z. B. Leitweg-ID) ist Pflicht.",
        "en": "XRechnung: the buyer reference (BT-10, e.g. Leitweg-ID) is mandatory."
      }
    }
  ],
  "versions": {
    "xrechnungConfiguration": "xrechnung-3.0.2-validator-configuration-2026-08-31",
    "koSitValidator": "1.6.3",
    "mustang": "2.26.0",
    "cenSchematron": "1.3.16"
  }
}

source indica la fase di validazione (xsd, schematron, pdf, api, plausibility). versions registra quale insieme di regole è stato usato per il controllo; puoi memorizzarlo insieme al risultato.

Plausibilità: più del formato

Con checks=plausibility l'API controlla anche ciò che le regole di formato non coprono. I rilievi hanno ID della regola che iniziano con PL- e sono accompagnati da un blocco separato di valori calcolati.

curl -s -X POST 'https://api.electronic-invoice.app/v1/validate?checks=plausibility' \
  -H 'Authorization: Bearer eia_live_YOUR_KEY' \
  -H 'Content-Type: application/xml' \
  --data-binary @invoice.xml | jq '.plausibility'

La risposta, abbreviata:

{
  "verdict": "warnings",
  "summary": { "errors": 0, "warnings": 1, "infos": 1 },
  "computed": {
    "recalculated": {
      "sumOfLineNetAmounts": "200.00",
      "totalVat": "38.00",
      "totalWithVat": "238.00",
      "amountDue": "238.00"
    },
    "paymentTerms": { "dueDate": "2026-11-16", "daysFromIssueToDue": 14, "skonto": [] }
  }
}

L'avviso in questo esempio è PL-VATID-02: il numero di esempio DE123456789 ha una cifra di controllo errata. Per le fatture fino a EUR 250 lordi (§ 33 del regolamento tedesco di attuazione dell'IVA, UStDV), diversi dati vengono segnalati solo come avviso.

Più fatture in una volta

/v1/validate/batch accetta uno ZIP con fino a 200 file, fino a 5 MiB per file e 50 MiB in totale. L'API segnala i numeri di fattura duplicati dello stesso venditore all'interno del batch come PL-DUP-01. Con report=csv o report=pdf ottieni un report di riepilogo invece del JSON. Il batch è disponibile a partire dal piano Starter; ogni file controllato conta come una chiamata.

curl -s -X POST 'https://api.electronic-invoice.app/v1/validate/batch?report=csv' \
  -H 'Authorization: Bearer eia_live_YOUR_KEY' \
  -H 'Content-Type: application/zip' \
  --data-binary @inbox.zip \
  -o report.csv

file;status;verdict;errors;warnings;infos;syntax;profile;invoice_number;seller;duplicate_of;first_error_rule;first_error_message
a.xml;checked;invalid;1;0;0;UBL-Invoice;XRECHNUNG;RE-2026-0001;Test GmbH;b.xml;PL-DUP-01;Invoice number RE-2026-0001 of seller Test GmbH appears in 2 files of this batch (different content).

Cosa non fa il controllo

Le regole controllano il formato, le regole di business e, con checks=plausibility, i punti elencati sopra. Se il servizio, l'aliquota IVA o i dati bancari siano corretti nel merito è qualcosa che l'API non può sapere. Quali formati copre la validazione e con quale profondità è mostrato nella tabella dei formati supportati. Per i formati contrassegnati come "schema only" o "core rules only", autorità o regole nazionali eseguono ulteriori controlli, quindi un esito positivo non li sostituisce. Controlla le regole francesi con country=FR.

Piani

Free: 0 EUR al mese, 50 chiamate. Starter: 19 EUR al mese, 2000 chiamate. Business: 49 EUR al mese, 10.000 chiamate. Pro: 149 EUR al mese, 50.000 chiamate. Prezzi mensili fissi, nessuna fatturazione a consumo; esaurita la quota, l'API risponde con 429. Solo per aziende. Nessuna IVA applicata ai sensi del § 19 della legge tedesca sull'IVA (UStG). Altri limiti

A differenza del validatore gratuito nel browser, la tua fattura passa attraverso la rete Cloudflare fino al nostro server a Norimberga. L'API la elabora in memoria e non memorizza il contenuto della fattura. Puoi generare fatture con XRechnung via API e ZUGFeRD via API; l'invio al destinatario spetta a te.

Domande frequenti

I testi legali sono disponibili in tedesco e inglese: informativa sulla privacy, termini API e note legali. Solo la versione tedesca è giuridicamente vincolante.