API pre vykresľovanie Peppol BIS faktúr do PDF

100 vykreslení denne zadarmo. Rovnaký renderer, ktorý poháňa epodatelna24.

Rýchly štart

1
Vytvor API kľúč
Prihlás sa do nástenky a vygeneruj kľúč a tajný kľúč.
2
Pošli UBL XML
POST faktúru ako application/xml s príslušnými hlavičkami.
3
Dostaneš PDF
V predvolenom režime PDF v odpovedi, v Blob režime URL k uloženému súboru.

Vykresli faktúru

curl -X POST https://www.zobrazfakturu.sk/api/v1/render \
  -H "Content-Type: application/xml" \
  -H "X-API-Key: $ZEF_API_KEY" \
  -H "X-API-Secret: $ZEF_API_SECRET" \
  -H "X-Language: sk" \
  --data-binary @invoice.xml \
  -o invoice.pdf

Pred spustením nastav ZEF_API_KEY a ZEF_API_SECRET ako environment premenné.

Dva režimy odpovede

Predvolený režim

Vráti PDF bajty (Content-Type: application/pdf). Metadáta sú v hlavičkách X-Peppol-*.

Blob režim — X-Document-Id

Nahrá PDF do Vercel Blob a vráti JSON descriptor s blobUrl. Opakované vykreslenie rovnakého XML je zadarmo (cache hit).

Endpointy

POST/api/v1/render

Vykresli Peppol BIS XML do PDF.

Vyžaduje X-API-Key + X-API-Secret

GET/api/v1/renders

História vykreslení tohto API kľúča za posledných 30 dní.

Vyžaduje X-API-Key + X-API-Secret

GET/api/v1/health

Stav DB, validátora a Blob storage. Pre uptime monitory pridaj ?strict=true.

Bez autentifikácie

GET/api/v1/ping

Minimálna kontrola dostupnosti (vracia 200 OK).

Bez autentifikácie

Chybové stavy

Status	Kód	Význam	Opakovať?
200	—	Úspech (vrátane validačných chýb — banner je v PDF)	—
400	INVALID_XML / XXE_REJECTED / INVALID_DOCUMENT_ID	Chybné XML, XXE-zachytenie, alebo neplatné X-Document-Id	Nie
401	—	Chýbajúce alebo neplatné credentials	Nie
403	—	Prekročená kvóta	Nie
413	—	Telo požiadavky väčšie ako max_body_bytes	Nie
422	LINE_LIMIT_EXCEEDED	Faktúra má viac riadkov ako max_lines	Nie
422	BLOB_UPLOAD_FAILED	PDF vykreslené, ale upload do Blob zlyhal	Raz
429	—	Prekročený rate limit (100/min na kľúč)	Exponenciálny backoff
500	BLOB_NOT_CONFIGURED	Server nemá nakonfigurovaný BLOB_READ_WRITE_TOKEN	Nie
502	RENDER_FAILED / OUTPUT_SIZE_ANOMALY	Renderer havaroval alebo vyprodukoval nezmyselný výstup	Raz
503	—	/health?strict=true — niektorá závislosť je degraded	—

Validačné chyby (Peppol BIS schematron) vracajú 200 s PDF — error banner je vykreslený v hornej časti dokumentu.

Verzionovanie

Žiadne nekompatibilné zmeny v /api/v1/.... Nové tvary idú do /api/v2/.... Pri vydaní v2 zostáva v1 funkčná aspoň 6 mesiacov.

Logovanie a súkromie

Telá požiadaviek (UBL XML) nikdy nelogujeme. Auditový log obsahuje len SHA-256 hash UBL a štrukturálne metadáta — nikdy nie samotný obsah faktúry.