Napíšte nám
Z pracovného e-mailu pošlite žiadosť na info@epostak.sk. Uveďte firmu, požadované rozhranie a stručný účel integrácie.
Produkčný postup
Od sandboxu po produkciu
Od manuálne vytvoreného sandboxu cez objednanie produkcie a podpis zmluvy až po zapojenie prvého klienta.
1. Začnite v sandboxe
Sandbox je manuálne schvaľované testovacie prostredie. Nevytvára produkčnú zmluvu, fakturáciu ani oprávnenie konať za reálne firmy.
ePošťák vytvorí prístup
Po overení žiadosti operátor manuálne vytvorí integrátorský účet, testovacie firmy a potrebné testovacie prístupy. Samoobslužná registrácia sandboxu nie je podporovaná.
Prihláste sa do integrátorského prostredia
Testovanie prebieha na dev.epostak.sk/integrator s oddelenými testovacími firmami, kľúčmi a Peppol testovacou sieťou.
Dokončite integračné testy
Overte autentifikáciu, oddelenie firiem, odoslanie, príjem, stavové udalosti a odvolanie súhlasu. Sandboxové firmy, súhlasy ani kľúče sa do produkcie neprenášajú.
2. Vyberte produkčný režim
API rozhranie neurčuje, kto uzatvára zmluvu a kto platí. Model vyberte ešte pred produkčnou aktiváciou.
Technický partner
Dodávateľ ERP používa centrálny partnerský prístup, ale každá klientská firma má vlastnú API objednávku a platí svoju spotrebu priamo ePošťáku.
- SAPI alebo Enterprise API
- odvolateľný súhlas každej firmy
- firemný tajný kľúč sa partnerovi neposiela
Spravovaný integrátor
Integrátor spravuje schválené klientské firmy a ich API spotrebu platí ePošťáku súhrnne podľa integrátorskej zmluvy.
- Connector alebo Enterprise API
- súhlas vlastníka alebo správcu firmy zostáva povinný
- jedna súhrnná fakturácia integrátorovi
White-label digitálny poštár
Po samostatnom schválení Finančnou správou vystupuje partner voči klientovi ako digitálny poštár pod vlastnou značkou. ePošťák poskytuje technickú a Peppol infraštruktúru.
- klient si vo vPDS volí priamo partnera
- bez klientskeho účtu ePošťák a bez ePošťák OAuth
- partner spracuje provider webhook a registráciu firmy v SMP
3. Objednajte a aktivujte produkciu
Úspešné sandboxové testy produkciu neaktivujú automaticky. Produkčná objednávka a produkčné prístupy vznikajú samostatne.
Otvorte produkčnú aktiváciu
Na /integrator/aktivacia vyberte API pre vlastnú firmu, technického partnera alebo integrátora/white-label podľa toho, kto spravuje klientov a kto platí.
Vyplňte objednávku
Doplníte firemnú a fakturačnú identitu, zvolíte SAPI alebo Enterprise API, obchodný režim, odhad spotreby, API program a prípadný white-label program.
Podpíšte presný zmluvný balík
Oprávnená osoba skontroluje pripravenú objednávku, cenník, zmluvu a prílohy a elektronicky odošle podpísanú ponuku. Automatické potvrdenie znamená iba prijatie žiadosti.
ePošťák žiadosť overí a spolupodpíše
Kaja Solutions overí firmu, podpisujúcu osobu a zvolený režim. Zmluva a produkčné oprávnenie vzniknú až naším spolupodpisom; žiadosť môžeme vrátiť na opravu alebo odmietnuť.
Po spolupodpise dostanú obe strany finálny zmluvný PDF balík a partnerovi sa sprístupní príslušný produkčný portál. V režime integrátora alebo technického partnera si následne v časti API kľúče vytvorí vlastný produkčný
sk_int_*. Celý tajný kľúč sa zobrazí iba raz; ePošťák ho automaticky neposiela e-mailom.Pri API pre vlastnú firmu ide o firemný produkčný prístup. Pri integrátorovi a technickom partnerovi ide o partnerský prístup; samotný
sk_int_* ešte neoprávňuje konať za ľubovoľnú firmu. Ak si klient volí ePošťák, firma potvrdzuje partnerské oprávnenie v ePošťáku. Ak si klient volí schváleného white-label partnera, firma prichádza cez jeho provider webhook a SMP onboarding bez účtu ePošťák.4. Zapojte klienta podľa zvoleného poskytovateľa
Najprv určte, koho si klient volí vo vPDS ako digitálneho poštára. Štandardný integrátor a white-label poskytovateľ používajú dva rozdielne onboardingové toky.
Klient si volí ePošťák
Klient si vo vPDS vyberie ePošťák, dokončí registráciu firmy a vytvorí alebo použije svoje konto ePošťák. Partner potom v LIVE dashboarde pripraví jednorazový odkaz pre presné IČO alebo DIČ a požadované oprávnenia.
- vlastník alebo správca firmy sa prihlási a potvrdí rozsah
- partner používa svoj centrálny kľúč iba pre schválenú firmu
- odvolanie prístupu neruší Peppol schránku klienta
Klient si volí vášho white-label poštára
Po vašom samostatnom schválení a zaradení do zoznamu poskytovateľov si klient vo vPDS vyberie priamo vašu firmu. Vaša provider vrstva prijme aktivačné údaje od Finančnej správy a cez pridelené rozhranie zaregistruje klienta v SMP.
- klient si nevytvára konto ePošťák
- nepoužíva sa ePošťák OAuth ani ePošťák pozvánka
- dokumenty a udalosti smerujú na webhooky partnera
Rozhodujúca otázka je: koho si klient zvolil vo vPDS? Ak ePošťák, použije sa konto a samostatné oprávnenie firmy. Ak vášho schváleného white-label poskytovateľa, autorizačným zdrojom je provider výber vo vPDS a následný provider webhook; klient nemá konto ePošťák.
5. Sledujte stav onboardingu
Stavy required, pending, active a revoked nižšie opisujú štandardnú väzbu medzi firmou a technickým alebo spravovaným integrátorom v ePošťáku. White-label poskytovateľ sleduje vlastný provider webhook, SMP registráciu a stav zmeny poskytovateľa.
required
Firma ešte nie je pripojená alebo potrebuje novú pozvánku pre požadované rozhranie a oprávnenia.
pending
Pozvánka alebo riadená aktivácia prebieha. Nezačínajte produkčné volania, kým sa stav nezmení na active.
active
Existuje aktívna, neodvolaná väzba pre požadované rozhranie a rozsah. Môžete pokračovať prvým produkčným volaním.
revoked
Firma súhlas odvolala. Zastavte ďalšie spracovanie a vytvorte novú pozvánku iba vtedy, ak chce firma prístup opäť udeliť.
Stav môžete pri Enterprise API overiť cez GET /api/v1/firms/consent-status. SAPI nemá vlastné rozhranie na správu firiem; ak tento Enterprise endpoint používate pri SAPI onboardingu, SAPI aj Enterprise API musia byť povolené v zmluve aj pozvánke.
6. Použite správny firemný kontext
SAPI
Partnerský token doplňte hlavičkou X-Peppol-Participant-Id: 0245:DIČ. Server overí aktívnu väzbu, súhlas a rozsah tokenu.
Enterprise API
Pri volaní s partnerským sk_int_* určite schválenú firmu hlavičkou X-Firm-Id. Oprávnenia sa vždy orežú rozsahom súhlasu firmy.
Connector
Connector používa stabilné customerRef nastavené integrátorom pre schválenú firmu. Na Connector endpointoch neposielajte X-Firm-Id.
7. Odvolanie prístupu a ukončenie služby
Odvolanie súhlasu partnerovi, keď si klient zvolil ePošťák, bezodkladne ukončí jeho technický prístup ku konkrétnej firme. Neruší konto firmy, jej Peppol schránku ani registráciu. Zmena digitálneho poštára je samostatný migračný proces.
Keď si klient zvolil white-label partnera, deaktivácia alebo zmena poskytovateľa prichádza do jeho provider toku. Partner spracuje uvoľnenie alebo migráciu Peppol účastníka v SMP tak, aby doručovanie pokračovalo do prevzatia novým poskytovateľom. Žiadny účet ePošťák sa neruší, pretože klient ho v tomto režime nemá.