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. 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
• 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 (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

   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.

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.

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.

// 200 OK (prvé nastavenie)
{ "url": "https://vasa-appka.sk/peppol/events", "secret": "vpt_…", "hasSecret": true,
"events": ["company.activated","company.deactivated","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 partner konzole (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.