Send-only referencia
Registračné API
Presný kontrakt onboardingových volaní: autentifikácia, telo, idempotencia, stavy a to, čo partner nikdy nedostane.
Predpoklady
- Neobmedzený partnerský kľúč (nie kľúč viazaný na jednu firmu) s firms:manage.
- Aktuálna produkčná zmluva s Enterprise API pre daný typ vzťahu. Samostatné povolenie od ePošťáka netreba.
POST /api/v1/onboarding-requests
- Hlavička Idempotency-Key má 8–128 znakov a musí byť stabilná pri opakovaní tej istej požiadavky.
- Volanie je bez X-Firm-Id; partner koná ako partner, nie ako klientska firma.
- Kľúč partnera musí byť prevádzkovo povolený; samotné oprávnenie firms:manage nestačí.
- Odpoveď má kód 202 a rovnaký tvar ako GET: stav, nextAction a clientMessage { sk, en } s textom, ktorý môžete zobraziť firme.
| Pole | Povinné | Význam |
|---|---|---|
| serviceMode | áno | Pre túto cestu hodnota send_only. |
| relationshipMode | nie | technical_delegation (predvolené; platí firma) alebo managed_service (platí integrátor). |
| customerRef | áno | Stabilné označenie klientskej firmy vo vašom ERP. |
| dic | áno | DIČ firmy, na ktorú sa požiadavka vzťahuje. |
| contactEmail | áno | Kontakt pre evidenciu; nie je adresát PFS pozvánky ani dôkaz identity. |
{
"id": "<REQUEST_ID>",
"customerRef": "erp-klient-42",
"serviceMode": "send_only",
"status": "awaiting_pfs",
"relationshipMode": "technical_delegation",
"payerMode": "firm_billed",
"keyCreation": null,
"firmId": null,
"nextAction": "select_provider_on_pfs",
"clientMessage": {
"sk": "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.",
"en": "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."
}
}GET /api/v1/onboarding-requests/{id}
- Vracia stav vašej vlastnej požiadavky; partner nevidí cudzie požiadavky.
- Až stav active sprístupní firmId a možnosť vytvorenia kľúča.
- Aktivačný odkaz a PFS token sa partnerovi nevracajú nikdy, ani počas čakania na aktiváciu.
status -> nextAction
awaiting_pfs -> select_provider_on_pfs
action_required -> complete_client_activation
activating -> provider_approval
active -> null (firmId and keyCreation available)
revoked -> null
blocked -> null
expired -> nullExpirovaná a odvolaná žiadosť
- Žiadosť, ktorú firma nepotvrdí do 30 dní od poslednej zmeny, prejde do stavu expired a partner dostane onboarding.expired.
- Expirovanú žiadosť znovu otvoríte novým POST s rovnakým customerRef a rovnakým telom, ale s novým Idempotency-Key. Žiadosť si ponechá svoje id a začne znova v stave awaiting_pfs (alebo rovno active, ak už platné prepojenie existuje).
- Odvolanú žiadosť (revoked) znovu otvoriť nemožno. Firmu pripojte novou žiadosťou s novým customerRef.
Webhook pre onboarding: PUT, GET a DELETE /api/v1/onboarding-requests/webhook
- Partner má jeden webhook pre onboarding, bez X-Firm-Id. PUT ho vytvorí alebo nahradí (url a events), GET ho prečíta, DELETE ho zruší. PUT a DELETE vyžadujú webhooks:write, GET webhooks:read.
- url musí byť https. events je neprázdny zoznam z: onboarding.pfs_received, onboarding.signed, onboarding.review_required, onboarding.active, onboarding.expired, onboarding.revoked.
- Tajomstvo na overenie podpisu (secret) sa vráti iba raz: pri vytvorení (201) alebo po opätovnom vytvorení po DELETE. Ďalšie PUT (200) menia url a udalosti a tajomstvo ponechajú.
curl -X PUT "https://epostak.sk/api/v1/onboarding-requests/webhook" \
-H "Authorization: Bearer <PARTNERSKY_JWT>" \
-H "Content-Type: application/json" \
-d '{
"url": "https://erp.example/hooks/epostak",
"events": ["onboarding.pfs_received", "onboarding.signed", "onboarding.review_required", "onboarding.active", "onboarding.expired", "onboarding.revoked"]
}'{
"webhook": {
"url": "https://erp.example/hooks/epostak",
"events": ["onboarding.pfs_received", "onboarding.signed", "onboarding.review_required", "onboarding.active", "onboarding.expired", "onboarding.revoked"],
"isActive": true
},
"secret": "<TAJOMSTVO_ZOBRAZENE_IBA_RAZ>"
}Čo partner nikdy nedostane
- Verification token, provider secret ani aktivačný odkaz.
- Prístup k prijatej pošte firmy, k cudzím dokumentom alebo k nepoverovaným dokladom.
- Možnosť zmeniť platiteľa svojvoľne z requestu.
Očakávaný výsledok
Požiadavka existuje pod vaším Idempotency-Key, jej stav je čitateľný a kľúč vznikne až po stave active.
Keď to nefunguje
- 403 pri vytvorení: kľúč je obmedzený na firmu, chýba firms:manage alebo produkčná zmluva partnera nepokrýva Enterprise API pre zvolený relationshipMode (SEND_ONLY_NOT_AUTHORIZED).
- 409 ONBOARDING_CONFLICT: customerRef alebo Idempotency-Key už patrí žiadosti s iným telom. Pri opakovaní použite rovnaký Idempotency-Key a rovnaké telo; pre inú firmu použite nový customerRef.
- 400 INVALID_REQUEST: skontrolujte serviceMode, relationshipMode, dic a kontakt. 400 INVALID_IDEMPOTENCY_KEY: chýba hlavička Idempotency-Key alebo nemá 8–128 znakov.