Spustenie naostro

Checklist prechodu zo sandboxu do produkcie. V sandboxe overte celý tok, potom prepnite na produkčný kľúč, base URL ostáva rovnaká.

Pred spustením

Otestované v sandboxe

Vystavenie faktúry, odoslanie cez Peppol a (ak relevantné) prijatie dokladu prebehlo v sandboxe s kľúčom efk_pk_test_….

Ošetrené chyby a 429

Aplikácia korektne spracúva chybové kódy a rešpektuje Retry-After pri rate limite.

Bezpečné uloženie kľúčov

Kľúče sú v server-side prostredí / secret store, nie v klientskom kóde ani v repozitári.

Idempotencia

Pri opakovaní požiadaviek si ukladáte id vytvorených dokladov, aby ste predišli duplicitám.

Mapovanie organizácií

Pre každú klientsku organizáciu posielate správne X-Organization-Id.

Prepnutie na produkciu

Produkčný kľúč

Administrátor po aktivácii partnera vydá produkčný kľúč efk_pk_live_…. Nahraďte ním sandbox kľúč v produkčnej konfigurácii.

Reálne odoslanie

Live odoslania idú reálne cez Peppol: overte si fakturáciu/kredity a stav doručenia v sekcii Dokumenty.

Jedna cesta kódu: v sandboxe aj v produkcii volajte rovnaké endpointy v rovnakom poradí, vrátane POST /v1/agent/peppol/enroll s tokenom. Prechod na produkciu je výmena testovacieho kľúča za live kľúč. Rozdiely a časový plán sú v Sandbox vs. produkcia.

Sandbox a produkcia sú oddelené iba prefixom kľúča. Skontrolujte, že v produkcii naozaj používate efk_pk_live_… a nie testovací kľúč.

FS verifikačný token

Produkčný (live) Peppol enroll vyžaduje FS verifikačný token, hex kód z verifikácie DIČ na Finančnej správe. V sandboxe je povinný tiež, stačí ľubovoľný hex (mäkký sandbox účtov registrovaných pred 02.10.2026 ho do 01.11.2026 nevyžaduje a vráti varovanie), pri efk_pk_live_… kľúči je povinný vždy a bez neho POST /v1/agent/peppol/enroll vráti VALIDATION_ERROR.

Token sa posiela v tele enrollu ako verificationTokenHex (lowercase / uppercase hex). Klient ho dostane na portáli Finančnej správy: keď si tam zvolí poskytovateľa, Finančná správa mu vydá verifikačný kód (Verifikačný údaj) a nám pošle mandát. Organizáciu klienta preto založte cez POST /v1/agent/organizations skôr, než klient poskytovateľa zvolí.

Enroll s tokenom nie je jediná cesta. Bez neho pošle eFaktúra klientovi potvrdzovací e‑mail, klient klikne a organizácia sa aktivuje sama (webhook participant.activated so source: "partner_claim"). Ak chcete, aby klient e‑mail od nás nedostal, zapnite v portáli (Tím) „Potvrdenie príjmu cez vaše API“ a kód od klienta pošlite cez enroll. Oba toky: Onboarding na produkciu.

POST /v1/agent/organizations/{id}/activation-token s telom { "token": "…" } len zaznamená stav onboardingu (caka_na_token → caka_na_fs). Finančnej správe nič neposiela a organizáciu neaktivuje, na aktiváciu ho nepotrebujete.

Offboarding organizácie (zrušenie Peppol príjmu)

Odchod klienta alebo prechod k inému poskytovateľovi spustíte bez tiketu: POST /v1/agent/organizations/{id}/peppol/deactivate (scope org:provision). Odregistrujeme účastníka zo SMP, pozastavíme príjem, zrušíme viazaný FS mandát a organizáciu prepneme na deaktivovane. Odpoveď nesie status (deactivated alebo already_inactive pri opakovanom volaní), participant_id a deregistered_at; partnerské endpointy dostanú udalosť participant.deactivated.

Rozpracované prenosy sa dokončia skôr, než odregistrujeme účastníka: kým má organizácia odoslania v stave QUEUED alebo SENDING, volanie vráti 409 PEPPOL_PENDING_TRANSFERS s počtom v details.pending_transfers. Zopakujte ho neskôr alebo pošlite telo { "force": true }. Prijaté doklady, originálne UBL a evidencia doručenia ostávajú dostupné cez API aj po deaktivácii. Opätovná aktivácia: POST /v1/agent/peppol/enroll s novým FS tokenom.

Aktivácia partnera: 4 kroky

Produkčný prístup (a s ním kľúč efk_pk_live_…) prechádza štyrmi krokmi priamo v partnerskom portáli: celý priebeh sledujete na Prehľade (sekcia Onboarding), žiadne manuálne e‑maily s kľúčom alebo prílohami. Podpis dokumentov nikdy automaticky neodošle ani neschváli produkčnú žiadosť.

Program a dokumenty

Na Prehľade vyberiete produkčný program. Systém pripraví API partnerskú zmluvu; pri white-label partnerovi pripraví naraz white-label zmluvu aj NDA.

Zmluva: podpis kódom z e-mailu

Dokumenty s dohodnutými podmienkami podpíšete cez odkaz priamo v portáli: skontrolujete PDF, vyplníte meno a funkciu podpisujúceho, vyžiadate si 6-miestny kód e-mailom na kontaktnú adresu partnera a zadaním kódu zmluvu podpíšete: žiadne kreslenie, tlačenie ani skenovanie. Finálne podpísané PDF (s auditným záznamom overenia kódu) je na stiahnutie v portáli aj v potvrdzujúcom e‑maile. White-label pokračuje až po podpise zmluvy aj NDA.

Žiadosť o produkciu

Až po podpise všetkých povinných dokumentov sa zobrazí tlačidlo „Odoslať žiadosť o produkciu“. Jedným kliknutím odošlete žiadosť do Owner panela eFaktúry; dovtedy nevzniká žiadna produkčná žiadosť.

Schválenie a LIVE kľúč

eFaktúra Owner žiadosť manuálne skontroluje a klikne na „Schváliť a aktivovať produkciu“. Až potom sa aktivuje produkcia a v onboardingu si jednorazovo zobrazíte kľúč efk_pk_live_…. Uložte si ho hneď; neskôr sa už celý nezobrazí. API – Mesačný program: faktúra mesačne pozadu; Ročný program: po aktivácii príde faktúra na platbu vopred na 12 mesiacov (splatnosť 14 dní). White-label je len v Ročnom programe: po schválení príde faktúra na platbu vopred a LIVE kľúč sa zobrazí až po jej úhrade.

SAPI-SK je voliteľné: ak rozhranie nepoužívate, krok sa vás netýka a nič vám neblokuje postup cez zvyšné kroky.

Zmena dohodnutých podmienok po podpise (objem, balík, cenník) nemení existujúcu zmluvu: pri renegociácii sa vygeneruje a znova podpíše nová zmluva s aktuálnymi podmienkami; pôvodná zostáva ako archívny záznam.

Kredity a fakturácia

Sandbox je vždy zadarmo: test sendy (efk_pk_test_…) idú cez TEST sieť, neúčtujú sa a nestrhávajú kredity. Produkčné odoslanie cez Peppol spotrebúva kredit / účtuje sa za transakciu.

Obdobie	Účtovanie produkčných sendov
Do 30. 11. 2026 (promo)	Základný poplatok 0 € do promo limitu transakcií za mesiac (API 1000 tx/mesiac, neprorátuje sa). Spotreba nad limit sa fakturuje mesačne pozadu sadzbou celkového objemu; na účtovanú sumu sa vzťahuje minimálna mesačná platba 10 € bez DPH (v promo období len v mesiaci s účtovanou transakciou). White-label partneri (zmluvy od 5. 9. 2026) platia minimálnu mesačnú platbu 99 € bez DPH za každý mesiac od aktivácie produkcie; pokrýva objem až 2 500 transakcií mesačne. White-label je len v Ročnom programe – platba vopred na 12 mesiacov; LIVE kľúč sprístupníme po jej úhrade.
Od 1. 12. 2026	Objemový cenník: mesačný objem transakcií určí jednu sadzbu (0,055 – 0,0194 € / tx) na celý objem; odoslaný doklad a dobropis = 1 tx, prijatý doklad = 0,5 tx. Dva programy: Ročný program – platba vopred (tabuľkové sadzby ×1,00; 12 mesiacov sa platí vopred z odhadu objemu po aktivácii, pásmo z ročného objemu, vyúčtovanie po 12 mesiacoch) a Mesačný program – bez viazanosti (×1,20; pásmo z objemu daného mesiaca, faktúra mesačne pozadu). Bez vstupného poplatku; minimálna mesačná platba 10 € bez DPH za každý kalendárny mesiac od aktivácie produkcie, aj bez transakcií (v oboch programoch rovnako, koeficient ×1,20 sa na ňu nevzťahuje). Cenník a kalkulačka: efaktura.sk/api-rest.

Obdobie

Účtovanie produkčných sendov

Do 30. 11. 2026 (promo)

Základný poplatok 0 € do promo limitu transakcií za mesiac (API 1000 tx/mesiac, neprorátuje sa). Spotreba nad limit sa fakturuje mesačne pozadu sadzbou celkového objemu; na účtovanú sumu sa vzťahuje minimálna mesačná platba 10 € bez DPH (v promo období len v mesiaci s účtovanou transakciou). White-label partneri (zmluvy od 5. 9. 2026) platia minimálnu mesačnú platbu 99 € bez DPH za každý mesiac od aktivácie produkcie; pokrýva objem až 2 500 transakcií mesačne. White-label je len v Ročnom programe – platba vopred na 12 mesiacov; LIVE kľúč sprístupníme po jej úhrade.

Od 1. 12. 2026

Objemový cenník: mesačný objem transakcií určí jednu sadzbu (0,055 – 0,0194 € / tx) na celý objem; odoslaný doklad a dobropis = 1 tx, prijatý doklad = 0,5 tx. Dva programy: Ročný program – platba vopred (tabuľkové sadzby ×1,00; 12 mesiacov sa platí vopred z odhadu objemu po aktivácii, pásmo z ročného objemu, vyúčtovanie po 12 mesiacoch) a Mesačný program – bez viazanosti (×1,20; pásmo z objemu daného mesiaca, faktúra mesačne pozadu). Bez vstupného poplatku; minimálna mesačná platba 10 € bez DPH za každý kalendárny mesiac od aktivácie produkcie, aj bez transakcií (v oboch programoch rovnako, koeficient ×1,20 sa na ňu nevzťahuje). Cenník a kalkulačka: efaktura.sk/api-rest.

Partnerské promo (koniec 30. 11. 2026) je odlišné od FA web promo (koniec 1. 1. 2027, per‑org kreditový model), preto ich nezamieňajte. Ak pri live sende nie je dostatok kreditu, POST /v1/agent/peppol/send vráti 402 s kódom INSUFFICIENT_CREDIT.

Potrebujete pomoc s nasadením? Kontaktujte nás cez partnerský portál alebo na podpora@efaktura.sk.