Validați facturile electronice prin API

Trimiteți o factură electronică (de exemplu o XRechnung ca UBL sau CII, sau un PDF ZUGFeRD) către POST /v1/validate. Răspunsul este un JSON cu un verdict și toate constatările, astfel încât procesul dumneavoastră de facturi primite să poată sorta automat facturile eronate.

Verificați o factură

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"])

Răspunsul

O factură nevalidă returnează de asemenea starea 200; verdictul se află în verdict: valid, warnings sau invalid. Aici lipsește referința cumpărătorului 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 numește etapa de validare (xsd, schematron, pdf, api, plausibility). versions înregistrează setul de reguli utilizat pentru verificare; îl puteți stoca împreună cu rezultatul.

Plauzibilitate: mai mult decât formatul

Cu checks=plausibility, API-ul verifică și ceea ce regulile de format nu acoperă. Constatările au ID-uri de reguli care încep cu PL- și vin cu un bloc separat de valori calculate.

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'

Răspunsul, prescurtat:

{
  "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": [] }
  }
}

Avertismentul din acest exemplu este PL-VATID-02: numărul de exemplu DE123456789 are o cifră de control greșită. Pentru facturile de până la 250 EUR brut (§ 33 din Regulamentul german de punere în aplicare a TVA, UStDV), mai multe detalii sunt raportate doar ca indiciu.

Mai multe facturi simultan

/v1/validate/batch acceptă un ZIP cu până la 200 de fișiere, până la 5 MiB per fișier și 50 MiB în total. API-ul raportează numerele de factură duplicate de la același vânzător din cadrul lotului ca PL-DUP-01. Cu report=csv sau report=pdf primiți un raport sumar în loc de JSON. Lotul este disponibil începând cu planul Starter; fiecare fișier verificat contează ca un apel.

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

Ce nu face verificarea

Regulile verifică formatul, regulile de business și, cu checks=plausibility, punctele enumerate mai sus. Dacă serviciul, cota de TVA sau datele bancare sunt corecte în fond este ceva ce API-ul nu poate ști. Ce formate acoperă validarea și cât de profund este prezentat în tabelul formate acceptate. Pentru formatele marcate „doar schemă” sau „doar reguli de bază”, autoritățile sau regulile naționale efectuează verificări suplimentare, astfel încât un verdict de trecere nu le înlocuiește. Verificați regulile franceze cu country=FR.

Planuri

Free: 0 EUR pe lună, 50 apeluri. Starter: 19 EUR pe lună, 2.000 apeluri. Business: 49 EUR pe lună, 10.000 apeluri. Pro: 149 EUR pe lună, 50.000 apeluri. Prețuri lunare fixe, fără facturare în funcție de utilizare; după epuizarea cotei, API-ul răspunde cu 429. Numai pentru întreprinderi. Nu se percepe TVA în temeiul § 19 din Legea germană privind taxa pe valoarea adăugată (UStG). Mai multe limite

Spre deosebire de validatorul gratuit din browser, factura dumneavoastră trece prin rețeaua Cloudflare către serverul nostru din Nürnberg. API-ul o procesează în memorie și nu stochează conținutul facturii. Puteți genera facturi cu XRechnung prin API și ZUGFeRD prin API; trimiterea lor către destinatar rămâne în sarcina dumneavoastră.

Întrebări frecvente

Textele juridice sunt disponibile în germană și engleză: politica de confidențialitate, condițiile API și impresum. Numai versiunea germană este obligatorie din punct de vedere juridic.