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.

Bezpečnosť prevádzky pre vašich klientov: sme certifikovaný poskytovateľ Finančnej správy SR (EFSK000031) s vlastným prístupovým bodom; certifikácia ISO/IEC 27001:2022 prebieha u akreditovaného orgánu SKQS, s. r. o., Žilina (SNAS), vybraného v septembri 2026, certifikát plánujeme do 1. 7. 2027; OpenPeppol ho vyžaduje od všetkých poskytovateľov od 1. 10. 2027, zatiaľ ho nemusí mať nikto. Zmluvy (VOP, DPA, SLA, NDA) sú v plnom znení na /zmluvy, dostupnosť na /status.

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, zákazník ju aktivuje výberom poskytovateľa na portáli Finančnej správy (prihlásením cez eID alebo prihlasovacími údajmi do portálu FS). Ste zapísaný sprostredkovateľ: zákazník vyberá vašu značku cez váš výberový odkaz (pole vpdsUrl v GET /api/v1/resellers/me), nie Verteco priamo, lebo priamy výber Verteco firmu z vášho programu vyradí (udalosť company.released_to_direct). FS pošle výber na váš webhook, vy ho preposielate nám (kapitola FS webhook) a my firmu aktivujeme, zaregistrujeme do SMP a pošleme vám company.activated. Nie ste zapísaný sprostredkovateľ: zákazník zvolí ako poskytovateľa Verteco a zvyšok prebehne rovnako. Overený výber firmu zároveň oprávni odosielať. Ak priamy výber Verteco k nám nedorazil, záložnou cestou je 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, invoice.report_pending, invoice.report_rejected 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

Zápis sprostredkovateľa predpokladá vlastný systém, ktorý výbery klientov prijme a prepošle nám. Našu adresu do tlačiva FS nevkladajte: FS má volať vás. Ak vlastný systém nemáte, nie ste sprostredkovateľ; správna cesta je registračná stránka s vaším označením a provízia (/affiliate).

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
x-pds-secret: <nezmenená hodnota z požiadavky FS>
(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. Udalosť company.client_registered_directly príde, keď si váš klient pridá svoju firmu priamo v portáli Verteco: linked = true znamená, že jeho účet sme pripojili ako spoluvlastníka (kontaktný e-mail firmy sa zhodoval), false je len informácia o pokuse (najviac raz denne); na vašom vzťahu s klientom ani na fakturácii sa nič nemení. Udalosť company.released_to_direct príde, keď si váš klient na portáli Finančnej správy vyberie Verteco priamo: firma tým opúšťa váš program (vaše účty strácajú prístup, white-label sa ruší, kontakt z výberu je vlastník); klienta o tom informujeme z portálu a vám príde aj e-mail. Platí pre výbery od 21. 9. 2026. Opačný smer, výber pod vašou značkou pre firmu, ktorú váš partnerský účet už vlastní (napríklad vašu vlastnú firmu, ktorú ste si pridali ako priamy zákazník), firmu nepreregistruje: prístupový bod aj záznam v centrálnom SMP ostávajú rovnaké (opakovaná registrácia je len potvrdenie), firma sa iba prepne do režimu white-label, od tej chvíle jej od nás nechodia e-maily o dokladoch, dozviete sa o nich len cez webhooky a API a účtuje sa v partnerskom modeli; archív a nastavenia ostávajú. Hodí sa to na overenie integrácie na vlastnej firme.

Transportný kľúč (hlavička x-pds-secret): po zverejnení zápisu pošle FS zip WebhookSecret_Verteco_<názov>.zip e-mailom žiadateľovi, teda nám, a heslo k nemu v SMS na telefónne číslo, ktoré ste uviedli vo formulári /sprostredkovatel/ziadost (tlačivo FS zo 17. 9. 2026 ho má v samostatnom poli), teda vám. Zip si stiahnete v konzole poštára, záložka FS webhook (tlačidlo Stiahnuť zip od FS), otvoríte ho heslom zo SMS a 32-znakový kľúč z textového súboru zadáte na tom istom mieste, kde si ho neskôr aj zobrazíte alebo stiahnete ako .txt (každé zobrazenie sa zapíše do auditu vášho účtu). Ak SMS neprišla, napíšte nám. Pri zápisoch podaných pred 17. 9. 2026 prišlo heslo nám a kľúč sme uložili sami. Od uloženia kľúča overujeme, že podpis sha512(telo + kľúč) každého volania sedí. Kým kľúč nie je zadaný, podpis len zaznamenávame. Pri uložení kľúč porovnáme s volaniami, ktoré FS na váš endpoint už poslala, a kľúč, ktorý s nimi nesedí, odmietneme; vaša proxy preto musí preposielať telo bajt po bajte (bez re-serializácie JSON).

3a · Čo odpovedá náš endpoint

Volanie spracujeme hneď (synchrónne). Telo odpovede 200 zámerne neprezrádza, či bol token platný a či sa firma aktivovala, aby sa endpoint nedal použiť na zisťovanie, ktoré DIČ je náš zákazník. Výsledok spracovania sa dozviete udalosťou company.activated na vašom notifikačnom webhooku a kedykoľvek ho prečítate cez GET /api/v1/resellers/me/clients (stav active, vyplnené peppolParticipantId).

Ak po odpovedi 200 do pár minút nepríde company.activated, pošlite nám čas volania; každé volanie máme v trvalom audite.

3b · Overenie požiadavky u vás pred preposlaním

Odporúčame, aby vaša proxy každú požiadavku overila ešte pred preposlaním. Tak nám posielate len pravé výbery FS a náhodné alebo podvrhnuté volania nezaberajú váš limit.

1. Najprv uložte celú požiadavku (surové telo aj hlavičky). FS výber nezopakuje, uložená kópia je jediná cesta, ako ho obnoviť.
2. Overte hlavičku x-pds-secret: musí sa rovnať hex(SHA-512(surové bajty tela + váš kľúč FS)), 128 hexadecimálnych znakov. Hash počítajte z tela presne tak, ako prišlo, ešte pred parsovaním JSON; kľúč pripojte hneď za telo bez oddeľovača; porovnávajte v konštantnom čase a bez ohľadu na veľké a malé písmená.
3. Prepošlite len zhodné požiadavky, s nezmeneným telom a pôvodnou hlavičkou x-pds-secret. Telá nad 64 KB zahoďte, výber FS má okolo 1 KB.

import crypto from 'node:crypto';

// rawBody = Buffer s telom presne tak, ako prišlo (napr. express.raw({ type: '*/*' }))
function isFromFs(rawBody, header, fsKey) {
  const expected = crypto.createHash('sha512')
    .update(Buffer.concat([rawBody, Buffer.from(fsKey, 'utf8')]))
    .digest('hex');
  const got = String(header || '').trim().toLowerCase();
  return got.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}

Rovnaké overenie v PHP, Pythone a C#:

<?php
// $rawBody = file_get_contents('php://input'); $header = $_SERVER['HTTP_X_PDS_SECRET'] ?? null;
function isFromFs(string $rawBody, ?string $header, string $fsKey): bool
{
    $expected = hash('sha512', $rawBody . $fsKey);
    $got = strtolower(trim((string) $header));
    return hash_equals($expected, $got);
}

import hashlib
import hmac

# raw_body = bajty tela presne tak, ako prišli (Flask: request.get_data(), FastAPI: await request.body())
def is_from_fs(raw_body: bytes, header: str | None, fs_key: str) -> bool:
    expected = hashlib.sha512(raw_body + fs_key.encode("utf-8")).hexdigest()
    got = (header or "").strip().lower()
    return hmac.compare_digest(expected, got)

using System.Security.Cryptography;
using System.Text;

// rawBody = bajty tela presne tak, ako prišli (ASP.NET Core: Request.Body skopírujte do MemoryStream pred čítaním JSON)
static bool IsFromFs(byte[] rawBody, string? header, string fsKey)
{
    byte[] key = Encoding.UTF8.GetBytes(fsKey);
    byte[] data = new byte[rawBody.Length + key.Length];
    Buffer.BlockCopy(rawBody, 0, data, 0, rawBody.Length);
    Buffer.BlockCopy(key, 0, data, rawBody.Length, key.Length);
    string expected = Convert.ToHexString(SHA512.HashData(data)).ToLowerInvariant();
    string got = (header ?? "").Trim().ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(got));
}

• Kľúč: je to ten istý kľúč FS, ktorým podpis overujeme my (zo zipu od FS, otvoreného heslom zo SMS); po zadaní ho nájdete v konzole poštára, záložka FS webhook. Držte ho len na serveri. Zhoda u vás znamená zhodu aj u nás.
• Iný mechanizmus nie je: FS transport nepodpisuje asymetrickým kľúčom a verejný kľúč na overenie hlavičky neexistuje. verification_token v tele je podpis FS nad DIČ; ten overujeme my voči certifikátu FS, vy ho len nezmenený prepošlete.
• Limit: 600 volaní za minútu z jednej IP adresy platí pre každé volanie na /peppol/webhook/…, platné aj neplatné. Volanie bez platnej hlavičky u nás skončí 403 a nič sa nespracuje, spam by však míňal limit vášho servera.
• Keď podpis nesedí už pri prvom reálnom výbere, požiadavku nezahadzujte: uložte ju a napíšte nám, chybu nájdeme spolu.

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).
• Keď preposlanie zlyhá (napríklad 403 alebo výpadok vášho servera), FS výber nezopakuje. Pošlite nám znova uložené pôvodné telo s pôvodnou hlavičkou x-pds-secret; spracovanie je idempotentné a firma sa aktivuje. Ak ste volanie neuložili, napíšte nám.
• 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). Adresu si overíte cez GET na váš registračný endpoint (odpoveď ready). Testovací POST bez platnej hlavičky x-pds-secret po uložení vášho kľúča dostane 403 a nič nezaloží; celý reťazec vrátane aktivácie firmy si vyskúšate v testovacom prostredí test.peppol.verteco.digital (simulovaný výber na /register-vpds-test; zápis sprostredkovateľa je tam bez poplatku a bez podania na FS, firma vytvorená cez POST /companies sa tam aktivuje hneď a simulovaný výber dostanete na svoj webhook ako od FS). 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.8), 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","company.client_registered_directly","company.released_to_direct","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; limit 1 000 dokladov mesačne sa pri per_document neuplatňuje, každá odoslaná faktúra sa účtuje od prvej (dobropis je odoslaný doklad) a prijaté sú zadarmo bez limitu. 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.

Kalkulačka: ktorý model vyjde pri vašom počte firiem a dokladov lacnejšie, vrátane ročnej sumy so zápisom a s DPH, si spočítate na stránke /sprostredkovatel (sekcia Kalkulačka).

Mesačný výpis spotreby po klientoch: GET /api/v1/resellers/me/usage?month=YYYY-MM (bez parametra predchádzajúci mesiac) vráti za každú firmu pod vašou značkou, ktorú vlastní váš účet, počty odoslaných a prijatých dokladov, doklady nad limit 1 000 (odoslané a prijaté spolu), sumu v modeli A (2 € za firmu, ktorá v mesiaci odoslala doklad, plus 0,01 € za každý doklad nad limit; archív sa firme pod vašou značkou nikdy neúčtuje) aj v modeli B (0,01 € za odoslaný doklad), súčty oboch modelov s doplnením do minima 300 € v modeli B a model, ktorý pre vás v danom mesiaci platil (appliedModel); priame firmy, ktorých je účet členom, platia zo svojho kreditu a vo výpise nie sú. Sumy sú v centoch bez DPH, ocenené rovnakým spôsobom ako mesačné vyúčtovanie, ale z aktuálneho stavu firiem v čase čítania (záväzné sú položky vyúčtovania vo vašom kredite), a pri firmách nad limitom sa líšia od náhľadu aktuálneho mesiaca v GET /resellers/me/billing, ktorý počíta model A ako 2 € × aktívne firmy. S ?format=csv dostanete to isté ako súbor pre účtovníctvo (UTF-8 s BOM, oddeľovač bodkočiarka, slovenské hlavičky, sumy s desatinnou čiarkou, posledný riadok Spolu) a v konzole poštára je výpis na záložke Spotreba s výberom posledných 12 mesiacov.

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.

Odporúčaný tok pre vlastný portál alebo aplikáciu partnera (podľa otázok partnerov v októbri 2026):

1. Kópie dokladov držte u seba. Firmám pod vašou značkou je Archív dát predvolene vypnutý, takže obsah dokladu (XML, PDF) u nás ostáva 14 dní po doručení a potom sa maže; dôkazy o doručení (doručenka, časy, stav hlásenia) ostávajú. Váš portál preto číta z vlastnej kópie a od nás sťahuje len nové doklady.
2. Nové doklady cez webhook, nie dopytovaním. Partnerský notifikačný webhook (vyššie) dostane invoice.received za každú firmu; doklad stiahnete cez GET /sapi/document/receive/{id} (XML, PDF, HTML a prílohy majú vlastné cesty) a potvrdíte cez POST /sapi/document/receive/{id}/acknowledge. Záložná cesta je stránkované čítanie GET /sapi/document/receive?status=received&limit=200 s pageToken (najstaršie prvé; potvrdené doklady z filtra vypadnú).
3. Stavy odoslaných dokladov chodia rovnako webhookom (invoice.sent, invoice.delivered, invoice.rejected, invoice.undeliverable, invoice.reported) a sú aj na dopyt cez GET /sapi/document/sent.
4. Vlastná doména pre klientov. Vaša aplikácia môže naše API volať cez vlastný mostík (napríklad api.vasa-domena.sk) jedným partnerským kľúčom pre všetky firmy pod vaším účtom; klienti našu adresu nepotrebujú a webhooky im preposielate z vašej strany.
5. Limity. 300 volaní za minútu na API kľúč, hlavičky RateLimit-* vracajú zostatok; vyšší limit nastavíme na požiadanie. Limit 1 000 dokladov mesačne na IČO platí v modeli A (odoslané a prijaté spolu, každý ďalší doklad 0,01 €); v modeli B sa neuplatňuje.

Ktorý model odplaty: model B (0,01 € za odoslaný doklad, minimum 300 € mesačne, prijaté zadarmo) je lacnejší než model A (2 € za každé IČO, ktoré v mesiaci odoslalo doklad) vtedy, keď v mesiaci odosiela viac ako 150 IČO a na jedno odosielajúce IČO pripadá v priemere menej ako 200 odoslaných dokladov (150 IČO = do 30 000 dokladov, 300 IČO = do 60 000); model meníte v konzole poštára s účinnosťou od nasledujúceho mesiaca.

Archív dát klienta cez partnerské API: ak má váš portál klientovi archív zapnúť alebo vypnúť, nemusí ho posielať do nášho portálu.

Čo zapnutý archív znamená pre cenu firmy pod vašou značkou, presne podľa kódu vyúčtovania: zapnutý Archív dát firme pod značkou sprostredkovateľa nikdy nespustí základ 2 €, takže v modeli A platíte 2 € len za mesiac, v ktorom firma odoslala doklad, plus 0,01 € za každý doklad nad 1 000 (odoslané a prijaté spolu), a v modeli B 0,01 € za odoslaný doklad; zapnutie archívu teda mení len to, ako dlho držíme originály (počas trvania zmluvy namiesto lehoty), nie sumu. Úložisko sa meria raz za noc a upozornenia pri 80 % a pri ďalšom začatom GB chodia na kontaktný e-mail partnera (náhradne na e-mail vlastníka zápisu), nikdy klientovi; mesačné vyúčtovanie položku za úložisko neobsahuje. Polia archiveReceived, archiveSent, wipeDaysReceived, wipeDaysSent a storageUsedBytes vidíte pri každej firme aj v GET /resellers/me/clients.

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.

Ak po čase prejdete od nás k inému certifikovanému poskytovateľovi, vaši klienti idú s vami. Technický prevod registrácií zvládneme hromadne a bez výpadku; jeden krok však určuje Finančná správa, nie my, a platí rovnako pre každého poskytovateľa na Slovensku. Sloboda odísť je záruka, nie scenár, s ktorým počítame: garancia pre partnerov (poplatok za zápis dorovnáme až na nulu, ročná cena za doklady o 10 % nižšia než v predloženej ponuke) platí počas celej spolupráce, takže dôvod odchádzať u nás nevzniká.

1. 1

   Výpoveď z konzoly

   V Nastaveniach poštára podáte výpoveď a potvrdíte ju odkazom z e-mailu; lehota je jeden mesiac od 1. dňa nasledujúceho mesiaca (čl. 7.1). Do zániku zmluvy beží všetko ako doteraz.
2. 2

   Migračné kódy hromadne

   Pošlite nám zoznam DIČ svojich klientov. Kódy z centrálneho SMP vydáme naraz pre všetkých (nie po jednom cez portál) a odovzdáme vám ich pre nového poskytovateľa. Alternatívne klientov v zákonnej lehote 3 pracovných dní po zániku zmluvy odregistrujeme (pravidlá PA SK).
3. 3

   Prevzatie v SMP bez výpadku

   Nový poskytovateľ zaregistruje každého klienta vo svojom SMP s migračným kódom; SML prepíše väzbu okamžite a náš záznam prejde na „Unpublished“. Doklady po celý čas chodia bez prerušenia: na Slovensku má každý subjekt jeden záznam v SMP na príjem, odosielať však môže cez viacerých poskytovateľov, takže nový poskytovateľ môže za klienta odosielať hneď, ako má jeho verifikačný údaj, aj skôr, než prevezme príjem.
4. 4

   Výber nového poskytovateľa na portáli Finančnej správy

   Verifikačný údaj, ktorý FS vydá pri výbere poskytovateľa, je jej podpis nad dvojicou DIČ poskytovateľa a DIČ klienta, teda je viazaný na konkrétneho poskytovateľa. Centrálne SMP ho vyžaduje pri každej registrácii slovenského účastníka, aj s migračným kódom. Nový poskytovateľ preto potrebuje verifikačný údaj vydaný pre seba a ten vzniká len výberom na portáli FS: prihlásením cez eID alebo prihlasovacími údajmi do portálu FS, urobiť ho môže aj osoba s autorizáciou (napríklad účtovník). Je to rovnaká autorizácia (plná moc), na základe ktorej sa podáva priznanie k DPH a kontrolný výkaz, a rovnaký úkon ako pri prvom výbere. Migračný kód rieši výpadok a čakanie na deregistráciu, výber na FS nenahrádza.
5. 5

   Export dát

   Na požiadanie vám hromadne exportujeme originálne XML dokladov, doručenky a metadáta, ktoré v čase zániku uchovávame; neodstránime ich skôr než 90 dní po zániku zmluvy alebo do potvrdenia exportu (čl. 7.4).

Zmluvný základ: čl. 7.1, 7.3 a 7.4 obchodných podmienok sprostredkovania. Opačný smer (klient prichádza od iného poskytovateľa) je v predchádzajúcej kapitole.

Finančná správa o vás ako o sprostredkovateľovi eviduje údaje z tlačiva, ktoré sme za vás podali (obchodné meno, sídlo, IČO, DIČ, kontaktná osoba, e-mail, telefón, web, adresa vášho webhooku). Zmenu nepíšete e-mailom: v konzole poštára otvorte záložku Údaje u FS, zapíšte nové hodnoty vedľa aktuálnych, ostatné nechajte tak a potvrďte všetky zmeny naraz. My pošleme na peppol​@​financnasprava.sk žiadosť podpísanú konateľom Verteco spolu s aktualizovaným tlačivom a o výsledku vás informujeme e-mailom (vlastníka účtu aj kontaktnú adresu).

V zozname a vo výbere Finančnej správy vystupujete pod obchodným menom právnickej osoby z tlačiva; názov produktu tlačivo nepozná. Značku, web a popis služby vyplníte v konzole poštára na záložke Informácie a tak vás zobrazíme na /partneri a /nasi-sprostredkovatelia (značka veľkým písmom, obchodné meno pod ňou); karta existuje odo dňa podania žiadosti.

Žiadosti odchádzajú v pracovných dňoch medzi 8:00 a 16:00 (slovenské sviatky vynímame), vždy najskôr 2 hodiny po podaní; dovtedy (a mimo okna až do najbližšieho odoslania) žiadosť čaká a môžete ju zrušiť. Zmenu obchodného mena, sídla alebo krajiny najprv overí náš tím (podklad, napríklad výpis z registra) a odošle ju až po overení. Platí jedna žiadosť za 48 hodín a vždy len jedna otvorená (čakajúca alebo odovzdaná FS) naraz, preto do nej dajte všetky zmeny. Cez API to isté: GET /resellers/me/fs-registration (aktuálne hodnoty, otvorená žiadosť, história, okno odoslania), POST /resellers/me/fs-change-requests s changes, note a confirm: true (429 s Retry-After počas 48 h), DELETE /resellers/me/fs-change-requests/{id} kým žiadosť čaká.

Zmeny Obchodných podmienok sprostredkovania doručovacej služby zverejňujeme na stránke podmienok (aj ako PDF) a oznamujeme e-mailom vlastníkovi účtu a kontaktnej osobe. Podľa čl. 9.1 nevyžadujú váš súhlas a platia odo dňa zverejnenia; konzola poštára na ne neupozorňuje ani nič neblokuje. Ak so zmenou nesúhlasíte, môžete zmluvu podľa čl. 9.2 ukončiť oznámením na [email protected] s okamžitou účinnosťou a bez sankcie.

V záložke „Podmienky“ uveďte, kde ste zverejnili informáciu pre zákazníkov podľa bodu 4.4 (informácia podľa Prílohy A vo vašich obchodných podmienkach, na webe a v softvéri v mieste aktivácie e-faktúry); pri existujúcich zmluvách najneskôr do 30 dní od oznámenia zmeny. Náš tím prezentáciu skontroluje (bod 4.5) a výsledok uvidíte v tej istej záložke.