Vstavajte Peppol e-fakturáciu do svojho produktu

Model je proxy / multi-tenant: váš backend drží jeden API token (vpt_…) výhradne na serveri a každý váš zákazník je u nás jedna firma (tenant). Všetky volania robí váš server. Token nikdy nepatrí do prehliadača ani do mobilnej appky. Ktorú firmu volanie obsluhuje, určíte pri dokladoch hlavičkou X-Peppol-Participant-Id, pri správe firiem priamo ID firmy v ceste.

váš SaaS (backend)                      Verteco Peppol AP                      svet
──────────────────                      ─────────────────                      ────
POST /api/v1/companies  ──────────────▶ založenie tenanta
                                        zákazník: výber na FS (eID) ─────────▶ Finančná správa SR
                                        ◀── FS webhook: firma active + SMP reg.
POST /sapi/document/send ─────────────▶ validácia → AS4 ─────────────────────▶ Peppol sieť (príjemca)
                                        ◀── MLS doručenka (delivered/rejected)
◀── webhook invoice.received ────────── prijatá faktúra z Peppol siete ◀────── odosielateľ

1. 1. Vytvorte si účet na /register (e-mail + heslo, zadarmo, bez viazanosti).
2. 2. V dashboarde otvorte API tokeny (/dashboard/tokens) a vytvorte token. Formát je vpt_ + 40 hex znakov; plaintext sa zobrazí iba raz pri vytvorení (my ukladáme len SHA-256 hash). Spolu s tokenom si poznačte aj jeho UUID. Je to zároveň OAuth2 client_id pre SAPI-SK.
3. 3. Token má prístup ako váš účet: funguje pre všetky firmy, ktoré spravujete (multi-tenant bez ďalších kľúčov). Zrušenie tokenu v portáli okamžite zastaví portálové volania aj vydávanie nových SAPI tokenov.

Overenie, že kľúč funguje:

curl https://peppol.verteco.digital/api/v1/auth/me -H 'Authorization: Bearer vpt_8f2a…'
# → 200 { "id": "…", "email": "dev@vasa-saas.sk", … }

Pre každého zákazníka založte firmu jedným volaním. Vrátené id si uložte k svojmu tenantovi. Je to kľúč pre všetky ďalšie volania.

curl -X POST https://peppol.verteco.digital/api/v1/companies \
  -H 'Authorization: Bearer vpt_8f2a…' \
  -H 'Content-Type: application/json' \
  -d '{
    "ico": "12345678",
    "dic": "SK1234567890",
    "legalName": "Firma zákazníka s.r.o.",
    "street": "Príkladná 12",
    "postalCode": "010 01",
    "city": "Žilina",
    "iban": "SK31 1200 0000 1987 4263 7541"
  }'
# → 201 { "id": "9fa8fd81-…", "status": "pending_verification", "peppolParticipantId": null, … }
# (IČO/DIČ vyššie sú ukážkové, použite reálne údaje zákazníka)

Tip: údaje firmy predvyplníte z Registra právnických osôb (rovnaké API používa náš vlastný onboarding formulár):

curl "https://peppol.verteco.digital/api/v1/lookup/company?ico=53412834" -H 'Authorization: Bearer vpt_8f2a…'
# → 200 { "name": "Verteco digital services, s. r. o.",
#         "street": "Daniela Dlabača 21", "city": "Žilina", "zip": "010 01" }

pending_verification ≠ živé v Peppole. Slovenský zákon vyžaduje, aby si firma svojho poskytovateľa („digitálneho poštára") zvolila sama u štátu. Sú to dva nezávislé kroky:

curl -X POST https://peppol.verteco.digital/api/v1/companies/{id}/verification \
  -H 'Authorization: Bearer vpt_8f2a…' \
  -H 'Content-Type: application/json' \
  -d '{"token": "<verifikačný údaj, 1024 hex znakov>"}'
# → 200 { "companyId": "…", "status": "active",
#         "sendingVerified": true,
#         "verificationMethod": "self", "verifiedAt": "…" }

A · Push: webhook per tenant (odporúčané)

Každej firme nastavte webhook URL (a voliteľne notifikačný e-mail) a vyzdvihnite podpisový secret (vráti sa iba raz):

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": "zakaznik@firma.sk"}'

curl -X POST https://peppol.verteco.digital/api/v1/companies/{id}/webhook/secret -H 'Authorization: Bearer vpt_8f2a…'
# → 200 { "secret": "vpt_…" }   ← uložte, zobrazí sa iba raz

Pri prijatej faktúre pošleme na vašu URL POST (event invoice.received; pri odoslanej invoice.sent):

POST https://vasa-saas.sk/peppol/webhook
Content-Type: application/json
X-Verteco-Event: invoice.received
X-Verteco-Signature: sha256=3f1a9c…   ← HMAC-SHA256 nad surovým telom

{
  "event": "invoice.received",
  "companyId": "9fa8fd81-…",
  "companyDic": "SK2121358349",
  "peppolParticipantId": "0245:2121358349",
  "documentId": "574d4e52-…",
  "invoiceNumber": "2027-0142",
  "senderId": "0245:2120433843",
  "supplierName": "Dodávateľ s.r.o.",
  "receiverId": "0245:2121358349",
  "issueDate": "2027-01-15",
  "dueDate": "2027-01-29",
  "deliveryDate": "2027-01-15",
  "currency": "EUR",
  "totalAmount": "1234.56",
  "peppolMessageId": "a0b1c2d3-…"
}

Partnerský podpisový kľúč si nastavíte sami (sprostredkovatelia): PUT /api/v1/resellers/me/notification-webhook s telom { "url": "https://…" } uloží URL, na ktorú budeme udalosti všetkých vašich zákazníckych firiem posielať, a pri prvom nastavení vráti podpisový kľúč (secret); zobrazí sa iba raz. Neskoršie zobrazenie vyžaduje heslo účtu (v portáli v detaile firmy, alebo POST …/notification-webhook/reveal s telom { "password": "…" }); každé zobrazenie sa zapisuje do bezpečnostného logu s IP a časom a posledné vidíte v odpovedi GET. Autentifikácia je vaším portálovým účtom (session alebo Bearer token); kľúč nikdy neposielame e-mailom. To, že je firma sprostredkovateľ, vidíte v API na jej zázname ako reseller: true (príznak whiteLabel označuje až firmy vašich zákazníkov).

Overenie podpisu (Node.js):

import crypto from 'node:crypto';

function verifyVertecoWebhook(rawBody, signatureHeader, secret) {
  // podpis = "sha256=" + hex( HMAC-SHA256(secret, surové telo requestu) )
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return signatureHeader?.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
}
// Dôležité: počítajte HMAC nad SUROVÝM telom (raw bytes), nie nad re-serializovaným JSON-om.

B · Pull: SAPI-SK receive (alternatíva alebo doplnok)

# zoznam prijatých dokladov (inkrementálne cez ?since=)
curl "https://peppol.verteco.digital/sapi/document/receive?since=2027-01-01T00:00:00Z&limit=200" \
  -H 'Authorization: Bearer <sapi_access_token>' \
  -H 'X-Peppol-Participant-Id: 0245:2121358349'
# → { "documents": [ { "documentId": "…", "documentTypeId": "…",
#       "senderParticipantId": "…", "receiverParticipantId": "…", … } ],
#     "nextPageToken": "50" }

# detail vrátane originálneho XML presne tak, ako prišlo zo siete
curl https://peppol.verteco.digital/sapi/document/receive/{documentId} \
  -H 'Authorization: Bearer <sapi_access_token>' -H 'X-Peppol-Participant-Id: 0245:2121358349'
# → { "metadata": { … }, "payload": "<Invoice …>", "payloadFormat": "XML" }

# potvrdenie spracovania (idempotentné)
curl -X POST https://peppol.verteco.digital/sapi/document/receive/{documentId}/acknowledge \
  -H 'Authorization: Bearer <sapi_access_token>' -H 'X-Peppol-Participant-Id: 0245:2121358349'

K dokladom sa dostanete aj cez portálové API: GET /companies/{id}/documents?direction=received, sťahovanie …/documents/{docId}/download?format=xml|html|mls, hromadné exporty …/documents/export.csv a …/documents/export.zip (originály XML). E-mailová notifikácia firme (ak ju zapnete) nesie faktúru ako PDF + originál XML v prílohe, odosielateľ nesie meno firmy a Reply-To smeruje na majiteľa účtu (správanie pripravené na white-label).

1 · Výmena tokenu (OAuth2 client_credentials)

curl -X POST https://peppol.verteco.digital/sapi/auth/token -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "<UUID vášho API tokenu>",
    "client_secret": "vpt_8f2a…"
  }'
# → 200 { "access_token": "eyJ…", "token_type": "Bearer",
#         "expires_in": 900, "refresh_token": "eyJ…" }
# access token platí 15 min (obnova cez POST /sapi/auth/renew, refresh 30 dní);
# GET /sapi/auth/token/status vráti should_refresh: true < 3 min pred expiráciou

2 · Odoslanie dokladu (UBL 2.1, Peppol BIS Billing 3.0)

curl -X POST https://peppol.verteco.digital/sapi/document/send \
  -H 'Authorization: Bearer <sapi_access_token>' \
  -H 'X-Peppol-Participant-Id: 0245:2121358349' \
  -H 'Idempotency-Key: fa-2027-0142' \
  -H 'Content-Type: application/json' \
  -d '{
    "metadata": {
      "documentId": "FA-2027-0142",
      "documentTypeId": "busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
      "processId": "cenbii-procid-ubl::urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
      "senderParticipantId": "0245:2121358349",
      "receiverParticipantId": "0245:2120433843"
    },
    "payload": "<?xml version=\"1.0\"?><Invoice …>…</Invoice>",
    "payloadFormat": "XML",
    "checksum": "<voliteľné: SHA-256 hex payloadu>"
  }'
# → 202 { "providerDocumentId": "<UUID u nás>", "status": "ACCEPTED", "receivedAt": "…", "timestamp": "…" }
# pri "REJECTED" (neprešiel validáciou / sieť odmietla) nesie odpoveď aj pole
# "detail" s konkrétnym dôvodom (napr. porušené pravidlá BR-CO-15, …)

3 · Dávkové odosielanie (až 100 dokladov)

curl -X POST https://peppol.verteco.digital/sapi/document/batch \
  -H 'Authorization: Bearer <sapi_access_token>' -H 'X-Peppol-Participant-Id: 0245:2121358349' \
  -H 'Content-Type: application/json' \
  -d '{ "documents": [
        { "itemId": "fa-2027-0142", "idempotencyKey": "fa-2027-0142", "metadata": { … }, "payload": "…", "payloadFormat": "XML" },
        …
      ] }'
# (schematický príklad: metadata má rovnaké polia ako pri jednotlivom sende)
# → 202 { "total": 100, "accepted": 98, "rejected": 1, "failed": 1,
#         "results": [ { "itemId": "…", "ok": true, "providerDocumentId": "…", "status": "ACCEPTED" }, … ] }
# položky sa spracúvajú sekvenčne; zlyhanie jednej neovplyvní ostatné

4 · Stav doručenia a doručenky (MLS)

Životný cyklus odoslaného dokladu: pending → submitted → delivered / rejected (potvrdené doručenkou MLS od Access Pointu príjemcu) alebo failed (transportné zlyhanie; retry s rovnakým Idempotency-Key). Stavy sledujte inkrementálne:

curl "https://peppol.verteco.digital/sapi/document/sent?since=2027-01-15T00:00:00Z" \
  -H 'Authorization: Bearer <sapi_access_token>' -H 'X-Peppol-Participant-Id: 0245:2121358349'
# → { "documents": [ { "documentId": "574d4e52-…", "peppolMessageId": "a0b1c2d3-…",
#       "status": "delivered", "statusDateTime": "…", … } ], … }
# documentId = providerDocumentId zo send odpovede (UUID u nás); párujte podľa neho
# alebo podľa peppolMessageId; pri "rejected" riadok nesie aj statusDetail s dôvodom.
# ?since= zachytáva aj ZMENY STAVU (nie len nové doklady); ideálne na polling každých pár minút

# doručenka (MLS ApplicationResponse XML), právny dôkaz o doručení:
curl "https://peppol.verteco.digital/api/v1/companies/{id}/documents/{documentId}/download?format=mls" \
  -H 'Authorization: Bearer vpt_8f2a…'

Váš tenant nemusí nikdy otvoriť náš portál: každá funkcia, ktorú má priamy zákazník v dashboarde, existuje ako REST endpoint pod vaším tokenom. Prehľad celej správcovskej plochy (všetko Authorization: Bearer vpt_…, base /api/v1):

Cieľový stav: váš zákazník používa váš produkt, vašu značku a váš support; my sme neviditeľná infraštruktúra. Tri kroky, ktoré to zaistia:

1. 1 · Zapnite white-label režim na firme

   S whiteLabel: true platforma neposiela tenantovi žiadne vlastné e-maily (napr. potvrdenie výberu poskytovateľa) a nepreberá si jeho kontaktnú adresu z výberu na FS. Komunikáciu vediete vy, pod vlastnou značkou.

   bashKopírovať

   curl -X PUT https://peppol.verteco.digital/api/v1/companies/{id} -H 'Authorization: Bearer vpt_8f2a…' \
     -H 'Content-Type: application/json' \
     -d '{"ico":"12345678","dic":"SK1234567890","legalName":"Firma zákazníka s.r.o.",
          "street":"Príkladná 12","postalCode":"010 01","city":"Žilina",
          "iban":"SK31 1200 0000 1987 4263 7541","whiteLabel":true}'
   # najjednoduchšie je poslať whiteLabel už pri POST /companies (založení firmy);
   # POZOR: PUT je plná aktualizácia; pošlite všetky voliteľné polia (adresa, IBAN),
   # vynechané sa vymažú

2. 2 · Notifikácie riešte webhookmi, nie našimi e-mailami

   V white-label režime platforma neposiela e-maily o faktúrach vôbec (pole notificationEmail sa ignoruje). Nastavte webhook a o prijatej faktúre sa dozviete cez invoice.received. Obsah si stiahnete cez API (XML / tlačiteľné HTML) a zákazníkovi pošlete vlastný e-mail z vlastnej domény.

3. 3 · Dokončenie výberu na FS zachytíte webhookom company.activated

   Keď zákazník dokončí výber poskytovateľa na portáli Finančnej správy, pošleme na webhook firmy udalosť (nemusíte pollovať):

   httpKopírovať

   POST https://vasa-saas.sk/peppol/webhook
   X-Verteco-Event: company.activated
   X-Verteco-Signature: sha256=…
   
   {
     "event": "company.activated",
     "companyId": "9fa8fd81-…",
     "companyDic": "SK2121358349",
     "peppolParticipantId": "0245:2121358349",
     "status": "active",
     "verifiedAt": "2027-01-05T09:12:33Z"
   }

   Udalosť znamená: výber kryptograficky overený, firma prepnutá na status: "active", registrácia do SK SMP odoslaná; tenant je pripravený prijímať aj odosielať (Verifikačný údaj prišiel spolu s výberom). Udalosť je at-least-once; spracujte ju idempotentne a vždy sa riaďte poľom status v tele (posielame ju len pre reálne aktivované firmy; firma pozastavená administrátorom ju nedostane).

Čo tenant uvidí a čo nie (úprimne)

Aj toto posledné okno sa dá prebrandovať: Finančná správa umožňuje certifikovaným poskytovateľom registrovať partnerov ako sprostredkovateľov doručovacej služby. Po zápise si zákazník na vpds.financnasprava.sk vyberá priamo vašu značku zo zoznamu. Žiadosť o zápis vygenerujete za pár minút na /sprostredkovatel.

Bezpečnosť a zákonné požiadavky

Právne dokumenty: obchodné podmienky · ochrana osobných údajov. Zmluvný vzťah máte s nami vy ako partner; voči svojim zákazníkom vystupujete podľa vlastných podmienok.

Celý SAPI-SK kontrakt si vyskúšate okamžite s verejnými prihlasovacími údajmi client_id = sandbox / client_secret = sandbox. Sandbox validuje požiadavky presne ako produkcia, ale nikdy nič nedoručí a nevidí reálne dáta; izolácia je vynútená priamo v podpísanom tokene.

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

# 2 · mock send: plná validácia kontraktu, nič sa nedoručí
curl -X POST https://peppol.verteco.digital/sapi/document/send \
  -H 'Authorization: Bearer <sandbox_token>' -H 'X-Peppol-Participant-Id: 0245:0000000000' \
  -H 'Content-Type: application/json' \
  -d '{"metadata":{"documentId":"TEST-1","documentTypeId":"…","senderParticipantId":"0088:sandbox-sender","receiverParticipantId":"0088:sandbox-receiver"},"payload":"<Invoice/>","payloadFormat":"XML"}'
# → 202 { "providerDocumentId": "sandbox-…", "status": "ACCEPTED", … }

# 3 · vzorový prijatý doklad
curl "https://peppol.verteco.digital/sapi/document/receive" -H 'Authorization: Bearer <sandbox_token>' -H 'X-Peppol-Participant-Id: 0245:0000000000'
curl "https://peppol.verteco.digital/sapi/document/receive/sandbox-doc-0001" -H 'Authorization: Bearer <sandbox_token>' -H 'X-Peppol-Participant-Id: 0245:0000000000'

Doplnky k sandboxu: verejný validátor e-faktúr (rovnaké pravidlá ako produkčný AP), testovací webhook (POST /companies/{id}/webhook/test) a skúšobná faktúra cez reálnu sieť na vlastnú firmu (POST /companies/{id}/documents/send-test).

Rate limity (pevné 60-sekundové okno)

Každá odpoveď nesie hlavičky RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset; pri prekročení príde 429 s hlavičkou Retry-After a telom { "error": "rate_limited", "message": "Too many requests. Slow down." }. (Výnimka: /auth/me a /auth/logout idú v bežnom bucket-e na token.) Aktuálne hodnoty limitov čítajte vždy z hlavičiek; sú nastavené tak, aby ich bežná prevádzka vrátane špičiek nikdy nedosiahla. Pri hromadnom onboardingu / batch odosielaní dávkujte s backoffom na 429. Potrebujete vyšší limit? Napíšte nám.

Dva tvary chýb

{ "error": "ico_taken",
  "message": "A company with this IČO already exists" }

// pri validácii polí navyše:
{ "error": "validation_failed", "message": "Some fields are invalid",
  "fields": { "dic": "IČ DPH musí byť 'SK' a 10 číslic" } }

{ "error": {
    "category": "AUTH",
    "code": "SAPI-AUTH-003",
    "message": "Sending is not enabled for this participant: a verified Verifikačný údaj is required.",
    "retryable": false,
    "correlation_id": "b4191dfc-…"
} }

Veľkostné limity

• ✓Účet + API token vytvorený, token bezpečne uložený na serveri (nikdy vo frontende).
• ✓Onboarding flow: POST /companies + presmerovanie zákazníka na výber poskytovateľa na portáli FS (eID).
• ✓Stavový polling: sledujete peppolParticipantId (signál, že firma prijíma) a príznak verified + status active pred prvým odoslaním.
• ✓Webhook endpoint: overuje X-Verteco-Signature (HMAC-SHA256 nad surovým telom), odpovedá 2xx do 15 s, deduplikuje podľa documentId.
• ✓Odosielanie: Idempotency-Key na každom sende, backoff na 429 a SAPI-PROC-001, polling /sapi/document/sent?since= na stavy doručenia.
• ✓Mapovanie dokladov otestované cez verejný validátor a sandbox; prvý ostrý test cez send-test.
• ✓Ošetrené chybové stavy: 403 sending_not_verified, 409 ico_taken, REJECTED verdikt s dôvodom.
• ✓Limity účtu navýšené podľa počtu firiem (napíšte nám pri >10 firmách).

Musí mať každý náš zákazník účet vo vašom portáli?

Nie. Model je proxy: váš backend drží jeden API token a firmy zákazníkov zakladáte a obsluhujete cez API vo svojom účte. Zákazník robí jediný krok mimo vášho produktu: jednorazový výber poskytovateľa na portáli Finančnej správy cez eID (zákonná podmienka). Portálový účet u nás je preňho voliteľný bonus, nie podmienka.

Ako zistíme, že zákazník dokončil výber na Finančnej správe?

Najjednoduchšie: nastavte firme webhook a počúvajte udalosť company.activated. Pošleme ju hneď po kryptografickom overení výberu, spolu s prideleným peppolParticipantId. Alternatívne polling: GET /api/v1/companies/{id}, kde spoľahlivý signál dokončeného výberu (a teda schopnosti prijímať) je vyplnené pole peppolParticipantId (nastavuje sa výhradne po výbere na portáli FS). Samotný status active nestačí: nastaví ho aj doloženie Verifikačného údaja cez API, ktoré sprístupňuje iba odosielanie.

Môžeme službu predávať pod vlastnou značkou (white-label)?

Áno. Riešenie pod vlastnou značkou je súčasťou balíka Odosielanie a príjem, bez osobitných partnerských poplatkov. Firme nastavíte whiteLabel: true a platforma jej neposiela žiadne vlastné e-maily; notifikácie odoberáte webhookmi a komunikujete pod vlastnou značkou. Vy určujete cenu pre svojich zákazníkov a fakturujete im sami; nám platíte podľa verejného cenníka.

Ako otestujeme integráciu bez reálnych dokladov?

Tri nástroje: verejný SAPI sandbox (client_id aj client_secret = "sandbox") s plnou validáciou kontraktu, ktorý nikdy nič nedoručí; verejný validátor e-faktúr (POST /api/v1/public/peppol-validate) s rovnakými EN 16931 + Peppol BIS pravidlami ako produkčný Access Point; a testovací webhook (POST /companies/{id}/webhook/test), ktorý pošle podpísanú vzorovú udalosť na vašu URL.

Čo ak zákazník posiela tisíce faktúr mesačne?

Žiadny tvrdý strop: nad 1 000 faktúr mesačne je každá ďalšia faktúra €0,01. API podporuje dávkové odosielanie (batch až 100 dokladov na volanie) a inkrementálne sťahovanie cez parameter since. Pri veľkom objeme firiem alebo dokladov pripravíme objemovú dohodu.

Aké typy dokladov viete prijímať a odosielať?

Peppol BIS Billing 3.0 faktúry a dobropisy (UBL 2.1) vrátane SK Billing pravidiel, self-billing faktúry a dobropisy a MLS doručenky. Slovenské daňové hlásenie (TDD) k dokladom obstarávame automaticky podľa harmonogramu sprístupnenia rozhrania Finančnej správy.

Je API verzované a stabilné?

Áno. Strojovo čitateľná OpenAPI 3.1 špecifikácia je na /api/v1/openapi.json a pokrýva portálové API aj SAPI-SK. SAPI-SK je národné štandardizované rozhranie, nie proprietárny kontrakt, takže integrácia nie je vendor lock-in. Zmeny robíme spätne kompatibilne.