eFakturuj / API Docs
Všetky onboarding návody
Pre partnerov · onboardingDostupné v produkcii

Hromadná príprava, individuálne potvrdenie na FS

Predregistrujte DIČ klientov spolu s e-mailom a telefónom, ktoré zadajú vo VPDS. Po ich voľbe vo VPDS ich eFakturuj automaticky priradí k vášmu partner účtu. Finančná správa dnes dokumentuje potvrdenie samostatne za každý daňový subjekt.

Partner API
až 5 000 DIČ naraz
Finančná správa
1 potvrdenie na subjekt
Priradenie
automaticky podľa DIČ, e-mailu a telefónu

Proces

Hromadné zapojenie v 4 krokoch

  1. 01

    Partner predregistruje DIČ

    JSON API a potvrdenie mandátu.

    Backend pripravený
  2. 02

    Oprávnená osoba potvrdí VPDS

    Samostatne za každý subjekt.

    Manuálny krok
  3. 03

    Webhook spojí DIČ, e-mail a telefón

    Bez kódu, ak sa zhodujú všetky tri údaje.

    Automaticky
  4. 04

    Firma sa sprístupní partnerovi

    Publikovanie siete dobieha asynchrónne.

    Automaticky
0

Vy ako sprostredkovateľ pre svojich zákazníkov

Voliteľný krok, robíme ho my

Pri výbere poskytovateľa vo VPDS môže byť pri každom klientovi uvedený aj sprostredkovateľ — Vaša firma. Je to Vaša voľba: klienti môžu byť zapojení aj bez tohto zápisu, no so zápisom figuruje Vaša firma priamo v označení každého klienta na Finančnej správe.

Toto je samostatný krok a nerobíte ho Vy na portáli, robíme ho my. Zapíšeme Vás do zoznamu Finančného riaditeľstva ako nášho sprostredkovateľa podľa § 76a ods. 5. Žiadosť podávame do 5 pracovných dní od podpisu zmluvy a potrebujeme k tomu iba názov firmy, IČO a DIČ.

Aby ste vedeli dopredu: tento zápis vyžaduje zmluvu na jeden rok pri ktoromkoľvek platenom programe. Hovoríme to hneď na začiatku, aby to pre Vás nebolo prekvapenie neskôr.

Cenník platených programov
VPDS: vybraný poskytovateľ Efakturuj a vybraný sprostredkovateľ — partnerská firma
VPDS zobrazuje pri klientovi poskytovateľa (Efakturuj) aj zvoleného sprostredkovateľa — Vašu firmu.

Ak ste sprostredkovateľ: preposielajte nám správy z FS

Keď si firma vo VPDS vyberie Vás ako sprostredkovateľa, Finančná správa pošle jej údaje na Váš webhook, nie nám. Každú takú správu nám prepošlite. Bez nej firmu nemôžeme zaregistrovať v sieti Peppol.

  • Pošlite ju na POST https://api.efakturuj.sk/api/v1/partner/fs-relay s partnerským API kľúčom v hlavičke X-API-Key (scope invoices:write).
  • Telo pošlite presne tak, ako prišlo od FS, bez úprav, a pridajte hlavičku X-PDS-Secret od FS. Voliteľne aj X-Relay-Received-At s časom, keď ste správu prijali, vo formáte ISO 8601 s posunom od UTC, napríklad 2026-10-27T09:25:00Z alebo 2026-10-27T11:25:00+02:00. Čas bez posunu odmietneme (422).
  • Hlavičku X-PDS-Secret si pri prijatí overte (hex(sha512(telo + tajný kľúč odkazu))), aby ste vedeli, že správa prišla od FS nezmenená. Prepošlite nám ju aj vtedy, keď kontrola nesedí: overíme ju aj my.
  • Preposielajte každú správu, nič nefiltrujte.
  • Správu si uložte presne tak, ako prišla od FS (telo, hlavičku X-PDS-Secret a čas prijatia), kým od nás nedostanete odpoveď 202, v ktorej žiadna firma nemá stav fix_and_resend. Pri chybe alebo bez odpovede ju pošlite znova; opakované odoslanie tej istej správy je bezpečné. Pri stave fix_and_resend nám pošlite pôvodnú správu od FS presne tak, ako prišla. Ak sa stav ani potom nezmení, napíšte nám.

Stav každej firmy uvidíte v konzole v časti Klienti → Prichádzajúce z FS, v odpovedi na volanie (aj v zozname GET /api/v1/partner/fs-relay/arrivals) a vo webhooku client.arrival_updated. Webhook nastavíte tak ako client.linked: v konzole na vlastnej firme, Connect → Webhooks → Add Endpoint, do poľa Events zadajte client.arrival_updated.

1

Predregistrujte klientov

Backend pripravený

Partner API prijíma DIČ a voliteľne celý profil klienta — IČO, IČ DPH, adresu, IBAN aj fakturačný e-mail. Profil sa pri prepojení nasadí na organizáciu, takže je fakturačne použiteľná okamžite (bez IČ DPH prvá odoslaná faktúra neprejde validáciou BT-31 — doplniť sa dá aj neskôr). Požiadavka je idempotentná pre kombináciu partner + DIČ, preto je bezpečné zoznam odoslať znova. DIČ zapisujte ako presne 10 číslic bez medzier a oddeľovačov. Povinné sú aj contact_email a contact_phone: e-mail a telefón, ktoré klient zadá vo VPDS. Klientovi ich pošlite, aby ich zadal presne takto. Záznam, ktorý ešte nie je prepojený, opravíte opakovaným nahratím alebo cez PATCH /api/v1/partner/enrollment-intents/{id}. Pri zmene DIČ cez PATCH pošlite aj mandate_attested: true. Opakované nahratie nahradí celý záznam (polia, ktoré nepošlete, sa vyprázdnia); na zmenu jedného poľa použite PATCH. API kľúč potrebuje scope invoices:write.

POST /api/v1/partner/enrollment-intentsmax. 5 000 položiek
curl -X POST https://api.efakturuj.sk/api/v1/partner/enrollment-intents \
  -H 'X-API-Key: efk_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "mandate_attested": true,
    "items": [
      {
        "dic": "2020123456",
        "legal_name": "Klient A, s. r. o.",
        "ico": "12345678",
        "vat_id": "SK2020123456",
        "street": "Hlavná 1",
        "city": "Bratislava",
        "postal_code": "81101",
        "iban": "SK31…",
        "billing_email": "fakturacia@klient-a.sk",
        "contact_email": "konatel@klient-a.sk",
        "contact_phone": "+421 905 123 456"
      },
      { "dic": "2120000001", "legal_name": "Klient B, s. r. o.", "contact_email": "info@klient-b.sk", "contact_phone": "0905 654 321" }
    ]
  }'

Mandát v eFakturuj

mandate_attested: true je vyhlásenie partnera, že má oprávnenie za uvedených klientov. Nenahrádza registráciu zastupovania ani rozsah oprávnení evidovaný vo Finančnej správe. Rovnaké DIČ nepredregistrujte cez viac partner účtov; prednosť má najstarší čakajúci záznam, ktorého e-mail a telefón sa zhodujú s údajmi klienta vo VPDS.

CSV a úplný profil

Úplný profil klienta (adresa, IČ DPH, IBAN, fakturačný e-mail) je už súčasťou API požiadavky a pri prepojení sa nasadí na organizáciu.

Platiteľ DPH musí mať v zázname vyplnené IČ DPH. Bez neho sa faktúry firmy od verzie 1.2.213 tlačia ako doklad neplatiteľa DPH (nadpis FAKTÚRA a poznámka „Nie je platiteľ DPH.“), nie ako daňový doklad.

Zoznam môžete nahrať aj ako súbor .csv alebo .xlsx (najviac 5 000 riadkov, 10 MB) v konzole alebo cez POST /api/v1/partner/enrollment-intents/import. Šablónu stiahnete na GET /api/v1/partner/enrollment-intents/import-template?format=csv|xlsx. Povinné stĺpce: DIČ, Kontaktný e-mail, Kontaktný telefón; odmietnuté riadky vrátime s číslom riadku a dôvodom.

2

Potvrďte jedného klienta vo VPDS

Jediný manuálny krok

Klient alebo jeho zástupca evidovaný vo Finančnej správe sa prihlási podporovaným spôsobom, vyberie daňový subjekt, doplní e-mail a telefón, udelí súhlas a žiadosť odošle. Zástupca môže vidieť viac klientov podľa svojich oprávnení, ale výber vykonáva po jednom.

  1. 1Otvorte priamy odkaz na Efakturuj vo VPDS.
  2. 2Prihláste sa a zvoľte jeden daňový subjekt.
  3. 3Skontrolujte údaje z FS a doplňte e-mail a telefón.
  4. 4Povoľte poskytnutie údajov a odošlite žiadosť.
Obrazovka VPDS s nadpisom Výber daňového subjektu a rozbaľovacím poľom Vyberte subjekt.
Vo VPDS vyberte subjekt, za ktorý vykonávate označenie.Kliknutím zväčšíte

Zamknutá firma a jej prvý správca

Keď sa DIČ, e-mail aj telefón zhodujú s Vašou predregistráciou, firma sa pri označení vo VPDS zamkne u Vás: odvtedy ju nikto neaktivuje žiadnym aktivačným kódom, kým ju neuvoľníte. Prístup pre ľudí firmy vytvárate Vy: v konzole partnera v časti Hromadné zaradenie alebo na stránke klienta (záložka Používatelia) vytvoríte správcu firmy. Dostane e-mail s odkazom na nastavenie hesla (platí 7 dní) a pri prvom prihlásení SMS kód. Ak e-mail už má účet v eFakturuj, firma sa k nemu pridá. Môžete zapnúť aj automatické vytvorenie správcu hneď po zamknutí. Ak sa e-mail alebo telefón nezhoduje, firma sa nezamkne a aktivuje sa samostatne aktivačným kódom (detail v postupe Aktivácia firmy).

3

Webhook priradí firmu podľa DIČ, e-mailu a telefónu

Automaticky

Po potvrdení VPDS odošle Finančná správa webhook. eFakturuj nájde najstarší čakajúci partner záznam s rovnakým DIČ, e-mailom aj telefónom, ako klient zadal vo VPDS, a priradí k nemu organizáciu. Ak sa e-mail alebo telefón nezhoduje, firma sa neprepojí: záznam dostane stav contact_mismatch a firma pokračuje bežnou registráciou s aktivačným kódom. Opravte záznam a klient zvolí eFakturuj vo VPDS znova. Stav contact_mismatch zruší zmena DIČ, contact_email alebo contact_phone v zázname, alebo prepojenie; úprava ostatných polí (napríklad názvu, adresy alebo fakturačného e-mailu) ani opakované nahratie nezmenených údajov ho nezruší.

pendingPOST /api/v1/webhooks/fs/pds-onboardinglinked
4

Firma sa sprístupní v partner API

Automaticky

eFakturuj vytvorí pracovný priestor, uloží partner väzbu a odvodí Peppol ID. Stav môžete sledovať cez GET /api/v1/partner/enrollment-intents — alebo push formou cez lifecycle webhooky nižšie.

Lifecycle webhooky: client.linked a client.activated

Automaticky
  • client.linked — vystrelí v momente spracovania FS webhooku: DIČ, e-mail aj telefón sa zhodli s Vašou predregistráciou, organizácia je priradená k partnerovi a profil klienta je nasadený.
  • client.activated — vystrelí, keď je účastník overený v sieti Peppol (SMP/SML publikovanie dokončené). Od tohto momentu je firma plne prevádzkyschopná: smerovateľná, schopná prijímať aj odosielať. Prihlásenie klienta nemá na túto udalosť žiadny vplyv.

Kde sa konfiguruje

V konzole na vlastnej firme partnera: Connect → Webhooks → Add Endpoint. Do poľa Events zadajte client.linked,client.activated (možno kombinovať s invoice eventami). Doručovanie ide štandardným webhook kanálom — HMAC-SHA256 podpis, automatické opakovanie pri 5xx a delivery log priamo v konzole.

Payload

{
  "id": "3f6c…",
  "event": "client.activated",
  "created_at": "2026-08-29T10:15:00+00:00",
  "data": {
    "organisation_id": "48ecb56f-…",
    "dic": "2020555666",
    "name": "Klient A, s. r. o.",
    "peppol_id": "0245:2020555666"
  }
}

Realita vs. cieľ

Stav funkcií

Stav funkcií hromadného zapojenia klientov
FunkciaStavPoznámka
JSON predregistrácia DIČBackend pripravenýAž 5 000 položiek, idempotentné opakovanie.
Úplný profil klienta v APIBackend pripravenýAdresa, IČ DPH, IBAN, e-mail — nasadia sa pri prepojení.
Individuálny výber vo VPDSManuálneOficiálne zdokumentovaný proces FS.
DIČ + e-mail + telefón auto-link + client.linkedBackend pripravenýPartner väzba sa vytvorí po webhooku, iba ak sa zhodujú všetky tri údaje; inak stav contact_mismatch.
SMP/SML publikovanieBackend pripravenýSpustené po webhooku, dokončenie je asynchrónne.
Partner webhooky client.linked / client.activatedBackend pripravenýlinked = priradenie po webhooku; activated = účastník overený v sieti. Nastavíte v Connect → Webhooks na vlastnej firme partnera (pridajte tieto eventy k endpointu).
Zamknutie firmyHotové (1.2.216)Zamknutú firmu neaktivuje žiadny kód, kým ju partner neuvoľní.
Správca firmy od partneraHotové (1.2.216)Odkaz na nastavenie hesla 7 dní, SMS pri prvom prihlásení; existujúci účet sa pridá.
Hromadné a automatické vytvorenie správcovHotové (1.2.216)Najviac 500 naraz; automatika sa zapína v konzole.
Nahratie zoznamu zo súboruHotové (1.2.216)CSV alebo XLSX, šablóna v slovenčine.
Uvoľnenie firmy partneromPripravuje saSamostatná špecifikácia.

Oficiálne zdroje FS