E-faktúra na Slovensku — jednoducho a po slovensky

Nemusíte byť technik. Ak ste živnostník, s. r. o. alebo účtovník, stačí vám náš portál v prehliadači — faktúry prijímate aj vystavujete klikaním, bez programovania. Takto to funguje v troch krokoch:

1. 1

   Zaregistrujte sa (zadarmo)

   Vytvorte si účet e-mailom v registrácii. Príjem faktúr je zadarmo (do 1000 mesačne).

2. 2

   Vyberte si nás na portáli Finančnej správy

   Aby vám mohli chodiť e-faktúry, zvoľte si nás ako svojho certifikovaného poskytovateľa (digitálneho poštára) na portáli FS. My vás potom automaticky zaregistrujeme do siete Peppol a pošleme e-mail s prihlásením.

3. 3

   Prijímajte a vystavujte faktúry

   Prijaté faktúry vám prídu do portálu aj e-mailom. Faktúru vystavíte v jednoduchom editore (ako vo Worde) — alebo si existujúcu faktúru duplikujete na pár klikov. Daňové hlásenie na Finančnú správu (TDD) odošleme za vás automaticky.

Podrobné návody (po slovensky, pre začiatočníkov):

Všetky návody na jednom mieste: Sprievodca e-fakturáciou.

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.

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

Ak prevádzkujete fakturačnú appku, ERP alebo platformu a chcete cez nás napojiť na Peppol viacero svojich zákazníkov (tenantov), integrujete sa raz a obsluhujete N firiem. Model je proxy: váš backend drží jeden API token (vpt_…) len na serveri (nikdy nie v prehliadači) a každý váš tenant = jedna firma u nás (jeden token → N firiem).

1. 1

   Jeden token, server-side

   Vytvorte si API token a držte ho v zabezpečenom prostredí backendu. Všetky volania robí váš server (Bearer), nie prehliadač zákazníka.
2. 2

   Onboarding tenanta = založenie firmy

   Pre každého zákazníka POST /companies s jeho IČO/IČ DPH; vráti { id, status: "pending_verification" } — id si uložte k tenantovi (detail viď Firmy).

   bashKopírovať

   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":"Firma s.r.o.",
          "street":"Príkladná 12","postalCode":"010 01","city":"Žilina","iban":"SK…"}'

3. 3

   Aktivácia v Peppole (krok zákazníka u štátu)

   pending_verification ≠ živé v Peppole. Aby firma prijímala, musí si zákazník na portáli Finančnej správy (cez eID) zvoliť Verteco ako poskytovateľa — vtedy ju zaregistrujeme do SMP a stav sa zmení na active. Aby firma mohla odosielať, doložte jej Verifikačný údaj cez Overenie odosielania (POST /companies/{id}/verification).
4. 4

   Príjem faktúr — webhook per tenant

   Nastavte webhook (a/alebo e-mail) pre každú firmu a vyzdvihnite podpisový secret:

   bashKopírovať

   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://vasa-saas.sk/peppol/webhook","notificationEmail":"…"}'
   
   curl -X POST https://peppol.verteco.digital/api/v1/companies/{id}/webhook/secret -H 'Authorization: Bearer vpt_8f2a…'
   # → { "secret": "…" }   (uložte na overovanie X-Verteco-Signature)

   Pri prijatej faktúre vám príde podpísaný POST (event invoice.received), durable s retry/dead-letter. Overenie podpisu, payload aj tlačidlo „Otestovať webhook" viď Notifikácie & webhooky.
5. 5

   Odoslanie faktúr

   Faktúru (UBL Peppol BIS 3.0) odošlite cez národné rozhranie SAPI-SK 1.0 — POST /sapi/document/send (OAuth2 client_credentials, client_secret = váš vpt_ token). SK daňové hlásenie (TDD/C5) doplníme automaticky.
6. 6

   Škálovanie a robustnosť

   Zoznamy stránkujte: GET /companies?page&limit aj GET /companies/{id}/documents?page&limit (s hlavičkami X-Total-Count a i.). Rešpektujte rate-limit 120/min na token — pri hromadnom onboardingu dávkujte s backoffom na 429 (Retry-After) a ošetrite 409 ico_taken (idempotentne).

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

409

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

429

prekročený rate limit

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

120 / min na API token (alebo session, inak IP)

Auth (/auth/*)

20 / min 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: 120
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": "SUBMITTED", … }

# 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": "…" }

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:

{
  "event": "invoice.received",
  "companyId": "08dd…",
  "documentId": "…",
  "invoiceNumber": "2026001",
  "senderId": "0088:7300010000001",
  "receiverId": "0245:2121358349",
  "issueDate": "2026-06-03",
  "currency": "EUR",
  "totalAmount": "120.00",
  "peppolMessageId": "…"
}

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 120/min na token — 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

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

Ing. Mariana Považanová

+421 902 059 753·mariana​@​verteco.digital