Prístup k API

Tri cesty k API

Ak firma používa vlastný softvér, aktivuje API v Nastaveniach a vloží si kľúč. Ak ju pripája program partnera, program jej otvorí odkaz na súhlas, firma ho potvrdí a program ďalej pracuje s kľúčom partnera.

Firma, ktorá ostáva pri inom poštárovi, dnes môže odosielať cez ePošťák iba cez program partnera; samostatná registrácia iba na odosielanie zatiaľ nie je.

Vlastný kľúč: Nastavenia → API

1. 1

   1. Objednajte a aktivujte API

   V Nastaveniach → API je štandardná objednávka: bez mesačného paušálu a minimálnej viazanosti, spotrebu platí firma podľa cenníka. Po súhlase s podmienkami kliknite Objednať a aktivovať API. Štandardnú objednávku aktivujeme automaticky po overení podmienok.

2. 2

   2. Vytvorte produkčný API kľúč

   Kliknite Vytvoriť produkčný API kľúč. Zobrazí sa client_id a client_secret; celý client_secret sa ukáže iba raz, preto si ho hneď uložte.

3. 3

   3. Vložte kľúč do svojho softvéru

   client_id a client_secret zadajte priamo do svojho účtovného alebo ERP systému. Neposielajte ich e-mailom dodávateľovi ani podpore.

Program partnera krok za krokom

Partner má od ePošťáka jeden partnerský kľúč (client_id a client_secret). Tým istým kľúčom vytvára odkazy na súhlas a po súhlase pracuje s každou pripojenou firmou. Token získate cez POST /api/v1/auth/token (rovnaký endpoint ako /sapi/v1/auth/token).

1. 1

   1. Partner vytvorí odkaz na súhlas

   POST /api/v1/consent-offers s DIČ (alebo IČO) firmy, režimom, rozhraniami a oprávneniami (odporúčaný endpoint; POST /api/v1/firms/consent-link ostáva ako staršia možnosť s rovnocennými údajmi). Odpoveď obsahuje consentUrl, platný 14 dní. Voliteľné returnUrl (https, origin registrovaný pre partnera) vráti klienta do vášho programu po potvrdení. Bez programovania vytvoríte ten istý odkaz v partnerskom portáli v časti Consenty.

2. 2

   2. Program otvorí odkaz zákazníkovi

   Zákazník klikne v programe na tlačidlo, ktoré otvorí consent_url v prehliadači. Odkaz môžete poslať aj e-mailom.

3. 3

   3. Zákazník sa prihlási a potvrdí súhlas

   Stránka ukáže partnera, firmu a rozsah oprávnení. Zákazník sa prihlási do ePošťáka ako vlastník alebo správca firmy a súhlas potvrdí. Ak firma ešte nemá účet v ePošťáku, najprv si na vpds.financnasprava.sk vyberie ePošťáka ako poštára a potom odkaz otvorí znova. Žiadny kľúč nevidí ani nikam nevkladá.

4. 4

   4. Program zistí firm_id

   GET /api/v1/firms/consent-status?dic=… Po potvrdení vráti consent_status: active, next_action: use_firm_id a firm.id. Kým zákazník nepotvrdí, vracia await_consent_acceptance. Webhook o potvrdení neposielame, stav preto overujte opakovane alebo po návrate zákazníka do programu.

5. 5

   5. Program volá API za firmu

   Každé volanie za firmu posiela partnerský token a hlavičku X-Firm-Id: firm.id. Ak program beží u zákazníka, použite namiesto hlavného kľúča kľúč obmedzený na firmu (nasledujúca časť).

curl -X POST "https://epostak.sk/api/v1/consent-offers" \
  -H "Authorization: Bearer <PARTNERSKY_JWT>" \
  -H "Content-Type: application/json" \
  -d '{"targetIdentifierType":"dic","targetIdentifier":"2022988022","customerReference":"ZAKAZNIK-001","requestedInterfaces":["enterprise_api"],"relationshipMode":"technical_delegation","scopes":["firms:manage","documents:send","documents:read"],"returnUrl":"https://program.example/spat"}'

# 201 → {"id":"…","consentUrl":"https://epostak.sk/auth/integrator-consent?token=…","status":"issued","expiresAt":"…"}
# Webhooky consent.accepted, consent.revoked a consent.expired: PUT /api/v1/onboarding-requests/webhook
# Ďalšie: consent.declined (nextAction contact_client), consent.awaiting_pfs, consent.scopes_updated, webhook.disabled

curl "https://epostak.sk/api/v1/firms/consent-status?dic=2022988022" \
  -H "Authorization: Bearer <PARTNERSKY_JWT>"

# 200 → {"firm":{"id":"<FIRM_ID>",…},"consent_status":"active","next_action":"use_firm_id"}

Program nainštalovaný u zákazníka: kľúč pre jednu firmu

Hlavný partnerský kľúč pracuje so všetkými vašimi firmami. Do inštalácie u zákazníka ho preto nedávajte. Po súhlase vydajte pre firmu vlastný kľúč obmedzený na ňu: POST /api/v1/integrator/keys so scopedFirmId = firm.id. Odpoveď obsahuje clientId a jednorazovo zobrazený key (client_secret). Tieto dve hodnoty nastavíte do inštalácie zákazníka.

Inštalácia si s týmto kľúčom získa token cez POST /api/v1/auth/token a volá API s hlavičkou X-Firm-Id: firm.id. Pre inú firmu kľúč nefunguje. Ak zákazník súhlas odvolá, kľúč prestane fungovať.

Kroky 1, 4 a vydanie kľúča robí váš server s hlavným kľúčom. Ak server nemáte, urobíte ich ručne v partnerskom portáli: Consenty (odkaz) a API kľúče (kľúč pre firmu).

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

# 201 → {"clientId":"<CLIENT_ID>","key":"sk_int_…","scopedFirmId":"<FIRM_ID>",…}

Iba odosielanie: firma ostáva u iného poštára

• Návod Iba odosielanie cez partnera

• Partner pošle žiadosť POST /api/v1/onboarding-requests s DIČ firmy. Firma na portáli Finančnej správy vyberie ePošťák a potvrdí jednu stránku z e-mailu. 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. Celý postup, stavy a webhooky opisuje návod Iba odosielanie.
• Firmy môže takto pripájať každý partner s platnou produkčnou zmluvou, ktorá pokrýva Enterprise API: technický partner (platí firma) alebo spravovaný integrátor (platí integrátor). Samostatné povolenie od ePošťáka netreba.
• Priama zmluva firmy na Enterprise API (firma používa API iba sama pre seba) neoprávňuje pripájať iné firmy.

Príjem: cez ePošťák alebo ostáva u vášho poštára

• Prijímať cez ePošťák — firma je v SMP u nás a doklady prijíma v ePošťáku.
• Iba odosielať — SMP nemeníme, príjem ostáva u vášho súčasného poštára. Odosielame ako 0245:DIČ; odpovede a prijaté faktúry idú tam, kde je firma zapísaná v SMP. Túto voľbu dnes ponúka iba pripojenie cez program partnera.
• Príjem k nám nikdy nepresunieme potichu; prechod ide existujúcim postupom zmeny poštára.

Kto platí