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 Enterprise autorizácia pre daný typ vzťahu a povolenie na tento onboarding.
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čí.
| 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. |
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Č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 partner nemá povolený tento onboarding.
- Konflikt pri opakovaní: použite rovnaký Idempotency-Key a rovnaké telo; nové telo znamená novú požiadavku.
- 422 pri tele: skontrolujte serviceMode, relationshipMode, dic a kontakt.