Pro zprostředkovatele: partnerský model

Co má běžný multi-tenant účet

• Jeden API token pro všechny firmy účtu (hlavička X-Peppol-Participant-Id v SAPI-SK).
• Notifikační webhook nastavený u každé firmy zvlášť (GET/PUT /api/v1/companies/{id}/notifications) se stejným podpisem X-Verteco-Signature.
• Odregistraci vlastní firmy (POST /api/v1/companies/{id}/deregister) a přehled spotřeby po firmách (GET /api/v1/companies/usage).
• Firmy jsou vždy pod správou svého vlastníka, ne partnera: jednostranné odpojení klienta a brzda odesílání v běžném modelu nejsou.

Jak se stát zprostředkovatelem

Žádost vyplníte na stránce Staňte se digitálním pošťákem, tiskopis Finanční správě podepíšeme a podáme my. Poplatek je 99 € ročně bez DPH. Po zveřejnění ve výběru Finanční správy si vás klienti vybírají pod vaší značkou, jejich firmy vznikají pod vaším partnerským účtem automaticky a zapisují se do centrálního SMP, pokud jejich záznam nedrží jiný poskytovatel (tehdy dostanete událost company.smp_registered_elsewhere a postup s migračním kódem). V testovacím prostředí proběhne registrace zprostředkovatele bez poplatku a hned dostanete testovací partnerský endpoint.

• Staňte se digitálním pošťákem (žádost)
• Obchodní podmínky zprostředkování
• Naši zprostředkovatelé
• Klient od jiného poskytovatele: migrační kód (návod)
• Smlouvy: VOP, DPA, SLA, NDA

Pokud provozujete fakturační aplikaci, ERP nebo platformu a chcete přes nás napojit na Peppol více svých zákazníků (tenantů), integrujete se jednou a obsluhujete N firem. Model je proxy: váš backend drží jeden API token (vpt_…) jen na serveru (nikdy ne v prohlížeči) a každý váš tenant = jedna firma u nás (jeden token → N firem). Rozšířený veřejný návod se vzorovými kódy, webhook podpisy a go-live checklistem: peppol.verteco.digital/cs/saas.

Bezpečnost provozu pro vaše klienty: jsme certifikovaný poskytovatel Finanční správy SR (EFSK000031) s vlastním přístupovým bodem; certifikace ISO/IEC 27001:2022 probíhá u akreditovaného orgánu SKQS, s. r. o., Žilina (SNAS), vybraného v září 2026, certifikát plánujeme do 1. 7. 2027; OpenPeppol ho vyžaduje od všech poskytovatelů od 1. 10. 2027, zatím ho nemusí mít nikdo. Smlouvy (VOP, DPA, SLA, NDA) jsou v plném znění na /zmluvy, dostupnost na /status.

1. 1

   Jeden token, server-side

   Vytvořte si API token a držte ho v zabezpečeném prostředí backendu. Všechna volání dělá váš server (Bearer), ne prohlížeč zákazníka.
2. 2

   Onboarding tenanta = založení firmy

   Pro každého zákazníka POST /companies s jeho IČO/IČ DPH; vrátí { id, status: "pending_verification" }; id si uložte k tenantovi (detail viz 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

   Aktivace v Peppolu (krok zákazníka u státu)

   pending_verification ≠ živé v Peppolu. Aby firma přijímala, zákazník ji aktivuje výběrem poskytovatele na portálu Finanční správy (přihlášením přes eID nebo přihlašovacími údaji do portálu FS). Jste zapsaný zprostředkovatel: zákazník vybírá vaši značku přes váš výběrový odkaz (pole vpdsUrl v GET /api/v1/resellers/me), ne Verteco přímo, protože přímý výběr Verteco firmu z vašeho programu vyřadí (událost company.released_to_direct). FS pošle výběr na váš webhook, vy ho přeposíláte nám (kapitola FS webhook) a my firmu aktivujeme, zaregistrujeme do SMP a pošleme vám company.activated. Nejste zapsaný zprostředkovatel: zákazník zvolí jako poskytovatele Verteco a zbytek proběhne stejně. Ověřený výběr firmu zároveň oprávní odesílat. Pokud přímý výběr Verteco k nám nedorazil, záložní cestou je Ověření odesílání (POST /companies/{id}/verification). Pokud zákazník už měl jiného poskytovatele, po výběru se firma sice aktivuje, ale záznam v SMP drží starý pošťák a je třeba migrační kód: postup je v kapitole Klient přichází od jiného poskytovatele.
4. 4

   Příjem faktur: webhook per tenant

   Nastavte webhook (a/nebo e-mail) pro každou firmu a vyzvedněte 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 ověřování X-Verteco-Signature)

   Při přijaté faktuře vám přijde podepsaný POST (event invoice.received; stejně invoice.sent, invoice.delivered, invoice.rejected, invoice.undeliverable, invoice.reported, invoice.report_pending, invoice.report_rejected a company.* za všechny vaše klienty), durable s retry/dead-letter. Ověření podpisu, payload i tlačítko „Otestovat webhook“ viz Notifikace & webhooky.
5. 5

   Odeslání faktur

   Fakturu (UBL Peppol BIS 3.0) odešlete přes národní rozhraní SAPI-SK 1.0: POST /sapi/document/send (OAuth2 client_credentials, client_secret = váš vpt_ token). SK daňové hlášení (TDD/C5) doplníme automaticky.
6. 6

   Podklady pro přefakturaci

   GET /companies/usage?month=YYYY-MM vrátí počty odeslaných a přijatých dokladů za každou vaši firmu zvlášť i souhrnně, přesně v jednotkách, ve kterých je postaven ceník, takže si umíte svým klientům přefakturovat přímo z toho. Bez parametru vrátí aktuální měsíc; období je polouzavřené a v odpovědi jsou explicitně pole from/to, abyste nemuseli hádat hranici měsíce. Firmy bez provozu jsou v seznamu s nulami.
7. 7

   Škálování a robustnost

   Seznamy stránkujte: GET /companies?page&limit i GET /companies/{id}/documents?page&limit (s hlavičkami X-Total-Count a dalšími). Respektujte rate-limit na token: při hromadném onboardingu dávkujte s backoffem na 429 (Retry-After) a ošetřete 409 ico_taken (idempotentně).

Pokud jste zapsaný jako zprostředkovatel (žádost přes /sprostredkovatel/ziadost), Finanční správa posílá na vaši webhook URL notifikaci vždy, když si vás klient vybere na portálu VPDS. Tento manuál popisuje přesný kontrakt tak, jak ho FS reálně volá v produkci (ověřeno na živých výběrech). FS k webhookům vlastní veřejný manuál nevydává; toto je to, co k implementaci potřebujete.

1 · Jak notifikace vypadá + 2 · ověření pravosti

3 · Co s tím: přeposlat nám surové tělo

Zápis zprostředkovatele předpokládá vlastní systém, který výběry klientů přijme a přepošle nám. Naši adresu do tiskopisu FS nevkládejte: FS má volat vás. Pokud vlastní systém nemáte, nejste zprostředkovatel; správná cesta je registrační stránka s vaším označením a provize (/affiliate).

Doporučená (a nejjednodušší) implementace je raw-byte proxy: přijměte POST, odpovězte rychle a surové bajty těla přepošlete na váš registrační endpoint u nás. Ten vzniká automaticky po vyplnění formuláře /sprostredkovatel/ziadost, je aktivní hned a jeho přesnou URL (s vaším klíčem) vidíte po přihlášení přes GET /api/v1/resellers/me (pole webhookUrl):

POST https://peppol.verteco.digital/peppol/webhook/reseller/{vas-klic}
Content-Type: application/json
x-pds-secret: <nezměněná hodnota z požadavku FS>
(tělo = nezměněné surové bajty od FS)

My verification_token kryptograficky ověříme, firmu automaticky založíme pod vaším partnerským účtem (white-label), zaregistrujeme ji do centrálního SK SMP a od té chvíle jí doručujeme e-faktury. Vy si z payloadu můžete uložit kontaktní údaje pro vlastní onboarding; nic víc netřeba. Výjimka: pokud subjekt už měl jiného poskytovatele, záznam v SMP zůstává u něj a od nás dostanete událost company.smp_registered_elsewhere plus e-mail; jak to dořešit, popisuje samostatná kapitola. Událost company.client_registered_directly přijde, když si váš klient přidá svou firmu přímo v portálu Verteco: linked = true znamená, že jeho účet jsme připojili jako spoluvlastníka (kontaktní e-mail firmy se shodoval), false je jen informace o pokusu (nejvýše jednou denně); na vašem vztahu s klientem ani na fakturaci se nic nemění. Událost company.released_to_direct přijde, když si váš klient na portálu Finanční správy vybere Verteco přímo: firma tím opouští váš program (vaše účty ztrácejí přístup, white-label se ruší, kontakt z výběru je vlastník); klienta o tom informujeme z portálu a vám přijde i e-mail. Platí pro výběry od 21. 9. 2026. Opačný směr, výběr pod vaší značkou pro firmu, kterou váš partnerský účet už vlastní (například vaši vlastní firmu, kterou jste si přidali jako přímý zákazník), firmu nepřeregistruje: přístupový bod i záznam v centrálním SMP zůstávají stejné (opakovaná registrace je jen potvrzení), firma se jen přepne do režimu white-label, od té chvíle jí od nás nechodí e-maily o dokladech, dozvíte se o nich jen přes webhooky a API a účtuje se v partnerském modelu; archiv a nastavení zůstávají. Hodí se to na ověření integrace na vlastní firmě.

Transportní klíč (hlavička x-pds-secret): po zveřejnění zápisu pošle FS zip WebhookSecret_Verteco_<název>.zip e-mailem žadateli, tedy nám, a heslo k němu v SMS na telefonní číslo, které jste uvedli ve formuláři /sprostredkovatel/ziadost (tiskopis FS ze 17. 9. 2026 ho má v samostatném poli), tedy vám. Zip si stáhnete v konzoli pošťáka, záložka FS webhook (tlačítko Stáhnout zip od FS), otevřete ho heslem ze SMS a 32znakový klíč z textového souboru zadáte na tomtéž místě, kde si ho později i zobrazíte nebo stáhnete jako .txt (každé zobrazení se zapíše do auditu vašeho účtu). Pokud SMS nepřišla, napište nám. U zápisů podaných před 17. 9. 2026 přišlo heslo nám a klíč jsme uložili sami. Od uložení klíče ověřujeme, že podpis sha512(tělo + klíč) každého volání sedí. Dokud klíč není zadán, podpis jen zaznamenáváme. Při uložení klíč porovnáme s voláními, která FS na váš endpoint už poslala, a klíč, který s nimi nesedí, odmítneme; vaše proxy proto musí přeposílat tělo bajt po bajtu (bez re-serializace JSON). Klíč ukládáte v konzoli pošťáka na záložce FS webhook; endpoint PUT /api/v1/resellers/me/fs-secret přijímá jen přihlášenou relaci, ne API klíč.

3a · Co odpovídá náš endpoint

Volání zpracujeme hned (synchronně). Tělo odpovědi 200 záměrně neprozrazuje, zda byl token platný a zda se firma aktivovala, aby se endpoint nedal použít ke zjišťování, které DIČ je náš zákazník. Výsledek zpracování se dozvíte událostí company.activated na vašem notifikačním webhooku a kdykoli ho přečtete přes GET /api/v1/resellers/me/clients (stav active, vyplněné peppolParticipantId).

Pokud po odpovědi 200 do pár minut nepřijde company.activated, pošlete nám čas volání; každé volání máme v trvalém auditu.

3b · Ověření požadavku u vás před přeposláním

Doporučujeme, aby vaše proxy každý požadavek ověřila ještě před přeposláním. Tak nám posíláte jen pravé výběry FS a náhodná nebo podvržená volání nezabírají váš limit.

1. Nejprve uložte celý požadavek (surové tělo i hlavičky). FS výběr nezopakuje, uložená kopie je jediná cesta, jak ho obnovit.
2. Ověřte hlavičku x-pds-secret: musí se rovnat hex(SHA-512(surové bajty těla + váš klíč FS)), 128 hexadecimálních znaků. Hash počítejte z těla přesně tak, jak přišlo, ještě před parsováním JSON; klíč připojte hned za tělo bez oddělovače; porovnávejte v konstantním čase a bez ohledu na velká a malá písmena.
3. Přepošlete jen shodné požadavky, s nezměněným tělem a původní hlavičkou x-pds-secret. Těla nad 64 KB zahoďte, výběr FS má kolem 1 KB.

import crypto from 'node:crypto';

// rawBody = Buffer s tělem přesně tak, jak přišlo (např. 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));
}

Stejné ověření v PHP, Pythonu 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 těla přesně tak, jak přišly (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 těla přesně tak, jak přišly (ASP.NET Core: Request.Body zkopírujte do MemoryStream před čtení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));
}

• Klíč: je to tentýž klíč FS, kterým podpis ověřujeme my (ze zipu od FS, otevřeného heslem ze SMS); po zadání ho najdete v konzoli pošťáka, záložka FS webhook. Držte ho jen na serveru. Shoda u vás znamená shodu i u nás.
• Jiný mechanismus není: FS transport nepodepisuje asymetrickým klíčem a veřejný klíč k ověření hlavičky neexistuje. verification_token v těle je podpis FS nad DIČ; ten ověřujeme my vůči certifikátu FS, vy ho jen nezměněný přepošlete.
• Limit: 600 volání za minutu z jedné IP adresy platí pro každé volání na /peppol/webhook/…, platné i neplatné. Volání bez platné hlavičky u nás skončí 403 a nic se nezpracuje, spam by však spotřebovával limit vašeho serveru.
• Když podpis nesedí už při prvním reálném výběru, požadavek nezahazujte: uložte ho a napište nám, chybu najdeme společně.

4 · Provozní pravidla (důležité)

• Idempotence: tentýž subjekt může výběr zopakovat; zpracování stejného DIČ musí být bezpečné (u nás je).
• Když přeposlání selže (například 403 nebo výpadek vašeho serveru), FS výběr nezopakuje. Pošlete nám znovu uložené původní tělo s původní hlavičkou x-pds-secret; zpracování je idempotentní a firma se aktivuje. Pokud jste volání neuložili, napište nám.
• Zdrojová IP: volání chodí z infrastruktury FS (pozorováno z 194.1.2.13); IP allowlist doporučujeme jen jako doplněk, ne jako jedinou ochranu (rozsah FS negarantuje).
• Odpověď: vracejte 200 i při interní chybě zpracování (chybu si zalogujte); nic jiného FS nevyhodnotí.
• Pořadí nasazení: webhook musí být živý před podáním žádosti FS; první výběr může přijít krátce po zveřejnění.
• Odmítnutí výběru: nejste povinen přijmout každý výběr (bod 4.6 OP). Subjekt, jehož výběr nám nepřepošlete, bez zbytečného odkladu informujte (e-mail stačí), aby si mohl zvolit jiného poskytovatele; na portálu FS žádný krok odmítnutí není, nový výběr subjektu ten předchozí nahradí. Nepřeposlání není porušením bodu 4.1 písm. c OP.

Referenční implementace proxy má ~30 řádků (přijmi POST → ulož → přepošli surové bajty). Adresu si ověříte přes GET na váš registrační endpoint (odpověď ready). Testovací POST bez platné hlavičky x-pds-secret po uložení vašeho klíče dostane 403 a nic nezaloží; celý řetězec včetně aktivace firmy si vyzkoušíte v testovacím prostředí test.peppol.verteco.digital (simulovaný výběr na /register-vpds-test; zápis zprostředkovatele je tam bez poplatku a bez podání na FS, firma vytvořená přes POST /companies se tam aktivuje hned a simulovaný výběr dostanete na svůj webhook jako od FS). Otázky: Podpora.

5 · Ukončení smlouvy o zprostředkování

Smlouvu o zprostředkování je možné ukončit i přímo z prostředí aplikace: vlastník partnerského účtu v Nastavení pošťáka vyplní žádost o ukončení (kontrolní otázka + potvrzení důsledků) a výpověď potvrdí odkazem, který mu přijde e-mailem. Potvrzením je výpověď doručena; výpovědní doba je jeden měsíc a běží od 1. dne následujícího měsíce (čl. 7.1 obchodních podmínek zprostředkování). Žádost o výmaz ze seznamu zprostředkovatelů podáváme Finanční správě my do 5 pracovních dnů po zániku smlouvy (čl. 7.3); podklad dostane náš tým, klientům zprostředkovatele se nic neposílá. Nepotvrzenou žádost lze v aplikaci zrušit. Programově: GET/POST/DELETE /api/v1/resellers/me/termination.

6 · Jak je rozdělena odpovědnost

Shrnutí čl. 5 obchodních podmínek zprostředkování (v1.8), abyste věděli, co od vás v praxi očekáváme. Smluvní pokuta ani odpovědnost za škodu vám nevzniká ze samotného technického přenosu dokladu vašeho klienta a nejste povinen ověřovat hospodářskou realitu ani věcnou správnost jednotlivých dokladů (čl. 5.8). Výběr na portálu Finanční správy potvrzený eID nebo přihlašovacími údaji spolu s naším ověřeným Verifikačním údajem je dostatečným ověřením oprávnění jednat za firmu a poskytnutí přístupu k API vašim vlastním klientům není zpřístupněním přístupu třetí osobě (čl. 5.9). Smluvní pokuty mají strop 5 000 EUR na jednu událost nebo sérii porušení z jedné příčiny a 10 000 EUR za kalendářní rok (čl. 5.3). Sankce a opatření, které nám reálně uloží orgány nebo autority sítě Peppol za jednání ve vaší sféře, se nadále přenášejí bez stropu (čl. 5.2), protože je vůči Finanční správě a OpenPeppolu neseme bez omezení my; nárok se však poměrně snižuje o náš podíl, přikládáme k němu doklad a písemné vyčíslení, máte 15 dnů na vyjádření, zrušenou nebo sníženou sankci vám vrátíme do 15 dnů i bez výzvy a nároky vůči klientovi, který ji vyvolal, vám postoupíme i s podklady (čl. 5.5 a 5.7). Proto od vás čl. 4.1 písm. h) žádá přenést odpovídající povinnosti do smluv s klienty a vést záznamy o tom, kdo který doklad vytvořil; vzorové znění klauzule pošleme na požádání zdarma.

Partnerský notifikační webhook (zprostředkovatelé)

Pokud jste zapsaný zprostředkovatel, nemusíte nastavovat webhook u každé firmy zvlášť: jeden partnerský notifikační webhook dostává všechny události firem pod vaším partnerským účtem a má přednost před webhooky jednotlivých firem. Vaši klienti tedy nic nenastavují; firmu rozlišíte podle companyDic / peppolParticipantId.

E-maily o jednotlivých fakturách: partnerský účet je členem každé klientské firmy, takže by se standardním nastavením účtu dostával e-mail o každé přijaté faktuře každé z nich. White-label klientům e-maily neposíláme nikdy (kanál je webhook); u ostatních firem si je pro partnerský účet vypnete v Nastavení pošťáka → Notifikace (jedním přepínačem; totéž nastavení je i v Nastavení → Notifikace účtu).

// 200 OK (první nastavení)
{ "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 se počítá stejně jako u firemního webhooku (níže), jen s partnerským secretem.

Správa klientů přes API (jednostranné odpojení a brzda odesílání)

Klient, který od partnera odejde, zpravidla neudělá nic, proto jsou tyto operace jednostranné a nevyžadují žádnou součinnost klienta. Příjem faktur jimi není dotčen: je vázán na registraci firmy v centrálním SMP, ne na spravující účet.

Migrační kód pro klienta, který od vás přechází k jinému poskytovateli: API pro něj záměrně není, kód je živý klíč k zápisu klienta v síti. Vyžádá ho vlastník firmy po přihlášení, tedy váš partnerský účet, v detailu firmy na konci záložky Síť Peppol; kód vydá centrální SMP a do 24 hodin přijde na e-mail účtu, který o něj požádal (do té doby se žádost dá zrušit). Hromadně pro více klientů ho vydáme na váš pokyn e-mailem se seznamem DIČ. Pořadí je vždy: nejprve kód, potom odregistrace.

Klient, se kterým jste ukončili spolupráci: podle pravidel Peppol autority SR musí dosavadní poskytovatel firmu odregistrovat z centrálního SMP do 3 pracovních dnů od zániku smlouvy s klientem (bod 4.1 písm. g OP vyžaduje vaši bezodkladnou součinnost, bod 7.6 OP = odregistrace nejpozději do 3 pracovních dnů od vaší žádosti). Dokud firmu neuvolníte ani neodregistrujete, zůstává pod vaší značkou: doklady jí chodí, hlášení Finanční správě běží a měsíc s odeslaným dokladem nebo se zapnutým Archivem dat se účtuje. Uvolněnou firmu držíme jen kvůli příjmu dokladů; subjekt vyzveme, aby si zvolil poskytovatele nebo přijal naše VOP, a pokud do 30 dnů neudělá ani jedno, odregistrujeme ho (bod 7.6 OP). Klientovi, který jen neplatí a smlouvu s vámi má dál, žádná lhůta z OP neběží; zastavte mu odesílání přes pause-sending a rozhodněte o uvolnění nebo odregistraci.

Fakturační model partnera

V Nastavení pošťáka, záložka Fakturace (a přes GET/PUT /api/v1/resellers/me/billing) si volíte fakturační model (volba je dostupná jen zapsaným zprostředkovatelům): per_company = 2 € měsíčně za aktivně odesílající IČO, nebo per_document = 0,01 € za každou odeslanou fakturu vašich firem (přijaté doklady zdarma) s minimální měsíční fakturací 300 € + DPH; limit 1 000 dokladů měsíčně se při per_document neuplatňuje, každá odeslaná faktura se účtuje od první (dobropis je odeslaný doklad) a přijaté jsou zdarma bez limitu. Změna modelu platí vždy od 1. dne následujícího měsíce (v odpovědi pendingModel a pendingFrom); odpověď obou volání vrací i přepočet aktuálního měsíce pod modely, takže přepínáte informovaně.

Kalkulačka: který model vyjde při vašem počtu firem a dokladů levněji, včetně roční částky se zápisem a s DPH, si spočítáte na stránce /sprostredkovatel (sekce Kalkulačka).

Měsíční výpis spotřeby po klientech: GET /api/v1/resellers/me/usage?month=YYYY-MM (bez parametru předchozí měsíc) vrátí za každou firmu pod vaší značkou, kterou vlastní váš účet, počty odeslaných a přijatých dokladů, doklady nad limit 1 000 (odeslané a přijaté dohromady), částku v modelu A (2 € za firmu, která v měsíci odeslala doklad, plus 0,01 € za každý doklad nad limit; archiv se firmě pod vaší značkou nikdy neúčtuje) i v modelu B (0,01 € za odeslaný doklad), součty obou modelů s doplněním do minima 300 € v modelu B a model, který pro vás v daném měsíci platil (appliedModel); přímé firmy, jejichž je účet členem, platí ze svého kreditu a ve výpisu nejsou. Částky jsou v centech bez DPH, oceněné stejným způsobem jako měsíční vyúčtování, ale z aktuálního stavu firem v době čtení (závazné jsou položky vyúčtování ve vašem kreditu), a u firem nad limitem se liší od náhledu aktuálního měsíce v GET /resellers/me/billing, který počítá model A jako 2 € × aktivní firmy. S ?format=csv dostanete totéž jako soubor pro účetnictví (UTF-8 s BOM, oddělovač středník, slovenské hlavičky, částky s desetinnou čárkou, poslední řádek Spolu) a v konzoli pošťáka je výpis na záložce Spotřeba s výběrem posledních 12 měsíců.

Doporučený postup při ukončeném klientovi (strop nákladů na vaší straně): průběžný stav čerpání vidíte v GET /api/v1/companies/usage?month=YYYY-MM (rozpis sent/received po firmách přesně na přeúčtování) a v GET /api/v1/resellers/me/clients (počty za aktuální měsíc); o každém odeslaném i přijatém dokladu vašich firem navíc chodí událost na partnerský webhook, takže „ukončenou“ firmu zachytíte hned při prvním dokladu. Potom stačí zavolat pause-sending nebo release.

Doporučený tok pro vlastní portál nebo aplikaci partnera (podle otázek partnerů v říjnu 2026):

1. Kopie dokladů držte u sebe. Firmám pod vaší značkou je Archiv dat předvoleně vypnutý, takže obsah dokladu (XML, PDF) u nás zůstává 14 dní po doručení a potom se maže; důkazy o doručení (doručenka, časy, stav hlášení) zůstávají. Váš portál proto čte z vlastní kopie a od nás stahuje jen nové doklady.
2. Nové doklady přes webhook, ne dotazováním. Partnerský notifikační webhook (výše) dostane invoice.received za každou firmu; doklad stáhnete přes GET /sapi/document/receive/{id} (XML, PDF, HTML a přílohy mají vlastní cesty) a potvrdíte přes POST /sapi/document/receive/{id}/acknowledge. Záložní cesta je stránkované čtení GET /sapi/document/receive?status=received&limit=200 s pageToken (nejstarší první; potvrzené doklady z filtru vypadnou).
3. Stavy odeslaných dokladů chodí stejně webhookem (invoice.sent, invoice.delivered, invoice.rejected, invoice.undeliverable, invoice.reported) a jsou i na dotaz přes GET /sapi/document/sent.
4. Vlastní doména pro klienty. Vaše aplikace může naše API volat přes vlastní můstek (například api.vase-domena.cz) jedním partnerským klíčem pro všechny firmy pod vaším účtem; klienti naši adresu nepotřebují a webhooky jim přeposíláte z vaší strany.
5. Limity. 300 volání za minutu na API klíč, hlavičky RateLimit-* vracejí zůstatek; vyšší limit nastavíme na požádání. Limit 1 000 dokladů měsíčně na IČO platí v modelu A (odeslané a přijaté dohromady, každý další doklad 0,01 €); v modelu B se neuplatňuje.

Který model úplaty: model B (0,01 € za odeslaný doklad, minimum 300 € měsíčně, přijaté zdarma) je levnější než model A (2 € za každé IČO, které v měsíci odeslalo doklad) tehdy, když v měsíci odesílá více než 150 IČO a na jedno odesílající IČO připadá v průměru méně než 200 odeslaných dokladů (150 IČO = do 30 000 dokladů, 300 IČO = do 60 000); model měníte v konzoli pošťáka s účinností od následujícího měsíce.

Archiv dat klienta přes partnerské API: pokud má váš portál klientovi archiv zapnout nebo vypnout, nemusí ho posílat do našeho portálu.

Co zapnutý archiv znamená pro cenu firmy pod vaší značkou, přesně podle kódu vyúčtování: zapnutý Archiv dat firmě pod značkou zprostředkovatele nikdy nespustí základ 2 €, takže v modelu A platíte 2 € jen za měsíc, v němž firma odeslala doklad, plus 0,01 € za každý doklad nad 1 000 (odeslané a přijaté dohromady), a v modelu B 0,01 € za odeslaný doklad; zapnutí archivu tedy mění jen to, jak dlouho držíme originály (po dobu trvání smlouvy namísto lhůty), ne částku. Úložiště se měří jednou za noc a upozornění při 80 % a při dalším započatém GB chodí na kontaktní e-mail partnera (náhradně na e-mail vlastníka zápisu), nikdy klientovi; měsíční vyúčtování položku za úložiště neobsahuje. Pole archiveReceived, archiveSent, wipeDaysReceived, wipeDaysSent a storageUsedBytes vidíte u každé firmy i v GET /resellers/me/clients.

Slovensko má jeden centrální SMP pro všechny pošťáky a každý účastník má v něm jeden záznam. Když si váš klient zvolí vaši značku na portálu Finanční správy, my ho ověříme a aktivujeme, ale pokud jeho záznam už drží předchozí poskytovatel, síť dál doručuje jemu. Přepnutí dělá jednorázový migrační kód, který klientovi vydá dosavadní pošťák (standardní mechanismus SML, FAQ FS příklad 46; podle pravidel PA SK musí původní pošťák klienta po skončení smlouvy do 3 pracovních dnů z centrálního SMP odregistrovat). Pozor: podle FAQ FS (příklady 36 a 73) může klient přijímat u jiného pošťáka a přes vás jen odesílat; pokud je to jeho záměr, zavolejte PUT /resellers/me/clients/{id}/receiving-provider s elsewhere=true (stav smpState = "external") a připomínky i automatická registrace přestanou. Tato kapitola je návod, jak tuto situaci ve vaší platformě rozpoznat, uložit, vyřešit a co od nás přitom dostanete.

1. 1

   Připravte si přijímač: partnerský webhook

   Jeden webhook pro všechny vaše klienty nastavíte přes PUT /resellers/me/notification-webhook (výše). Ověřte podpis X-Verteco-Signature a zpracujte událost company.smp_registered_elsewhere: znamená „záznam drží jiný poskytovatel, potřebný migrační kód“. Deduplikujte podle companyId + event; událost se opakuje jednou týdně, dokud 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: kdy se ptát a co číst

   Webhook může chybět (ještě jste ho nenastavili) nebo ho ztratíte při výpadku, proto stav i čtěte: GET /resellers/me/clients vrací u každé firmy smpRegistered a smpState; detail dá GET /companies/{id}. Doporučený rytmus: jednou denně pro všechny klienty, při otevření klientské stránky ve vaší aplikaci a 2 až 3 minuty po události company.activated (registrace v SMP proběhne obvykle do minuty). Před založením klienta se vyplatí GET /public/peppol-check?id=0245:<DIČ>: pokud je DIČ už v síti, klient bude potřebovat kód a umíte mu to říct dopředu.

   smpState	Význam	Co udělat
   registered	Záznam v SMP je pod naším účtem, síť doručuje k nám.	Nic, klient přijímá.
   pending	Registrace běží (sekundy, při výpadku SMP až hodiny; opakujeme automaticky).	Počkat, znovu přečíst za pár minut.
   elsewhere	Záznam drží jiný poskytovatel; klient potřebuje migrační kód.	Zobrazit klientovi výzvu, získat kód, zavolat smp-migrate (krok 4).
   rejected	FS verifikační token byl odmítnut.	Klient musí výběr na portálu FS zopakovat.
   null	Nevztahuje se (firma ještě není ověřena výběrem na FS).	Dovést klienta k výběru na portálu FS.

3. 3

   Uložte si stav u sebe

   Ke každému klientovi si držte companyId, peppolParticipantId, smpState, smpStateAt (kdy jste ho naposledy viděli) a noticeShownAt (kdy jste klienta upozornili). Při elsewhere zobrazte klientovi ve vaší aplikaci trvalé upozornění s polem na vložení kódu; odesílání neblokujte, firma odesílat smí. Při registered upozornění zrušte.

   textKopírovať

   // zpracování události ve vašem backendu (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žádejte si migrační kód od dosavadního poskytovatele")   // + 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ískejte kód a převezměte záznam

   Klient si vyžádá u dosavadního poskytovatele migrační kód (SMP migration code) pro své DIČ; kód je jednorázový a časově omezený, použijte ho hned. Zavolejte POST /companies/{companyId}/smp-migrate vaším partnerským tokenem (jste vlastníkem firmy). Odpověď 200 nese firmu se smpRegistered = true, síť se přepne okamžitě a bez výpadku; samostatná událost se neposílá, stav si zapište z odpovědi nebo znovu přečtěte přes 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	Co udělat
   400 migration_code_rejected	Kód je neplatný, použitý nebo vypršel.	Vyžádat od starého poskytovatele nový kód.
   409 registered_elsewhere	SMP kód nepřijalo, záznam stále drží jiný poskytovatel.	Ověřit, že kód patří k tomuto DIČ; zkusit s novým kódem.
   403 company_not_verified	Firma ještě není ověřena výběrem na FS.	Nejprve výběr na portálu FS.
   503 smp_unavailable	Centrální SMP neodpovídá.	Zopakovat za pár minut (kód zůstává platný).

5. 5

   Co vám posíláme my

   Při zjištění pošleme e-mail na kontaktní adresu partnera (ze zápisu zprostředkovatele) s DIČ, Peppol ID a postupem, potom jednou týdně, dokud převzetí neproběhne (nejvýše čtyřikrát); stejná informace jde webhookem. Klientovi white-label firmy nepíšeme. Pokud kód dostanete vy, ale nechcete volat API, pošlete ho na peppol​@​verteco.digital a převzetí provedeme z administrace.

   Text pro klienta, který můžete převzít:

   Vaše firma je u nás už aktivována, ale záznam v národním registru Peppol (SMP) stále drží váš předchozí poskytovatel, takže e-faktury vám zatím chodí k němu. Vyžádejte si u něj migrační kód (SMP migration code) pro DIČ … a vložte ho sem. Přepnutí je okamžité a bez výpadku.

Pokud po čase přejdete od nás k jinému certifikovanému poskytovateli, vaši klienti jdou s vámi. Technický převod registrací zvládneme hromadně a bez výpadku; jeden krok však určuje Finanční správa, ne my, a platí stejně pro každého poskytovatele na Slovensku. Svoboda odejít je záruka, ne scénář, se kterým počítáme: garance pro partnery (poplatek za zápis dorovnáme až na nulu, roční cena za doklady o 10 % nižší než v předložené nabídce) platí po celou dobu spolupráce, takže důvod odcházet u nás nevzniká.

1. 1

   Výpověď z konzole

   V Nastavení pošťáka podáte výpověď a potvrdíte ji odkazem z e-mailu; doba je jeden měsíc od 1. dne následujícího měsíce (čl. 7.1). Do zániku smlouvy běží všechno jako dosud.
2. 2

   Migrační kódy hromadně

   Pošlete nám seznam DIČ svých klientů. Kódy z centrálního SMP vydáme najednou pro všechny (ne po jednom přes portál) a předáme vám je pro nového poskytovatele. Alternativně klienty v zákonné lhůtě 3 pracovních dnů po zániku smlouvy odregistrujeme (pravidla PA SK).
3. 3

   Převzetí v SMP bez výpadku

   Nový poskytovatel zaregistruje každého klienta ve svém SMP s migračním kódem; SML přepíše vazbu okamžitě a náš záznam přejde na „Unpublished“. Doklady po celou dobu chodí bez přerušení: na Slovensku má každý subjekt jeden záznam v SMP pro příjem, odesílat však může přes více poskytovatelů, takže nový poskytovatel může za klienta odesílat hned, jak má jeho verifikační údaj, i dříve, než převezme příjem.
4. 4

   Výběr nového poskytovatele na portálu Finanční správy

   Verifikační údaj, který FS vydá při výběru poskytovatele, je její podpis nad dvojicí DIČ poskytovatele a DIČ klienta, tedy je vázán na konkrétního poskytovatele. Centrální SMP ho vyžaduje při každé registraci slovenského účastníka, i s migračním kódem. Nový poskytovatel proto potřebuje verifikační údaj vydaný pro sebe a ten vzniká jen výběrem na portálu FS: přihlášením přes eID nebo přihlašovacími údaji do portálu FS, udělat ho může i osoba s autorizací (například účetní). Je to stejná autorizace (plná moc), na jejímž základě se podává přiznání k DPH a kontrolní výkaz, a stejný úkon jako při prvním výběru. Migrační kód řeší výpadek a čekání na deregistraci, výběr na FS nenahrazuje.
5. 5

   Export dat

   Na požádání vám hromadně exportujeme originální XML dokladů, doručenky a metadata, která v době zániku uchováváme; neodstraníme je dříve než 90 dnů po zániku smlouvy nebo do potvrzení exportu (čl. 7.4).

Smluvní základ: čl. 7.1, 7.3 a 7.4 obchodních podmínek zprostředkování. Opačný směr (klient přichází od jiného poskytovatele) je v předchozí kapitole.

Finanční správa o vás jako o zprostředkovateli eviduje údaje z tiskopisu, který jsme za vás podali (obchodní jméno, sídlo, IČO, DIČ, kontaktní osoba, e-mail, telefon, web, adresa vašeho webhooku). Změnu nepíšete e-mailem: v konzoli pošťáka otevřete záložku Údaje u FS, zapište nové hodnoty vedle aktuálních, ostatní nechte tak a potvrďte všechny změny najednou. My pošleme na peppol​@​financnasprava.sk žádost podepsanou jednatelem Verteco spolu s aktualizovaným tiskopisem a o výsledku vás informujeme e-mailem (vlastníka účtu i kontaktní adresu).

V seznamu a ve výběru Finanční správy vystupujete pod obchodním jménem právnické osoby z tiskopisu; název produktu tiskopis nezná. Značku, web a popis služby vyplníte v konzoli pošťáka na záložce Informace a tak vás zobrazíme na /partneri a /nasi-sprostredkovatelia (značka velkým písmem, obchodní jméno pod ní); karta existuje ode dne podání žádosti.

Žádosti odcházejí v pracovních dnech mezi 8:00 a 16:00 (slovenské svátky vyjímáme), vždy nejdříve 2 hodiny po podání; do té doby (a mimo okno až do nejbližšího odeslání) žádost čeká a můžete ji zrušit. Změnu obchodního jména, sídla nebo země nejprve ověří náš tým (podklad, například výpis z rejstříku) a odešle ji až po ověření. Platí jedna žádost za 48 hodin a vždy jen jedna otevřená (čekající nebo předaná FS) najednou, proto do ní dejte všechny změny. Přes API totéž: GET /resellers/me/fs-registration (aktuální hodnoty, otevřená žádost, historie, okno odeslání), POST /resellers/me/fs-change-requests s changes, note a confirm: true (429 s Retry-After během 48 h), DELETE /resellers/me/fs-change-requests/{id} dokud žádost čeká.

Změny Obchodních podmínek zprostředkování doručovací služby zveřejňujeme na stránce podmínek (i jako PDF) a oznamujeme e-mailem vlastníkovi účtu a kontaktní osobě. Podle čl. 9.1 nevyžadují váš souhlas a platí ode dne zveřejnění; konzole pošťáka na ně neupozorňuje ani nic neblokuje. Pokud se změnou nesouhlasíte, můžete smlouvu podle čl. 9.2 ukončit oznámením na [email protected] s okamžitou účinností a bez sankce.

V záložce „Podmínky“ uveďte, kde jste zveřejnili informaci pro zákazníky podle bodu 4.4 (informace podle Přílohy A ve vašich obchodních podmínkách, na webu a v softwaru v místě aktivace e-faktury); u stávajících smluv nejpozději do 30 dnů od oznámení změny. Náš tým prezentaci zkontroluje (bod 4.5) a výsledek uvidíte v téže záložce.