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();

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]

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.

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

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)

Kompletný katalóg chýb

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." }

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.

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 }

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.

{ "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ž 8× s exponenciálnym backoffom (30 s → max 1 h), potom dead-letter. Výpadok vášho servera teda notifikáciu nestratí, doručíme ju pri ďalšom pokuse. 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, 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 8× s odstupom 30 s až 1 h; 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

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). Náš limit je 25 MB na prílohu – 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/SMP 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/SMP)
• validate_document: validácia UBL proti EN 16931 + BIS 3.0 vrátane SK pravidiel
• 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

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.

• POST/companies/{id}/peppol/register· Manuálna registrácia do Peppol SMP cez API (dnes prebieha automaticky pri výbere poskytovateľa na portáli FS).

Chcete skorý prístup k integrácii, sandbox alebo máte otázku? Ozvite sa priamo:

Váš Peppol kontakt

Miriama Mrkávková

+421 944 488 269·peppol​@​verteco.digital