Pre vývojárov: API referencia

Verteco API je REST nad HTTPS. Request aj response sú JSON (UTF-8). Začnite vytvorením účtu, potom API tokenu, a urobte prvé volanie do minúty. Všetky cesty sú relatívne voči základnej URL nižšie.

Celé testovacie prostredie nájdete na test.peppol.verteco.digital. Správa sa rovnako ako produkcia, navyše má testovacie nástroje (FS webhook, verifikačný token, odstránenie firmy) a simulovaný výber poskytovateľa namiesto portálu Finančnej správy.

Base URL

https://peppol.verteco.digital/api/v1

Verzia

v1 (v ceste). Spätne nekompatibilné zmeny prídu pod novou verziou.

Protokol

HTTPS only · TLS 1.2+ · TLS A+

Formát

application/json (UTF-8)

Auth

cookie session (portál) alebo Bearer token (server-to-server)

Časy

ISO-8601 (UTC), napr. 2026-06-03T09:40:27Z

Účet aj API token si vytvoríte v portáli (cez prehliadač). Integrácia potom beží výhradne cez API token. Registráciu, prihlásenie ani heslá vaša appka nerieši.

1. 1

   Vytvorte si účet v portáli

   Zaregistrujte sa e-mailom a potvrďte ho odkazom z e-mailu.
2. 2

   Vygenerujte API token

   V portáli API tokeny → Vytvoriť. Token vpt_… sa zobrazí iba raz. Uložte si ho bezpečne.
3. 3

   Urobte prvé volanie

   Token použite v hlavičke Authorization:

   javascriptKopírovať

   const res = await fetch('https://peppol.verteco.digital/api/v1/companies', {
   headers: { Authorization: 'Bearer vpt_8f2a…' },
   });
   const companies = await res.json();

4. 4

   Výber poskytovateľa na portáli Finančnej správy

   V ostrej prevádzke je výber Verteco na portáli FS (vpds.financnasprava.sk) potrebný aj pri čisto odosielacom použití: odomyká odosielanie (Verifikačný údaj) a firmu aktivuje. Príjem pritom môže ostať u poskytovateľa vášho účtovného programu: príjemcu má firma v sieti práve jedného, odosielateľov môže mať viac.

export BASE=https://test.peppol.verteco.digital   # production: https://peppol.verteco.digital
export KEY=vpt_…        # step 1

Okrem SAPI mock sandboxu (nižšie) prevádzkujeme aj plnohodnotné testovacie prostredie, kompletnú kópiu tohto portálu s oddelenými dátami, kde si celý tok (registrácia → firma → odoslanie → prijatie → notifikácie) vyskúšate end-to-end bez akéhokoľvek dopadu na ostrú prevádzku.

URL

https://test.peppol.verteco.digital

Registrácia

bez potvrdzovacieho e-mailu; účet je použiteľný okamžite

Schválenie firmy

automatické, priamo v rozhraní alebo cez API (bez výberu na portáli Finančnej správy, bez prihlásenia na portál FS); hneď po vytvorení firmy s IČ DPH môžete odosielať aj prijímať

Registrácia v sieti

automatická do testovacej siete Peppol. Pozor na dve vrstvy identifikátora: API a portál používajú rovnaký formát ako produkcia (peppolParticipantId = 0245:<číslice DIČ>, váš integračný kód sa nemení); do testovacieho SMP/SML sa firma technicky zapisuje ako 9950:SK<DIČ>, lebo schéma 0245 vyžaduje overovací kód Finančnej správy, ktorý v teste neexistuje. V produkcii sa registruje 0245:<číslice DIČ> do ostrej siete až po výbere poskytovateľa na portáli Finančnej správy (prihlásenie cez eID alebo prihlasovacími údajmi)

Validácia

reálna: EN 16931 + Peppol BIS 3.0 pravidlá, rovnaké ako v ostrej prevádzke

Doručenie

reálne cez testovaciu sieť Peppol (AS4, testovací certifikát, testovacie SML/SMP): príjemcovi registrovanému v testovacej sieti sa faktúra doručí ako prijatá (vrátane e-mailu, PDF a webhooku); do ostrej siete nič neodchádza

Doručenka

reálna MLS doručenka z testovacej siete

E-maily

reálne odchádzajú (na adresy, ktoré zadáte), s prefixom [TEST]

Simulácia chýb

hlavička X-Sandbox-Simulate: 503 (alebo 502, 500, 429) na ľubovoľnom volaní /sapi/document/* s platným tokenom vráti zodpovedajúcu chybu; nič sa nespracuje ani neuloží. Pri 500 (SAPI-PROC-500) a 429 (SAPI-SYS-003 s Retry-After) dostanete chybovú obálku SAPI; 503 a 502 prejdú cez okraj siete (DigitalOcean, Cloudflare) ako HTTP 504 s HTML telom bez obálky, presne tak vyzerá skutočný výpadok zvonku, takže si overíte aj spracovanie odpovede, ktorá nie je JSON. Chyby validácie vyvoláte nevalidným XML, 429 aj prekročením 300 volaní za minútu. V produkcii sa hlavička ignoruje

Cena

zadarmo, bez limitov na skúšanie

Funguje tam všetko čo tu: portál, REST API, SAPI-SK 1.0, e-shop pluginy aj webhooky. Stačí v integrácii vymeniť doménu za test.peppol.verteco.digital a použiť tokeny vytvorené v testovacom prostredí. Ideálne na vývoj integrácie, CI testy a zaškolenie účtovníkov pred ostrým nasadením. Skúšobné doklady patria len tam: v ostrej prevádzke sa každý domáci doklad medzi platiteľmi DPH hlási Finančnej správe a hlásenie sa nedá vziať späť. V ostrom portáli skúšajte iba tlačidlom „Poslať skúšobnú faktúru“ (0,00 €); od 1. 1. 2027 ostrá prevádzka čísla TEST-/VITAJTE- odmietne (test_document_in_production).

Pozn.: edge ochrana testovacej domény blokuje generické hlavičky User-Agent: Python-urllib a User-Agent: Java/1.8.x (predvolený User-Agent HttpsURLConnection v Jave 8) odpoveďou HTTP 403 „error code: 1010“ ešte pred naším API; ostrá doména peppol.verteco.digital ich prepúšťa. Stačí nastaviť vlastný User-Agent: v Jave buď parametrom JVM -Dhttp.agent=moja-app/1.0 (bez zmeny kódu; Java pripojí „Java/1.8“, výsledný „moja-app/1.0 Java/1.8.0_xxx“ ochrana prepúšťa, blokuje len hlavičku začínajúcu na „Java/1.8“), alebo na spojení conn.setRequestProperty("User-Agent", "moja-app/1.0"). Bežné klienty (requests, httpx, Java 11+, Apache HttpClient, okhttp, axios, Go, PHP, curl) fungujú bez zmeny.

Prečo sa firmy schvaľujú automaticky

Finančná správa nemá testovacie prostredie portálu VPDS: výber poskytovateľa na vpds.financnasprava.sk beží len v produkcii a overuje sa prihlásením na portál FS (eID alebo prihlasovacie údaje PFS), takže v ostrej prevádzke si nemôžete „vybrať" ľubovoľnú cudziu firmu. Aby ste napriek tomu vedeli integráciu otestovať, v testovacom prostredí tento krok simulujeme: každá firma, ktorú vytvoríte, sa schváli automaticky (bez výberu na FS), takže si viete založiť odosielateľa aj príjemcu a prejsť celý tok.

Na testovanie FS webhookov (výber poskytovateľa) máme vlastnú obdobu nástroja Finančnej správy: test.peppol.verteco.digital/sandbox-nastroje. Vygenerujete si tam platný verifikačný token (verifikačný údaj) v štýle FS a odošlete kompletný webhook na svoj endpoint, presne ako to robí portál FS pri reálnom výbere. Firmy vytvorené na testovanie viete zase odregistrovať (z portálu aj z testovacieho SMP), práve pre chýbajúci testovací režim na strane Finančnej správy.

Integrácia sa autentifikuje API tokenom v hlavičke Authorization: Bearer vpt_…. Token vytvoríte v portáli (API tokeny); má formát vpt_ + 40 hex znakov, ukladáme len jeho SHA-256 hash a má rovnaký prístup ako váš účet. Otestujte ho cez /auth/me:

curl https://peppol.verteco.digital/api/v1/auth/me -H 'Authorization: Bearer vpt_8f2a…'
# 200 → { "id": "…", "email": "vy(at)firma.sk" }   (token funguje)

Pri chýbajúcom alebo neplatnom tokene API vráti:

// 401 Unauthorized
{ "error": "unauthorized", "message": "Authentication required" }

Stránkovanie & idempotencia

• Kontrakt len rastie: nové polia (vynechané, keď sú null), nové voliteľné parametre, nové endpointy a udalosti. Existujúce názvy polí, hodnoty enumov a stavové kódy sa nemenia.
• Nový enum alebo udalosť webhooku môže pribudnúť kedykoľvek; klient ignoruje, čo nepozná, a na neznámu udalosť odpovie 2xx.
• Časové pečiatky sú ISO 8601 v UTC s premenlivým počtom desatinných miest; parsujte ich, neporovnávajte ako text. Sumy prichádzajú ako reťazce s dvoma desatinnými miestami.
• Ak by zmena nemohla byť aditívna, oznámime ju v changelogu (odber e-mailom) najmenej 90 dní vopred a starý tvar ponecháme počas prechodného obdobia.
• Bezpečnostný model API kľúča (od 3. 10. 2026): kľúč číta a odosiela doklady, spravuje firmy, notifikácie a webhooky. Správu účtu a kľúčov (vytvorenie, rozsah a zrušenie kľúča, MFA, heslo, relácie, pozvánky, prevod firmy, podpisy zmlúv) vykoná len prihlásená osoba; kľúč tam dostane 403 token_not_allowed. GET /api/v1/tokens ostáva kľúču dostupný.
• Verzia kontraktu je v openapi.json (info.version) a každá zmena má riadok v changelogu s tagom API alebo Webhooky.

/changelog · /changelog/odber · openapi.json

Chyby majú jednotný tvar s machine-readable error kódom. Validačné chyby pridávajú mapu fields (prvá chyba na pole).

// business chyba
{ "error": "invalid_credentials", "message": "Invalid email or password" }

// validačná chyba (400)
{ "error": "validation_failed", "message": "Some fields are invalid",
"fields": { "ico": "IČO musí byť 8 číslic" } }

HTTP stavy

200 / 201 / 204

úspech (OK / vytvorené / bez obsahu)

400

neplatný vstup (pozri error / fields)

401

chýbajúca alebo neplatná autentifikácia

403

nedostatočné oprávnenie (rola)

404

zdroj neexistuje alebo naň nemáte prístup

405

nepodporovaná HTTP metóda pre danú cestu

409

konflikt (IČO / e-mail už existuje)

415

nepodporovaný Content-Type (XML endpointy očakávajú application/xml)

429

prekročený rate limit (hlavičky RateLimit-* a Retry-After, telo JSON rate_limited)

Najčastejšie chybové kódy

Výpadok prístupového bodu a opakovanie

• Ak API odpovie 502, 503 alebo 504, prípadne neodpovie vôbec, doklad sme neprevzali: zopakujte volanie neskôr s rovnakým Idempotency-Key, nič sa neodošle dvakrát.
• Doklad, ktorý API prijalo (202 ACCEPTED, aj s retrying: true), odíde po obnove sám: prístupový bod doručenie opakuje a stav vidíte cez GET /sapi/document/sent alebo webhook; ak doručenie napokon vzdá, doklad skončí ako zlyhaný a rovnaký kľúč ho pošle znova.
• Príjem na úrovni siete od portálu nezávisí: doručenie, ktoré počas výpadku portálu neprešlo, odosielajúci prístupový bod podľa pravidiel Peppol zopakuje a doklad sa v portáli objaví po obnove. Hlásenia Finančnej správe, ktoré pre výpadok neodišli, doplní automatický obnovovací beh (prenosové zlyhanie sa opakuje, obsahové odmietnutie nie).
• Stav a históriu dostupnosti nájdete na /status; výpadok si v testovacom prostredí nasimulujete hlavičkou X-Sandbox-Simulate (sekcia Testovacie prostredie).

API je chránené rate limitingom v 60-sekundovom okne (per inštancia). Limit a zostatok vraciame v každej odpovedi cez hlavičky; pri prekročení vráti 429 Too Many Requests s Retry-After.

Bežné volania

dynamický limit s veľkou rezervou, na API token (alebo session, inak IP); aktuálnu hodnotu vracia hlavička RateLimit-Limit

Auth (/auth/*)

prísnejší limit na IP (anti brute-force; mimo /auth/me a /auth/logout)

RateLimit-Limit

limit v okne

RateLimit-Remaining

koľko ešte ostáva

RateLimit-Reset

sekúnd do resetu okna

Retry-After

sekúnd do ďalšieho pokusu (pri 429)

HTTP/2 429 Too Many Requests
RateLimit-Limit: <limit v okne>
RateLimit-Remaining: 0
RateLimit-Reset: 37
Retry-After: 37

{ "error": "rate_limited", "message": "Too many requests. Slow down." }

HTTP/2 200
RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 41
RateLimit-Policy: 300;w=60

Opaque tokeny vpt_… pre server-to-server prístup. Plaintext sa zobrazí iba raz pri vytvorení. Uložte si ho. Ukladáme len SHA-256 hash a 12-znakový prefix na zobrazenie.

curl -X POST https://peppol.verteco.digital/api/v1/tokens -b cookies.txt \
-H 'Content-Type: application/json' -d '{"name":"moja-appka"}'
# 201 Created
{ "id":"…","name":"moja-appka","token":"vpt_8f2a…","prefix":"vpt_8f2a3b…","createdAt":"…" }

Firmy (IČO / IČ DPH), ktoré spravujete. Prístup je viazaný na členstvo: vidíte len firmy, ktorých ste členom. Tvorca firmy sa stáva jej owner.

curl -X POST https://peppol.verteco.digital/api/v1/companies \
-H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
-d '{"ico":"53412834","dic":"SK2121358349","legalName":"Verteco digital services, s. r. o."}'

# 201 Created
{ "id":"08dd…","ico":"53412834","dic":"SK2121358349","legalName":"…",
"registeredAddress":null,"peppolParticipantId":null,
"status":"pending_verification","role":"owner","createdAt":"2026-06-03T09:40:27Z" }

Pole status

pending_verification

po vytvorení; odosielanie ešte nie je odomknuté

active

overená, odosielanie odomknuté

Rola člena

owner

tvorca firmy (plný prístup)

admin

správca (úpravy, webhooky, overenie)

member

člen (čítanie)

viewer

iba čítanie

Pred odosielaním treba firmu overiť cez Verifikačný údaj (VÚ), podpísaný token od Finančnej správy. Po úspešnom overení sa status firmy zmení na active a odomkne sa odosielanie. V bežnom toku VÚ nikto neprepisuje: Finančná správa ho pošle na náš webhook v momente, keď si firma na portáli FS zvolí Verteco (alebo vášho sprostredkovateľa), a overenie prebehne automaticky. Tento endpoint je záložná cesta pre prípad, že VÚ máte z e-mailu FS a webhook nedorazil; neregistruje firmu do SMP.

curl -X POST https://peppol.verteco.digital/api/v1/companies/{id}/verification \
-H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
-d '{"token":"<1024-hex VÚ>"}'

# 200 OK
{ "companyId":"08dd…","status":"active","sendingVerified":true,
"verificationMethod":"self","verifiedAt":"2026-06-15T…Z" }

Log Peppol dokladov (prijatých a odoslaných) za firmu. Napĺňa sa, ako cez Access Point tečú faktúry. Viazané na členstvo vo firme, zoradené createdAt zostupne.

curl 'https://peppol.verteco.digital/api/v1/companies/{id}/documents?direction=received' \
-H 'Authorization: Bearer vpt_8f2a…'
# 200 OK
[ { "id":"…","direction":"received","peppolMessageId":"…","docTypeId":"…",
  "senderId":"0088:7300010000001","receiverId":"0245:2121358349",
  "invoiceNumber":"2026001","issueDate":"2026-06-03",
  "currency":"EUR","totalAmount":120.00,"status":"received","createdAt":"…" } ]

SAPI-SK je štandardizované národné REST rozhranie medzi klientskym/ERP systémom a Access Pointom (sapi-sk.sk). Implementujeme ho v plnom rozsahu. Vďaka tomu nie ste viazaní na náš proprietárny tvar API a integráciu napíšete raz pre ktorýkoľvek SAPI-SK Access Point. Prehľad bez technických detailov je v článku SAPI-SK pre vývojárov.

Base URL

https://peppol.verteco.digital/sapi

Autentifikácia

OAuth2 client_credentials → krátkodobý access token (JWT)

client_id

UUID vášho API tokenu (zoznam v sekcii API tokeny / dashboard)

client_secret

samotný vpt_… token z portálu

Verzia

1.3 (10 operácií: 4× auth, 6× dokumenty)

Sandbox (skúšobné prostredie)

Chcete si SAPI-SK vyskúšať bez registrácie a bez rizika? Použite verejné sandbox prihlasovacie údaje. Sandbox validuje požiadavky presne ako ostrá prevádzka, ale nikdy nič neodošle na Peppol sieť a nepracuje s reálnymi dátami; vráti realistické mock odpovede. Ideálne na vývoj, CI a onboarding integrácie.

client_id

sandbox

client_secret

sandbox

send

plná validácia kontraktu + mock 202 (nič sa nedoručí)

receive

1 vzorový doklad sandbox-doc-0001 na test parsovania a acknowledge

# 1) sandbox token (bez registrácie)
curl -X POST https://peppol.verteco.digital/sapi/auth/token \
-H 'Content-Type: application/json' \
-d '{ "client_id": "sandbox", "client_secret": "sandbox",
      "grant_type": "client_credentials" }'

# 2) mock odoslanie: zvaliduje sa, ale NIČ sa reálne nedoručí
curl -X POST https://peppol.verteco.digital/sapi/document/send \
-H 'Authorization: Bearer <sandbox access_token>' \
-H 'X-Peppol-Participant-Id: 0245:0000000000' \
-H 'Content-Type: application/json' \
-d '{ "metadata": { "documentId": "TEST-1",
        "documentTypeId": "urn:…::Invoice##…::2.1",
        "senderParticipantId": "0088:sandbox-sender",
        "receiverParticipantId": "0088:sandbox-receiver" },
      "payload": "<Invoice>…</Invoice>", "payloadFormat": "XML" }'
# 202 { "providerDocumentId": "sandbox-…", "status": "ACCEPTED", … }

# 3) vzorová schránka + detail vzorového dokladu
curl https://peppol.verteco.digital/sapi/document/receive \
-H 'Authorization: Bearer <sandbox access_token>'
curl https://peppol.verteco.digital/sapi/document/receive/sandbox-doc-0001 \
-H 'Authorization: Bearer <sandbox access_token>'

Autentifikácia

curl -X POST https://peppol.verteco.digital/sapi/auth/token \
-H 'Content-Type: application/json' \
-d '{ "client_id": "<UUID tokenu>", "client_secret": "vpt_8f2a…",
      "grant_type": "client_credentials" }'
# 200 OK
{ "access_token": "eyJhbGciOi…", "token_type": "Bearer",
"expires_in": 900, "refresh_token": "eyJhbGciOi…" }

// body
{ "refresh_token": "eyJhbGciOi…" }

Odoslanie dokumentu

curl -X POST https://peppol.verteco.digital/sapi/document/send \
-H 'Authorization: Bearer eyJ…' \
-H 'X-Peppol-Participant-Id: 0245:2121358349' \
-H 'Idempotency-Key: 7b1f0e2a-…' \
-H 'Content-Type: application/json' \
-d '{ "metadata": {
        "documentId": "INV-2026-001",
        "documentTypeId": "urn:…::Invoice##…::2.1",
        "processId": "urn:…:bis:billing:3.0",
        "senderParticipantId": "0245:2121358349",
        "receiverParticipantId": "0088:7300010000001",
        "creationDateTime": "2026-06-17T10:00:00Z" },
      "payload": "<Invoice …>…</Invoice>",
      "payloadFormat": "XML" }'
# 202 Accepted
{ "providerDocumentId": "…", "status": "ACCEPTED",
"receivedAt": "2026-06-17T10:00:01Z", "timestamp": "…" }
# pri status "REJECTED" nesie odpoveď aj pole "detail"
# s dôvodom odmietnutia (validačné pravidlá, napr. BR-CO-15)

curl -X POST https://peppol.verteco.digital/sapi/document/validate \
-H 'Authorization: Bearer eyJ…' \
-H 'Content-Type: application/xml' \
--data-binary @faktura.xml
# 200 OK
{ "valid": false,
  "errors": [ "BR-CO-15: Invoice total amount with VAT (BT-112) = … " ],
  "warnings": [],
  "checkedAt": "2026-09-10T12:00:00Z" }

Príjem dokumentov

// 200 OK
{ "documents": [ { "documentId":"…","documentTypeId":"…",
  "senderParticipantId":"0088:…","receiverParticipantId":"0245:…",
  "creationDateTime":"2026-06-17T…Z" } ],
"nextPageToken": "50" }

Stav odoslaných dokumentov

// 200 OK
{ "documents": [ {
  "documentId": "…",
  "receiverParticipantId": "0245:1084695645",
  "peppolMessageId": "befc9112-…",
  "status": "delivered",
  "statusDateTime": "2026-07-09T14:52:31Z",
  "creationDateTime": "2026-07-09T14:52:12Z" } ],
"nextPageToken": null }

Doručenka (MLS) a dôkazy doručenia

Doručenka MLS (Peppol Message Level Status) je odpoveď Access Pointu príjemcu na našu zásielku: AP = prijaté a doručené, AB = doručené bez obchodného potvrdenia, RE = odmietnuté s dôvodom. Portál ju uloží k odoslanému dokladu a podľa nej prepne stav: AP aj AB znamenajú delivered (pri AB začína statusDetail „MLS AB: “ a mls.responseCode je AB; podľa SPOG on MLS je to doručenie bez obchodného potvrdenia, nie výhrada), RE znamená rejected. Podľa § 76a ods. 2 písm. d zákona 222/2004 musí poskytovateľ vedieť preukázať dátum a čas odoslania, doručenia a prijatia; tie tri časy nesie každý riadok GET /sapi/document/sent aj webhook: sentAt (odovzdanie doručovacej službe, tým je podľa § 85o ods. 11 splnená povinnosť vystaviteľa), deliveredAt (potvrdenie AP príjemcu doručenkou) a fsReportedAt (hlásenie údajov FS). Zahraničný Access Point doručenku nemusí poslať nikdy: doklad ostane delivered s detailom as4_receipt_only a bez MLS.

// 200 OK
{ "document": {
    "documentId": "…", "peppolMessageId": "befc9112-…", "status": "delivered",
    "sentAt": "2026-09-17T08:00:12Z", "deliveredAt": "2026-09-17T08:00:31Z", "fsReportedAt": null,
    "hasMls": true,
    "links": { "detail": "…/sapi/document/sent/…", "mls": "…/sapi/document/sent/…/mls" } },
  "mls": { "responseCode": "AP", "receivedAt": "2026-09-17T08:00:31Z", "url": "…/sapi/document/sent/…/mls" } }

Dôkazy hlásenia FS, integrita a časová os (SAPI 1.8.14)

Od verzie 1.8.14 nesie každý riadok GET /sapi/document/sent aj detail a zoznam prijatých dokladov objekt fsReport: state = reported (hlásenie odovzdané zbernému bodu C5, reportedAt = fsReportedAt), pending (hlásenie je dlžné, odovzdanie zlyhalo a opakuje sa automaticky, reason = c5_unavailable) alebo not_required (hlásenie nevzniká; reason vysvetľuje prečo: cross_border, self_send_test, issuer_without_vat_id, recipient_without_vat_id, not_billing_document, tdd_disabled, before_2026_09_01, not_recorded). Po odovzdaní pribudne tddMessageId (SBDH InstanceIdentifier hlásenia) a po odpovedi C5 c5ResponseCode (AP/AB/RE), c5ResponseAt, c5Detail a zhrnutie outcome: accepted (AP), accepted_with_reservations (AB), rejected (RE) alebo null, kým C5 neodpovedalo. outcome = rejected znamená, že hlásenie sme odovzdali, ale Finančná správa ho odmietla (c5Detail nesie porušené pravidlo, napríklad BR-AE-08); state ostáva reported, lebo odovzdanie prebehlo, a portál opravené hlásenie odošle znova automaticky (po prijatí sa outcome zmení na accepted). Odoslané riadky majú navyše statusReason (strojový kód za statusDetail: network_retrying, network_retrying_sent, as4_receipt_only, recipient_not_registered, transport_failed, mls_rejected, validation_failed), xmlSha256 (SHA-256 odovzdaného XML, ostáva aj po výmaze obsahu), retention a receiptRetention = permanent (doručenka MLS sa nikdy nemaže). Doručenka v detaile má mls.sha256 a mls.messageId. Prijaté doklady dostali peppolMessageId, status (received/acknowledged), receivedAt, acknowledgedAt a xmlSha256 (SHA-256 bajtov obchodného dokladu presne tak, ako ich vydáva links.xml, bez prenosovej obálky SBDH; počíta sa pri prijatí a ostáva aj po výmaze obsahu). Oba zoznamy filtrujete cez ?fsReport=reported|pending|not_required|rejected (rejected = outcome rejected), odoslané aj cez ?status=undeliverable. Odpoveď POST /sapi/document/send nesie peppolMessageId už pri prevzatí. Všetko je doplnené ako nové polia, existujúce zostávajú nezmenené.

// POST { "documentIds": ["7c1e…", "9af0…", "neznáme"] }  (max 200)
{ "documents": [ {
    "documentId": "7c1e…", "status": "delivered", "statusReason": null, "peppolMessageId": "befc9112-…",
    "sentAt": "2026-09-21T08:00:12Z", "deliveredAt": "2026-09-21T08:00:31Z", "fsReportedAt": "2026-09-21T08:05:40Z",
    "fsReport": { "state": "reported", "reportedAt": "2026-09-21T08:05:40Z", "reason": null, "outcome": "accepted",
                  "tddMessageId": "3f2a…", "c5ResponseCode": "AP", "c5ResponseAt": "2026-09-21T08:06:02Z", "c5Detail": null },
    "xmlSha256": "9b74…", "retention": { "mode": "storage", "contentAvailableUntil": null }, "receiptRetention": "permanent",
    "hasMls": true, "links": { "detail": "…", "mls": "…" },
    "mls": { "responseCode": "AP", "receivedAt": "2026-09-21T08:00:31Z", "url": "…", "sha256": "e1c0…", "messageId": "mls-…" } } ],
  "missing": ["9af0…", "neznáme"] }

Hromadné odoslanie

// request
{ "documents": [ {
  "itemId": "fa-2026-001",
  "idempotencyKey": "fa-2026-001",
  "metadata": { "documentId": "2026001", "documentTypeId": "…", "processId": "…",
                "senderParticipantId": "0245:2121358349", "receiverParticipantId": "0245:1084695645" },
  "payload": "<Invoice …>", "payloadFormat": "XML" } ] }

// 202 Accepted
{ "total": 2, "accepted": 1, "rejected": 1, "failed": 0,
"results": [
  { "itemId": "fa-2026-001", "ok": true,  "providerDocumentId": "…", "status": "ACCEPTED" },
  { "itemId": "fa-2026-002", "ok": false, "errorCode": "SAPI-AUTH-003", "errorMessage": "…" } ] }

Model chýb

Všetky SAPI chyby majú jednotnú obálku s kategóriou, stabilným kódom, príznakom retryable a correlation_id na podporu. Pri chybe prihlásenia (SAPI-AUTH-001) nesie obálka navyše hint (ľudsky čitateľné vysvetlenie, čo patrí do Client Id a Client Secret) a docs (odkaz na návod; pre programy MK-soft priamo na /navody/mksoft#prepojenie). Obe polia sú voliteľné a inde chýbajú (1.8.20).

{ "error": {
  "category": "AUTH",
  "code": "SAPI-AUTH-001",
  "message": "Invalid client credentials.",
  "retryable": false,
  "correlation_id": "b4191dfc-…" } }

Pri prijatej faktúre vieme firmu upozorniť e-mailom alebo webhookom (POST na vašu URL). Doručenie je durable: ukladá sa do výstupnej fronty a doručuje asynchrónne (15 s timeout); pri zlyhaní opakujeme až 12× s exponenciálnym backoffom (30 s → max 8 h, spolu približne 16 hodín), potom dead-letter. Výpadok vášho servera teda notifikáciu nestratí, doručíme ju pri ďalšom pokuse. HTTP 401/403 znamená, že váš endpoint vyžaduje autentifikáciu, ktorú neposielame; overujte podpis webhook-signature a odpovedajte 2xx. SSRF ochrana blokuje loopback/lokálne adresy; webhook URL musí byť verejná.

curl -X PUT https://peppol.verteco.digital/api/v1/companies/{id}/webhook \
-H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
-d '{"url":"https://vas-system.sk/peppol/webhook"}'
# 200 OK { "url":"https://vas-system.sk/peppol/webhook", "hasSecret": true }

// 200 OK
{ "secret": "vpt_8f2a…" }

// 200 OK
{
"sent":     { "url": "https://vas-system.sk/peppol/webhook", "event": "webhook.test",
              "signed": true, "payload": "{…}" },
"received": { "status": 200, "body": "OK", "durationMs": 142, "error": null }
}
// 400 webhook_not_configured, ak nie je uložená webhook URL

Payload webhooku

Pri prijatej (invoice.received) aj odoslanej (invoice.sent) faktúre pošleme POST s týmto telom; pole event rozlišuje typ.

Ďalšie dve udalosti oznamujú verdikt siete o faktúre, ktorú ste odoslali: invoice.delivered (príjemcov Access Point potvrdil doručenie doručenkou MLS) a invoice.rejected (odmietnutá, či už sieťou, alebo pri validácii ešte pred odoslaním); invoice.undeliverable hlási príjemcu bez záznamu v sieti Peppol (prevzaté, nahlásené FS, nedoručené). Nesú identifikáciu dokladu a firmy (documentId, invoiceNumber, receiverId, peppolMessageId, companyDic, peppolParticipantId) plus status, statusDetail s dôvodom odmietnutia a statusDateTime. Ak prvý pokus o doručenie zlyhal a prístupový bod ho sám opakuje (spravidla do hodiny), doklad ostáva submitted a statusDetail začína predponou network_retrying: ; po doručení príde delivered, po vzdaní rejected s predponou network_gave_up: . Vďaka nim nemusíte stav odoslaných faktúr zisťovať polovaním.

Udalosť company.activated príde, keď zákazník dokončí výber poskytovateľa na portáli Finančnej správy (telo: event, companyId, companyDic, peppolParticipantId, status, verifiedAt); company.deactivated zase pri odregistrovaní firmy zo siete (rovnaké telo bez verifiedAt). company.smp_registered_elsewhere príde, keď firma dokončila výber na portáli FS, ale jej záznam v národnom SMP drží iný poskytovateľ (telo ako pri company.activated plus action: "migration_code_required" a migrateUrl). Postup pre partnerov je v dokumentácii pre sprostredkovateľov. Kým zákazník nevloží migračný kód, sieť doručuje starému poskytovateľovi. Detaily v návode /saas:

{
"event": "invoice.received",
"eventId": "7f1c2d9e-4b1a-4e3d-9c1f-0a2b3c4d5e6f",
"occurredAt": "2026-09-03T15:04:05Z",
"companyId": "08dd…",
"documentId": "…",
"invoiceNumber": "2026001",
"senderId": "0088:7300010000001",
"supplierName": "Dodávateľ s.r.o.",
"receiverId": "0245:2121358349",
"issueDate": "2026-06-03",
"dueDate": "2026-06-17",
"deliveryDate": "2026-06-03",
"currency": "EUR",
"totalAmount": "120.00",
"peppolMessageId": "…",
"companyDic": "SK2121358349",
"peppolParticipantId": "0245:2121358349"
}

Polia companyDic a peppolParticipantId identifikujú firmu, ktorej sa udalosť týka (dôležité pre partnerov, ktorí majú jednu webhook URL pre všetkých svojich klientov).

Verdikt siete o odoslanej faktúre:

{
"event": "invoice.delivered",          // alebo "invoice.rejected"
"occurredAt": "2026-09-03T15:04:05Z",
"companyId": "08dd…",
"companyDic": "SK2121358349",
"peppolParticipantId": "0245:2121358349",
"documentId": "…",
"invoiceNumber": "2026001",
"receiverId": "0245:2120049096",
"peppolMessageId": "…",
"status": "delivered",                 // alebo "rejected"
"statusDetail": null,                  // pri rejected: dôvod odmietnutia
"statusDateTime": "2026-06-03T10:15:42Z"
}

Aktivácia firmy po výbere na portáli Finančnej správy:

{
"event": "company.activated",          // company.deactivated má rovnaké telo bez verifiedAt
"occurredAt": "2026-09-03T15:04:05Z",
"companyId": "08dd…",
"companyDic": "SK2121358349",
"peppolParticipantId": "0245:2121358349",
"status": "active",
"verifiedAt": "2026-06-03T10:02:11Z"
}

Názov udalosti nesie aj hlavička X-Verteco-Event. Úplný zoznam udalostí: invoice.received, invoice.sent, invoice.delivered, invoice.rejected, invoice.undeliverable, invoice.reported, invoice.report_pending, invoice.report_rejected, company.activated, company.deactivated, company.smp_registered_elsewhere a testovací webhook.test. Neznámy typ udalosti odporúčame odložiť bokom a zalogovať; nový typ vždy vopred ohlásime. Každá udalosť nesie aj occurredAt (čas vzniku udalosti, ISO-8601 UTC), podľa ktorého udalosti radíte, a eventId (rovnaká hodnota aj v hlavičke X-Verteco-Delivery-Id): jedinečný pre každú udalosť a nemenný pri jej opakovaní, preto je to správny kľúč na dedupliáciu (peppolMessageId sa opakuje naprieč invoice.sent, invoice.delivered a invoice.reported). Udalosti invoice.* nesú aj časy sentAt, deliveredAt, receivedAt a fsReportedAt (ISO-8601 UTC, null kým skutočnosť nenastala). invoice.reported príde, keď bolo hlásenie Finančnej správe (TDD) k dokladu odovzdané doručovacej službe (§ 85o ods. 11), a to aj s odstupom dní pri výpadku zberného bodu C5. Formálne schémy všetkých udalostí sú v sekcii webhooks špecifikácie OpenAPI.

Overenie podpisu

Ak má firma secret, posielame hlavičku X-Verteco-Signature v tvare sha256=HMAC-SHA256(secret, raw telo) (lowercase hex). Vždy počítajte HMAC nad presnými bajtmi tela:

import crypto from 'node:crypto';

// rawBody = presné bajty tela requestu (nie znova serializovaný JSON)
function verify(rawBody, header, secret) {
const expected = 'sha256=' +
  crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Hlavičky každého doručenia: X-Verteco-Event (názov udalosti), X-Verteco-Delivery-Id (= eventId v tele, rovnaké pri každom opakovaní), X-Verteco-Signature (HMAC vyššie) a paralelne hlavičky podľa štandardu Standard Webhooks: webhook-id (= eventId), webhook-timestamp (unix sekundy okamihu pokusu) a webhook-signature = v1,base64(HMAC-SHA256(secret, id + "." + timestamp + "." + telo)). Kľúčom sú bajty vášho secretu v UTF-8; knižnica standardwebhooks ho očakáva ako whsec_ + base64(secret). Odporúčaný postup: overte podpis, odmietnite doručenie s webhook-timestamp starším ako 5 minút (ochrana pred prehratím), spracúvajte idempotentne podľa eventId, odpovedzte 2xx do 15 sekúnd a ťažšie spracovanie odložte do vlastnej fronty. Neúspešné doručenie opakujeme 12× s odstupom 30 s až 8 h (spolu približne 16 hodín); potom skončí ako dead-letter s upozornením e-mailom a je viditeľné v Realtime logu. Produkčná webhook URL musí byť https://, v testovacom prostredí je dovolené aj http://.

Hromadné nastavenie: jeden token, viac firiem

Jeden API token (viazaný na váš účet/e-mail) spravuje všetky firmy, ktoré vlastní: kto firmu založí cez POST /companies, stáva sa jej ownerom a vie jej nastaviť webhook. Webhook je per firma (vlastná URL aj secret), takže rovnakým tokenom napojíte ľubovoľný počet firiem:

# 1) zoznam vašich firiem (stránkovane, viď Firmy)
curl 'https://peppol.verteco.digital/api/v1/companies?page=0&limit=100' -H 'Authorization: Bearer vpt_8f2a…'

# 2) pre KAŽDÚ firmu {id}: nastavte webhook (a/alebo e-mail)
curl -X PUT https://peppol.verteco.digital/api/v1/companies/{id}/notifications \
-H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
-d '{"webhookUrl":"https://vas-system.sk/peppol/webhook","notificationEmail":"faktury@firma.sk"}'

# 3) vyzdvihnite podpisový secret (vráti sa LEN RAZ) a uložte si ho pre overovanie podpisu
curl -X POST https://peppol.verteco.digital/api/v1/companies/{id}/webhook/secret -H 'Authorization: Bearer vpt_8f2a…'
# → { "secret": "…" }

• Token musí byť owner/admin danej firmy; pri firme, kde je len member/viewer, vráti 403 forbidden (žiadny cross-tenant zásah).
• Každej firme môžete dať inú URL alebo všetkým rovnakú; v payloade ich rozlíšite podľa companyId (a receiverId).
• Pri stovkách firiem rešpektujte rate-limit na token (aktuálnu hodnotu vracia hlavička RateLimit-Limit); dávkujte s backoffom na 429 (hlavička Retry-After).
• Webhook reálne chodí, až keď je firma aktívna v Peppole (po výbere Verteco ako poskytovateľa u Finančnej správy) a teda skutočne prijíma doklady.

Polia objektov vracaných API.

Company

Document

User · Token · Webhook

DIČ

Daňové identifikačné číslo (10 číslic). Slovenský Peppol identifikátor je 0245: + číslice DIČ, bez SK.

IČ DPH

Identifikačné číslo pre DPH (SK + DIČ). Majú ho len platitelia DPH; neplatiteľ vystavuje s kategóriou O.

IČO

Identifikačné číslo organizácie (8 číslic). V API pole ico, v UBL BT-30.

Verifikačný údaj (VÚ)

Podpis Finančnej správy, ktorý vznikne výberom poskytovateľa na portáli FS; odomyká odosielanie za firmu.

VPDS

Výber poskytovateľa doručovacej služby, aplikácia Finančnej správy, kde si subjekt volí poštára (nás).

TDD

Tax Data Document, hlásenie údajov o faktúre Finančnej správe; zostavujeme a posielame ho za vás.

C5 / C6

Piaty a šiesty roh Peppol modelu: prístupový bod Finančnej správy, ktorý TDD prijíma (0242:001180).

MLS

Message Level Status, doručenka od prístupového bodu príjemcu (AP = prijaté, RE = odmietnuté, AB = potvrdené).

SBDH

Standard Business Document Header, obálka, v ktorej doklad cestuje sieťou; jej InstanceIdentifier je peppolMessageId.

SML / SMP

Adresár siete: SML nájde SMP príjemcu, SMP povie, aký prístupový bod a aké typy dokladov príjemca prijíma.

Nad rámec Peppol BIS Billing 3.0 sa slovenskí výrobcovia ERP a fakturačných systémov priebežne zhodujú na spoločnej interpretácii voliteľných polí (diskusia prebieha v Slack kanáli Finančnej správy). Nižšie sú konvencie, ktoré náš portál už dnes rešpektuje – všetko sú platné BIS konštrukcie, cez naše API prechádzajú bez zmeny a prijaté doklady ich zobrazujú aj v ľudsky čitateľnom náhľade a PDF.

• Odpočet zdanenej zálohy na riadku: záporný riadok s cac:DocumentReference, kde cbc:ID nesie číslo daňového dokladu k prijatej platbe a cbc:DocumentTypeCode je 130 (BIS: invoice line object identifier, max. 1 na riadok). Prijatá faktúra s takýmto riadkom sa v našom náhľade zobrazí s poznámkou „odpočet zálohy – daňový doklad č. …".
• Daňový doklad k prijatej platbe: podľa FAQ Finančnej správy sa používa InvoiceTypeCode 388 (Tax invoice). Naším API aj validáciou prechádza; odpočet neuhradenej (nezdanenej) zálohy sa vyjadruje cez cbc:PrepaidAmount.
• Storno faktúry: dobropis 381 (CreditNote) s cac:BillingReference na pôvodnú faktúru – nie záporná faktúra 380. Pozor: kód 384 sieť pre slovenské strany odmieta (pravidlo PEPPOL-EN16931-P0112 ho povoľuje len medzi nemeckými subjektmi); na opravu nahor slúži ťarchopis 383.
• BT-83 PaymentID: v SK praxi sa presadzuje tvar referencie platiteľa /VS…/SS…/KS…; samotný variabilný symbol je tiež bežný. Naše spracovanie hodnotu prenáša bez zmeny a zobrazuje ju pri platobných údajoch.
• Doplnkové údaje položiek (šarže, sériové čísla, expirácie) cez cac:AdditionalItemProperty s ustálenými názvami ako BatchNumber, SerialNumber, ExpirationDate.

K e-faktúre je možné pripojiť prílohy (PDF, obrázky) ako base64 v elemente cac:AdditionalDocumentReference (BT-125). Pri prijatých dokladoch spracujeme prílohy do 25 MB na prílohu; pri odosielaní musí celé XML vrátane base64 príloh zostať do 10 MB cez SAPI-SK a do 2 MB cez záložku Odoslať súborom v portáli. Peppol jednotný celosieťový limit neurčuje, jednotliví poskytovatelia si ho stanovujú sami (FS FAQ 9/DPH/2025/IM, príklad č. 67), takže pri veľmi veľkých prílohách si overte aj limit poskytovateľa druhej strany.

Dva pomocné endpointy bez autentifikácie – rovnaké validačné jadro a rovnaký SML lookup, aké používa náš Access Point. Hodia sa do CI aj do predodoslacích kontrol; platí na ne prísnejší verejný rate limit.

curl -X POST https://peppol.verteco.digital/api/v1/public/peppol-validate \
-H "Content-Type: application/xml" \
--data-binary @faktura.xml

// 200 OK
{
"valid": false,
"errors": [
  "BR-CO-09: [BR-CO-09]-The Seller VAT identifier (BT-31) … shall have a prefix in accordance with ISO code…"
],
"warnings": []
}
// 400 = prázdne telo (empty_document) alebo dokument nad 3 MB (document_too_large)

// 200 OK
{
"registered": true,
"participantId": "0245:2121358349",
"smp": "sml.peppol-smp.sk",
"capabilities": ["Faktúra (BIS Billing)", "Dobropis", "Self-billing", "MLS doručenky"],
"lastCheckedAt": "2026-08-31T…Z"
}

Portál má vlastný server pre Model Context Protocol, otvorený štandard, cez ktorý sa AI asistenti (Claude Code, Claude Desktop, Cursor, VS Code Copilot a ďalší) pripájajú k externým systémom. Asistent sa prihlási bežným API kľúčom účtu a dostane šesť nástrojov; nikdy nevidí viac než ten účet a každé volanie je v API logu kľúča.

Adresa: https://peppol.verteco.digital/api/mcp. Transport: Streamable HTTP, JSON-RPC 2.0, bezstavovo (POST /api/mcp, žiadny SSE stream, GET vráti 405). Prihlásenie hlavičkou Authorization: Bearer <API kľúč>. Podporované metódy: initialize, ping, tools/list, tools/call, resources/list, prompts/list.

Nástroje

• list_companies: firmy účtu s Peppol ID, stavom a rolou (začiatok každej konverzácie)
• list_documents: odoslané/prijaté faktúry firmy s stavom doručenia a hlásenia FS, stránkované
• get_document: detail faktúry vrátane doručenky MLS a hlásenia FS, voliteľne UBL XML (do 1 MB)
• check_participant: živé overenie príjemcu v sieti Peppol (SML)
• validate_document: validácia UBL proti EN 16931 + Peppol BIS 3.0
• send_document: odoslanie faktúry za firmu, vyžaduje confirm = true a platí brána Verifikačného údaja

Pripojenie v Claude Code

claude mcp add --transport http verteco-peppol https://peppol.verteco.digital/api/mcp \
  --header "Authorization: Bearer vpt_..."

Claude Desktop (cez most mcp-remote, potrebuje Node.js)

{
  "mcpServers": {
    "verteco-peppol": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://peppol.verteco.digital/api/mcp", "--header", "Authorization: Bearer vpt_..."]
    }
  }
}

Odoslanie faktúry je právne záväzné: nástroj bez confirm = true odmietne volanie a asistent má v inštrukciách servera pokyn vyžiadať si výslovný súhlas používateľa s konkrétnou faktúrou a príjemcom. Hotové konfigurácie pre Cursor a VS Code a tlačidlo na vytvorenie kľúča nájdete v portáli: API kľúče → záložka MCP server. API kľúče → MCP server

Firma si v portáli zapne vlastnú adresu <24 náhodných znakov>@peppol.send.verteco.app. E-mail s prílohou UBL XML poslaný na túto adresu z povolenej schránky odošleme cez sieť Peppol rovnako, ako keby ste súbor nahrali na záložke Odoslať súborom; odosielateľ dostane jednu odpoveď s výsledkom za každú prílohu a doklad je v portáli aj v API so stavom doručenia, doručenkou MLS a hlásením FS. Nastavenie: Prepojenia a integrácie → Odosielanie e-mailom (vlastník alebo správca firmy, len po prihlásení). /dashboard/integrations/email

Pravidlá spracovania

• Prijmeme len správu od adresy na zozname povolených odosielateľov firmy (najviac 20); ostatné zahodíme bez odpovede.
• Predvolene musí doména odosielateľa prejsť overením SPF alebo DKIM u doručujúceho servera (zladenie ako pri DMARC, relaxed). Doručujúci server navyše odmieta správy, ktoré neprešli ani SPF, ani DKIM, a správy proti DMARC politike odosielateľa. Kontrolu možno vypnúť v nastavení, neodporúčame.
• Príloha: UBL 2.1 Invoice alebo CreditNote (Peppol BIS Billing 3.0), prípona .xml, prípadne v obálke SBDH; najviac 10 príloh v správe, 15 MB na prílohu, 200 správ na adresu za deň. PDF a text správy sa nespracúvajú.
• IFS Finvoice 2.0: prílohu .xml so SOAP obálkou IFS (IFSFinvoice) alebo samotný Finvoice prevedieme na UBL a ďalej spracujeme rovnako. Pravidlá prevodu: INV02 alebo záporná suma = dobropis (381) s kladnými sumami a odkazom na pôvodnú faktúru (OriginalInvoiceNumber, u IFS OrderIdentifier); predajca a odberateľ podľa slovenského IČ DPH (SellerOrganisationTaxCode, BuyerOrganisationTaxCode → 0245:DIČ), odberateľ mimo SR sa neprevádza; rozpis DPH z VatSpecificationDetails, riadky s 0 % ako kategória E s dôvodom z VatFreeText, inak „Oslobodené od DPH“; zaokrúhľovacie riadky IFS (základ 0,00, DPH 0,01) sa vynechajú, cena riadku, ktorá nesedí so sumou riadku, sa prepočíta; jednotky podľa UN/ECE (kg → KGM, pcs → H87, h → HUR, neznáme → C62 s pôvodným textom v poznámke riadku); vložený obraz faktúry (InvoiceAttachments, PDF) ide ako príloha dokladu do 5 MB; len EUR. Výsledok prevodu je v odpovedi aj v denníku firmy.
• Adresa pre výsledky: ak faktúry posiela systémová schránka, v nastavení zvolíte inú adresu, na ktorú chodí odpoveď s výsledkom (pole replyTo v PUT /companies/{id}/email-send, prázdne = odpovedať odosielateľovi).
• Predajca v XML (EndpointID dodávateľa, BT-34) musí byť táto firma, inak správu odmietneme (preposlaná faktúra od vášho dodávateľa sa nikdy neodošle ako vaša). Odberateľ musí mať EndpointID so schémou (BT-49).
• Rovnaká správa (Message-ID) sa spracuje raz. Doklad má v API a webhookoch origin = email, aktér = adresa odosielateľa.

Verejný health-check endpoint, vhodný na monitoring.

// 200 OK
{ "service": "peppol-portal-backend", "status": "ok", "timestamp": "2026-06-17T…Z" }

Živý prehľad všetkých komponentov nájdete na stránke stavu systémov.

Už v produkcii (často mylne považované za chýbajúce)

• POST /companies/{id}/documents/send je stabilné rozhranie portálu; pre ERP integrácie ostáva odporúčané SAPI-SK s Idempotency-Key.
• Registrácia do SMP prebieha automaticky po výbere na portáli FS; prechod od iného poštára cez POST /companies/{id}/smp-migrate s migračným kódom.
• Doručenky MLS, dôkazy doručenia a hlásenia FS (fsReport) v každom riadku /sapi/document/sent; replay webhookov za časové okno.
• Kľúč obmedzený na vybrané firmy; MCP server pre AI asistentov; vzory UBL na /vzory; verejný validátor.

Pripravujeme (poradie podľa dopytu integrátorov)

• Asynchrónny batch: POST /sapi/document/batch odpovie 202 s odkazom na job a stav po položkách.
• Zmenový kanál GET /sapi/document/changes?since&cursor s kurzorom namiesto stránkovania offsetom.
• Expirácia a rotácia API kľúčov v portáli, kľúč len na čítanie.
• Viac webhook endpointov na firmu s filtrom udalostí.