Onboarding na produkciu

Ako dostať klientsku firmu na ostrý Peppol (príjem aj odosielanie e‑faktúr). Produkčná aktivácia je gateovaná Finančnou správou (FS) — Peppol účastníka nevieme založiť sami, FS to musí autorizovať. Sú na to dve cesty; nižšie je celý proces aj endpointy.

Produkciu spúšťajte až po overení celého toku v sandboxe (Rýchly štart). Produkčný kľúč (efk_pk_live_…) páli kredity a vytvára reálne daňové doklady.

Dve produkčné cesty

Cesta	Kedy	Čo robí partner
A — webhook + e‑mail (odporúčaná)	Firma si na portáli FS zvolí eFaktúru ako poskytovateľa doručovania (PDS). FS pošle mandát webhookom.	Spáruje firmu → eFaktúra pošle firme potvrdzovací e‑mail → firma klikne. Bez tokenu, bez prihlásenia firmy.
B — FS token (záloha)	FS pošle mandát len e‑mailom (bez webhooku), alebo chcete aktivovať priamo.	Získa FS verifikačný token (Verifikačný údaj z PFS) a pošle ho na enroll.

Prečo nie len token? Cesta A nevyžaduje, aby ste manuálne získavali a kopírovali FS token — firma potvrdí príjem klikom v e‑maile. Anti‑misrouting poistka je zachovaná: potvrdzuje schránka firmy (jej FS company_email), nie partner.

Ako to celé funguje (flow)

  PARTNER                    eFaktúra (SP)                 FINANČNÁ SPRÁVA / FIRMA
  ───────                    ─────────────                 ───────────────────────
  1. POST /organizations  ─▶ child org (partner_id)
     (IČO/DIČ/adresa)

                                          firma na PFS zvolí ◀── 2. výber PDS
                                          eFaktúru ako PDS
       FS PDS webhook  ─────────────────▶ 3. mandát prijatý
                                          provisioning + SMP
                                          registrácia 0245:DIČ

  4. POST /:id/peppol-claim ─▶ pošle      ──── e‑mail ────▶  firma dostane
     (re‑send, scope          partnerský                     „Potvrďte príjem…"
      invoice:send)           potvrdzovací mail

                              bind príjmu  ◀──── klik ──────  5. firma potvrdí
                              na child org                    (verejná stránka)

  6. GET /organizations/:id ─▶ claim_status: "claimed"
     (polling)                 participant_id: "0245:DIČ"
                               peppol_eligible: true   ✅ HOTOVO

Krok 4 je často automatický — keď FS webhook nájde spárovanú partner child org pre dané DIČ, eFaktúra pošle potvrdzovací e‑mail sama. peppol-claim slúži na opätovné poslanie (alebo keď ste firmu spárovali až po príchode mandátu).

Kanonická cesta (A) — krok za krokom

Získajte produkčný (live) kľúč

V partnerskom portáli v sekcii API kľúče požiadajte o live kľúč. Produkčné kľúče sú schvaľované (zmluva + licencia) — po schválení si kľúč jednorazovo vygenerujete. Sandbox kľúč (efk_pk_test_…) si vytvoríte okamžite. Base URL je rovnaká pre obe prostredia; rozhoduje prefix kľúča.

Spárujte / založte klientsku organizáciu

Cez POST /v1/agent/organizations založte child org pre firmu (IČO, DIČ — 10 cifier, IČ DPH, úplná adresa). Idempotentné podľa IČO — ak už existuje, vráti sa tá istá. Vyžaduje scope org:provision.

curl -X POST https://api.efaktura.sk/v1/agent/organizations \
  -H "X-API-Key: efk_pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name":"Klient s.r.o.", "ico":"55460399", "dic":"2122027985",
        "ic_dph":"SK2122027985",
        "address":{"street":"Hlavná 1","city":"Trenčín","postalCode":"91101","country":"SK"} }'

Ak váš live kľúč nemá scope org:provision a firma už existuje vo vašom eFaktúra účte, párovanie prebehne podľa IČO. Ak firmu treba založiť a kľúč scope nemá, napíšte na partners@efaktura.sk.

Firma si na portáli FS zvolí eFaktúru ako poskytovateľa

Na Portáli Finančnej správy (PFS) subjekt (firma alebo jej zástupca) zvolí eFaktúru ako poskytovateľa doručovania elektronických faktúr (Peppol PDS). FS následne pošle eFaktúre mandát — obvykle webhookom, ktorý firmu automaticky zaregistruje ako Peppol účastníka 0245:<DIČ>.

Pošlite firme potvrdzovací e‑mail (claim)

Ak mandát prišiel po spárovaní (alebo chcete e‑mail poslať znova), zavolajte POST /v1/agent/organizations/{id}/peppol-claim (scope invoice:send, telo prázdne). eFaktúra pošle na FS company_email firmy mail „Potvrďte príjem e‑faktúr…".

curl -X POST https://api.efaktura.sk/v1/agent/organizations/{org_id}/peppol-claim \
  -H "X-API-Key: efk_pk_live_..."

Odpoveď (pozn.: tento endpoint vracia stav priamo, nie v obálke):

// 202 — e‑mail odoslaný
{ "organization_id": "1ecf…", "status": "pending_email_confirmation" }

// 200 — nič na poslanie
{ "organization_id": "1ecf…", "status": "no_mandate" }      // FS mandát ešte neprišiel
{ "organization_id": "1ecf…", "status": "no_email" }        // mandát nemá e‑mail firmy

// 409 — nejednoznačné priradenie (viď Riešenie problémov)
{ "organization_id": "1ecf…", "status": "collision", "reason": "real_org_exists_for_ico" }

Firma potvrdí príjem klikom v e‑maile

V e‑maile je odkaz na verejnú stránku (žiadne prihlasovanie). Po potvrdení sa príjem e‑faktúr naviaže na vašu child org. Tým je firma naživo na ostrom Peppole pod vaším partnerským účtom.

Overte stav (polling)

Stav sledujte cez GET /v1/agent/organizations/{id}. Hotovo =claim_status: "claimed" a peppol_eligible: true s prideleným participant_id.

curl https://api.efaktura.sk/v1/agent/organizations/{org_id} \
  -H "X-API-Key: efk_pk_live_..."

{
  "organization_id": "1ecf…",
  "ico": "55460399",
  "status": "aktivne",
  "participant_id": "0245:2122027985",
  "peppol_status": "active",
  "claim_status": "claimed",
  "peppol_eligible": true,
  "pending_mandate": false
}

Odteraz firma prijíma e‑faktúry cez Peppol a vy za ňu viete odosielať (vystavenie + send). Príchodzie doklady čítate cez GET /v1/agent/peppol/received a dostávate peppol.document.received webhook.

Záložná cesta (B) — FS token

Keď FS pošle mandát len e‑mailom (bez webhooku) alebo chcete aktivovať priamo, použite FS verifikačný token (Verifikačný údaj, hex z PFS) a zavolajte enroll:

curl -X POST https://api.efaktura.sk/v1/agent/peppol/enroll \
  -H "X-API-Key: efk_pk_live_..." \
  -H "X-Organization-Id: {org_id}" \
  -H "Content-Type: application/json" \
  -d '{ "verificationTokenHex": "a1b2c3…" }'

Token musí byť čistý hex (0‑9, a‑f) bez medzier/zalomení — z viacriadkového .txt sa často zatúlajú whitespace znaky a FS ho odmietne ako invalid_format. Pre live enroll je token povinný; v sandboxe nepovinný.

Stavy organizácie

Pole	Hodnota	Význam
`claim_status`	`claimed`	FS mandát je naviazaný na túto org — príjem aktívny.
`pending_mandate`	`true`	FS mandát prišiel, ale firma ešte nepotvrdila (čaká na klik v e‑maile).
`peppol_status`	`active`	Peppol účet je aktívny (registrovaný v SMP).
`peppol_eligible`	`true`	Org môže odosielať/prijímať na produkčnom Peppole.
`status`	`caka_na_token` / `caka_na_fs` / `aktivne`	Onboarding stav organizácie (čaká na FS overenie → aktívna).

Riešenie problémov

Príznak	Príčina	Riešenie
claim → `409 collision` (`real_org_exists_for_ico`)	Pre to isté IČO existuje ďalšia (ne‑partnerská) reálna org, ktorú nemožno naslepo degradovať.	Napíšte na partners@efaktura.sk — duplikát treba zlúčiť/prepojiť na vašu org.
claim → `no_mandate`	FS mandát pre dané DIČ ešte nedorazil.	Najprv si firma musí zvoliť eFaktúru ako PDS na portáli FS (krok 3).
enroll → `invalid_format`	FS token obsahuje medzery/zalomenia.	Odstráňte všetok whitespace; token je čistý hex.
claim → `403` scope	Kľúč nemá `invoice:send`.	peppol-claim vyžaduje invoice:send (NIE org:provision). Skontrolujte scopes kľúča.

Pozri aj Spustenie naostro (checklist a aktivačné brány) a Chybové kódy.