Pre sprostredkovateľov: partnerský model

Čo má bežný multi-tenant účet

• Jeden API token pre všetky firmy účtu (hlavička X-Peppol-Participant-Id v SAPI-SK).
• Notifikačný webhook nastavený pri každej firme zvlášť (GET/PUT /api/v1/companies/{id}/notifications) s rovnakým podpisom X-Verteco-Signature.
• Odregistráciu vlastnej firmy (POST /api/v1/companies/{id}/deregister) a prehľad spotreby po firmách (GET /api/v1/companies/usage).
• Firmy sú vždy pod správou svojho vlastníka, nie partnera: jednostranné odpojenie klienta a brzda odosielania v bežnom modeli nie sú.

Ako sa stať sprostredkovateľom

Žiadosť vyplníte na stránke Staňte sa digitálnym poštárom, tlačivo Finančnej správe podpíšeme a podáme my. Poplatok je 99 € ročne bez DPH. Po zverejnení vo výbere Finančnej správy si vás klienti vyberajú pod vašou značkou, ich firmy vznikajú pod vaším partnerským účtom automaticky a zapisujú sa do centrálneho SMP, ak ich záznam nedrží iný poskytovateľ (vtedy dostanete udalosť company.smp_registered_elsewhere a postup s migračným kódom). V testovacom prostredí prebehne registrácia sprostredkovateľa bez poplatku a hneď dostanete testovací partnerský endpoint.

• Staňte sa digitálnym poštárom (žiadosť)
• Obchodné podmienky sprostredkovania
• Naši sprostredkovatelia
• Klient od iného poskytovateľa: migračný kód (návod)
• Zmluvy: VOP, DPA, SLA, NDA

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). Rozšírený verejný návod so vzorovými kódmi, webhook podpismi a go-live checklistom: peppol.verteco.digital/saas.

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 (prihlásením cez eID alebo prihlasovacími údajmi do portálu FS) 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). Ak zákazník už mal iného poskytovateľa, po výbere sa firma síce aktivuje, ale záznam v SMP drží starý poštár a treba migračný kód: postup je v kapitole Klient prichádza od iného poskytovateľa.
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; rovnako invoice.sent, invoice.delivered, invoice.rejected, invoice.undeliverable, invoice.reported a company.* za všetkých vašich klientov), 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

   Podklady na prefakturáciu

   GET /companies/usage?month=YYYY-MM vráti počty odoslaných a prijatých dokladov za každú vašu firmu zvlášť aj súhrnne, presne v jednotkách, v ktorých je postavený cenník, takže si viete svojim klientom prefakturovať priamo z toho. Bez parametra vráti aktuálny mesiac; obdobie je polouzavreté a v odpovedi sú explicitne polia from/to, aby ste nemuseli hádať hranicu mesiaca. Firmy bez prevádzky sú v zozname s nulami.
7. 7

   Š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 na token: pri hromadnom onboardingu dávkujte s backoffom na 429 (Retry-After) a ošetrite 409 ico_taken (idempotentne).

Ak ste zapísaný ako sprostredkovateľ (žiadosť cez /sprostredkovatel/ziadost), Finančná správa posiela na vašu webhook URL notifikáciu vždy, keď si vás klient vyberie na portáli VPDS. Tento manuál popisuje presný kontrakt tak, ako ho FS reálne volá v produkcii (overené na živých výberoch). FS k webhookom vlastný verejný manuál nevydáva; toto je to, čo na implementáciu potrebujete.

1 · Ako notifikácia vyzerá + 2 · overenie pravosti

3 · Čo s tým: preposlať nám surové telo

Odporúčaná (a najjednoduchšia) implementácia je raw-byte proxy: prijmite POST, odpovedzte rýchlo a surové bajty tela prepošlite na váš registračný endpoint u nás. Ten vzniká automaticky po vyplnení formulára /sprostredkovatel/ziadost, je aktívny hneď a jeho presnú URL (s vaším kľúčom) vidíte po prihlásení cez GET /api/v1/resellers/me:

POST https://peppol.verteco.digital/peppol/webhook/reseller/{vas-kluc}
Content-Type: application/json
(telo = nezmenené surové bajty od FS)

My verification_token kryptograficky overíme, firmu automaticky založíme pod vaším partnerským účtom (white-label), zaregistrujeme ju do centrálneho SK SMP a od tej chvíle jej doručujeme e-faktúry. Vy si z payloadu môžete uložiť kontaktné údaje pre vlastný onboarding; nič viac netreba. Výnimka: ak subjekt už mal iného poskytovateľa, záznam v SMP ostáva u neho a od nás dostanete udalosť company.smp_registered_elsewhere plus e-mail; ako to doriešiť, popisuje samostatná kapitola.

4 · Prevádzkové pravidlá (dôležité)

• Idempotencia: ten istý subjekt môže výber zopakovať; spracovanie rovnakého DIČ musí byť bezpečné (u nás je).
• Zdrojová IP: volania chodia z infraštruktúry FS (pozorované z 194.1.2.13); IP allowlist odporúčame len ako doplnok, nie ako jedinú ochranu (rozsah FS negarantuje).
• Odpoveď: vracajte 200 aj pri internej chybe spracovania (chybu si zalogujte); nič iné FS nevyhodnotí.
• Poradie nasadenia: webhook musí byť živý pred podaním žiadosti FS; prvý výber môže prísť krátko po zverejnení.

Referenčná implementácia proxy má ~30 riadkov (prijmi POST → ulož → prepošli surové bajty). Ak si chcete overiť celý reťazec ešte pred zverejnením u FS, pošlite testovací POST na váš registračný endpoint; na neznámy/nepodpísaný obsah odpovie bezpečne a nič nezaloží. Otázky: Podpora.

5 · Ukončenie zmluvy o sprostredkovaní

Zmluvu o sprostredkovaní je možné ukončiť aj priamo z prostredia aplikácie: vlastník partnerského účtu v Nastaveniach poštára vyplní žiadosť o ukončenie (kontrolná otázka + potvrdenie dôsledkov) a výpoveď potvrdí odkazom, ktorý mu príde e-mailom. Potvrdením je výpoveď doručená; výpovedná lehota je jeden mesiac a plynie od 1. dňa nasledujúceho mesiaca (čl. 7.1 obchodných podmienok sprostredkovania). Žiadosť o výmaz zo zoznamu sprostredkovateľov podávame Finančnej správe my do 5 pracovných dní po zániku zmluvy (čl. 7.3); podklad dostane náš tím, klientom sprostredkovateľa sa nič neposiela. Nepotvrdenú žiadosť možno v aplikácii zrušiť. Programovo: GET/POST/DELETE /api/v1/resellers/me/termination.

6 · Ako je rozdelená zodpovednosť

Zhrnutie čl. 5 obchodných podmienok sprostredkovania (v1.6), aby ste vedeli, čo od vás v praxi očakávame. Zmluvná pokuta ani zodpovednosť za škodu vám nevzniká zo samotného technického prenosu dokladu vášho klienta a nie ste povinný overovať hospodársku realitu ani vecnú správnosť jednotlivých dokladov (čl. 5.8). Výber na portáli Finančnej správy potvrdený eID alebo prihlasovacími údajmi spolu s naším overeným Verifikačným údajom je dostatočným overením oprávnenia konať za firmu a poskytnutie prístupu k API vašim vlastným klientom nie je sprístupnením prístupu tretej osobe (čl. 5.9). Zmluvné pokuty majú strop 5 000 EUR na jednu udalosť alebo sériu porušení z jednej príčiny a 10 000 EUR za kalendárny rok (čl. 5.3). Sankcie a opatrenia, ktoré nám reálne uložia orgány alebo autority siete Peppol pre konanie vo vašej sfére, sa naďalej prenášajú bez stropu (čl. 5.2), pretože ich voči Finančnej správe a OpenPeppolu nesieme bez obmedzenia my; nárok sa však pomerne znižuje o náš podiel, prikladáme k nemu doklad a písomné vyčíslenie, máte 15 dní na vyjadrenie, zrušenú alebo zníženú sankciu vám vrátime do 15 dní aj bez výzvy a nároky voči klientovi, ktorý ju vyvolal, vám postúpime aj s podkladmi (čl. 5.5 a 5.7). Preto od vás čl. 4.1 písm. h) žiada preniesť zodpovedajúce povinnosti do zmlúv s klientmi a viesť záznamy o tom, kto ktorý doklad vytvoril; vzorové znenie klauzuly pošleme na požiadanie zadarmo.

Partnerský notifikačný webhook (sprostredkovatelia)

Ak ste zapísaný sprostredkovateľ, nemusíte nastavovať webhook pri každej firme zvlášť: jeden partnerský notifikačný webhook dostáva všetky udalosti firiem pod vaším partnerským účtom a má prednosť pred webhookmi jednotlivých firiem. Vaši klienti teda nič nenastavujú; firmu rozlíšite podľa companyDic / peppolParticipantId.

E-maily o jednotlivých faktúrach: partnerský účet je členom každej klientskej firmy, takže by so štandardným nastavením účtu dostával e-mail o každej prijatej faktúre každej z nich. White-label klientom e-maily neposielame nikdy (kanál je webhook); pri ostatných firmách si ich pre partnerský účet vypnete v Nastavenia poštára → Notifikácie (jedným prepínačom; to isté nastavenie je aj v Nastavenia → Notifikácie účtu).

// 200 OK (prvé nastavenie)
{ "url": "https://vasa-appka.sk/peppol/events", "secret": "vpt_…", "hasSecret": true,
"events": ["company.activated","company.deactivated","company.smp_registered_elsewhere","invoice.received","invoice.sent","invoice.delivered","invoice.rejected"] }

Podpis X-Verteco-Signature sa počíta rovnako ako pri firemnom webhooku (nižšie), len s partnerským secretom.

Správa klientov cez API (jednostranné odpojenie a brzda odosielania)

Klient, ktorý od partnera odíde, spravidla neurobí nič – preto sú tieto operácie jednostranné a nevyžadujú žiadnu súčinnosť klienta. Príjem faktúr nimi nie je dotknutý: je viazaný na registráciu firmy v centrálnom SMP, nie na spravujúci účet.

Fakturačný model partnera

V Nastaveniach poštára, záložka Fakturácia (a cez GET/PUT /api/v1/resellers/me/billing) si volíte fakturačný model (voľba je dostupná len zapísaným sprostredkovateľom): per_company = 2 € mesačne za aktívne odosielajúce IČO, alebo per_document = 0,01 € za každú odoslanú faktúru vašich firiem (prijaté doklady zadarmo) s minimálnou mesačnou fakturáciou 300 € + DPH. Zmena modelu platí vždy od 1. dňa nasledujúceho mesiaca (v odpovedi pendingModel a pendingFrom); odpoveď oboch volaní vracia aj prepočet aktuálneho mesiaca pod modelmi, takže prepínate informovane.

Odporúčaný postup pri ukončenom klientovi (strop nákladov na vašej strane): priebežný stav čerpania vidíte v GET /api/v1/companies/usage?month=YYYY-MM (rozpis sent/received po firmách presne na preúčtovanie) a v GET /api/v1/resellers/me/clients (počty za aktuálny mesiac); o každom odoslanom aj prijatom doklade vašich firiem navyše chodí udalosť na partnerský webhook, takže „ukončenú" firmu zachytíte hneď pri prvom doklade. Potom stačí zavolať pause-sending alebo release.

Slovensko má jeden centrálny SMP pre všetkých poštárov a každý účastník má v ňom jeden záznam. Keď si váš klient zvolí vašu značku na portáli Finančnej správy, my ho overíme a aktivujeme, ale ak jeho záznam už drží predchádzajúci poskytovateľ, sieť ďalej doručuje jemu. Prepnutie robí jednorazový migračný kód, ktorý klientovi vydá doterajší poštár (štandardný mechanizmus SML, FAQ FS príklad 46; podľa pravidiel PA SK musí pôvodný poštár klienta po skončení zmluvy do 3 pracovných dní z centrálneho SMP odregistrovať). Pozor: podľa FAQ FS (príklady 36 a 73) môže klient prijímať u iného poštára a cez vás len odosielať; ak je to jeho zámer, zavolajte PUT /resellers/me/clients/{id}/receiving-provider s elsewhere=true (stav smpState = "external") a pripomienky aj automatická registrácia prestanú. Táto kapitola je návod, ako túto situáciu vo vašej platforme rozpoznať, uložiť, vyriešiť a čo od nás pritom dostanete.

1. 1

   Pripravte si prijímač: partnerský webhook

   Jeden webhook pre všetkých vašich klientov nastavíte cez PUT /resellers/me/notification-webhook (vyššie). Overte podpis X-Verteco-Signature a spracujte udalosť company.smp_registered_elsewhere: znamená „záznam drží iný poskytovateľ, potrebný migračný kód“. Deduplikujte podľa companyId + event; udalosť sa opakuje raz za týždeň, kým klient kód nevloží.

   jsonKopírovať

   // POST na váš webhook, hlavičky X-Verteco-Event + X-Verteco-Signature
   {
     "event": "company.smp_registered_elsewhere",
     "occurredAt": "2026-09-03T15:04:05Z",
     "companyId": "bb6eb4a7-1a98-48fe-97e6-e5abbaa56e54",
     "companyDic": "SK1028310426",
     "peppolParticipantId": "0245:1028310426",
     "status": "active",
     "action": "migration_code_required",
     "migrateUrl": "https://peppol.verteco.digital/dashboard/companies/migrate"
   }

2. 2

   Doplňte lookup: kedy sa pýtať a čo čítať

   Webhook môže chýbať (ešte ste ho nenastavili) alebo ho stratíte pri výpadku, preto stav aj čítajte: GET /resellers/me/clients vracia pri každej firme smpRegistered a smpState; detail dá GET /companies/{id}. Odporúčaný rytmus: raz denne pre všetkých klientov, pri otvorení klientskej stránky vo vašej aplikácii a 2 až 3 minúty po udalosti company.activated (registrácia v SMP prebehne zvyčajne do minúty). Pred založením klienta sa oplatí GET /public/peppol-check?id=0245:<DIČ>: ak je DIČ už v sieti, klient bude potrebovať kód a viete mu to povedať dopredu.

   smpState	Význam	Čo urobiť
   registered	Záznam v SMP je pod naším účtom, sieť doručuje k nám.	Nič, klient prijíma.
   pending	Registrácia beží (sekundy, pri výpadku SMP až hodiny; opakujeme automaticky).	Počkať, znovu prečítať o pár minút.
   elsewhere	Záznam drží iný poskytovateľ; klient potrebuje migračný kód.	Zobraziť klientovi výzvu, získať kód, zavolať smp-migrate (krok 4).
   rejected	FS verifikačný token bol odmietnutý.	Klient musí výber na portáli FS zopakovať.
   null	Nevzťahuje sa (firma ešte nie je overená výberom na FS).	Doviesť klienta k výberu na portáli FS.

3. 3

   Uložte si stav u seba

   Ku každému klientovi si držte companyId, peppolParticipantId, smpState, smpStateAt (kedy ste ho naposledy videli) a noticeShownAt (kedy ste klienta upozornili). Pri elsewhere zobrazte klientovi vo vašej aplikácii trvalé upozornenie s poľom na vloženie kódu; odosielanie neblokujte, firma odosielať smie. Pri registered upozornenie zrušte.

   textKopírovať

   // spracovanie udalosti vo vašom backende (pseudokód)
   on webhook(event):
     verify X-Verteco-Signature == sha256=HMAC(secret, rawBody)   // else 401
     if event.event == "company.smp_registered_elsewhere":
         tenant = tenants.byCompanyId(event.companyId)
         tenant.smpState = "elsewhere"; tenant.smpStateAt = event.occurredAt
         showBanner(tenant, "Vyžiadajte si migračný kód od doterajšieho poskytovateľa")   // + input
     if event.event == "company.activated":
         schedule(in 3 min): tenant.smpState = GET /companies/{id}.smpState
   
   daily job:
     for row in GET /resellers/me/clients: tenants[row.companyId].smpState = row.smpState
   
   on code entered by the client:
     r = POST /companies/{id}/smp-migrate { migrationCode }
     if r.status == 200: tenant.smpState = "registered"; hideBanner(tenant)
     else: showError(tenant, r.error)   // 400 migration_code_rejected → ask for a new code

4. 4

   Získajte kód a prevezmite záznam

   Klient si vyžiada u doterajšieho poskytovateľa migračný kód (SMP migration code) pre svoje DIČ; kód je jednorazový a časovo obmedzený, použite ho hneď. Zavolajte POST /companies/{companyId}/smp-migrate vaším partnerským tokenom (ste vlastníkom firmy). Odpoveď 200 nesie firmu so smpRegistered = true, sieť sa prepne okamžite a bez výpadku; samostatná udalosť sa neposiela, stav si zapíšte z odpovede alebo znovu prečítajte cez GET.

   bashKopírovať

   curl -X POST https://peppol.verteco.digital/api/v1/companies/<companyId>/smp-migrate \
     -H 'Authorization: Bearer vpt_8f2a…' -H 'Content-Type: application/json' \
     -d '{ "migrationCode": "MIGR-7K3Q-…" }'
   # 200 { "company": { …, "smpRegistered": true, "smpState": "registered" }, "outcome": "REGISTERED" }

   HTTP · kód	Význam	Čo urobiť
   400 migration_code_rejected	Kód je neplatný, použitý alebo vypršal.	Vyžiadať od starého poskytovateľa nový kód.
   409 registered_elsewhere	SMP kód neprijalo, záznam stále drží iný poskytovateľ.	Overiť, že kód patrí k tomuto DIČ; skúsiť s novým kódom.
   403 company_not_verified	Firma ešte nie je overená výberom na FS.	Najprv výber na portáli FS.
   503 smp_unavailable	Centrálne SMP neodpovedá.	Zopakovať o pár minút (kód ostáva platný).

5. 5

   Čo vám posielame my

   Pri zistení pošleme e-mail na kontaktnú adresu partnera (zo zápisu sprostredkovateľa) s DIČ, Peppol ID a postupom, potom raz za týždeň, kým prevzatie neprebehne (najviac štyrikrát); rovnaká informácia ide webhookom. Klientovi white-label firmy nepíšeme. Ak kód dostanete vy, ale nechcete volať API, pošlite ho na peppol​@​verteco.digital a prevzatie vykonáme z administrácie.

   Text pre klienta, ktorý môžete prevziať:

   Vaša firma je u nás už aktivovaná, ale záznam v národnom registri Peppol (SMP) stále drží váš predchádzajúci poskytovateľ, takže e-faktúry vám zatiaľ chodia k nemu. Vyžiadajte si u neho migračný kód (SMP migration code) pre DIČ … a vložte ho sem. Prepnutie je okamžité a bez výpadku.