Odporúčané postupy integrácie

Ktorý vstup použiť

Pravidlo je jedno. Ak je vlastník alebo správca firmy práve prihlásený vo vašej aplikácii, použite OAuth (tlačidlo „Prepojiť s ePošťákom“). Ak pripájate firmu zo servera alebo jej posielate odkaz e-mailom, použite odkaz na súhlas (consent link). Nastavenia → API je iba pre firmu, ktorá používa vlastný softvér (typ 2).

OAuth aj odkaz skončia v tom istom prepojení: ponuka súhlasu s uloženým odtlačkom, KYC záznam, väzba integrátora na firmu a webhook consent.accepted. Kliknutie „Povoliť prístup“ je súhlas firmy; podmienky (spravovaný integrátor alebo technický partner) sa berú z vašej zmluvy rovnako ako pri odkaze. Ani jedna cesta nevydáva firemný kľúč: pracujete s centrálnym sk_int_* a hlavičkou X-Firm-Id.

Presné názvy v ovládacom paneli API

Pri firme vidíte tieto polia. V texte nižšie ich používame presne takto.

OAuth krok za krokom

1. 1

   1. Presmerujte vlastníka na autorizačnú adresu

   GET https://epostak.sk/oauth/authorize s parametrami client_id, redirect_uri, response_type=code, scope, state, code_challenge a code_challenge_method=S256. PKCE je povinné, state (náhodný reťazec proti CSRF) odporúčame vždy. Oprávnenia sú prienik požadovaných, oprávnení OAuth klienta a oprávnení ponuky a musia obsahovať firms:manage a aspoň jedno documents:*.

2. 2

   2. Vlastník sa prihlási a klikne na „Povoliť prístup“

   Vlastník alebo správca firmy sa prihlási do ePošťáka a uvidí zhrnutie ponuky: kto, čo a za akých podmienok. Kliknutie na „Povoliť prístup“ je súhlas firmy. Ak už platný prijatý súhlas pokrýva požadované oprávnenia, použije sa; inak sa vytvorí nová ponuka a prijme sa rovnakým postupom ako odkaz na súhlas. Iný používateľ dostane FORBIDDEN.

3. 3

   3. Prijmite kód na redirect_uri

   ePošťák presmeruje vlastníka na redirect_uri s parametrami code a state. Skontrolujte state. Kód je jednorazový a platí 10 minút.

4. 4

   4. Vymeňte kód a uložte firm_id

   POST https://epostak.sk/api/oauth/firm-consent (grant_type=authorization_code, code, client_id, client_secret, redirect_uri, code_verifier). Odpoveď obsahuje firm_id, firm_name, firm_ico, firm_peppol_participant_id (null, kým firma nie je zaregistrovaná), consent_id a scope. Nevydá sa žiadny kľúč: uložte firm_id.

5. 5

   5. Volajte API centrálnym kľúčom a X-Firm-Id

   Svoj centrálny sk_int_* vymeňte cez POST /api/v1/auth/token za JWT a pri každom volaní za firmu pošlite X-Firm-Id: <firm_id>.

curl -X POST "https://epostak.sk/api/oauth/firm-consent" \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"authorization_code","code":"<KOD>","client_id":"<OAUTH_CLIENT_ID>","client_secret":"<OAUTH_CLIENT_SECRET>","redirect_uri":"https://program.example/oauth/callback","code_verifier":"<PKCE_VERIFIER>"}'

# 200 -> {"token_type":"central_credential","firm_id":"<FIRM_ID>","firm_name":"Example s.r.o.","firm_ico":"12345678","firm_peppol_participant_id":null,"consent_id":"<CONSENT_ID>","activation":"active","active_from":null,"scope":"firms:manage documents:send documents:read",...}

curl "https://epostak.sk/api/v1/firms" \
  -H "Authorization: Bearer <JWT_Z_CENTRALNEHO_SK_INT>" \
  -H "X-Firm-Id: <FIRM_ID>"

Odkaz na súhlas krok za krokom

1. 1

   1. Vytvorte odkaz

   POST /api/v1/consent-offers (odporúčané) alebo staršie POST /api/v1/firms/consent-link s DIČ alebo IČO firmy a oprávneniami. Voliteľné return_url (https) musí mať pôvod z presmerovacích adries povolených pre integrátora, inak VALIDATION_ERROR. Odpoveď obsahuje id a consentUrl; odkaz platí 14 dní a nemožno ho načítať znova.

2. 2

   2. Vlastník firmy odkaz potvrdí

   Odkaz otvoríte vlastníkovi v prehliadači alebo ho pošlete e-mailom. Vlastník alebo správca sa prihlási a súhlas potvrdí.

3. 3

   3. Webhook a firm_id

   Webhook consent.accepted príde na adresu nastavenú cez PUT /api/v1/onboarding-requests/webhook. Po prijatí vráti GET /api/v1/consent-offers/{id} aj firmId, firmIco, firmName a firmPeppolParticipantId (pred prijatím sú null). Uložte firmId.

curl -X POST "https://epostak.sk/api/v1/firms/consent-link" \
  -H "Authorization: Bearer <JWT_Z_CENTRALNEHO_SK_INT>" \
  -H "Content-Type: application/json" \
  -d '{"dic":"2022988022","customer_reference":"ZAKAZNIK-001","scopes":["firms:manage","documents:send","documents:read"],"return_url":"https://program.example/spat"}'

curl "https://epostak.sk/api/v1/consent-offers/<OFFER_ID>" \
  -H "Authorization: Bearer <JWT_Z_CENTRALNEHO_SK_INT>"
# 200 -> {"status":"accepted","firmId":"<FIRM_ID>","firmIco":"12345678","firmName":"Example s.r.o.","firmPeppolParticipantId":null,...}

Typ 1: dodávateľ ERP alebo účtovníctva ako spravovaný integrátor

Dodávate softvér klientom a za doklady platíte vy. integrationPath: enterprise_api, relationshipMode: managed_service, payerMode: integrator_billed, dashboardAccessMode: compliance_only. Firma nedostáva žiadny kľúč (credentialsAvailable: false).

Typ 2: vlastný softvér firmy

Firma pripája vlastný systém a platí sama. payerMode: firm_billed, credentialsAvailable: true (keď je API aktívne a schránka registrovaná). Integrátor v tom nie je, preto sa nepoužíva OAuth ani odkaz na súhlas.

Typ 3: prísny White Label

Iba API: firma ePošťák nevidí, vzťah so zákazníkom vlastní partner pod vlastnou značkou. Nepoužíva sa OAuth ani odkaz na súhlas (OAuth takúto firmu odmietne s WHITE_LABEL_API_ONLY).

Typ 4: technický partner s delegovaním

Partner pracuje za firmu, ktorá má vlastnú API objednávku a platí sama. integrationPath: enterprise_api, relationshipMode: technical_delegation, payerMode: firm_billed, dashboardAccessMode: full_dashboard.

Typ 5: Connector

Pre programy, ktoré nevedia posielať UBL: Connector prijíma JSON a firmu určuje cez customerRef namiesto X-Firm-Id. integrationPath: connector. Režim a platiteľ (relationshipMode a payerMode) vyplývajú z vašej zmluvy ako pri type 1 alebo 4.

Výmena kódu: /oauth/firm-consent a /oauth/token

• Referencia: autorizačná adresa a výmena kódu

• Kód nového súhlasu vymeňte cez POST /api/oauth/firm-consent (rovnaký vstup ako /oauth/token). Vráti firm_id a údaje firmy, nie kľúč: uložte firm_id a API volajte centrálnym kľúčom sk_int_* s hlavičkou X-Firm-Id.
• POST /api/oauth/token sa nemení. Kód nového súhlasu odmietne s 400 invalid_grant a kód pritom nepoužije, takže ten istý kód hneď vymeníte cez /api/oauth/firm-consent.
• Ak si firma zatiaľ platí API sama a prijme vašu ponuku, odpoveď má activation "pending" a active_from. Súhlas platí a firm_id je konečné, volania s X-Firm-Id však fungujú až od active_from (začiatok ďalšieho fakturačného mesiaca), keď platenie prejde na vás. Firmu znova na súhlas neposielajte; ďalšie „Povoliť prístup“ použije ten istý súhlas.
• Staré kľúče sk_live_* z predchádzajúceho OAuth fungujú, kým ich niekto neodvolá. Kľúč sk_live_* cez /api/oauth/token dostanú už len staršie súhlasy bez uloženého odtlačku ponuky.
• Chyby autorizácie majú kódy INVALID_CLIENT, INVALID_SCOPE, FORBIDDEN, WHITE_LABEL_API_ONLY, PFS_SELECTION_REQUIRED, PFS_ACTIVATION_IN_PROGRESS (503), INTEGRATOR_NOT_READY, CONSENT_STATE_CHANGED, TEMPORARILY_UNAVAILABLE (503), BILLING_TRANSITION_CONFLICT, FIRM_PEPPOL_IDENTITY_REQUIRED a FIRM_IDENTITY_REQUIRED. Limit je 20 žiadostí za minútu.