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 eID); 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 cez eID

Validácia

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

Doručenie

simulované: dokument nikdy neopustí testovací server; ak príjemca (IČ DPH) existuje v testovacom prostredí, faktúra sa mu doručí ako prijatá (vrátane e-mailu, PDF a webhooku)

Doručenka

simulovaná, výslovne označená ako SANDBOX

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 cez slovensko.sk (eID), 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.

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)

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). Nesú identifikáciu dokladu a firmy (documentId, invoiceNumber, receiverId, peppolMessageId, companyDic, peppolParticipantId) plus status, statusDetail s dôvodom odmietnutia a statusDateTime. 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); detaily v návode /saas:

{
"event": "invoice.received",
"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"
"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
"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, company.activated, company.deactivated a testovací webhook.test. Neznámy typ udalosti odporúčame odložiť bokom a zalogovať; nový typ vždy vopred ohlásime.

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

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

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