API dla deweloperów · Strona odbiorcy
InvoiceIn.
Każda e-faktura, którą odbierasz, jako jeden JSON.
Jeden bezstanowy endpoint. Wyślij POST-em to, co trafia do Twojej skrzynki — XRechnung, ZUGFeRD, Factur-X, Peppol BIS 3, FatturaPA, KSeF — i odbierz kanoniczny JSON wg EN 16931, raport walidacji z podpowiedziami, co wystawca musi poprawić, PDF do pokazania człowiekowi oraz CSV lub DATEV do księgowości. Przetwarzanie w pamięci, ~10–50 ms na dokument.
Tylko w pamięci. Nic nie jest zapisywane. Bez punktu dostępowego Peppol.
Po co to istnieje
Dostawcy Twoich klientów wystawiają teraz faktury ustrukturyzowane FA(3) przez KSeF — a oprogramowanie klienta musi je odczytać. Do tego dochodzą XRechnung z Niemiec, FatturaPA z Włoch i Factur-X z Francji, a Twój kod był pisany pod PDF-y. Zamiast pięciu parserów i pięciu zestawów reguł wysyłasz nam plik i dostajesz jeden JSON plus listę tego, co jest w nim nie tak, opisaną słowami, które księgowa może przekazać dostawcy. Dokumentu nigdy nie przechowujemy.
Demo na żywo
Wrzuć prawdziwą fakturę, którą odbierasz. Parsujemy ją, walidujemy według oficjalnych zestawów reguł i pokazujemy podpowiedzi — nic nie zostaje zapisane.
Nagłówek
Uwagi
Surowy JSON
Pięć wyników. Jedno wywołanie.
Kanoniczny JSON wg EN 16931
Jeden kształt dla każdej składni. Pola nazwane według modelu semantycznego z numerami BT/BG: sprzedawca, nabywca, pozycje, podział VAT, sumy, płatność i IBAN, referencje, załączniki. Krajowe rozszerzenia trafiają do extensions.
Raport walidacji z podpowiedziami co poprawić
Oficjalne zestawy reguł plus arytmetyczne kontrole krzyżowe. Każda niespełniona reguła ma podpowiedź prostym językiem, po angielsku, niemiecku, francusku, włosku lub polsku — co wystawca musi zmienić i którego pola (numer BT) to dotyczy.
Czytelny PDF lub HTML
Ten sam układ A4 dla każdej składni, etykiety po angielsku, niemiecku, francusku, włosku lub polsku. Dla osoby zatwierdzającej, która chce zobaczyć fakturę, a nie XML.
CSV i DATEV
Płaski CSV per pozycja lub per dokument oraz paczka księgowań DATEV (niemiecki format księgowy; Buchungsstapel EXTF 700) dla faktury przychodzącej — SKR03 lub SKR04, Twoje konto wierzyciela.
Serwer MCP
Zdalnie pod /mcp lub lokalnie przez stdio. Claude, Cursor, n8n albo Twój własny agent odczytuje i waliduje fakturę jednym wywołaniem narzędzia.
Co wchodzi, co jest sprawdzane.
Wykrywanie jest automatyczne — wysyłasz plik, my mówimy, co to było. Hybrydowe PDF-y są otwierane, a osadzony XML wyodrębniany; sam PDF nigdy nie trafia na dysk.
| Format | Składnia | Kontener | Stosowana walidacja |
|---|---|---|---|
| XRechnung 3.0 | UBL 2.1 lub CII D16B | XML | XSD · EN 16931 Schematron 1.3.17 · XRechnung 3.0.2 · arytmetyka |
| EN 16931 | UBL 2.1 lub CII D16B | XML | XSD · EN 16931 Schematron 1.3.17 · arytmetyka |
| Peppol BIS Billing 3 | UBL 2.1 | XML | XSD · EN 16931 · reguły Peppol BIS 3 · arytmetyka |
| ZUGFeRD 2.x / Factur-X — EN 16931, EXTENDED, XRECHNUNG | CII D16B | hybrydowy PDF/A-3 lub sam XML | XSD · EN 16931 Schematron 1.3.17 · arytmetyka |
| ZUGFeRD 2.x / Factur-X — BASIC, BASIC WL, MINIMUM | CII D16B | hybrydowy PDF/A-3 lub sam XML | XSD · reguły profilu Factur-X 1.09.2 (FX-SCH) · arytmetyka (reguły podstawowe EN 16931 nie mają zastosowania poniżej profilu EN 16931) |
| ZUGFeRD 1.0 | CII (CrossIndustryDocument 1p0) | hybrydowy PDF/A-3 lub sam XML | Schemat · arytmetyka |
| FatturaPA 1.2 | FatturaPA | XML | FatturaPA 1.2.2 XSD · arytmetyka (pliki wielodokumentowe zwracane jako paczka) |
| KSeF FA(2) / FA(3) | schemat FA | XML | FA(2) / FA(3) XSD · arytmetyka |
| Francja — CTC-FR (sprzedawca i nabywca we Francji) | UBL 2.1 lub CII D16B | XML lub PDF Factur-X | XSD · EN 16931 · FNFE CTC-FR 1.4.0.04 (reguły BR-FR, Flux 2) · arytmetyka |
| RO e-Factura (CIUS-RO) | UBL 2.1 | XML | XSD · CIUS-RO 1.0.1, który zawiera już reguły EN 16931 · arytmetyka |
| ZEA — PINT AE (Billing, Self-Billing) | UBL 2.1 | XML | XSD · OpenPeppol PINT AE 1.0.4 (wspólne reguły PINT + reguły ZEA) · bezpłatna strona sprawdzania (EN) |
Wersje reguł są też dostępne na żywo pod GET /v1/formats. Brakuje formatu, który odbierasz? Daj nam znać.
Dla zespołów, które teraz muszą to odbierać.
Odbiór faktur ustrukturyzowanych przestał być opcją: w Polsce KSeF jest obowiązkowy dla wszystkich B2B od 1 kwietnia 2026, w Niemczech obowiązek odbioru trwa od 1 stycznia 2025, Belgia przez Peppol od stycznia 2026, Francja od 1 września 2026. Strona odbiorcy potrzebuje parsera, walidatora i sposobu, by pokazać dokument człowiekowi — i to jest cały produkt.
SaaS do AP i księgowości
Twoi klienci przekazują to, co wysyłają ich dostawcy. Jeden endpoint zamienia sześć składni w jeden JSON, który Twój proces dopasowania i akceptacji już rozumie — plus podpowiedź, którą można przekazać dostawcy, gdy jego plik jest błędny.
Wtyczki do ERP i sklepów
Dolibarr, InvoicePlane, Sylius, Shopware, Odoo — wtyczka, która czyta przychodzące faktury KSeF, XRechnung i Factur-X, to funkcja do wdrożenia w tym sprincie zamiast półrocznego projektu parsera. Bez Javy, bez toolchainu Schematron w Twoim buildzie.
Agencje budujące narzędzia dla MŚP
Mali klienci w PL, DE, FR, IT i Beneluksie dostają e-faktury i pytają Cię, co z nimi zrobić. Zwaliduj, wyrenderuj, wyeksportuj do CSV lub DATEV — i odeślij odrzucenie wystawcy z dokładnym polem do poprawy.
Trzy linijki do pierwszego parsowania.
Wyślij plik jako pole multipart file albo jako surowe body XML/PDF. Uwierzytelnij się przez Authorization: Bearer <key> lub X-Api-Key. Bez klucza dostajesz limit demo: 20 faktur na IP dziennie.
curl -X POST "https://invoicein-api.peculiar.systems/v1/invoice?include=validation&lang=en" \
-H "Authorization: Bearer $INVOICEIN_KEY" \
-F "[email protected]"import { readFile } from "node:fs/promises";
const form = new FormData();
form.append("file", new Blob([await readFile("invoice.xml")]), "invoice.xml");
const res = await fetch("https://invoicein-api.peculiar.systems/v1/invoice?include=validation,datev&lang=de", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.INVOICEIN_KEY}` },
body: form,
});
const data = await res.json();
if (!data.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data.invoice.totals); // { net, tax, gross, due, … }
console.log(data.validation.issues); // [{ id, severity, hint, field, who }]import os, requests
r = requests.post(
"https://invoicein-api.peculiar.systems/v1/invoice",
params={"include": "validation,pdf", "lang": "en"},
headers={"X-Api-Key": os.environ["INVOICEIN_KEY"]},
files={"file": open("invoice.pdf", "rb")},
timeout=30,
)
data = r.json()
if not data["ok"]:
raise SystemExit(f'{data["error"]["code"]}: {data["error"]["message"]}')
print(data["source"]["format"], data["source"]["profile"])
print(data["validation"]["valid"], data["validation"]["errors"], "errors")Przykładowa odpowiedź (skrócona)
{
"ok": true,
"source": {
"format": "xrechnung-ubl",
"syntax": "UBL",
"profile": "XRechnung 3.0",
"container": "xml"
},
"invoice": {
"document": {
"id": "RE-2026-0421",
"issue_date": "2026-08-30",
"type_code": "380",
"currency": "EUR",
"buyer_reference": "04011000-12345-03"
},
"seller": {
"name": "Nordlicht Werkstatt GmbH",
"vat_id": "DE123456789",
"electronic_address": { "value": "[email protected]", "scheme": "EM" },
"address": { "line1": "Kanalstraße 12", "city": "Kiel", "postcode": "24103", "country": "DE" }
},
"buyer": { "name": "Beispiel Bau AG", "address": { "city": "Hamburg", "country": "DE" } },
"payment": {
"means_code": "58",
"credit_transfers": [{ "iban": "DE02120300000000202051" }]
},
"totals": { "line_net": 314.86, "net": 314.86, "tax": 22.04, "gross": 336.09, "due": 336.09 },
"tax_breakdown": [{ "category": "S", "rate": 7, "taxable": 314.86, "tax": 22.04 }],
"lines": [
{ "id": "1", "quantity": 3.5, "unit": "HUR", "net_amount": 314.86,
"price": { "amount": 89.96 }, "tax": { "category": "S", "rate": 7 },
"item": { "name": "Wartung Lüftungsanlage" } }
],
"extensions": {}
},
"validation": {
"valid": false,
"errors": 1,
"warnings": 0,
"rule_sets": [
{ "id": "EN16931-UBL", "version": "EN 16931 validation artefacts 1.3.17" },
{ "id": "XRechnung-UBL", "version": "XRechnung 3.0.2 Schematron 2.6.0" }
],
"issues": [
{
"id": "BR-CO-15",
"severity": "error",
"rule_set": "EN16931-UBL",
"message": "[BR-CO-15]-Invoice total amount with VAT (BT-112) = Invoice total amount without VAT (BT-109) + Invoice total VAT amount (BT-110).",
"hint": "Kwota faktury z VAT (BT-112) musi być równa kwocie bez VAT (BT-109) plus łączny VAT (BT-110). 314.86 + 22.04 = 336.90, ale dokument podaje 336.09 — wystawca zaokrąglił sumy niezależnie od pozycji.",
"field": "totals.gross (BT-112)",
"who": "sender"
}
]
},
"timings_ms": { "detect": 1.2, "map": 3.8, "validate": 18.1, "total": 23.4 }
}Endpointy
- POST /v1/invoice
- Wszystko w jednym JSON.
?include=validation,html,pdf,csv,datev&lang=en|de|fr|it|pl - POST /v1/validate
- Tylko raport.
- POST /v1/parse
- Tylko kanoniczny JSON, bez walidacji.
- POST /v1/render.html
- Czytelny HTML.
- POST /v1/render.pdf
- Czytelny PDF A4.
- POST /v1/export.csv
- Płaski CSV.
?level=lines|documents - POST /v1/export.datev
- Paczka księgowań DATEV.
?skr=03|04&creditor_account=70000 - GET /v1/formats
- Obsługiwane formaty wejściowe i wersje zestawów reguł.
- GET /v1/rules/{id}
- Objaśnienie id reguły prostym językiem.
?lang=de - GET /v1/countries
- Jakiego formatu wymaga obowiązek w danym kraju i czym go walidujemy.
- GET /v1/vat/{number}
- Sprawdza numer VAT UE: format offline, potem VIES na żywo, z datowanym potwierdzeniem.
- GET /v1/peppol/{id}
- Czy kontrahent jest opublikowany w Peppol i co może odbierać.
- GET /docs
- Dokumentacja OpenAPI.
- MCP /mcp
- Zdalny serwer MCP; lokalny build stdio na życzenie.
Błędy wracają jako {"ok": false, "error": {"code", "message", "hint"}} z odpowiadającym statusem HTTP. Pozostałe kredyty są w nagłówku X-Credits-Remaining.
Płacisz za dokument. Kupione kredyty nigdy nie wygasają.
Jedna faktura = jeden kredyt, niezależnie od tego, jakie wyniki zażądasz w danym wywołaniu; plik zawierający kilka faktur kosztuje jeden kredyt za każdą. Bez miesięcznego minimum, bez opłat za użytkowników.
Z pierwszym kluczem, ważne 30 dni. Bez karty. Wystarczy, by podpiąć integrację i przetestować ją na prawdziwych plikach dostawców.
Dla wtyczki w produkcji z garstką klientów.
Typowy przedział dla narzędzia AP lub agencji obsługującej kilku klientów.
Większe wolumeny i obrazy on-premise na fakturę — zapytaj.
Ceny netto (bez VAT). Płatność na fakturę lub przez link płatniczy; samoobsługowy checkout wkrótce. Faktura na życzenie przy większych wolumenach. Limit demo (20 faktur na IP dziennie) nie wymaga żadnego klucza.
Poproś o klucz.
Zostaw e-mail i, jeśli chcesz, napisz, co odbierasz. Odpowiemy kluczem oraz fakturą lub linkiem płatniczym dla płatnych pakietów.
Wyniki walidacji opisują, co oficjalne zestawy reguł mówią o pliku. Nie są poradą prawną ani podatkową i żadna automatyczna kontrola nie certyfikuje dokumentu jako przyjętego przez administrację skarbową (w tym KSeF) ani przez nabywcę.
Krótkie odpowiedzi.
Czy to punkt dostępowy Peppol?
Czy przechowujecie moje faktury?
Które wersje reguł uruchamiacie?
- Artefakty walidacyjne EN 16931 1.3.17 (Schematron UBL i CII)
- XRechnung 3.0.2 — KoSIT Schematron 2.6.0 (UBL i CII)
- Reguły Peppol BIS Billing 3.0, aktualny master
- Profil przejściowy FNFE CTC-FR 1.4.0.04 (reguły BR-FR, Flux 2) — stosowany, gdy sprzedawca i nabywca mają siedzibę we Francji
- CIUS-RO 1.0.1 (ro16931-ubl-1.0.9) — werdykt i treść komunikatów są takie jak w SPV ANAF
- Konwencje rynkowe, których nie czyta żaden Schematron: niemieckie warunki skonta (Skonto) w wolnym tekście oraz polski numer KSeF (
?ksef=) - UBL 2.1 XSD · CII D16B XSD · FatturaPA 1.2.2 XSD · KSeF FA(2) i FA(3) XSD
- Arytmetyczne kontrole krzyżowe (sumy pozycji, VAT per kategoria, sumy końcowe) dla każdego formatu
Każda odpowiedź podaje użyte wersje: validation.rule_sets w treści i nagłówek X-Invoicein-Rulesets. Zmiany są datowane na /rules/changelog (kanał Atom) i w GET /v1/rulesets; każde id reguły można objaśnić przez GET /v1/rules/{id}?lang=pl.
A co z Factur-X BASIC i MINIMUM?
coverage: schema.