Iba odosielanie

Č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 a webhook.disabled). 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.