Od sandboxu po produkciu

Pripojenie ďalšej firmy

Dokončíte pripojenie jednej klientskej firmy k svojmu partnerskému prístupu — cez portál alebo cez API — a overíte, že prístup naozaj vznikol.

• Aktívna partnerská autorizácia a partnerský kľúč (portal alebo sk_int_* podľa prostredia).
• Presné IČO alebo DIČ klientskej firmy a osoba, ktorá je jej vlastníkom alebo správcom.
• Rozhodnutie, kto platí API spotrebu: firma alebo vy ako integrátor.

White label na pripojenie firmy nepotrebujete

Jeden partnerský prístup obslúži aj viac klientskych firiem. Každá firma vám však musí samostatne povoliť prístup a vy musíte vedieť, kto platí API spotrebu.

Partnerský kľúč identifikuje vás. Sám osebe vám nedáva prístup k ľubovoľnej firme — ten vzniká až potvrdeným súhlasom.

Postup cez partnerský portál

1. 1

   Prihláste sa do správneho prostredia

   Rozlíšte DEV a produkciu ešte pred vytvorením pozvánky. Testovacia väzba v DEV neplatí v produkcii.

2. 2

   Otvorte Súhlasy klientov

   Panel „Pripojiť ďalšiu firmu“ nájdete v časti so súhlasmi. Ak ho nevidíte, partnerský prístup ešte nie je aktivovaný alebo nemá potrebné oprávnenie.

3. 3

   Zadajte presné IČO alebo DIČ

   Zhoda musí byť presná. Pri zhode samotného DIČ nevzniká vlastníctvo ani automatické práva k existujúcemu účtu.

4. 4

   Zvoľte režim a platiteľa

   Technická delegácia znamená, že firma platí svoju API spotrebu. Spravovaná služba znamená, že ju platí integrátor.

5. 5

   Zvoľte rozhranie a najmenší rozsah

   Voľba odosielania nie je pokyn na zmenu prijímajúceho poštára. Pridajte len tie oprávnenia, ktoré naozaj potrebujete.

6. 6

   Doručte odkaz a nechajte ho potvrdiť

   Odkaz doručte vlastným kanálom a nechajte ho potvrdiť vlastníkom alebo správcom firmy. Vytvorenie odkazu samo neposiela e-mail.

7. 7

   Overte súhlas aj aktiváciu

   Súhlas je len prvý krok. Pred odosielaním overte, že firma má v zvolenom rozhraní prístup a správny firemný kontext.

Postup cez verejné consent API

• Volajúci kľúč aj JWT musia mať firms:manage a všetky požadované oprávnenia; telo musí obsahovať aspoň jedno documents:* oprávnenie.
• POST nie je idempotentný. Pri timeoute alebo neistej odpovedi ho neopakujte naslepo; customerReference nie je idempotency key.
• Voliteľné returnUrl: https adresa, ktorej origin je registrovaný pre partnera (inak VALIDATION_ERROR). Po potvrdení sa klient vráti do vášho programu.
• Pri technickej delegácii klient jedným potvrdením udelí súhlas aj objedná vlastné API. Ak ešte nevybral ePošťák na portáli Finančnej správy, GET vráti nextAction select_provider_on_pfs (awaitingPfs) a odkaz ostáva platný 14 dní.
• Webhooky consent.accepted, consent.revoked, consent.expired, consent.declined (firma žiadosť odmietla, nextAction contact_client), consent.awaiting_pfs a consent.scopes_updated (spolu s nextAction a clientMessage) prichádzajú na endpoint z PUT /api/v1/onboarding-requests/webhook, každá zmena stavu najviac raz.
• GET /api/v1/consent-offers/{offerId} vráti stav, ale nikdy nezopakuje stratený consentUrl.
• Verejný POST nevytvára firmu, neregistruje ju do SMP, neudeľuje súhlas a neposiela e-mail.

curl -X POST "https://epostak.sk/api/v1/consent-offers" \
  -H "Authorization: Bearer <PARTNERSKY_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "targetIdentifierType": "dic",
    "targetIdentifier": "<DIC_TESTOVACEJ_FIRMY>",
    "customerReference": "erp-klient-42",
    "integrationPath": "sapi",
    "relationshipMode": "technical_delegation",
    "scopes": ["firms:manage", "documents:send"]
  }'

{
  "id": "3f4f0b7e-0a8d-4c39-9d0f-1a2b3c4d5e6f",
  "status": "required",
  "consentUrl": "https://epostak.sk/d/consent/<JEDNORAZOVY_TOKEN>"
}

Očakávaný výsledok a chyby

Firma má potvrdený súhlas a prístup v zvolenom rozhraní. V GET odpovedi vidíte stav active, nie iba required.

• Pozvánky a súhlas
• Firemný kontext
• Autentifikácia

• Tlačidlo alebo panel chýba: partnerský prístup nie je aktivovaný, alebo kľúč nemá firms:manage.
• Odkaz expiroval alebo bol zrušený: vytvorte nový pozvánkový odkaz. GET starý consentUrl nevráti.
• Súhlas je revoked alebo prístup nefunguje: firma musí súhlas obnoviť novým odkazom; starý súhlas sa neoživuje.
• Nesprávna firma: nesnažte sa to opraviť zmenou identifikátora v existujúcej pozvánke, vytvorte novú pre správnu firmu.

Pozvánky a súhlas

Prejdete celý životný cyklus jedného súhlasu: vytvorenie, doručenie, potvrdenie, kontrola stavu a odvolanie.

• Rozhodnutý režim spolupráce a platiteľ API spotreby.
• Bezpečné miesto na uloženie id pozvánky a jednorazového consentUrl.

Čo znamenajú stavy

Odkaz na súhlas je tajomstvo

• consentUrl patrí oprávnenej osobe firmy, nie logom, analytike ani verejným príkladom.
• Portálové akcie pre vlastníka nie sú verejné API; externému integrátorovi neodporúčajte interné cesty.

Odvolanie súhlasu

Po odvolaní prestanú platiť nové volania tohto partnera pre túto firmu. Existujúce Peppol registrácie, iné poverenia ani už doručené doklady sa nemenia.

Očakávaný výsledok a chyby

Vidíte stav active pre správnu firmu a partnera a viete, čo presne sa zmení po odvolaní.

• Firemný kontext
• Technický partner
• Odvolanie prístupu

• 403 pri práci s firmou: chýba firms:manage alebo požadované documents:* oprávnenie.
• Odkaz potvrdila nesprávna osoba: súhlas sa nedá preniesť, vytvorte novú pozvánku pre firmu.

Technický partner

Nastavíte režim, v ktorom každá klientská firma platí vlastnú API spotrebu a vy máte delegovaný prístup.

• Partnerská autorizácia pre technickú delegáciu (nie iba pre spravovanú službu).
• Firmy, ktoré sú ochotné objednať si API a platiť ju priamo.

Čo technická delegácia znamená

• Firma vystupuje ako účastník a platiteľ svojej API spotreby; vy spracúvate jej dokumenty v jej mene.
• Pri technickej delegácii firma na jednej stránke jedným potvrdením udelí rozsah aj objedná vlastné API (štandardné podmienky, aktivuje sa hneď); bez jej potvrdenia prístup nevzniká. Ak už objednávku má, iba udelí súhlas.
• Nejde o white label. Vaša značka sa nemení a vy nedržíte klientske faktúry za API spotrebu.

Ako režim nastaviť

1. 1

   Vytvorte pozvánku v režime technickej delegácie

   V portáli zvoľte režim spolupráce a platiteľa API = Firma; cez API pošlite relationshipMode: "technical_delegation".

2. 2

   Nechajte firmu potvrdiť rozsah

   Oprávnená osoba potvrdí firmu, partnera, rozhranie a oprávnenia.

3. 3

   Overte aktiváciu pred odosielaním

   Súhlas samo nie je aktivácia. Overte stav aj prístup v zvolenom rozhraní.

Očakávaný výsledok a chyby

Firma má vlastnú API objednávku a vy máte delegovaný prístup k jej dokumentom v dohodnutom rozsahu.

• Spravovaný integrátor
• Pripojenie ďalšej firmy
• Produkčná aktivácia

• Firma odmietne objednávku: prístup nevznikne, nedá sa obísť partnerským kľúčom.
• Zvolené rozhranie nie je pre firmu povolené: aktivácia konkrétneho rozhrania je samostatný krok, ktorý treba dokončiť.

Spravovaný integrátor

Nastavíte režim, v ktorom vy spravujete schválené klientske firmy a platíte agregovanú API spotrebu.

• Aktívna integrátorská autorizácia a fakturačný účet na vašej strane.
• Súhlas každej klientskej firmy s tým, že jej dokumenty spracúvate vy.

Čo spravovaná služba znamená

• Vy ste fakturačný zákazník za API spotrebu klientskych firiem; firmy platia vám, nie ePošťákovi.
• Za spravovanú službu sa nepovažuje white label. Značka poskytovateľa sa nemení a nie je to podmienka na prácu s viacerými firmami.
• Súhlas každej firmy je stále povinný; agregovaná platba ho nenahrádza.

Čo si strážiť

• Rozsah oprávnení držte na minime potrebnom pre konkrétnu firmu.
• Firemný kontext volania musí vždy ukazovať na oprávnenú klientsku firmu.
• Pri odchode firmy použite odvolanie prístupu; nezasahuje do iných poverení ani do Peppol registrácie.

Očakávaný výsledok a chyby

Klientske firmy majú prístup cez váš integrátorský účet a API spotrebu fakturuje ePošťák vám.

• White label
• Pripojenie ďalšej firmy
• Produkčná aktivácia

• Firma nesúhlasí s delegovaním: použite technickú delegáciu, kde platiteľom zostáva firma.
• Firma žiada vlastnú značku poskytovateľa: to je samostatná white-label cesta, nie spravovaná služba.

Enterprise firmy

Spravujete firemný kontext v Enterprise API a držíte izoláciu medzi klientskymi firmami.

• Enterprise oprávnenie firms:manage.
• Prehľad, ktoré firmy máte oprávnené obsluhovať a akým režimom.

Firemný kontext volania

• GET /api/v1/firms vracia firmy, ku ktorým má váš prístup oprávnenie.
• Pri operáciách v mene konkrétnej firmy použite X-Firm-Id len na endpointoch, ktoré ho podporujú.
• Nikdy nepoužívajte identifikátor cudzej firmy; izolácia firiem je súčasť kontraktu.

Režimy spolupráce

Očakávaný výsledok a chyby

Každé volanie má správny firemný kontext a vy viete, ktorý režim a platiteľ za firmou stojí.

• Firemný kontext
• Enterprise webhooky
• Odvolanie prístupu

• Firma chýba v zozname: prístup nie je udelený alebo je odvolaný.
• Volanie v mene firmy vracia 403: chýba X-Firm-Id alebo oprávnenie pre danú firmu.

Sandbox

Získate vlastný sandbox, otestujete odoslanie na testovacie protistrany a budete vedieť, čo sandbox naozaj overí a čo sa v produkcii zmení.

• Rozhodnuté rozhranie (SAPI, Connector alebo Enterprise API), ktoré chcete testovať.

Ako získať sandbox

Žiadosť vyplníte na https://dev.epostak.sk/dev. Prístup pripravíme v pracovný deň do 4 hodín, príde e-mailom. Prihlásite sa na https://dev.epostak.sk/integrator, kde nájdete integrátorský účet a dve testovacie firmy, už prepojené. Vlastný API kľúč si vytvoríte v portáli. Verejné demo účty nájdete v dokumentácii v časti Demo účty; zdieľajú ich všetci, preto v nich nenechávajte dôverné údaje a na vlastné testy používajte svoje firmy.

Testovacie protistrany (boty)

Doklady posielajte týmto príjemcom. Každý je firma ePošťáka v testovacej sieti Peppol a na každý doklad odpovie pevným výsledkom cez normálnu AS4 cestu. Nevymýšľajte si vlastné Peppol ID: príjemca, ktorého nie je v testovacej sieti, odoslanie odmietne.

Scenáre cez API

Scenárové API spustí jeden z výsledkov na skutočnej odosielacej ceste: vygeneruje faktúru Peppol BIS 3 z vašej testovacej firmy a pošle ju príslušnej protistrane. Doklad potom vidíte v GET /api/v1/documents/{id}/status, v udalostiach a vo webhookoch ako pri bežnom odoslaní. Existuje iba na dev.epostak.sk; na produkcii vráti 404.

1. 1

   1. Získajte token

   Vymeňte svoj sk_int_* kľúč za JWT cez POST https://dev.epostak.sk/api/v1/auth/token (grant_type=client_credentials, client_id a client_secret zo stránky Začíname). Kľúč a token musia mať oprávnenie documents:send. Prihlásenie do portálu (session) tu nestačí, potrebný je bearer token.

2. 2

   2. Uveďte firmu

   Hlavička X-Firm-Id je povinná a musí byť jedna z vašich prepojených testovacích firiem s platným súhlasom. Iná alebo neprepojená firma vráti 403.

3. 3

   3. Spustite a sledujte beh

   POST /api/sandbox/v1/scenarios s telom {"scenario": "<id>"} vráti 202 s run_id, document_id, status a status_url. Stav behu čítate cez GET /api/sandbox/v1/scenarios/{run_id}: z pending a running prejde na completed (výsledok zodpovedá scenáru) alebo failed s textom chyby. Limit je 60 spustení za hodinu na jeden kľúč. GET /api/sandbox/v1/scenarios vráti zoznam scenárov.

curl -sS -X POST https://dev.epostak.sk/api/sandbox/v1/scenarios \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Firm-Id: <firm-uuid>" \
  -H "Content-Type: application/json" \
  -d '{"scenario":"rejected"}'

{
  "run_id": "<run-uuid>",
  "scenario": "rejected",
  "document_id": "<document-uuid>",
  "status": "running",
  "status_url": "/api/sandbox/v1/scenarios/<run-uuid>"
}

Pravidlá testovania

• DEV a produkcia majú oddelené kľúče, identity aj callbacky; DEV hodnoty sa do produkcie neprenášajú.
• Odoslanie testujte na testovacích protistranách, najprv na „ePošťák Test – Prijaté“ (0245:4188071545). Doklad sám sebe (rovnaké Peppol ID odosielateľa aj príjemcu) odmietne DEV rovnako ako produkcia.
• Úspech v portáli doplňte dôkazom zo svojho systému; portál sám nie je dôkaz integrácie.

Sandbox vs produkcia

Očakávaný výsledok a chyby

Máte jasno, ktoré prostredie používate, aké má limity a kedy je výsledok skutočným dôkazom vašej integrácie.

• Autentifikácia
• Produkčná aktivácia
• Iba odosielanie

• Volanie v DEV vracia produkčné údaje: máte pomiešané prostredia — skontrolujte base URL a kľúč.
• Testovacia firma neexistuje alebo scenár vráti 403: sandbox pripravíme po žiadosti na dev.epostak.sk/dev; X-Firm-Id musí byť jedna z prepojených firiem z portálu.
• 422 SELF_ADDRESSED_SEND (SAPI-DOC-042): príjemca je tá istá firma ako odosielateľ — pošlite doklad testovacej protistrane z tabuľky vyššie.

Produkčná aktivácia

Dokončíte prechod z testovacieho prostredia do produkcie vrátane objednávky, schválenia a prvého reálneho dokladu.

• Odskúšaná integrácia v sandboxe vrátane spracovania chýb.
• Oprávnená osoba firmy, ktorá môže potvrdiť objednávku a podmienky.

Čo sa prenáša a čo vzniká nanovo

Postup aktivácie

1. 1

   Dokončite objednávku

   Objednávku potvrdzuje oprávnená osoba; cena, záväzok a platiteľ musia byť viditeľné pred potvrdením.

2. 2

   Počkajte na schválenie

   Aktivácia nie je okamžitá. Stav overte predtým, než začnete posielať.

3. 3

   Vytvorte produkčné prístupy

   Nový kľúč a nový JWT pre produkciu. DEV hodnoty nepoužívajte.

4. 4

   Pošlite prvý produkčný doklad

   Overte prijatie odpovede, stav dokumentu a potvrdenie na strane príjemcu, ak je dostupné.

Očakávaný výsledok a chyby

Produkčné volanie vracia úspešnú odpoveď a stav dokumentu zodpovedá realite, nie iba testovaciemu prostrediu.

• Stavy dokumentov
• Idempotencia
• Diagnostika chýb

• 401 alebo 403 v produkcii: používate DEV kľúč, alebo firma ešte nie je aktivovaná.
• Firma nevidí svoje doklady: skontrolujte firemný kontext volania, nie oprávnenie partnera.

Iba odosielanie

Prejdete celý send-only onboarding: partner vytvorí požiadavku, firma vyberie ePošťák na portáli Finančnej správy a potvrdí prepojenie, príjem zostáva u pôvodného poskytovateľa a firma nepotrebuje nový účet ani kľúč.

• Firma má prijímaciu službu u existujúceho poskytovateľa a nechce ju meniť.
• Partner má platnú produkčnú zmluvu, ktorá pokrýva Enterprise API (technický partner alebo spravovaný integrátor), a kľúč s oprávnením firms:manage. Samostatné povolenie od ePošťáka netreba. Priama zmluva firmy, ktorá API používa iba sama pre seba, neoprávňuje pripájať iné firmy.

Čo táto cesta je a čo nie je

• Firma vznikne s lokálnou identitou, zmluvnou evidenciou a API oprávnením — nevzniká používateľ, heslo ani dashboardové členstvo.
• Príjem sa nemení. Send-only vetva nevykonáva registráciu, migráciu ani odregistráciu v SMP.
• Overtoken nie je súčasťou tejto cesty; patrí k white-label onboardingu.

Kto čo robí v jednotlivých krokoch

Postup krok za krokom

1. 1

   1. Partner vytvorí jednu onboardingovú požiadavku

   POST /api/v1/onboarding-requests so serviceMode: send_only, relationshipMode a customerRef. Vyžaduje neobmedzený partnerský kľúč, firms:manage a Idempotency-Key.

2. 2

   2. Autoritatívne podanie spustí pozvánku

   Firma na portáli Finančnej správy vyberie ePošťák ako poštára na odosielanie. Váš digitálny poštár na príjem faktúr sa nemení. Výber ePošťáka na portáli Finančnej správy používame výlučne na overenie, že ste oprávnený daňový subjekt používať dané Peppol ID. Po autentifikovanom podaní PFS dostane odkaz kontakt uvedený pri overení, nie kontakt z API požiadavky. E-mail z requestu nie je dôkaz identity. Žiadosť prejde do action_required a partner dostane onboarding.pfs_received.

3. 3

   3. Firma potvrdí jedno prepojenie

   Na jednej obrazovke vidí firmu, konkrétneho partnera, odosielanie, platiteľa a podmienky. Tlačidlo Potvrdiť a prepojiť zaznamená výslovný súhlas (onboarding.signed). Štandardná objednávka podľa cenníka sa aktivuje hneď (onboarding.active); neštandardná ostane v stave activating na posúdenie ePošťákom (onboarding.review_required). Pri managed_service platí partner a prepojenie sa aktivuje v rámci jeho zmluvy.

4. 4

   4. Partner vytvorí kľúč viazaný na firmu

   Až stav active (alebo webhook onboarding.active) sprístupní firmId. Potom vytvorte kľúč s scopedFirmId a oprávneniami documents:send a documents:read. Rodičovský kľúč potrebuje keys:manage aj požadované oprávnenia a vytváranie kľúčov musí byť prevádzkovo povolené. Kľúč sa nikdy nevracia v onboardingovej odpovedi. Pri programe nainštalovanom u zákazníka kľúč nastaví dodávateľ programu; zákazník nič negeneruje ani nevkladá.

5. 5

   5. Odošlite prvý doklad a overte stav

   Použite firemný kontext konkrétnej firmy. Prijímanie dokladov zostáva zakázané; overte stav dokumentu a dostupný dôkaz odoslania.

Stavy, ďalší krok a text pre firmu

Každá odpoveď aj webhook nesie nextAction a clientMessage { sk, en }. Text clientMessage môže program zobraziť firme bez vlastnej formulácie.

Webhooky onboarding.*

Partner si nastaví jeden webhook cez PUT /api/v1/onboarding-requests/webhook a vyberie udalosti (okrem onboarding.* aj consent.accepted, consent.revoked, consent.expired, consent.declined, consent.awaiting_pfs, consent.scopes_updated, webhook.disabled a pre White Label partnerov participant.released). Každá udalosť príde pre danú žiadosť najviac raz, aj keď firma klikne dvakrát; znovu otvorená expirovaná žiadosť dostáva udalosti odznova. GET /api/v1/onboarding-requests/{id} ostáva ako záloha.

• Overenie podpisu webhooku

{
  "id": "6f1c2d3e-4a5b-5c6d-a7e8-9f0a1b2c3d4e",
  "type": "onboarding.pfs_received",
  "occurredAt": "2026-09-30T09:15:00.000Z",
  "data": {
    "requestId": "<REQUEST_ID>",
    "customerRef": "erp-klient-42",
    "status": "action_required",
    "nextAction": "complete_client_activation",
    "clientMessage": {
      "sk": "Otvorte e-mail od ePošťáka zaslaný na kontakt z portálu Finančnej správy a potvrďte prepojenie.",
      "en": "Open the ePošťák e-mail sent to your Financial Administration contact and confirm the connection."
    },
    "firmId": null,
    "keyCreation": null
  }
}

Na poradí krokov nezáleží

Ak firma vyberie ePošťák na portáli Finančnej správy skôr, než program pošle žiadosť, odkaz z e-mailu jej povie, že čakáme na žiadosť od jej programu. Keď žiadosť so zhodným DIČ príde, firma dostane e-mail s odkazom na potvrdenie bez nového výberu na portáli a partner dostane onboarding.pfs_received.

Ak autorizácia z portálu medzitým vypršala, žiadosť ostane v stave awaiting_pfs a firma musí ePošťák na portáli vybrať znova.

Čo povedať zákazníkovi

Text môžete skopírovať do programu alebo e-mailu zákazníkovi.

Na odosielanie e-faktúr cez ePošťák: 1) v programe potvrďte odosielanie cez ePošťák, 2) na portáli Finančnej správy vyberte ePošťák ako poštára na odosielanie (Váš digitálny poštár na príjem faktúr sa nemení. Výber ePošťáka na portáli Finančnej správy používame výlučne na overenie, že ste oprávnený daňový subjekt používať dané Peppol ID.), 3) otvorte e-mail od ePošťáka a potvrďte prepojenie. Žiadny kľúč nikam nevkladáte.

To send e-invoices through ePošťák: 1) confirm sending through ePošťák in the program, 2) on the Financial Administration portal select ePošťák as your sending provider (Your digital postman for receiving invoices does not change. We use the selection of ePošťák on the Financial Administration portal solely to verify that you are an authorized taxpayer entitled to use the given Peppol ID.), 3) open the e-mail from ePošťák and confirm the connection. You do not insert any key anywhere.

Príklad: technický partner, firma platí, príjem inde

curl -X POST "https://epostak.sk/api/v1/onboarding-requests" \
  -H "Authorization: Bearer <PARTNERSKY_JWT>" \
  -H "Idempotency-Key: demo-send-only-2026-09-20-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceMode": "send_only",
    "relationshipMode": "technical_delegation",
    "customerRef": "erp-klient-42",
    "dic": "2120000000",
    "contactEmail": "kontakt@example.test"
  }'

curl "https://epostak.sk/api/v1/onboarding-requests/<REQUEST_ID>" \
  -H "Authorization: Bearer <PARTNERSKY_JWT>"

curl -X POST "https://epostak.sk/api/v1/integrator/keys" \
  -H "Authorization: Bearer <PARTNERSKY_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "scopedFirmId": "<FIRMID_Z_ONBOARDINGU>",
    "scopes": ["documents:send", "documents:read"]
  }'

Keď má firmu oslovených viac partnerov

• Zhoda DIČ neudeľuje súhlas. Klient výslovne vyberá konkrétneho partnera a rozsah.
• Jediná požiadavka môže byť predvybraná a viditeľná, ale predvýber nie je súhlas.
• Partner nikdy nevidí požiadavky ani stav iných partnerov.

Očakávaný výsledok a chyby

Firma má aktívne send-only oprávnenie, partner má kľúč viazaný na jej firmId a príjem zostal nezmenený.

• Registračné API
• Prístup k API
• Správa služby
• Odosielanie, príjem inde

• Neistý lookup príjmu: ponúkne sa opakovanie overenia. Výpadok hľadania neblokuje prijatie oznámenia a nespôsobí zápis do SMP.
• Duplicitné oznámenie alebo opakované dokončenie: nevzniká druhý záznam ani falošný aktívny stav.
• Expirovaný aktivačný odkaz: vyžaduje nové autoritatívne podanie; stratený token sa partnerovi nevracia.
• Existujúca firma bez zhodného súhlasu alebo konanie v zastúpení patrí do ručného posúdenia, nie do automatického toku.

Registračné API

Presný kontrakt onboardingových volaní: autentifikácia, telo, idempotencia, stavy a to, čo partner nikdy nedostane.

• Neobmedzený partnerský kľúč (nie kľúč viazaný na jednu firmu) s firms:manage.
• Aktuálna produkčná zmluva s Enterprise API pre daný typ vzťahu. Samostatné povolenie od ePošťáka netreba.

POST /api/v1/onboarding-requests

• Hlavička Idempotency-Key má 8–128 znakov a musí byť stabilná pri opakovaní tej istej požiadavky.
• Volanie je bez X-Firm-Id; partner koná ako partner, nie ako klientska firma.
• Kľúč partnera musí byť prevádzkovo povolený; samotné oprávnenie firms:manage nestačí.
• Odpoveď má kód 202 a rovnaký tvar ako GET: stav, nextAction a clientMessage { sk, en } s textom, ktorý môžete zobraziť firme.

{
  "id": "<REQUEST_ID>",
  "customerRef": "erp-klient-42",
  "serviceMode": "send_only",
  "status": "awaiting_pfs",
  "relationshipMode": "technical_delegation",
  "payerMode": "firm_billed",
  "keyCreation": null,
  "firmId": null,
  "nextAction": "select_provider_on_pfs",
  "clientMessage": {
    "sk": "Na portáli Finančnej správy vyberte ePošťák ako poštára na odosielanie. Váš digitálny poštár na príjem faktúr sa nemení. Výber ePošťáka na portáli Finančnej správy používame výlučne na overenie, že ste oprávnený daňový subjekt používať dané Peppol ID.",
    "en": "On the Financial Administration portal, select ePošťák as your sending provider. Your digital postman for receiving invoices does not change. We use the selection of ePošťák on the Financial Administration portal solely to verify that you are an authorized taxpayer entitled to use the given Peppol ID."
  }
}

GET /api/v1/onboarding-requests/{id}

• Vracia stav vašej vlastnej požiadavky; partner nevidí cudzie požiadavky.
• Až stav active sprístupní firmId a možnosť vytvorenia kľúča.
• Aktivačný odkaz a PFS token sa partnerovi nevracajú nikdy, ani počas čakania na aktiváciu.

status          -> nextAction
awaiting_pfs    -> select_provider_on_pfs
action_required -> complete_client_activation
activating      -> provider_approval
active          -> null (firmId and keyCreation available)
revoked         -> null
blocked         -> null
expired         -> null

Expirovaná a odvolaná žiadosť

• Žiadosť, ktorú firma nepotvrdí do 30 dní od poslednej zmeny, prejde do stavu expired a partner dostane onboarding.expired.
• Expirovanú žiadosť znovu otvoríte novým POST s rovnakým customerRef a rovnakým telom, ale s novým Idempotency-Key. Žiadosť si ponechá svoje id a začne znova v stave awaiting_pfs (alebo rovno active, ak už platné prepojenie existuje).
• Odvolanú žiadosť (revoked) znovu otvoriť nemožno. Firmu pripojte novou žiadosťou s novým customerRef.

Webhook pre onboarding: PUT, GET a DELETE /api/v1/onboarding-requests/webhook

• Partner má jeden webhook pre onboarding, bez X-Firm-Id. PUT ho vytvorí alebo nahradí (url a events), GET ho prečíta, DELETE ho zruší. PUT a DELETE vyžadujú webhooks:write, GET webhooks:read.
• url musí byť https. events je neprázdny zoznam z: onboarding.pfs_received, onboarding.signed, onboarding.review_required, onboarding.active, onboarding.expired, onboarding.revoked.
• Tajomstvo na overenie podpisu (secret) sa vráti iba raz: pri vytvorení (201) alebo po opätovnom vytvorení po DELETE. Ďalšie PUT (200) menia url a udalosti a tajomstvo ponechajú.

curl -X PUT "https://epostak.sk/api/v1/onboarding-requests/webhook" \
  -H "Authorization: Bearer <PARTNERSKY_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://erp.example/hooks/epostak",
    "events": ["onboarding.pfs_received", "onboarding.signed", "onboarding.review_required", "onboarding.active", "onboarding.expired", "onboarding.revoked"]
  }'

{
  "webhook": {
    "url": "https://erp.example/hooks/epostak",
    "events": ["onboarding.pfs_received", "onboarding.signed", "onboarding.review_required", "onboarding.active", "onboarding.expired", "onboarding.revoked"],
    "isActive": true
  },
  "secret": "<TAJOMSTVO_ZOBRAZENE_IBA_RAZ>"
}

Čo partner nikdy nedostane

• Verification token, provider secret ani aktivačný odkaz.
• Prístup k prijatej pošte firmy, k cudzím dokumentom alebo k nepoverovaným dokladom.
• Možnosť zmeniť platiteľa svojvoľne z requestu.

Očakávaný výsledok a chyby

Požiadavka existuje pod vaším Idempotency-Key, jej stav je čitateľný a kľúč vznikne až po stave active.

• Iba odosielanie
• Správa služby
• Enterprise webhooky
• Idempotencia

• 403 pri vytvorení: kľúč je obmedzený na firmu, chýba firms:manage alebo produkčná zmluva partnera nepokrýva Enterprise API pre zvolený relationshipMode (SEND_ONLY_NOT_AUTHORIZED).
• 409 ONBOARDING_CONFLICT: customerRef alebo Idempotency-Key už patrí žiadosti s iným telom. Pri opakovaní použite rovnaký Idempotency-Key a rovnaké telo; pre inú firmu použite nový customerRef.
• 400 INVALID_REQUEST: skontrolujte serviceMode, relationshipMode, dic a kontakt. 400 INVALID_IDEMPOTENCY_KEY: chýba hlavička Idempotency-Key alebo nemá 8–128 znakov.

Správa služby

Firma spravuje svoju send-only službu bez dashboardu: stav, zmluva, faktúry, platba a odvolanie poverenia.

• Dokončený send-only onboarding aspoň do stavu active.
• Prístup ku kontaktu, ktorý je uvedený pri overení PFS — kód chodí tam.

Ako sa firma prihlási bez účtu

1. 1

   Otvorte zabezpečenú stránku správy

   Firma používa zabezpečený odkaz z e-mailu, ktorý je viazaný na kontakt z overenia PFS.

2. 2

   Zadajte nový jednorazový kód

   Kód platí 10 minút, má päť pokusov a relácia trvá 20 minút. Odhlásenie reláciu na serveri ruší.

Čo firma v správe uvidí

• Stav služby a partnera, ktorý má k firme prístup.
• Vlastnú zmluvu a faktúry podľa schváleného modelu. Pri managed_service je fakturačným zákazníkom integrátor a jeho faktúry sa firme nezobrazujú.
• Možnosť odvolať poverenie partnera.

Čo urobí odvolanie partnera

• Zablokuje nové aj ešte neodoslané úlohy tohto partnera pre túto firmu.
• Nemení SMP, iné poverenia ani záväzky a nestrháva už doručené faktúry.

Odchod a ukončenie send-only služby

Odvolanie partnera zastaví jeho oprávnenie, ale samo osebe neukončuje službu ani fakturáciu. Pri úplnom odchode použite samostatný postup ukončenia. Keďže príjem zostáva u pôvodného poskytovateľa, ukončenie send-only odosielania nemení prijímajúci Participant ID ani SMP záznamy.

• Postup odchodu zo služby

Očakávaný výsledok a chyby

Firma vidí svoj stav, zmluvu a faktúry a dokáže odvolať poverenie bez akéhokoľvek nového účtu.

• Odchod a ukončenie
• Iba odosielanie
• Odvolanie prístupu

• Kód neprišiel: skontrolujte, že ide o kontakt z overenia PFS; e-mail z API požiadavky ho neprepisuje.
• Expirovaný alebo použitý kód: vyžiadajte nový; opakované použitie toho istého kódu je odmietnuté.

Odchod a ukončenie

Rozlíšite ukončenie spolupráce, odvolanie prístupu, zmenu digitálneho poštára a export údajov a pre každý krok použijete správny postup.

• Oprávnený kontakt, firma alebo partner, dotknutá služba a požadovaný dátum.
• Rozhodnutie, či chcete iba odobrať prístup, ukončiť službu, zmeniť poskytovateľa alebo si najprv vyžiadať export bez ukončenia.

Najprv rozlíšte, čo sa má skončiť

• Čo presne urobí odvolanie prístupu

Ukončenie white-label spolupráce

Pri štandardnom white-label programe platí od aktivácie počiatočná 12-mesačná viazanosť. Riadnu výpoveď možno doručiť aj počas nej, ale účinná je najskôr jej posledným dňom. Po viazanosti platí 90-dňová výpovedná lehota. Ak podpísaná individuálna objednávka určuje inú lehotu, má prednosť.

Možno ukončiť iba white-label vrstvu a po samostatnom potvrdení pokračovať cez API. Samotné ukončenie značky nemení Participant ID ani SMP/PFS záznamy.

• White-label prehľad — odchod

Prechod k inému digitálnemu poštárovi

Oprávnená osoba uvedie participanta, nového poskytovateľa, dotknuté služby a požadovaný dátum. Pri presune príjmu sa vydá migračný kód a koordinuje SMP/PFS smerovanie; rovnaký participant sa nesmie zaregistrovať druhýkrát.

• Technický postup a migračný kód

Lehoty pri prechode

Výstup a export údajov

• Úplný register exportovateľných údajov

• Vlastné dokumenty a prílohy, dostupné UBL/XML a PDF reprezentácie.
• Stavy, validácie, chyby, časové údaje a dostupné potvrdenia o doručení.
• Firemné, schránkové a integračné konfigurácie vrátane webhookov a mapovaní, ale bez hesiel, API kľúčov a iných tajomstiev.
• Exportný manifest a oddeliteľné auditné, prevádzkové, support a billing metadáta.

Odchod pri send-only a delegovanom prístupe

Pri send-only sa príjem u pôvodného poskytovateľa nemení, preto ukončenie odosielania samo osebe nevyžaduje migráciu prijímajúceho participanta. Pri technickej delegácii alebo spravovanom integrátorovi najprv odvolajte prístup konkrétneho partnera; ukončenie služby a fakturácie riešte oddelene.

• Správa a ukončenie send-only služby

Ako podať žiadosť

Napíšte z oprávnenej kontaktnej adresy na info@epostak.sk. Uveďte firmu a DIČ alebo Participant ID, dotknutú službu, požadovaný úkon, nového poskytovateľa, ak sa mení, a požadovaný dátum. Prípravný export výslovne označený ako bez ukončenia nie je výpoveďou.

Očakávaný výsledok a chyby

Viete, ktorý krok ruší prístup, ktorý ukončuje službu, ktorý presúva participanta a aké údaje dostanete na výstupe.

• Odvolanie prístupu
• Migrácia
• Správa služby

• Žiadosť neuvádza firmu alebo rozsah: doplňte DIČ alebo Participant ID, službu a požadovaný úkon.
• Individuálna objednávka má inú lehotu: rozhoduje podpísaná objednávka a jej verzia.

Odvolanie prístupu

Presne zistíte, čo odvolanie partnerského prístupu zastaví a čo zostáva nedotknuté.

• Prehľad, ktoré integračné kľúče a procesy danú firmu používajú.

Čo po odvolaní prestane fungovať

• Nové volania tohto partnera pre túto firmu sú odmietnuté.
• Úlohy, ktoré ešte neboli odoslané, sa neodošlú.

Čo odvolanie nemení

• Peppol registrácia a SMP záznamy zostávajú; odvolanie nie je migrácia ani odregistrácia.
• Iné partnerské poverenia a iné firmy nie sú dotknuté.
• Už doručené dokumenty sa nestrhávajú späť; doručená faktúra sa nedá vziať z príjemcu.

Keď nejde iba o odvolanie prístupu

Ak firma alebo partner končí službu, mení digitálneho poštára alebo potrebuje export údajov, samotné odvolanie prístupu nestačí. Použite samostatný postup odchodu; ten rozlišuje zmluvné ukončenie, technickú migráciu a prevzatie údajov.

• Odchod, ukončenie a export

Očakávaný výsledok a chyby

Partner má pre danú firmu zablokovaný prístup a viete, že registrácia ani iné firmy neboli zasiahnuté.

• Odchod a ukončenie
• Pozvánky a súhlas
• Firemný kontext

• Prístup funguje aj po odvolaní: ide o iné poverenie alebo iný partnera kľúč — skontrolujte, ktorý kľúč volanie použil.
• Firma chce späť prístup: vytvorte novú pozvánku, starý súhlas sa neobnovuje.