Walidacja e-faktur przez API

E-fakturę (na przykład XRechnung w formacie UBL lub CII albo plik PDF ZUGFeRD) można wysłać na adres POST /v1/validate. Odpowiedź to JSON z wynikiem i wszystkimi uwagami, dzięki czemu proces przyjmowania faktur może automatycznie wykluczyć błędne faktury.

Sprawdzenie jednej faktury

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

Odpowiedź

Również w przypadku nieprawidłowej faktury zwracany jest status 200; wynik znajduje się w polu verdict: valid, warnings lub invalid. W tym przykładzie brakuje referencji nabywcy 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 wskazuje etap walidacji (xsd, schematron, pdf, api, plausibility). versions zapisuje, który zestaw reguł został użyty do kontroli; można go zapisać razem z wynikiem.

Kontrole wiarygodności: więcej niż format

Z parametrem checks=plausibility API sprawdza także to, czego nie obejmują reguły formatu. Uwagi mają identyfikatory reguł rozpoczynające się od PL- i są opatrzone osobnym blokiem obliczonych wartości.

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'

Odpowiedź w skrócie:

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

Ostrzeżenie w tym przykładzie to PL-VATID-02: przykładowy numer DE123456789 ma nieprawidłową cyfrę kontrolną. W przypadku faktur o wartości do 250 EUR brutto (§ 33 niemieckiego rozporządzenia wykonawczego do ustawy o VAT, UStDV) kilka szczegółów jest zgłaszanych wyłącznie jako wskazówka.

Wiele faktur jednocześnie

/v1/validate/batch przyjmuje plik ZIP zawierający maksymalnie 200 plików, przy czym każdy plik może mieć do 5 MiB, a łączny rozmiar może wynosić do 50 MiB. API zgłasza zduplikowane numery faktur tego samego sprzedawcy w ramach partii jako PL-DUP-01. Z parametrem report=csv lub report=pdf otrzymuje się raport zbiorczy zamiast JSON. Walidacja wsadowa jest dostępna od planu Starter; każdy sprawdzony plik liczy się jako jedno wywołanie.

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

Czego kontrola nie obejmuje

Reguły sprawdzają format, reguły biznesowe, a w przypadku checks=plausibility również punkty wymienione powyżej. API nie może jednak wiedzieć, czy usługa, stawka VAT lub dane bankowe są merytorycznie prawidłowe. Formaty objęte walidacją i głębokość kontroli przedstawia tabela obsługiwanych formatów. W przypadku formatów oznaczonych jako „tylko schemat” lub „tylko reguły podstawowe” organy lub przepisy krajowe przeprowadzają dalsze kontrole, więc wynik pozytywny nie zastępuje tych kontroli. Reguły francuskie można sprawdzić za pomocą country=FR.

Plany

Free: 0 EUR miesięcznie, 50 wywołań. Starter: 19 EUR miesięcznie, 2000 wywołań. Business: 49 EUR miesięcznie, 10 000 wywołań. Pro: 149 EUR miesięcznie, 50 000 wywołań. Stałe ceny miesięczne, bez rozliczania za zużycie; po wyczerpaniu limitu API odpowiada kodem 429. Tylko dla firm. Nie nalicza się podatku VAT na podstawie § 19 niemieckiej ustawy o podatku od towarów i usług (UStG). Więcej limitów

W przeciwieństwie do bezpłatnego walidatora w przeglądarce, faktura jest przesyłana przez sieć Cloudflare na nasz serwer w Norymberdze. API przetwarza ją w pamięci i nie przechowuje treści faktury. Faktury można generować za pomocą XRechnung przez API i ZUGFeRD przez API; wysłanie ich do odbiorcy pozostaje po Państwa stronie.

Najczęściej zadawane pytania

Teksty prawne są dostępne w języku niemieckim i angielskim: polityka prywatności, warunki API i nota prawna. Wiążąca prawnie jest wyłącznie wersja niemiecka.