White label

Onboarding white-label partnera

Rozdiely medzi partnerskými režimami

• Pozvánka na súhlas pre existujúcu firmu (štandardný partnerský model).
• Send-only onboarding, kde príjem zostáva inde a firma nepotrebuje účet.
• White-label registrácia, kde vy vystupujete ako poskytovateľ a registrujete participanta.

Odchod a 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ť.

Odchod má tri oddelené časti: ukončenie obchodnej spolupráce, technický presun Participant ID k inému poskytovateľovi a prevzatie vlastných údajov. Partner môže ukončiť iba white-label vrstvu a po samostatnom potvrdení pokračovať cez API.

• Celý postup ukončenia a odchodu
• Verejný register exportovateľných údajov

• Ukončenie white-label vrstvy samo osebe nemení Participant ID ani SMP/PFS záznamy; ich presun alebo zrušenie sa rieši ako samostatný technický krok.
• Pred ukončením si možno vyžiadať export vlastných údajov. Export neobsahuje zdrojový kód, interné bezpečnostné pravidlá, tajomstvá ani údaje iných zákazníkov.

DEV a WL aktivácia

Zistíte, čo presne potrebuje váš DEV prístup, aby bolo možné testovať white-label registráciu a čo zostáva oddelené.

• Aktívny partnerský kľúč v DEV prostredí.
• Schválené rozšírenie prístupu na Enterprise API a white-label sandbox.

Prerekvizity DEV white labelu

• Aktívny kľúč s prístupom na Enterprise API (api-enterprise) a oprávnením enterprise_api.
• Aktívna sandbox fakturácia white labelu (white_label_sandbox) — bez nej sa registrácia neaktivuje.
• Aktuálna Enterprise autorizácia partnerského účtu pre daný typ vzťahu.

Čo zostáva oddelené

Očakávaný výsledok a chyby

Váš DEV prístup je výslovne aktivovaný, poznáte potrebné oprávnenia a viete, ktorú hodnotu kde použiť.

• Overtoken
• Testovanie
• Autentifikácia

• Registráciu nie je možné spustiť: najčastejšie chýba sandbox fakturácia white labelu alebo enterprise_api.
• Kľúč funguje v štandardnom rozhraní, ale nie v Enterprise: rozsahy rozhraní sú oddelené a treba ich povoliť osobitne.

Overtoken

Prejdete Overtoken tok od provider webhooku cez verification token až po registráciu participanta a čitateľný výsledok operácie.

• Aktívny white-label DEV podľa predchádzajúcej fázy.
• Vlastný provider webhook overený podľa X-PDS-Secret nad surovým telom požiadavky.

Priebeh toku

1. 1

   1. Klient zvolí vás u poskytovateľa

   Po výbere poskytovateľa príde na váš webhook podanie FS. Overte ho podľa skutočného podpisového kontraktu nad surovým telom.

2. 2

   2. Použite nový verification token

   Token dokazuje pôvod podania FS a je viazaný na dvojicu DIČ: DIČ prístupového bodu ePošťáka 2122701339 (Kaja Solutions s.r.o.) a DIČ registrovanej firmy. V Overtokene preto zadajte DIC1 (prístupový bod) = 2122701339 a DIC2 = DIČ firmy a to isté DIČ firmy pošlite v poli dic. Token vydaný pre iné DIC1 alebo iné DIČ firmy testovacie SMP odmietne (422 SMP_AUTHORIZATION_REJECTED). DIC2 môže byť ľubovoľné 10-miestne testovacie DIČ, ktoré ešte nie je zapísané v testovacom SMP. V produkcii token vydá Finančná správa SR sama, keď si vás klient vyberie. Neposielajte ho do browsera, logov ani partnerovi a neuchovávajte ho v čitateľnej podobe.

3. 3

   3. Zaregistrujte participanta

   POST /api/v1/white-label/participants/registrations s participants:write, Idempotency-Key a bez X-Firm-Id.

4. 4

   4. Prečítajte výsledok operácie

   Pri 202 čítajte GET /api/v1/white-label/operations/{operationId}. Po succeeded overte participanta cez GET /api/v1/white-label/participants/{participantId}.

Registračné volanie

curl -X POST "https://dev.epostak.sk/api/v1/white-label/participants/registrations" \
  -H "Authorization: Bearer <API_JWT>" \
  -H "Idempotency-Key: wl-reg-demo-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "customerRef": "erp-klient-42",
    "dic": "2120000000",
    "companyEmail": "firma@example.test",
    "verificationToken": "<VERIFICATION_TOKEN_Z_PODANIA_FS>"
  }'

Na čo si dať pozor

• Nevymýšľajte polia provider formulára ani podpisový algoritmus; overte ich podľa skutočnej externých obrazoviek a kontraktu.
• Token nepoužívajte pri inej firme: je viazaný na DIČ prístupového bodu 2122701339 a DIČ firmy, pre ktorú bol vydaný. Iný pár DIČ testovacie SMP odmietne.
• Existujúca lokálna identita sa druhou registráciou nepreberá; na prevzatie slúži migrácia.

Očakávaný výsledok a chyby

Máte uložené id operácie, participantId a firmId a viete, že registrácia skončila stavom succeeded, nie iba prijatím požiadavky.

• Testovanie
• Migrácia
• Enterprise webhooky

• Chybný podpis webhooku: registrácia sa nespustí. Opravte overenie nad surovým telom, nie parsovaným JSON.
• Neistý stav operácie: čítajte ju znova; nevytvárajte novú registráciu s novým kľúčom.
• 422 SMP_AUTHORIZATION_REJECTED pri registrácii: token nesedí na pár DIČ. Vygenerujte v Overtokene nový token s DIC1 = 2122701339 a DIC2 = DIČ firmy z tela požiadavky.
• Konflikt identity: použite migráciu s migračným kódom od aktuálneho poskytovateľa.

Testovanie

Overíte celý reťazec v DEV: zákaznícku väzbu, odoslanie a príjem dokumentu, stav a udalosti bez duplicít.

• Zaregistrovaný alebo migrovaný participant v DEV.
• Oddelené prístupy pre registráciu (participants:write) a čítanie (participants:read).

Zákaznícka väzba

• Toto volanie nie je všeobecná SAPI ani Connector operácia; vyžaduje Enterprise oprávnenie a firms:manage.
• Použite rovnaký customerRef a rovnaké testovacie identifikátory ako pri registrácii.
• customerAuthorization.confirmed nastavte na true iba s platným poverením klienta. Ukážkový evidenceReference nahraďte odkazom na váš auditovateľný doklad o poverení.
• Tento krok nespotrebúva verification token a nenahrádza registráciu participanta.

curl -X POST "https://dev.epostak.sk/api/v1/customers" \
  -H "Authorization: Bearer <API_JWT>" \
  -H "Idempotency-Key: wl-customer-demo-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "customerRef": "erp-klient-42",
    "relationship": "represented",
    "country": "SK",
    "taxId": "2120000000",
    "contactEmail": "firma@example.test",
    "customerAuthorization": {
      "confirmed": true,
      "evidenceReference": "mandate-demo-0001"
    }
  }'

Koncový test dokumentov

1. 1

   Odošlite syntetický dokument

   Overte odpoveď, stav dokumentu a uloženie na strane príjemcu.

2. 2

   Zopakujte s rovnakým idempotency kľúčom

   Overte, že nevznikol druhý dokument.

3. 3

   Overte udalosti alebo pull

   Pri Enterprise udalostiach najprv vytvorte odber; pre pravidelný pull použite url=null podľa kontraktu.

Očakávaný výsledok a chyby

Doklad prešiel od API po uloženie u príjemcu, opakovanie nevytvorilo duplicitu a udalosť alebo pull doručil očakávaný stav.

• Produkcia
• Enterprise webhooky
• Stavy dokumentov

• Druhý dokument pri opakovaní: telo alebo idempotency kľúč sa zmenil.
• Udalosť nechodí: skontrolujte, či je odber vytvorený a či callback prešiel overením podpisu.

Produkcia

Dokončíte prechod white labelu do produkcie a onboarding prvého reálneho klienta.

• Odskúšaný DEV tok vrátane registrácie, zákazníckej väzby a dokumentového testu.
• Samostatné produkčné white-label oprávnenie a pripravený partnerský účet.

Čo musí vzniknúť nanovo

• Produkčné identity, kľúče, JWT, callbacks a webhook secrety.
• Nový produkčný verification token pre každé podanie FS; DEV tokeny sa neprenášajú.
• Produkčná zákaznícka väzba s vlastným Idempotency-Key.

Prvý reálny klient

1. 1

   Klient si zvolí vás

   Podanie FS príde na váš produkčný provider webhook.

2. 2

   Zaregistrujte participanta v produkcii

   Rovnaký kontrakt ako v DEV, ale s produkčnými hodnotami a schválenými oprávneniami.

3. 3

   Vytvorte produkčného zákazníka

   POST /api/v1/customers s relationship=represented a vlastným Idempotency-Key.

4. 4

   Prejdite do bežnej prevádzky

   Sledujte stavy a dôkazy doručenia; prvé produkčné doklady overte manuálne.

Očakávaný výsledok a chyby

Prvý produkčný klient má vlastnú zmluvu, registráciu a API väzbu a vy máte dôkaz o doručení jeho dokladu.

• Migrácia
• Stavy dokumentov
• Diagnostika chýb

• Dev testy prešli, produkcia nie: hľadajte skôr produkčné oprávnenie, callback alebo nový token než kontrakt.
• Klient zdedil DEV identitu: to sa nesmie stať; vytvorte produkčnú registráciu s novým verification tokenom.

Migrácia

Rozlíšite migráciu existujúceho participanta od novej registrácie a viete, kedy použiť migračný kód.

• Participant, ktorý je už zaregistrovaný u iného poskytovateľa.
• Súhlas klienta s prevodom a jeho migračný kód od aktuálneho poskytovateľa.

Kedy migrácia a kedy registrácia

• POST /api/v1/white-label/participants/migrations pre príchod s migračným kódom.
• POST /api/v1/white-label/participants/{participantId}/migration-code so scope participants:migrate a hlavičkou Idempotency-Key pre odchod.
• Vyžiadanie kódu participanta neuvoľní. Uvoľní sa až po potvrdenom prevzatí v SMP alebo po ukončení služby: vtedy príde na partnerský webhook (PUT /api/v1/onboarding-requests/webhook) udalosť participant.released s reason provider_changed alebo service_terminated, GET /api/v1/white-label/participants/{participantId} začne vracať 404 a volania s X-Firm-Id tejto firmy 403 s reason consent_revoked. Prevzatie u iného poskytovateľa zisťujeme pravidelnou kontrolou, preto je autoritatívny GET a webhook je len skoršie upozornenie.

Postup migrácie

1. 1

   Získajte súhlas a migračný kód

   Klient požiada svojho aktuálneho poskytovateľa o migračný kód a potvrdí prevod.

2. 2

   Spustite migráciu

   POST /api/v1/white-label/participants/migrations s migračným kódom a stabilným Idempotency-Key.

3. 3

   Overte výsledok

   Sledujte operáciu a po úspechu overte participanta; až potom riešte zákaznícku väzbu a dokumenty.

Odchod k inému poskytovateľovi, lehoty a export

Oprávnená osoba označí participanta, nového poskytovateľa, dotknuté služby a požadovaný dátum. Technický prechod a ukončenie obchodnej spolupráce sú dva samostatné procesy; zmluvná viazanosť nesmie blokovať vydanie migračného kódu ani štandardný export.

• Celý postup odchodu
• Úplný register exportovateľných údajov

• Štandardný export zahŕňa vlastné dokumenty a prílohy, dostupné UBL/XML a PDF, stavy a doručovacie záznamy, konfigurácie bez hesiel a API kľúčov a exportný manifest.
• Neštandardná asistencia alebo vývoj na mieru sa nacenia individuálne podľa rozsahu.

Očakávaný výsledok a chyby

Vieš, ktorý tok použiť, a prevodbehne s migračným kódom namiesto opakovanej registrácie.

• Odchod a ukončenie
• Produkcia
• Odvolanie prístupu

• Registrácia vracia konflikt identity: použiť migráciu, nie ďalšiu registráciu.
• Klient nemá migračný kód: požiadajte jeho aktuálneho poskytovateľa; obísť sa to nedá.