Registrácia a aktivácia
Ako si vybrať Digitálneho poštára na Finančnej správe
Zjednodušená používateľská príručka pre podnikateľov
Krok 1 – Výber digitálneho poštára a prihlásenie
Aplikácia je dostupná na Portáli finančnej správy. Prihlásiť sa môžete cez Slovensko.sk alebo identifikátorom a heslom. Ak nemáte účet na Portáli finančnej správy, je potrebné si ho najskôr vytvoriť. Na stránke https://vpds.financnasprava.sk/ sa ako prvá zobrazí obrazovka „Potvrdenie súhlasu s cookies“, ktorú môže používateľ potvrdiť tlačidlom Súhlasím alebo odmietnuť tlačidlom Nesúhlasím. Následne sa zobrazí úvodná obrazovka “ Zoznam certifikovaných poskytovateľov doručovacej služby a ich sprostredkovateľov“ so zoznamom poskytovateľov a sprostredkovateľov. Zoznam je dostupný aj neprihláseným používateľom.

Vyberte si svojho poskytovateľa a sprostredkovateľa tlačidlom Výber.
Zobrazia sa údaje vybraného poskytovateľa a sprostredkovateľa. Kliknite na tlačidlo Pokračovať.

Používateľ sa môže prihlásiť:
- Prostredníctvom portálu slovensko.sk – Prihlásenie občianskym preukazom s čipom (eID), dokladom o pobyte s čipom, aplikáciou Slovensko v mobile alebo prihlasovacím prostriedkom vydaným v krajine EÚ
- Identifikátor a heslo – Prihlásenie zadaním ID používateľa a hesla.

Prihlásenie sa pomocou portálu slovensko.sk
- Na obrazovke prihlásenia vyberte možnosť „Prostredníctvom portálu slovensko.sk“.
- Prihláste sa jedným z podporovaných spôsobov:

Po úspešnom prihlásení budete presmerovaní do aplikácie Digitálny poštár.
Prihlásenie sa identifikátorom a heslom
- Na obrazovke prihlásenia vyberte možnosť „Identifikátor a heslo“.
- Zadajte svoj identifikátor a heslo a potvrďte tlačidlo Prihlásiť sa.

Krok 2 – Potvrdenie prístupu
Pri prvom prihlásení do aplikácie je potrebné potvrdiť prístup k údajom z Portálu finančnej správy.
- Prečítajte si informácie o požadovaných prístupoch.
- Kliknite na tlačidlo Pokračovať.
- Po potvrdení môžete pokračovať vo výbere digitálneho poštára.
Dôležité: Bez potvrdenia prístupu nie je možné aplikáciu používať. Poznámka: Udelené súhlasy môžete neskôr spravovať v Osobnej internetovej zóne (OIZ) v časti Profil používateľa.

Krok 3 – Výber daňového subjektu
- Zo zoznamu vyberte daňový subjekt, za ktorý konáte.
- Skontrolujte zobrazené identifikačné údaje subjektu.
- Kliknite na Pokračovať.
Dôležité: Pokračovať môžete len so subjektom, ktorý má pridelené a oznámené DIČ. Upozornenie: Ak vybraný subjekt nemá pridelené DIČ, systém zobrazí chybové hlásenie a nebude možné pokračovať.

Po výbere subjektu sa automaticky zobrazia jeho identifikačné údaje:
- IČO
- DIČ
- Adresa sídla
Skontrolujte zobrazené údaje a kliknite na Pokračovať.
Krok 4 – Zadanie kontaktných údajov
Po výbere daňového subjektu vyplňte jeho kontaktné údaje:
- Telefónne číslo
Telefónne číslo zadajte v medzinárodnom formáte, napríklad +421 900 123 456. Po vyplnení údajov kliknite na Pokračovať.
Dôležité: Polia E-mail a Telefón sú povinné. Ak nie sú vyplnené alebo sú zadané v nesprávnom formáte, systém zobrazí chybové hlásenie a nebude možné pokračovať.

Krok 5 – Udelenie súhlasu
Skontrolujte zobrazené údaje subjektu a vybraného digitálneho poštára.
Ak sú údaje správne, kliknite na Povoliť.
Tým udelíte súhlas na odovzdanie údajov vybranému digitálnemu poštárovi, ktorý zabezpečí doručovanie elektronických faktúr.
Poznámka: Pred udelením súhlasu si môžete zobraziť podrobné informácie kliknutím na odkaz Viac informácií.

Krok 6 – Kontrola údajov
Pred odoslaním žiadosti sa zobrazí prehľad zadaných údajov o daňovom subjekte, digitálnom poštárovi a poskytovateľovi doručovacej služby.
Skontrolujte správnosť zobrazených údajov, najmä:
- obchodné meno,
- DIČ,
- e-mail,
- telefónne číslo.
Ak sú všetky údaje správne, kliknite na Pokračovať. Po potvrdení budú údaje odoslané vybranému digitálnemu poštárovi.

Krok 7 – Potvrdenie odoslania
Žiadosť o výber digitálneho poštára bola úspešne odoslaná. Na obrazovke sa zobrazí potvrdenie o odoslaní spolu so zhrnutím odoslaných údajov. Po spracovaní žiadosti bude vybraný digitálny poštár informovaný o vašom výbere a môže vás kontaktovať prostredníctvom zadaných kontaktných údajov.

Ako získať autorizáciu na Portáli finančnej správy
Používateľská príručka na získanie autorizácie
Krok 1 – Prihlásenie na Portál finančnej správy SR
Prihláste sa na Portál finančnej správy SR (PFS) https://financnasprava.sk pomocou občianskeho preukazu s čipom (eID) alebo iným podporovaným spôsobom prihlásenia.

Po úspešnom prihlásení sa zobrazí Osobná internetová zóna (OIZ). Dôležité: O pridelenie oprávnení môže požiadať iba používateľ s aktívnym prístupom do OIZ.
Krok 2 – Výber subjektu
Kliknite na tlačidlo Výber subjektu

Vo výbere spôsobu konania zvoľte možnosť Autorizácie. Kliknite na tlačidlo Pokračovať bez výberu subjektu

Krok 3 – Vytvorenie žiadosti
V časti Autorizácie kliknite na položku Žiadosť o autorizáciu.

Vyberte možnosť Žiadosť o autorizáciu na daňový subjekt a kliknite na tlačidlo Potvrdiť.

Krok 4 – Vyplnenie údajov a podpis
V tomto kroku vyplňte všetky požadované údaje o firme (daňovom subjekte), ktorú chcete pridať do svojho zoznamu autorizovaných subjektov. Po skontrolovaní správnosti zadaných informácií kliknite na tlačidlo Podpísať a žiadosť podpíšte pomocou občianskeho preukazu (eID).
Dôležité: Po podpísaní žiadosti je potrebné kliknúť aj na tlačidlo Podať. Samotný podpis žiadosť neodošle.

Krok 5 – Potvrdenie autorizácie
Po odoslaní žiadosti vám bude na e-mailovú adresu doručené potvrdenie o jej spracovaní. V našom prípade bola autorizácia schválená približne do 30 minút od odoslania žiadosti.

Ak vám potvrdzovací e-mail nepríde do niekoľkých hodín, skontrolujte priečinok Spam alebo kontaktujte Call centrum Finančnej správy.
Poznámka k podpisovým certifikátom a podpore
Ak máte na občianskom preukaze (eID) aktivované podpisové certifikáty, proces autorizácie je zvyčajne veľmi rýchly a celú žiadosť je možné vybaviť elektronicky.
Podpisové certifikáty slúžia na vytvorenie kvalifikovaného elektronického podpisu, ktorým sa žiadosť podpisuje a odosiela.
Ak sa vám nepodarí subjekt vyhľadať alebo nemáte aktivované podpisové certifikáty potrebné na podpísanie žiadosti, odporúčame kontaktovať Call centrum Finančnej správy.
Telefón: 048/43 17 222, voľba 1 pre autorizácie a splnomocnenia, voľba 7 pre otázky k e-faktúre. Prevádzkové hodiny: pracovné dni od 8:00 do 16:00 hod.
Aktuálne kontaktné údaje nájdete aj na stránke Finančnej správy: https://www.financnasprava.sk/sk/kontakt
Automatické založenie firmy na základe Finančnej správy
Overenie cez Finančnú správu nadväzuje na registráciu firmy v Digitálnom poštárovi. Následné kroky vás prevedú aktiváciou služby a voľbou režimu.
Samostatná firma — postup:
- Oprávnená osoba začne registráciu cez odkaz Vybrať Digitálneho poštára Flowis a v prostredí Finančnej správy udelí príslušnú autorizáciu pre podnik.
- Finančná správa odošle poskytovateľovi registračné údaje a overovací token. Zákazník tento systémový webhook neposiela ručne.
- Pri zapnutom samoobslužnom onboardingu príde na firemný e-mail odkaz na dokončenie. Jeho platnosť je 7 dní.
- Zákazník skontroluje podnik, potvrdí podmienky a oprávnenie konať; nový používateľ nastaví svoje prístupové údaje a dokončí požadované zabezpečenie.
- Vyberie balík a režim. Pri prijímaní sa vykoná kontrola existujúcej registrácie a podľa výsledku registrácia v SMP.
- Skontroluje výsledok aktivácie. Ak už príjem zabezpečuje iný poskytovateľ, prijímanie sa neprevezme samotným výberom balíka; použije sa migrácia.
Sprostredkovateľ — rozdiel: PFS požiadavka musí smerovať k správnemu tenantovi. Ak firma neexistuje, vytvorí sa overený účet iba na odosielanie a požiadavka čaká na ďalšie spracovanie sprostredkovateľom. Vyžaduje sa aktívny vlastník, predplatné a kapacita firiem. Pri firme vopred pripravenej cez API sa podľa jej režimu vykoná overenie a prípadne automatická SMP registrácia.
API: vstupný POST /api/webhooks/pfs je integračný kanál Finančnej správy s overením podpisu, nie verejný endpoint na obídenie overenia. Zákazník používa API správy účtov a dostupné účtové webhooky.
Dôležité: samoobslužný proces závisí od zapnutia v nasadení. Opakované alebo neplatné žiadosti môžu vyžadovať podporu. Postup na portáli finančnej správy nájdete v samostatnom návode; snímka nižšie zobrazuje nadväzujúcu obrazovku Flowis.

Zmena režimu firmy cez API
Pri príprave firmy určte, či má odosielať, prijímať alebo používať oba smery. Aktivácia prijímania je previazaná s overením a registráciou v SMP.
Predpoklad: Máte globálny API credential, Bearer token a ID účtu, ktorý patrí pod váš fakturačný účet.
Hodnota document_mode |
Význam |
|---|---|
sender |
Odosielanie. Samotný režim nenahrádza overenie firmy. |
receiver |
Prijímanie. Vyžaduje zodpovedajúcu sieťovú registráciu. |
both |
Odosielanie aj prijímanie. |
V API odpovediach vždy sledujte dvojicu document_mode a status, pretože ďalší krok závisí od aktuálneho stavu účtu. Pred zmenou ho overte cez GET /api/v1/accounts/{id}.
Zmena režimu pred overením
Kým má účet status: pending_verification, režim môžete zmeniť cez PATCH /api/v1/accounts/{id}. Po overení sa už režim nemení priamou editáciou účtu, ale cez SMP endpointy.
Zmena režimu overeného účtu
Prijímanie pre účet sender + verified_sending_only zapnete registráciou do SMP. Výsledkom je both + verified. Pri presune registrácie od iného poskytovateľa použite jeho migračný kód; pri novej registrácii príjmu odošlite prázdny JSON objekt {}.
Vyžiadanie migračného kódu nemení document_mode. Účet ostáva prijímajúci, prejde do stavu verified_transferable a v odpovedi sa vráti migration_code. Ak migráciu zrušíte, kód sa odstráni a účet sa vráti na verified.
Pri vypnutí prijímania odstráňte registráciu zo SMP. Účet sa prepne na sender + verified_sending_only. Ak je migrácia aktívna, najprv ju zrušte.
Vyberte správny endpoint podľa cieľa
| Aktuálny stav | Cieľ | API |
|---|---|---|
pending_verification | zmeniť režim pred overením | PATCH /api/v1/accounts/{id} |
sender + verified_sending_only | zapnúť prijímanie | POST /api/v1/accounts/{id}/smp-registration |
receiver/both + verified | získať migračný kód | POST /api/v1/accounts/{id}/smp-migration |
receiver/both + verified_transferable | zrušiť migračný kód | DELETE /api/v1/accounts/{id}/smp-migration |
receiver/both + verified | vypnúť prijímanie | DELETE /api/v1/accounts/{id}/smp-registration |
Ak endpoint vráti validačnú chybu stavu, účet nie je v požadovanom vstupnom stave pre daný scenár.
Všetky endpointy v tomto návode používajú globálny API credential. SMP endpointy nepoužívajú X-Account-Id; účet sa vyberá podľa {id} v URL a musí patriť pod billing account použitého credentialu.
Konkrétne požiadavky a ukážky odpovedí nájdete v časti Registrácia príjmu a migrácia.
Zmena režimu v aplikácii
Pri neoverenom účte otvorte Nastavenia → Účty → Upraviť účet, v poli Režim fakturácie účtu vyberte Odosielateľ, Príjemca alebo Oboje a kliknite na Uložiť. Samotná voľba režimu nenahrádza overenie účtu ani aktiváciu prijímania v Peppol sieti.
Na overenom účte použite Migrácia účtu. Postupy v aplikácii nájdete v návode Zmena režimu účtu a vymazanie účtu.

Vytvorenie účtu zo žiadosti aj vopred cez API
Firmu možno pripraviť vopred vo vašom systéme alebo ju založiť nadväzne na autorizáciu z Finančnej správy.
Variant A — firma vopred:
- V existujúcom tenantovi s vlastníkom použite globálny API kľúč.
- Zavolajte
POST /api/v1/accountss názvom, DIČ, krajinou a požadovaným režimom; doplňte ostatné identifikačné údaje. - Uložte vrátené UUID firmy a stav
pending_verification. - Oprávnená osoba vykoná autorizáciu na Finančnej správe pre zhodné DIČ a správneho sprostredkovateľa.
- Po spracovaní žiadosti kontrolujte účet cez API alebo účtový webhook. Až potom povoľte odosielanie, prípadne overte aktiváciu prijímania.
Variant B — najprv žiadosť: sprostredkovateľský proces môže vytvoriť chýbajúcu firmu ako sender / verified_sending_only a oznámiť ju cez account_registered. Ak zákazník chce prijímať, nadväzuje SMP registrácia alebo migrácia. Pre samostatného zákazníka platí sprievodca v bode 08.
UI: v Účty skontrolujte existenciu firmy a stav; podľa oprávnení doplňte údaje a používateľov. Pri prvom založení vopred nevytvárajte duplicitný záznam len preto, že ešte nedorazilo overenie.
Hranice: API POST /accounts zakladá firmu v existujúcom tenantovi; nezakladá nový samostatný klientsky tenant ani neposkytuje overenie DIČ. Bežný účet s pending_verification nie je pripravený na sieťové odosielanie.

Migrácia medzi poskytovateľmi
Presuňte Peppol registráciu pomocou migračného kódu a sledujte stav presunu v aplikácii alebo cez API.
Príchod do Flowisu:
- Od pôvodného poskytovateľa získajte migračný kód.
- Vo Flowise pripravte a overte firmu v režime
sender / verified_sending_only; musí existovať platný overovací podklad z Finančnej správy. - Ako vlastník alebo správca firmy vyberte firmu, otvorte jej úpravu a Migrácia účtu.
- V časti Registrácia s migračným kódom zadajte kód a spustite registráciu.
- Po potvrdení skontrolujte
both / verifieda registráciu u správneho poskytovateľa. Registrácia bez migračného kódu je určená pre inú situáciu — prvú registráciu príjmu.
Odchod z Flowisu: vlastník/správca otvorí migračnú obrazovku prijímajúcej firmy a vyžiada kód. Firma prejde do verified_transferable. Kód odovzdá novému poskytovateľovi. Dostupná je aj akcia zrušenia rozpracovanej migrácie. Priame odstránenie zo SMP ruší príjem a nie je náhradou plynulého presunu; lokálne dokumenty zostávajú zachované.
API: POST /accounts/{id}/smp-migration vyžiada kód; GET na rovnakej ceste načíta/synchronizuje dostupný stav a DELETE ruší migráciu. Registrácia na novom mieste: POST /accounts/{id}/smp-registration s {"sml_migration_code":"<KOD>"}. Všetky majú prefix /api/v1 a vyžadujú globálny kľúč. DELETE /accounts/{id}/smp-registration je samostatné ukončenie registrácie.
Pri nejasnom výsledku: timeout nie je potvrdenie dokončenia. Overte stav; pri chybe registration_unconfirmed alebo persistence_failed kontaktujte podporu. Migračný kód môže byť jednorazovo spotrebovaný aj pri stratenej odpovedi.
Priebeh migrácie: Vyžiadanie migračného kódu nemení Peppol režim a okamžite neruší registráciu v našom SMP. Dokončenie prevzatia a aktiváciu prijímania si potvrďte u nového poskytovateľa. Migrácia závisí aj od druhého poskytovateľa a akcií zákazníka; nejde o úplne automatický proces bez účasti používateľa.

Webhooky registračných udalostí
Sprostredkovateľ dostáva udalosti o vytvorení a overení firmy priamo do svojho systému.
Postup v UI: vlastník alebo koordinátor sprostredkovateľského tenanta otvorí Integrácie → Spravovať webhooky → Nový webhook. Vyplní názov, HTTPS adresu a overovací token, vyberie účtové udalosti a uloží. Na cieľovej adrese musí byť pripravený prijímač HTTP POST s JSON.
event_type |
Význam a reakcia integrácie |
|---|---|
account_registered |
Systém vytvoril účet pod sprostredkovateľom; uložte account_id, DIČ a aktuálny stav. Nevyhodnocujte ho automaticky ako aktívne prijímanie v SMP. |
account_verified |
Overenie/aktivačný proces oznámil úspešný výsledok. Rozlíšte režim a stav v payload-e — overený odosielateľ nemusí prijímať. |
account_already_registered |
Registrácia bola zistená u iného prístupového bodu. Riešte existujúceho poskytovateľa a prípadnú migráciu. |
account_transferred | Iný poskytovateľ prevzal registráciu účtu v Peppol SMP pomocou migračného kódu. Účet potom faktúry iba odosiela. |
account_registration_duplicated | Finančná správa poslala ďalšiu žiadosť o registráciu už overeného účtu; udalosť obsahuje kontaktné údaje z novej žiadosti. |
API prijímača: kontrolujte Authorization: Bearer <NASTAVENY_TOKEN>, event_type, account_id, status a document_mode. Účtové payloady môžu obsahovať citlivý vpds_token; nepatrí do verejných logov. Po uložení udalosti načítajte aktuálny stav cez GET /api/v1/accounts/{id}, ak potrebujete rozhodnúť o ďalšom kroku.
Dostupnosť: účtové udalosti sú ponúkané sprostredkovateľom, nie všetkým bežným tenantom. Verejné API na konfiguráciu webhookov nie je publikované.
Dôležité: dokončenie migrácie k inému poskytovateľovi oznamuje udalosť account_transferred. Samostatné udalosti pre vyžiadanie alebo zrušenie migračného kódu nie sú. Opakovanie doručenia webhookov je popísané v bode 26.

Správa a nastavenie účtu
Ako rozumieť účtom a prístupom
Klientsky alebo fakturačný účet (tenant) zastrešuje predplatné, používateľskú správu, integračné kľúče a webhooky. Účet firmy predstavuje konkrétny podnik s vlastným DIČ, Peppol identifikátorom, režimom a dokumentmi. Jeden tenant môže obsahovať viac účtov firiem podľa balíka. Firma v tomto návode znamená účet firmy, nie ľubovoľného odberateľa uloženého na faktúre.
Používateľ môže mať v rôznych firmách rozdielne roly. Prepnutie firmy v UI mení pracovný kontext. V API V1 sa firma pri operáciách s konkrétnym dokumentom určuje hlavičkou X-Account-Id: <UUID>. V SAPI sa používa X-Peppol-Participant-Id: <participant_id>. Tieto identifikátory nie sú zameniteľné.
Spoločné predpoklady API: integračný prístup, aktívne a nepozastavené predplatné podľa pravidiel operácie, platný kľúč a prístup k danej firme. Autentifikácia sa posiela v Authorization: Bearer <TOKEN>. Správa firiem a používateľov vyžaduje globálny kľúč tenanta. Príklady používajú zástupné hodnoty, nie platné prihlasovacie údaje.
V ďalšom texte znamená „bez verejného API“ to, že v aktuálnom API V1/SAPI nie je publikovaný zákaznícky endpoint pre daný úkon. Interné webové formuláre nie sú náhradou stabilného integračného API.
Multitenant správa firiem
Spravujte viac firiem z jedného prostredia. Každá firma má vlastné dokumenty, identifikačné údaje a prístupy používateľov.
Čo má zákazník k dispozícii: zoznam prístupných účtov, vyhľadávanie a filtre, prepínanie firmy, založenie ďalšej firmy podľa balíka a úpravu firemných údajov. Vlastníci tenanta získavajú vlastnícky prístup k novým firmám. Koordinátorovi sa pri vytvorení firmy v UI pridelí správcovský prístup k tejto firme.
Kliknutím na firmu v zozname Účty otvoríte jej detail s identifikačnými údajmi. Údaje upravíte tlačidlom Upraviť, ktoré vidí vlastník a správca firmy.
Stav firmy vidíte na stránke Prehľad: Overený účet, Overený len na odosielanie, Pripravený na prenos alebo Čaká na overenie, spolu s režimom (Iba odosielanie, Iba prijímanie, Odosielanie aj prijímanie). Ak firma zatiaľ len odosiela, vlastník alebo správca firmy tu zapne aj prijímanie: tlačidlom Zapnúť aj prijímanie e-faktúr, alebo, ak aplikácia ponúkne Overiť na Finančnej správe, najprv potvrdením prijímania na Finančnej správe.
Postup v UI:
- Prihláste sa a otvorte Nastavenia → Účty.
- Vyhľadajte firmu podľa názvu alebo identifikátora; podľa potreby filtrujte režim a stav.
- Vyberte účet a použite akciu na prepnutie. Aktívnu firmu si overte v hornej lište.
- Ako vlastník alebo koordinátor môžete pri vhodnom balíku založiť ďalší účet. Vyplňte názov, krajinu, DIČ a kontaktné údaje; doplňte IČO, IČ DPH a adresu.
- Pred odosielaním dokončite overenie firmy. Samotné založenie účtu neznamená registráciu na prijímanie v Peppole.
API: GET/POST /api/v1/accounts, GET/PATCH /api/v1/accounts/{id}. Tieto operácie pracujú v rámci tenanta kľúča a nepoužívajú X-Account-Id. Zoznamy sú stránkované cez offset a limit; sledujte next. Dokumentové zoznamy môžu bez hlavičky firmy vrátiť dokumenty zo všetkých firiem dostupných kľúču, preto vždy spracujte aj objekt account.
Výsledok a hranice: samostatný pracovný kontext každej firmy; počet firiem podlieha balíku. Bežný účet firmy nie je samostatne platený tenant. Verejné API neposkytuje založenie nového fakturačného tenanta existujúcim zákazníckym kľúčom.

Roly a oprávnenia používateľov
Prideľte ľuďom prístup podľa ich práce — od vlastníka a koordinátora cez správcu a spracovateľa až po čitateľa.
Vlastník, koordinátor a IT administrátor sú roly fakturačného účtu; správca, spracovateľ a čitateľ sa prideľujú konkrétnej firme. Vlastník môže prideliť rolu vlastníka, koordinátora aj IT administrátora, koordinátor rolu koordinátora a IT administrátora.
| Rola | Čo smie robiť | Čo potrebuje navyše alebo čo nesmie |
|---|---|---|
Vlastník — owner |
Spravuje tenant, jeho používateľov a vlastníkov, predplatné, fakturačné údaje a integrácie. Pri povolenej funkcii spravuje používateľské politiky/SSO. Vo firmách s vlastníckym členstvom spravuje údaje aj dokumenty. | Stále platia limity balíka, overenie firmy a pravidlá SMP. Rolu vlastníka nemožno prideliť cez aktuálne používateľské API. |
Koordinátor — coordinator |
Spravuje používateľov, ich prístupy, API kľúče a webhooky; môže zakladať firmy podľa balíka. Môže udeľovať koordinátorský prístup. | Nevidí predplatné, nespravuje vlastníkov a neschvaľuje prístup podpory. Používateľské politiky spravuje okrem tých, do ktorých patrí vlastník. Ku každej firme fakturačného účtu, aj k budúcim, dostane automaticky prístup s rolou Správca. |
IT administrátor — it_admin |
Nastavuje API kľúče, webhooky a automatizácie v časti Integrácie. | Nevidí žiadnu firmu ani doklady, nemôže ich odosielať ani prijímať a nespravuje používateľov ani predplatné. V zozname Používatelia je pri ňom „Iba integrácie“. |
Správca firmy — admin |
Upravuje firemné údaje, vykonáva dostupné migračné úkony; vytvára, upravuje, odosiela a spracováva dokumenty. | Samotná táto rola nedáva správu používateľov tenanta, integrácií, predplatného ani SSO. |
Spracovateľ — processor |
Vytvára a importuje dokumenty, upravuje upraviteľné koncepty, odosiela, schvaľuje prijaté dokumenty, ruší schválenie a označuje prijaté dokumenty ako dokončené. | Neupravuje firemné údaje ani migráciu. Nemá správu tenanta. |
Čitateľ — reader |
Prezerá zoznamy, detaily a históriu dokumentov; môže stiahnuť dostupné dokumenty. | Nemôže vytvárať, upravovať, odosielať, schvaľovať ani dokončovať dokumenty. |
Postup v UI: vlastník alebo koordinátor otvorí Používatelia → Pridať používateľa, zadá meno a e-mail, pridá konkrétne firmy a pri každej vyberie rolu. Ak má osoba spravovať tenant, pridá aj prístup k fakturačnému účtu. Pozvánku odošle až po kontrole oboch častí. Pri úprave odoberie nepotrebné firmy a uloží zmeny. Koordinátor nemôže upravovať vlastníka; UI tiež blokuje úpravu vlastných prístupov.
API: POST /api/v1/users a PATCH /api/v1/users/{id} prijímajú accounts: [{"id":"<UUID>","role":"processor"}]. Podporované sú iba admin, processor, reader; vynechaná rola znamená reader. Vlastník, koordinátor a priradenie SSO politiky sa týmto API nenastavujú.

Počet používateľov a neobmedzený prístup
Zapojte do práce celý tím. Počet používateľov sa riadi zvoleným balíkom; systém podporuje aj balíky bez používateľského limitu.
Postup v UI:
- Vlastník overí podmienky balíka v Predplatné.
- Vlastník alebo koordinátor otvorí Používatelia → Pridať používateľa.
- Zadá osobu a jej firmy/roly a odošle pozvánku.
- Nový používateľ dokončí nastavenie prístupu podľa e-mailu. Existujúcemu používateľovi sa pridajú chýbajúce prístupy.
API: POST /api/v1/users. Nová osoba vracia 201, pridanie prístupu existujúcej osobe 200. Existujúce meno a e-mail sa týmto volaním neprepisujú; už pridelené roly sa pri opätovnom pridaní nemenia. Na zmenu roly slúži PATCH.
Ako sa počíta limit: počet rôznych používateľov s členstvom vo firmách daného tenanta. Ten istý človek vo viacerých jeho firmách neobsadí viac takýchto miest. Pri vyčerpaní obmedzeného balíka sa pridanie nového používateľa odmietne; API vracia 422 s plan_limit_exceeded.
Pozvánka: Pozvaný kolega dostane e-mail s odkazom. Po otvorení vidí, ku ktorým firmám a s akou rolou získa prístup. Ak ešte nemá prihlásenie, vytvorí si heslo a klikne na Vytvoriť prihlásenie a prijať; ak už prihlásenie má, prihlási sa a klikne na Prijať. Prihlasuje sa vlastným e-mailom a heslom a má vlastné dvojfaktorové overenie. Pozvánka platí 72 hodín. Kým ju kolega neprijme, je pri ňom v zozname Používatelia „Čaká na prijatie pozvánky“ a pozvánku môžete zrušiť tlačidlom Zrušiť pozvánku. Čakajúce pozvánky sa započítavajú do limitu používateľov balíka.
Dôležité: „Neobmedzený počet používateľov pre každého zákazníka“ nie je vlastnosť všetkých balíkov. Neobmedzenosť musí byť súčasťou konkrétnej ponuky.

Správa firiem a používateľov cez UI aj API
Zakladajte a spravujte firmy a prideľujte používateľom prístupy v aplikácii aj z vlastného systému.
Postup v UI: v Účty založte alebo upravte firmu; v Používatelia pridajte osobu alebo otvorte Upraviť prístup. Firemné údaje upravuje vlastník/správca firmy, používateľské prístupy vlastník/koordinátor tenanta. Zmenu skontrolujte opätovným otvorením záznamu.
| Úkon | UI | API V1 |
|---|---|---|
| Zoznam, založenie a úprava firmy | Áno, podľa oprávnení | GET/POST /accounts, GET/PATCH /accounts/{id} |
| Zoznam a pridanie používateľa | Áno | GET/POST /users, GET /users/{id} |
| Zmena firemných rolí/prístupov | Áno | PATCH /users/{id} |
| Vlastníci a koordinátori tenanta | Áno, podľa roly správcu | Bez verejného endpointu na zmenu |
| SSO politiky, notifikácie, správa webhookov | Áno, podľa funkcie | Bez verejného CRUD endpointu |
| Zmazanie firmy | Áno, v Nastavenia → Účty → Upraviť účet → Odstrániť, kým firma nemá dokumenty ani registráciu na prijímanie v SMP. | DELETE /accounts/{id} za rovnakých podmienok. |
| Zmazanie globálneho používateľa | Nie je bežná zákaznícka akcia | Bez DELETE /users/{id}. |
V tabuľke majú API cesty prefix /api/v1. PATCH /users/{id} synchronizuje celý poslaný zoznam firiem: zahrňte všetky prístupy, ktoré majú zostať. Vynechané nevlastnícke členstvá sa odstránia. accounts: [] odoberá takéto prístupy; nejde o vymazanie osoby. Vlastnícke členstvá sú chránené. Tento endpoint neaktualizuje meno ani e-mail.
Dôležité: dostupné sú kľúčové operácie v oboch rozhraniach, ale úplná funkčná zhoda UI a API sa nedá deklarovať.

Odstránenie firmy a zmenu režimu neovereného účtu opisuje návod Zmena režimu účtu a vymazanie účtu. Odstránenie firmy je iná operácia než odstránenie jej registrácie zo SMP.
Voliteľné e-mailové upozornenia
Nastavte si, či vám majú chodiť denné e-mailové súhrny prijatých dokumentov a zlyhaných doručení.
Postup v UI: v používateľskom menu vpravo hore otvorte Môj profil. V karte Nastavenie upozornení zapnite alebo vypnite prepínače „dostanete nový prijatý dokument“ a „doručenie odoslaného dokumentu zlyhá“. Zmena sa uloží hneď. Nastavenie je osobné: platí len pre vás, a to pre všetky firmy, ku ktorým máte prístup. Kolegovia si ho nastavujú každý sám.
Ako funguje doručenie: súhrn chodí každé ráno a obsahuje predchádzajúci deň. Dokončené prijaté dokumenty v ňom nie sú. Ak je dokumentov 10 a viac, súhrn uvedie ich počty namiesto zoznamu. Ak sa nič nestalo, súhrn nepríde.
API: verejný endpoint na čítanie/zmenu týchto e-mailových prepínačov nie je dostupný. Pre strojové udalosti použite samostatné webhooky; e-mailový súhrn a webhook sú odlišné funkcie.
Ak e-mail nepríde: overte aktívnu firmu, oba prepínače, e-mail osoby, jej členstvo, dátum udalosti a či dokument už nie je dokončený. Prázdny súhrn sa neposiela. V prostredí staging je táto denná úloha zámerne vypnutá.

Vyhľadanie účastníka v sieti Peppol
Overte obchodného partnera v Peppole a zistite identifikátor, poskytovateľa a dostupné typy dokumentov.
Postup v UI: otvorte Peppol vyhľadávanie, zadajte názov, DIČ alebo participant ID a spustite hľadanie. Pri nejednoznačnom názve vyhľadávajte presný identifikátor. Pre slovenskú firmu je používaný tvar 0245:<DIČ>. Porovnajte identitu partnera, jeho poskytovateľa a podporované typy dokumentov.
API: GET /api/v1/peppol-lookup?participant_id=0245:<DIC>, bez X-Account-Id. V odpovedi sledujte participant_id, document_types, smp_url, smp_registrator a source. Príklad volania je v prílohe A.
Význam výsledku: vyhľadávanie kombinuje Directory a SML/SMP. Firma nezverejnená v Directory môže byť registrovaná a dosiahnuteľná cez Peppol. Výsledok source: sml preto nemusí obsahovať názov a krajinu. Nájdená registrácia sama osebe nepotvrdzuje, že príjemca podporuje každý požadovaný proces; overte aj konkrétny typ dokumentu. Na snímke je vstupná obrazovka, nie tvrdenie o registrácii ukážkovej firmy.

Prehľad spotreby
Sledujte počet odoslaných a prijatých dokumentov a porovnajte odosielanie s limitom svojho balíka.
Postup v UI: ako vlastník otvorte Predplatné, skontrolujte aktuálny balík, obdobie a kartu spotreby. Cez História spotreby si zobrazte spotrebu za predchádzajúce mesiace. Porovnávajte rovnaké obdobia; spotreba sa sleduje mesačne aj pri ročnom predplatnom.
Čo údaje znamenajú: karta zobrazuje odoslané dokumenty voči limitu a počet prijatých dokumentov. Čerpanie odosielania sa eviduje pri úspešnom doručení. Prijímanie je na tejto karte zobrazené bez dokumentového limitu. Používateľské a firemné limity sú ďalšie podmienky balíka, nie synonymum počtu faktúr.
API: samostatný verejný endpoint na účtovnú spotrebu a historické výkazy nie je publikovaný. Zoznamy dokumentov možno použiť na vlastné prevádzkové reporty, ale ich počet nemožno automaticky vydávať za oficiálnu fakturovanú spotrebu.
Pri vyčerpaní limitu: skontrolujte balík a obdobie. Odosielanie môže byť odmietnuté aj pri pozastavenom alebo neuhradenom predplatnom; nový pokus bez odstránenia tejto príčiny problém nevyrieši.

Predplatné: výber balíka, platba a zmena balíka
Predplatné spravuje vlastník fakturačného účtu vo webovej aplikácii v menu Nastavenia → Predplatné.
- Balík vyberiete alebo zmeníte tlačidlom Zmeniť balík. Prechod na nižší balík sa naplánuje od ďalšieho fakturačného obdobia.
- Prvé obdobie aj prechod na vyšší balík zaplatíte kartou alebo bankovým prevodom na faktúru. Kartou platíte na zabezpečenej stránke Tatra banky, balík sa aktivuje hneď a kartu si uložíme na ďalšie platby. Pri prevode vystavíme riadnu faktúru s platobnými údajmi a QR kódom PAY by square; balík sa aktivuje po pripísaní platby, zvyčajne do pár minút.
- Kým nezaplatíte prvé obdobie alebo kým je faktúra po splatnosti, odosielanie dokumentov a integrácie sú pozastavené. Prijímanie faktúr funguje ďalej. Pri prechode na vyšší balík prevodom používate dovtedy svoj súčasný balík.
- Ak dosiahnete mesačný limit odosielania, aplikácia to oznámi. Vlastník si dokúpi doplnkový balík Extra s 10, 50, 100 alebo 500 faktúrami, alebo zmení balík.
- Ak nechcete platiť, prejdite cez Zmeniť balík na bezplatný Peppol Box, prijímanie e-faktúr vám ostane. Zrušenie predplatného si inak vyžiadate v aplikácii v časti Podpora.
- Fakturačné údaje upravíte v karte Fakturačné údaje tlačidlom Upraviť; zmena platí pre budúce faktúry.
- Faktúry za predplatné si stiahnete v časti História platieb.
Viac firiem pod jedným prihlásením
Ak spravujete viac firiem, nemusíte mať pre každú iné prihlásenie.
- V balíkoch Mini, Core a Max je vo fakturačnom účte jedna firma. Ďalšiu firmu zaregistrujte na Finančnej správe s tým istým e-mailom, ktorým sa prihlasujete; po dokončení registrácie pre ňu vznikne samostatný fakturačný účet s vlastným balíkom. Uvidíte ho pod tým istým prihlásením v menu Fakturačné účty.
- Viac firiem v jednom predplatnom ponúka balík Ultra. Ďalšiu firmu najprv pridajte v menu Nastavenia → Účty tlačidlom Nový účet, potom pri nej na Finančnej správe vyberte Digitálneho poštára a zadajte e-mail, ktorým sa prihlasuje vlastník vášho fakturačného účtu. Po potvrdení sa firma overí v tom istom účte.
- Medzi firmami sa prepínate v hornej lište, v menu Účty alebo na stránke Prehľad tlačidlom Zmeniť účet.
Uchovávanie údajov
Určte, ako dlho u nás zostávajú uložené vaše dokumenty.
Faktúry (PDF aj XML) u nás bez poplatku zostávajú uložené, kým máte účet, a po skončení zmluvy ešte 30 dní, ak sa nedohodneme na kratšej dobe. Digitálny poštár nie je zákonný archív; archívom zostáva vaše účtovníctvo. Zo zákona uchovávame záznamy o doručení 6 mesiacov.
- Otvorte Nastavenia → Uchovávanie údajov.
- Pre fakturačný účet nastavte Predvolenú dobu, ktorá platí pre každú firmu bez vlastného nastavenia, alebo pri konkrétnej firme zvoľte vlastnú dobu.
- Ak dobu skracujete, potvrďte zmenu. Obsah dokumentov, ktorých sa kratšia doba týka, sa vymaže najskôr k dátumu, ktorý aplikácia zobrazí; dovtedy môžete zmenu vrátiť.
O zmene pošleme e-mail. Po uplynutí zvolenej doby sa obsah starších dokumentov naozaj vymaže a k dispozícii zostane len to, čo ostalo uložené. Doklady o doručení sa uchovávajú bez ohľadu na toto nastavenie.
Zmena režimu účtu a vymazanie účtu
Návod ukazuje odstránenie účtu, zmenu režimu neoverenej firmy a zapnutie alebo presun prijímania faktúr v sieti Peppol.
Používateľ je prihlásený, má vybranú správnu firmu a oprávnenie na správu účtu (vlastník alebo administrátor). Pre migráciu musí byť účet overený.
V návode označuje „účet“ konkrétnu firmu v aplikácii. Firemné identifikačné a kontaktné údaje na obrázkoch sú anonymizované.
Ak je účet ešte neoverený na Finančnej správe
Správa firmy začína v časti Nastavenia → Účty. Otvorte úpravu požadovanej firmy a pred každou zmenou skontrolujte, že pracujete so správnym účtom.
Krok 1 – Ako odstrániť účet / firmu
Na stránke Upraviť účet kliknite na Odstrániť. Firmu odstránite, len kým nemá žiadne dokumenty a nie je registrovaná v SMP na prijímanie; registráciu najprv vymažte v kroku 8. V okne zadajte názov účtu a dôvod odstránenia a potvrďte Odstrániť účet. Ak je to posledná firma fakturačného účtu, vlastník ju odstráni spolu s fakturačným účtom tlačidlom Odstrániť účet aj fakturačný účet, a to len kým fakturačný účet nemá faktúry, platby ani spravovaných používateľov. Odstránenie je okamžité a nedá sa vrátiť späť.

Krok 2 – Ako zmeniť režim neovereného účtu
V poli Režim fakturácie účtu vyberte požadovanú možnosť: Odosielateľ, Príjemca alebo Oboje. Zmenu potvrďte tlačidlom Uložiť. Samotná voľba režimu nenahrádza overenie účtu ani aktiváciu prijímania v Peppol sieti.
Dostupnosť funkcií
Ak tlačidlo Odstrániť nevidíte, firma má dokumenty, je registrovaná na prijímanie alebo je poslednou firmou fakturačného účtu s faktúrami či platbami. Ak len nechcete platiť, vlastník v časti Predplatné cez Zmeniť balík prejde na bezplatný Peppol Box; zrušenie predplatného si inak vyžiadate v aplikácii v časti Podpora. Výber režimu sa zobrazuje, len kým firma čaká na overenie. Odstránenie firmy nie je rovnaká operácia ako odstránenie registrácie zo SMP (krok 8).
Ak je už účet overený na Finančnej správe
Na overenom účte sa prijímanie faktúr mení cez migráciu účtu. Dostupná obrazovka závisí od aktuálneho režimu firmy.
Krok 3 – Otvorte migráciu overeného účtu
V časti Nastavenia → Účty otvorte úpravu firmy. Vpravo dole kliknite na odkaz Migrácia účtu. V záhlaví migračnej stránky skontrolujte údaje firmy a jej Peppol režim.

Účet iba odosiela faktúry Ak je účet overený len na posielanie, zobrazí sa registrácia do nášho SMP. Prijímanie zapnete bez migračného kódu alebo s kódom od súčasného poskytovateľa. Pokračujte krokom 4.
Účet už prijíma faktúry cez našu službu Zobrazia sa možnosti ukončenia prijímania cez naše SMP: vyžiadanie migračného kódu (krok 6) alebo priame odstránenie registrácie (krok 8).
Ak odkaz alebo akcia nie sú dostupné
Skontrolujte vybraný účet, jeho overenie a svoje oprávnenie vlastníka alebo administrátora. Ak aplikácia hlási nedostupný stav registrácie, postupujte podľa hlásenia, prípadne nám napíšte v aplikácii v časti Podpora.
Pridanie prijímania faktúr v Peppol sieti
Východiskom je účet overený len na posielanie. Na stránke Migrácia účtu vyberte jednu z nasledujúcich možností.

Krok 4 – Registrácia bez migračného kódu
Použite ju, ak firma nemá aktívnu registráciu na prijímanie v inom SMP. Pri presune bez kódu musí byť pôvodná registrácia najprv odstránená u doterajšieho poskytovateľa. Kliknite na Registrovať bez kódu, v potvrdzovacom okne skontrolujte firmu a potvrďte Registrovať v SMP.
Krok 5 – Registrácia s migračným kódom
Od súčasného poskytovateľa si vyžiadajte migračný kód. Vložte ho do poľa Migračný kód v pravej časti obrazovky a kliknite na Použiť migračný kód. Overovací token účtu z PFS použije aplikácia automaticky; ide o iný údaj než migračný kód.
Ako spoznáte úspešné dokončenie
Aplikácia potvrdí úspešnú registráciu v SMP. Účet bude mať režim Oboje a bude môcť prijímať aj odosielať faktúry. Ak výsledok registrácie nie je potvrdený alebo chýba overovací token, napíšte nám v aplikácii v časti Podpora.
Prechod k inému poskytovateľovi s kódom
Tento postup použite, ak firma prijíma faktúry cez naše SMP a chcete preniesť jej registráciu k novému poskytovateľovi.
Krok 6 – Vyžiadajte si migračný kód
Otvorte Migrácia účtu a v časti Migrácia s kódom kliknite na Vyžiadať migračný kód. Po úspešnom vyžiadaní sa zobrazí pripravený kód.

Krok 7 – Odovzdajte kód novému poskytovateľovi
V zobrazenom výsledku použite Skopírovať migračný kód. Kód bezpečne odovzdajte iba novému poskytovateľovi, ktorý ním prevezme registráciu. Dokončenie prevzatia a aktiváciu prijímania si potvrďte u nového poskytovateľa.
Vyžiadanie kódu ešte nie je dokončená migrácia
Samotné vyžiadanie kódu nemení Peppol režim a okamžite neruší registráciu v našom SMP. Ak sa rozhodnete zostať, použite Zrušiť proces migrácie a potvrďte zrušenie; pôvodný kód prestane platiť.
Prechod bez migračného kódu
Najprv odstránite registráciu z nášho SMP. Následnú registráciu prijímania vykoná nový poskytovateľ podľa svojho postupu.
Krok 8 – Priame odstránenie zo SMP
V časti Migrácia účtu vyberte pravú kartu Priame odstránenie zo SMP a kliknite na Odstrániť zo SMP.

- V potvrdzovacom okne skontrolujte právny názov firmy a Peppol Participant ID.
- Do poľa Potvrdenie odstránenia zadajte slovo delete.
- Kliknite na potvrdzovacie tlačidlo Odstrániť zo SMP.
- Počkajte na správu o úspešnom odstránení. Účet sa prepne na Odosielateľ (Sender).
- U nového poskytovateľa dokončite registráciu na prijímanie a overte jej aktiváciu.
Dôsledok odstránenia
Prijímanie faktúr cez naše SMP sa ukončí; účet v aplikácii zostane aktívny iba na odosielanie. Samotným odstránením sa prijímanie u nového poskytovateľa nezapne. Medzi odstránením a novou registráciou môže vzniknúť prestávka v prijímaní.
Ak už máte vyžiadaný migračný kód
Pri aktívnej migrácii nie je priame odstránenie dostupné. Ak chcete pokračovať bez kódu, najprv použite Zrušiť proces migrácie a potvrďte zrušenie. Potom znovu otvorte možnosti migrácie.
Bezpečnosť
OAuth2 alebo jednoduchý API token
Integráciu pripojíte pomocou OAuth2 klientskych údajov alebo dlhodobého API tokenu.
Predpoklad: Používateľ je prihlásený na produkcii https://app.postarflowis.sk/ (alebo v testovacom prostredí https://test.postarflowis.sk/) a má oprávnenie majiteľa účtu.
Časť Integrácie vidí vlastník, koordinátor a IT administrátor, a to len pri balíku, ktorý obsahuje API a integrácie.
Tento návod slúži ako stručný pracovný postup pre vytvorenie a odovzdanie API kľúča do integračnej aplikácie. API kľúč považujte za citlivý údaj a zdieľajte ho iba cez bezpečný kanál.
Krok 1 – Otvorte Integrácie v nastaveniach
Po prihlásení do aplikácie prejdite v ľavom menu do časti Nastavenia a vyberte položku Integrácie. V karte API kliknite na tlačidlo Spravovať API kľúče.

Krok 2 – Vytvorte nový API kľúč
Na obrazovke API kľúčov môžete najprv otvoriť dokumentáciu. Ak chcete pokračovať priamo vytvorením kľúča, kliknite na tlačidlo Vytvoriť nový API kľúč.

Krok 3 – Pomenujte kľúč a zvoľte typ autentifikácie
Zadajte názov, podľa ktorého kľúč neskôr bezpečne rozpoznáte. Potom vyberte typ autentifikácie podľa integračného riešenia. Dostupné možnosti sú OAuth2 alebo jednoduchý autentifikačný kľúč. V poli Platnosť API kľúča zvoľte 7, 30, 90 alebo 365 dní, alebo Bez expirácie. Platí to pre jednoduchý token aj pre OAuth2 kľúč. Vlastníkom a koordinátorom pošleme upozornenie 30, 7 a 1 deň pred vypršaním.

Krok 4 – Vyberte prístup API kľúča
Pre väčšinu bežných integrácií postačuje globálny API kľúč. Po výbere prístupu kliknite na tlačidlo Vytvoriť API kľúč.

Podrobnosti o rozsahu nájdete v návode Globálne a firemne obmedzené API kľúče.
Krok 5 – Skopírujte vygenerovaný token
Po vytvorení sa zobrazia detaily API kľúča. Vygenerovaný token zadajte do integračnej aplikácie. Od tejto chvíle môže integrácia pristupovať k účtu podľa nastaveného rozsahu oprávnení.

Identifikátor konkrétnej firmy nájdete v časti Získanie X-Account-ID.
OAuth2 postup:
POST /api/v1/auth/tokens JSONclient_id,client_secreta voliteľnýmgrant_type: "client_credentials".- Z odpovede uložte
access_token,refresh_tokena ich platnosť. Access token platí 2 hodiny, refresh token 6 mesiacov. - Pri API volaniach posielajte
Authorization: Bearer <access_token>. - Obnovte pár cez
POST /api/v1/auth/renewsrefresh_token. Použitý refresh token sa zneplatní; uložte nový pár. - Stav tokenu overíte cez
GET /api/v1/auth/token/status; refresh token zrušíte cezPOST /api/v1/auth/revoke.
Jednoduchý token: vytvorený API token posielajte priamo v rovnakej Bearer hlavičke. Nepoužíva výmenu za dvojicu tokenov a nemá uvedenú dvojhodinovú platnosť JWT.
Správa existujúceho kľúča
V prípade potreby môžete API kľúč odstrániť alebo vygenerovať znova. Po odstránení alebo rotácii prestanú pôvodné prihlasovacie údaje fungovať vo všetkých aplikáciách, ktoré ich používajú.
Poznámka k bezpečnosti: API kľúč neukladajte do verejných repozitárov, e-mailových vlákien ani zdieľaných dokumentov bez obmedzeného prístupu.
Globálne a firemne obmedzené API kľúče
Jeden integračný prístup môže obsluhovať celý tenant alebo iba vybrané firmy.
Postup v UI: v správe API kľúčov vytvorte alebo upravte kľúč. Pre centrálnu integráciu vyberte globálny rozsah. Pre integráciu konkrétneho účtovného systému globálny rozsah vypnite, vyhľadajte a pridajte len potrebné firmy. Uložte a overte prístup na zamýšľanom účte.
Čo rozsah znamená: globálny kľúč má prístup ku všetkým firmám svojho tenanta vrátane nových. Na fakturačný účet môže byť aktívny najviac jeden globálny kľúč pre každý typ autentifikácie, teda jeden OAuth2 a jeden jednoduchý token. Obmedzený kľúč musí obsahovať aspoň jednu firmu a nemôže odkazovať na firmu mimo svojho tenanta.
API: pri dokumentovej operácii posielajte X-Account-Id; hlavička vyberá firmu, ale nerozširuje oprávnenia kľúča. Prístup k nepovolenej firme skončí 403. Správa firiem a používateľov vyžaduje globálny kľúč aj vtedy, keď obmedzený kľúč vidí danú firmu. Pri zoznamoch dokumentov bez X-Account-Id dostanete iba firmy dostupné danému kľúču.
Hranice: rozsah kľúča nie je používateľská rola reader/processor/admin. Aktuálny formulár neurčuje samostatné oprávnenie „iba čítanie“ alebo „iba odosielanie“ API kľúča. Verejný CRUD endpoint na správu kľúčov nie je publikovaný; konfigurácia prebieha v UI.

Získanie X-Account-ID
Pre skopírovanie x-account-id prosím v Nastaveniach – Účty vyberte a skopírujte X-account-ID daného účtu

Celý postup vytvorenia kľúča nájdete v návode OAuth2 alebo jednoduchý API token.
Dvojfaktorové overenie cez aplikáciu alebo e-mail
Prihlásenie chránite jednorazovým kódom z autentifikačnej aplikácie alebo z e-mailu.
Postup v UI:
- V používateľskom menu vpravo hore otvorte Môj profil a kliknite na Spravovať zabezpečenie. Otvorí sa stránka Zabezpečenie.
- V časti Dvojfaktorové overenie kliknite na Zmeniť 2FA.
- Vyberte E-mailové kódy alebo Autentifikačná aplikácia (napríklad Google Authenticator či Microsoft Authenticator).
- Pri aplikácii naskenujte zobrazený QR kód a opíšte 6-miestny kód z aplikácie. QR kód je tajný registračný údaj.
- Zadajte svoje súčasné heslo a kliknite na Uložiť spôsob 2FA.
Dvojfaktorové overenie nemožno vypnúť. Kód z e-mailu platí 15 minút a po použití sa spotrebuje.
Čo má zákazník k dispozícii: výber metódy, jej zmenu a prehľad zabezpečenia vlastného používateľa. Pri vynútenom dokončení 2FA treba nastavenie dokončiť pred bežným používaním aplikácie. Ak stratíte prístup k overovaciemu kódu, napíšte na info@postarflowis.sk z e-mailu, ktorým sa prihlasujete, a uveďte názov firmy; dvojfaktorové overenie vám resetujeme.
API: verejné API nesprístupňuje nastavenie ani reset používateľského 2FA. Serverové integrácie používajú API credential, nie jednorazový kód používateľa. Pri SAML prihlásení sa uplatňuje prihlásenie cez poskytovateľa identity; nepredpokladajte automaticky aj druhú lokálnu 2FA výzvu Flowis.

Zmena e-mailu a hesla
Prihlasovací e-mail aj heslo si zmeníte sami v Môj profil.
V menu Môj profil kliknite na Zmeniť e-mailovú adresu, zadajte novú adresu a súčasné heslo a kliknite na Poslať odkaz na potvrdenie. Odkaz na novej adrese otvorte do 24 hodín, keď ste prihlásení. O zmene upozorníme aj vašu doterajšiu adresu. Heslo zmeníte na stránke Zabezpečenie tlačidlom Zmeniť heslo; ostatné zariadenia sa potom odhlásia.
Prístup podpory
Podpora vidí údaje vášho účtu len s vaším súhlasom.
Naši kolegovia z podpory vidia údaje vášho účtu, len ak vlastník schváli ich žiadosť v menu Nastavenia → Prístup podpory. Prístup je časovo obmedzený, môžete ho kedykoľvek odvolať tlačidlom Odvolať a je zaznamenaný v histórii.
SSO a používateľské politiky
Prepojte firemné prihlasovanie cez SAML SSO a určte, či sa spravovaní používatelia prihlasujú heslom, SSO alebo oboma spôsobmi.
Predpoklad: funkcia používateľských politík musí byť povolená pre tenant. Spravuje ju vlastník alebo koordinátor; politiku, do ktorej patrí vlastník, mení len vlastník.
Postup v UI:
- Otvorte Používateľské politiky → Nová používateľská politika a zadajte názov.
- Vyberte povolené metódy. Aspoň jedna musí zostať zapnutá.
- Pri SAML vložte XML metadáta firemného poskytovateľa identity. Nastavte atribút e-mailu a podľa potreby mena.
- Politiku uložte, použite dostupné metadáta/údaje služby pri konfigurácii poskytovateľa identity a vykonajte test pripojenia.
- Až po úspešnom teste pripájajte používateľov a prípadne vypínajte heslo. Vlastník môže na detaile použiť pripojenie vlastného účtu po úspešnom teste.
- Pri pozvaní nového spravovaného používateľa vyberte politiku a osobitne prideľte firmy a roly.
Výsledok: politika určuje autentifikáciu a správu identity. Sama neudeľuje prístup k dokumentom ani firmám. Existujúceho nespravovaného používateľa nemožno automaticky previesť pod správu len opätovnou pozvánkou; môže byť potrebné vyriešenie vlastníctva identity. Politiku s priradenými používateľmi nemožno jednoducho deaktivovať.
API: verejné API V1/SAPI nemá správu politík ani SSO provisioning. Používateľské API neobsahuje parameter na priradenie politiky. SAML callback a metadata URL slúžia poskytovateľovi identity; nejde o všeobecné zákaznícke CRUD API. Tento postup sa vzťahuje na SAML. Podporu OIDC alebo SCIM je potrebné overiť samostatne.

Správa používateľov a rolí v každodennej prevádzke
Pridávajte kolegov, meňte ich oprávnenia a odoberajte prístup k firmám z aplikácie alebo integračného systému.
Postup v UI: vlastník/koordinátor otvorí Používatelia, vyhľadá osobu a klikne na Upraviť prístup. Pri každej firme zvolí Správca, Spracovateľ alebo Čitateľ; odstráni nepotrebné firmy. Osobitne skontroluje rolu vo fakturačnom účte. Po uložení overí zostávajúce prístupy. Pri odchode pracovníka skontroluje obe úrovne, nie iba jednu firmu.
Postup cez API: načítajte GET /api/v1/users/{id}, zostavte úplný požadovaný zoznam accounts a odošlite PATCH /api/v1/users/{id}. Napríklad firma Alfa môže zostať s processor a firma Beta s reader. Prázdne pole odoberá nevlastnícke firemné členstvá v rámci tenanta. Vynechanie poľa accounts nie je príkaz na odobratie prístupov.
Dôležité rozdiely: API upravuje firemné členstvá, nie heslo, e-mail, meno, SSO politiku alebo vlastnícke/koordinátorské roly. Existujúceho používateľa pridávajte cez POST len na doplnenie chýbajúcich prístupov; na zmenu existujúcej roly použite PATCH. Globálne zmazanie osoby ani deaktivácia celého používateľského účtu nie sú verejnou zákazníckou API operáciou. Presné oprávnenia všetkých rolí sú v bode 02.

Dokumenty a spracovanie
Faktúry, dobropisy, samofakturácia a ďalšie typové kódy
Vytvárajte faktúry a dobropisy a importujte aj doklady v režime samofakturácie. Štruktúrované XML sa kontroluje podľa príslušného Peppol profilu.
| Dokument/proces | Podoba v aplikácii | Základný generovaný kód |
|---|---|---|
| Faktúra | invoice, bez samofakturácie |
380 |
| Dobropis | credit_note, bez samofakturácie |
381 |
| Samofaktúra | invoice, zapnutá samofakturácia |
389 |
| Samofakturačný dobropis | credit_note, zapnutá samofakturácia |
261 |
Postup v UI: zvoľte firmu → Nový dokument → Vytvoriť dokument ručne → Začať. Prejdite výber odosielateľa, základné údaje, príjemcu, položky, prílohy a súhrn. V prvom kroku Odosielateľ vyberte v poli Typ dokladu jednu z možností: Faktúra, Dobropis, Ťarchopis, Faktúra k prijatej platbe, Samofaktúra, Samofakturovaný dobropis alebo Samofakturovaný ťarchopis. Pri samofakturácii je vybraný účet odberateľom a príjemca dokumentu dodávateľom. Samofakturačné doklady môžete pripraviť aj importom XML alebo CSV. Doplňte číslo, dátumy, menu a potrebné odkazy na pôvodný dokument. Po vytvorení skontrolujte detail a kliknite na Odoslať. Právo vytvárať a odosielať má vlastník/správca/spracovateľ firmy.
Samofakturácia: odosielateľom v prenose je kupujúci vystavujúci doklad za dodávateľa; preto sa technické smery nesmú slepo odvodiť z názvov „dodávateľ“ a „odberateľ“. Účet odosielateľa a XML musia byť v súlade s procesom self-billing.
API: prenáša sa UBL Invoice alebo CreditNote s príslušnými CustomizationID, ProfileID a typovým kódom. API V1 používa POST /send-documents, SAPI POST /document/send. Odpoveď V1 obsahuje document_type a is_self_billing.
Ťarchopis: ťarchopis (383) vytvoríte v sprievodcovi ako typ dokladu; odosiela sa ako Invoice s typovým kódom 383. Samostatný UBL koreň DebitNote pri importe XML podporovaný nie je. Štandardné kódy sa overujú v oficiálnej dokumentácii Peppol BIS Billing.

Schvaľovanie prijatých faktúr
Návod ukazuje, ako oprávnený používateľ schváli prijatú faktúru a ako účtovník zobrazí iba schválené faktúry.
Používateľ je prihlásený, má vybraný správny účet a rolu vlastník, administrátor alebo spracovateľ dokumentov.
Tento návod opisuje manuálne schválenie jednej prijatej faktúry a následné filtrovanie všetkých schválených faktúr v schránke prijatých dokumentov.
Krok 1 – Otvorte Prijaté dokumenty
V navigácii vyberte položku Prijaté dokumenty. Zobrazí sa schránka so zoznamom prijatých faktúr a dobropisov.

Krok 2 – Otvorte faktúru, ktorú chcete schváliť
V tabuľke kliknite na riadok požadovanej faktúry. Pri výbere si skontrolujte dodávateľa, ID dokumentu a sumu.

Krok 3 – Na detaile faktúry kliknite na Schváliť
Pred schválením skontrolujte základné údaje faktúry. Tlačidlo Schváliť sa nachádza vpravo hore.

Krok 4 – Doplňte komentár a potvrďte schválenie
Komentár je voliteľný. Odporúčame uviesť podklad schválenia, napríklad číslo objednávky alebo meno kontrolóra. Potom kliknite na Schváliť.

Krok 5 – Skontrolujte potvrdenie schválenia
Po úspešnom uložení sa zobrazí správa Dokument bol schválený. V prehľade pribudne zelené označenie schválenia a prípadný komentár.

Dôležité
Schválenie nemení procesný stav dokumentu (napríklad Dokončená). Ide o samostatné označenie, ktoré sa zapisuje aj do histórie dokumentu.
Ak bolo schválenie vykonané omylom, na detaile faktúry použite tlačidlo Zrušiť schválenie.
Krok 6 – Vo filtri Schválený vyberte Áno
V schránke Prijaté dokumenty otvorte pole Schválený a zvoľte Áno. Následne kliknite na tlačidlo Filtrovať.

Krok 7 – Skontrolujte zoznam schválených faktúr
Po aplikovaní filtra sa zobrazia iba dokumenty označené ako schválené. Aktívny filter zostáva viditeľný ako Schválený = Áno. Filter zrušíte tlačidlom Resetovať.

Uzatvorenie prijatej faktúry
Návod ukazuje, ako oprávnený používateľ označí prijatú faktúru ako dokončenú, doplní poznámku a následne zobrazí dokončené faktúry v zozname.
Používateľ je prihlásený na správnom účte a má oprávnenie vlastníka, administrátora alebo spracovateľa dokumentov.
Tento návod opisuje manuálne uzatvorenie jednej prijatej faktúry ako Dokončená a následné filtrovanie dokončených faktúr v schránke prijatých dokumentov.
Krok 1 – Otvorte Prijaté dokumenty
V navigácii vyberte položku Prijaté dokumenty. Zobrazí sa schránka so zoznamom prijatých faktúr a dobropisov.

Krok 2 – Otvorte faktúru, ktorú chcete uzatvoriť
V tabuľke kliknite na riadok požadovanej faktúry. Pred otvorením si skontrolujte dodávateľa, odberateľa, ID dokumentu a sumu.

Krok 3 – Na detaile faktúry kliknite na Označiť ako dokončené
Pred uzatvorením skontrolujte základné údaje faktúry. Tlačidlo Označiť ako dokončené sa nachádza vpravo hore a je dostupné pre dokumenty, ktoré ešte nemajú stav Dokončená.

Krok 4 – Doplňte poznámku a potvrďte uzatvorenie
Poznámka je voliteľná. Odporúčame uviesť dôvod uzatvorenia alebo interný odkaz, napríklad kto faktúru skontroloval. Potom kliknite na Označiť ako dokončené.

Krok 5 – Skontrolujte potvrdenie a poznámku
Po úspešnom uložení sa zobrazí potvrdenie, že dokument bol označený ako dokončený. V prehľade faktúry pribudne zelený stav Dokončená a uložená Poznámka k dokončeniu.

Dôležité
Uzatvorenie zmení procesný stav dokumentu na Dokončená. Nie je to samostatný príznak schválenia. Ak potrebujete hľadať uzatvorené faktúry, použite filter Stav = Dokončená. Ak potrebujete hľadať schválené faktúry, použite filter Schválený = Áno.
Krok 6 – Vo filtri Stav vyberte Dokončená
V schránke Prijaté dokumenty otvorte pole Stav a zvoľte Dokončená. Následne kliknite na tlačidlo Filtrovať.

Krok 7 – Skontrolujte zoznam dokončených faktúr
Po aplikovaní filtra sa zobrazia iba dokumenty so stavom Dokončená. V stĺpci Stav vidíte zelené označenie Dokončená; ak bola zadaná poznámka, pri stave sa zobrazí ikona poznámky s textom v náhľade.

Krok 8 – Voliteľne uzatvorte viac faktúr naraz
Ak potrebujete uzatvoriť viac prijatých faktúr, v zozname označte vybrané riadky, otvorte ponuku Akcie a zvoľte Označiť ako dokončené. Poznámka z modálneho okna sa uloží ku všetkým vybraným dokumentom.

Kontrola po hromadnej akcii
Po uložení môžete použiť rovnaký filter Stav = Dokončená. Dokumenty, ktoré už boli dokončené, sa v zozname nedajú znovu vybrať na uzatvorenie a zostanú označené stavom Dokončená.
Prijaté faktúry: zobrazenie, PDF, XML a tlač
Prijaté e-faktúry si pozriete v čitateľnej podobe, stiahnete ako PDF alebo XML a vytlačíte.
Prijaté e-faktúry nájdete v menu Prijaté dokumenty.
- Kliknite na faktúru. V detaile vidíte jej údaje v čitateľnej podobe.
- Tlačidlom Stiahnuť PDF si stiahnete PDF náhľad faktúry, ktorý môžete vytlačiť alebo uložiť.
- Tlačidlom Stiahnuť XML si stiahnete pôvodnú e-faktúru vo formáte Peppol BIS 3, ktorú načíta účtovný program.
- Tlačidlom Poslať kópiu e-mailom pošlete faktúru ako XML s PDF náhľadom, napríklad účtovníčke. Tlačidlo vidí správca a spracovateľ firmy.
Viac faktúr naraz si stiahnete exportom, pozrite návod Export faktúr.
Export faktúr: Excel, CSV a Peppol XML (ZIP)
Všetky faktúry za obdobie si stiahnete naraz do svojho archívu alebo pre účtovníčku.
- Vo webovej aplikácii otvorte Odoslané dokumenty alebo Prijaté dokumenty a filtrom si vyberte obdobie či dodávateľa.
- Kliknite na Exportovať a zvoľte formát. Excel a CSV obsahujú prehľad dokumentov podľa filtra.
- Pre Peppol XML (ZIP) najprv označte dokumenty. Zaškrtnutím v hlavičke a voľbou „Označiť všetkých … dokumentov podľa filtra“ označíte celý výsledok filtra. Jeden export môže obsahovať najviac 1 000 dokumentov.
- ZIP sa pripravuje na pozadí, medzitým môžete pracovať ďalej. Hotový súbor stiahnete v menu Exporty tlačidlom Stiahnuť ZIP do 30 dní, potom ho zmažeme. Samotné faktúry v aplikácii zostávajú.
ZIP obsahuje e-faktúry vo formáte Peppol BIS 3 XML.
Automatizácie: preposielanie prijatých faktúr
Automatizácia urobí akciu sama pri každej prijatej faktúre, napríklad ju pošle do schránky vašej účtovníčky.
- Otvorte Nastavenia → Integrácie a v časti Automatizácie kliknite na Spravovať automatizácie → Nová automatizácia.
- Zadajte názov, napríklad „Preposielať faktúry do účtovníctva“. Spúšťačom je prijatý dokument.
- V poli Vzťahuje sa na zvoľte typ dokumentu a v poli Spúšťa sa pre účty všetky alebo vybrané firmy.
- Vyberte akciu: E-mail – zadajte príjemcov a zvoľte, či priložiť pôvodné XML a PDF náhľad; alebo SFTP – zadajte server, používateľa, heslo alebo súkromný kľúč a priečinok a overte ho tlačidlom Otestovať pripojenie.
- Kliknite na Vytvoriť automatizáciu.
Automatizácie nastavuje vlastník, koordinátor alebo IT administrátor. Časť Integrácie je dostupná v balíkoch, ktoré obsahujú integrácie.
API V1 a rozhranie SAPI
Pripojte účtovný systém cez API V1 alebo rozhranie SAPI pre odosielanie a prevzatie elektronických dokumentov.
UI: v Integrácie → API otvorte dokumentáciu. Vo výbere definície zvoľte API V1 Docs, SAPI Docs alebo Webhook Docs. Údaje a hlavičky pre jednotlivé rozhrania nepreberajte bez úpravy medzi nimi.
Postup odoslania cez SAPI:
- Získajte OAuth2 token cez
/sapi/auth/tokenalebo použite podporovaný API token. - Pripravte JSON s
metadata,payload(XML),payloadFormat: "XML"; prípadnepayloadEncoding: "UTF-8"a SHA-256checksum. - V metadátach uveďte
documentId,documentTypeId,processId,senderParticipantId,receiverParticipantId,creationDateTimev ISO 8601. Údaje o stranách a profile musia zodpovedať XML. - Zavolajte
POST /sapi/document/sends Bearer tokenom,X-Peppol-Participant-Ida povinným UUID vIdempotency-Key. - Pri
202uložteproviderDocumentId. Odpoveď potvrdzuje prijatie požiadavky prístupovým bodom, nie konečné doručenie príjemcovi. Ďalší stav overte cez UI, API V1 alebo webhooky.
Postup prevzatia: GET /sapi/document/receive?status=RECEIVED&limit=20 → pre každé ID GET /sapi/document/receive/{documentId} → bezpečne uložte payload vo svojom systéme → POST /sapi/document/receive/{documentId}/acknowledge. Prejdite aj ďalšie stránky cez nextPageToken. Až úspešné uloženie je vhodným okamihom na potvrdenie prevzatia. ACKNOWLEDGED neznamená zaúčtovanie ani schválenie faktúry.
Opakovanie požiadavky: v rámci 24-hodinovej platnosti idempotency kľúča rovnaký kľúč a rovnaké telo vracajú pôvodný výsledok. Rovnaký kľúč s iným telom vyvolá 409. Pri rozpracovanej rovnakej požiadavke rešpektujte retryable a oneskorenie. Neposielajte pri každom timeoute nový kľúč.
Dôležité: implementované SAPI rozhranie nie je automaticky nezávislý dôkaz „100 % kompatibility“ so všetkými verziami štandardu. Aktuálna lokálna definícia je označená 2026-08-31. Rozsah technického prijatia a potvrdenia prevzatia vysvetľuje oficiálna SAPI dokumentácia.

Veľkosť súborov a hromadné odosielanie
Odosielajte viac pripravených dokumentov naraz z aplikácie alebo dávkového API. Každý dokument má vlastný výsledok spracovania.
UI — dávka: otvorte Odoslané dokumenty, označte dokumenty v stave Nová s pripraveným XML, zvoľte Akcie → Odoslať dokumenty. Skontrolujte správu o zaradení a následne stav každého dokumentu. Dávka pracuje v aktuálne vybranej firme. Nahrávanie PDF/CSV cez dlaždice je samostatný import, nie automaticky hromadný upload viacerých faktúr.
API — dávka: POST /api/v1/send-documents s Content-Type: application/json, Bearer tokenom, X-Account-Id a JSON poľom objektov {"xml":"<obsah XML>","xml_file_name":"faktura.xml"}. Aj jeden dokument sa posiela ako pole. Odozva obsahuje count, created_count, duplicate_count, invalid_count a results s indexom a výsledkom každej položky.
Vyhodnotenie: 201 znamená vytvorenie/zaradenie, 200 môže znamenať nájdenú duplicitu, 207 zmiešané výsledky. Vždy spracujte results, nielen HTTP status celej dávky. Existujúca duplicita sa automaticky znovu neposiela. Dokumentové kvóty platia aj pri dávkach.
| Cesta alebo limit | Aktuálna implementácia |
|---|---|
| PDF a CSV zdroj | Najviac 10 MiB na zdrojový súbor; UI používa označenie MB. |
| Importované XML cez UI/API V1 | Ukladá sa aj ako zdrojový súbor, takže podlieha limitu 10 MiB. |
SAPI payload |
Najviac 10 MiB XML. |
| XML pripojené k odosielanému dokumentu | Osobitná validácia vyžaduje menej ako 100 MiB. Tento interný limit neruší nižší limit uploadu zdroja. |
| Prílohy v ručnom formulári | Súhrnne najviac 10 MiB podľa aktuálnej kontroly formulára. |
Prílohy, napríklad vlastné PDF faktúry, rozpis prác či dodací list, pridáte v sprievodcovi v kroku Prílohy alebo pri úprave dokumentu vytvoreného z PDF. Podporované sú formáty PDF, PNG, JPEG, CSV, XLSX a ODS, spolu najviac 10 MB. Prílohy sa vložia priamo do XML e-faktúry a príjemca ich dostane spolu s ňou.
Dôležité: všeobecné zákaznícke „odosielanie súborov do 100 MB“ nezodpovedá dnešným uploadovým cestám. Pri nahrávaní sa riaďte limitom konkrétneho spôsobu importu; celkový HTTP request navyše podlieha konfigurácii nasadenia. SAPI odosiela jeden dokument na požiadavku, dávkový endpoint je súčasťou API V1.

BIS3 XML, PDF, CSV a vyťažovanie údajov
Začnite hotovým BIS3 XML, importujte CSV, vyťažte údaje z PDF alebo vytvorte dokument ručne. Pred odoslaním skontrolujete výsledok.
PDF — postup: Nový dokument → Vytvoriť dokument z PDF → Nahrať dokument. Aplikácia pripraví koncept a pokúsi sa vyčítať údaje. Porovnajte ich s PDF náhľadom: číslo, typ, dátumy, strany, Peppol identifikátory, menu, položky, DPH, sumy a platobné údaje. Opravte chýbajúce alebo nesprávne údaje. Rozpracovaný doklad uložte ako koncept; kompletný dokončite a následne odošlite. Neúspešné vyťaženie neznamená, že sa údaje nesmú ručne doplniť.
Mobilná aplikácia: v mobilnej aplikácii Digitálny poštár zvoľte Nový dokument a ťuknite na Naskenovať alebo nahrať. Papierovú faktúru naskenujte alebo odfoťte, prípadne vyberte PDF súbor. Údaje z dokumentu vyplníme za vás; pred odoslaním ich skontrolujte. Predplatné a niektoré nastavenia spravujete vo webovej aplikácii.
CSV — postup: otvorte Dokumentácia CSV importu, stiahnite vzor a pripravte jeden dokument v jednom súbore. Obsahuje riadok document, položky line_item a daňové súhrny tax_summary. Importer neprepočítava ceny, dane a súčty za zdrojový systém; pripravte konzistentné čísla. Nahrajte súbor, vyriešte chyby validácie, skontrolujte detail a odošlite.
XML — postup: pri Importovať XML BIS 3.0 súbor nahrajte platný UBL Invoice/CreditNote. Vstupný súbor nemá obsahovať obal StandardBusinessDocument; obálku pripravuje aplikácia. Po úspešnej validácii skontrolujte detail a odošlite. Chybné importované XML opravte v zdrojovom systéme a nahrajte znovu.
API: publikované odosielacie endpointy V1 a SAPI prijímajú XML. Zákaznícky API endpoint na nahratie PDF na vyťaženie alebo priamy CSV import nie je publikovaný. PDF vizualizáciu existujúceho dokumentu možno stiahnuť cez GET /api/v1/sent-documents/{id}/download-pdf, resp. rovnakú cestu pod received-documents; potrebný je prístup ku firme.
Výsledok: PDF a CSV sú vstupné podklady pre prípravu štruktúrovaného dokumentu. PDF súbor sám osebe nie je Peppol BIS XML. Stav Nová v UI ešte neznamená odoslanie. Limity sú v bode 20.

Rozpis polí e-faktúry
Zrozumiteľný sprievodca 163 poľami e-faktúry v desiatich častiach.
Zistite, čo znamenajú jednotlivé údaje vo faktúre, kde sa nachádzajú v XML a kedy ich treba vyplniť. Pri každom poli nájdete BT kód, názov, XML označenie a jednoduché vysvetlenie.
- Hlavička faktúry
- Informácie o dodávateľovi
- Informácie o odberateľovi
- Príjemca platby a daňový zástupca
- Dodacie údaje a referencie
- Fakturačné riadky
- Zľavy a príplatky
- Rozpis DPH
- Súčty faktúry
- Platobné údaje
V podrobnom rozpise môžete vyhľadávať podľa názvu poľa, BT kódu alebo XML označenia, napríklad BT-151 alebo EndpointID.
Peppol validácia a samostatný validačný endpoint
Overte štruktúru a pravidlá Peppol dokumentu pri jeho príprave alebo samostatným API volaním pred odoslaním.
UI: import alebo dokončenie dokumentu vykoná validáciu. Pri chybe si prečítajte konkrétne hlásenia, opravte formulár alebo zdrojové XML a kontrolu zopakujte. Najprv odstráňte chyby štruktúry XSD, potom pravidlá Schematron. Validný doklad ešte vyžaduje správneho odosielateľa, dostupného príjemcu a oprávnenie odosielať.
API: POST /api/v1/document-validation (alias /api/v1/validate-document) s Bearer tokenom, Content-Type: application/xml a surovým XML v tele. Hlavička X-Account-Id sa nevyžaduje. Endpoint dokument nevytvorí ani neodošle.
Čítanie odpovede: HTTP 200 môže obsahovať aj valid: false. Rozhodujúce je valid, potom checks.xsd a checks.schematron. Pri neúspešnej XSD kontrole sa Schematron časť nemusí vrátiť; z vážnych Schematron chýb sa vracajú zlyhania označené fatal. Prázdne/nepodporované telo, neplatné XML alebo nedostupná validačná služba sa nesmú interpretovať ako úspech.
Príklad reakcie zákazníka: ak chyba ukáže nesúlad súčtov, opravte zdrojové položky a súhrny; ak chýba požadovaný identifikátor, doplňte ho. Neprepisujte výsledok na „validné“ len preto, že syntakticky ide o XML. Kvalita účtovných údajov a prijatie obchodným partnerom sú samostatné otázky.

Automatické opakovanie odosielania dokumentov
Pri vybraných dočasných chybách systém opakuje doručenie dokumentu a zobrazuje priebeh pokusov.
Postup v UI: otvorte detail v Odoslané dokumenty, skontrolujte stav a časovú os. Pri retrying_delivery prebieha opakovanie na pozadí; netreba zakladať duplicitnú faktúru. Pri failed_delivery skontrolujte príčinu; chybovú poznámku nájdete v detaile dokumentu.
Pravidlá: najviac 4 pokusy o doručenie dokumentu — prvý a tri opakovania s odstupmi 5, 25 a 125 minút po neúspešných pokusoch. Nejde o pevný čas doručenia; začatie závisí aj od frontu úloh. Nenájdený príjemca a vyčerpanie oprávnenia/kapacity sa riešia ako konečné chyby, nie ako dôvod na nekonečné opakovanie. TDD má vlastnú schému: pri opakovateľnej chybe odstupy 2, 4 a 8 minút, s rovnakým maximom pokusov v doručovacej službe.
API: stav sledujte cez GET /api/v1/sent-documents/{id} (status, error_code) alebo zodpovedajúci webhook. Verejný endpoint „retry existujúceho zlyhaného dokumentu“ nie je publikovaný. Opakované odoslanie rovnakej dávkovej položky môže vrátiť existujúcu duplicitu bez spustenia nového doručovania.
Hranice: ak doručenie skončí stavom Odosielanie zlyhalo alebo Odoslaná bez príjemcu, otvorte detail dokumentu a po odstránení príčiny kliknite na Zopakovať odoslanie. Ak príjemca nie je registrovaný v sieti Peppol, aplikácia ponúkne Odoslať e-mailom: dokument mu pošleme ako XML s PDF náhľadom na e-mail príjemcu. Do 31. 12. 2026 e-mail nahrádza doručenie cez Peppol, od 1. 1. 2027 dokument vždy odchádza cez Peppol, ako to vyžaduje zákon. Ak dokument posielať nechcete, zvoľte Označiť ako neodoslaný. Kópiu odoslaného aj prijatého dokumentu pošlete komukoľvek tlačidlom Poslať kópiu e-mailom. Opakovanie webhookov opisuje návod Dokumentové webhooky.

Automatické daňové dátové dokumenty TDD
Pri dokumentoch, ktoré spĺňajú podmienky reportovania, systém pripraví a odošle daňový dátový dokument TDD a zaznamená prijatú odpoveď.
Čo to znamená: TDD je štruktúrované oznámenie fakturačných údajov daňovej autorite. Nie je to všeobecné vytvorenie všetkých daňových priznaní, kontrolných výkazov alebo účtovných uzávierok. Účel popisuje oficiálna špecifikácia slovenského TDD.
Postup zákazníka v UI: pripravte a skontrolujte obchodný dokument vrátane IČ DPH dodávateľa → odošlite ho bežným postupom → v časovej osi detailu sledujte udalosť odoslania TDD a následnú MLS odpoveď k TDD → pri negatívnej alebo chýbajúcej odpovedi odovzdajte podpore identifikátor dokumentu a detail udalosti. TDD sa neposiela osobitným bežným zákazníckym tlačidlom.
Podmienky aktuálneho kódu: automatické TDD sa pripravuje pre odosielaný dokument s vyplneným IČ DPH dodávateľa. Voliteľné nastavenie nasadenia môže reportovanie obmedziť na prípady, kde sú dodávateľ aj odberateľ v SR. V produkčnom prostredí je reportovanie v kóde blokované pred 1. januárom 2027. Tento dátum opisuje implementačný prepínač, nie samostatné právne posúdenie povinností zákazníka.
Potvrdenie: úspešný prenos TDD a pozitívna MLS odpoveď sú samostatné udalosti. Kód vie priradiť prijatú MLS k TDD a zapísať ju na časovú os faktúry. Potvrdenie treba skontrolovať; nepredpokladajte ho pri každom odoslaní.
API: pri relevantnom odoslaní cez V1/SAPI sa TDD plánuje automaticky. Verejná serializácia faktúry neobsahuje samostatný TDD stav/potvrdenie a publikovaný TDD CRUD endpoint nie je k dispozícii. Odpoveď na TDD posielame samostatnou udalosťou tdd_mls_received, nie cez mls_received. Typy TDD submit, resubmit, disregard existujú interne, ale zákaznícky opravný proces pre všetky tri nemožno z toho automaticky sľúbiť.

Spracovanie MLS pre dokumenty a TDD
Pri doručovaných dokumentoch sledujete MLS odpovede a ich dôvody. Odpovede na daňové dátové dokumenty sa zaznamenávajú do histórie súvisiaceho dokladu.
UI: otvorte Odoslané dokumenty a kliknite na dokument. Odpoveď MLS nájdete v detaile v časti Súbory (MLS odpoveď, MLS odpoveď na TDD) a v Histórii dokumentu. Pri zamietnutí si v nej prečítajte popis a chyby riadkov. Výsledok sa prejaví aj v stĺpci Stav (Akceptovaná alebo Zamietnutá).
| MLS | Význam v integračnom procese | Správanie obchodného dokumentu v aplikácii |
|---|---|---|
AP |
Pozitívna odpoveď | Prechod do accepted; API typicky mls_status: "AP_accepted". |
RE |
Zamietnutie s dostupným dôvodom | Prechod do rejected; API RE_rejected. |
AB |
Potvrdenie/acknowledgement na úrovni správy | Aktuálna implementácia tiež nastaví accepted, ale zachová AB_acknowledged v mls_status. |
| Bez MLS | Odpoveď ešte nie je evidovaná | Nie je to automaticky chyba ani dôkaz prijatia. |
API: pri faktúre použite GET /api/v1/sent-documents/{id} a vyhodnocujte status spolu s mls_status. Webhook mls_received dopĺňa objekt mls_response s status, dostupným description a line_errors. TDD odpoveď je samostatne spracovaná interne a zobrazená v histórii; nie je zahrnutá do tohto dokumentového webhooku.
Dôležité rozlíšenie: technická alebo validačná MLS nie je doklad o úhrade ani potvrdenie zaúčtovania zákazníkovým ERP. Lokálne schválenie prijatej faktúry používateľom je zase iná akcia. Najmä AB nemožno bez ďalších informácií označiť za obchodné schválenie alebo za pozitívne daňové rozhodnutie.

Dokumentové webhooky a spoľahlivé prevzatie udalostí
Pripájajte udalosti prijatia a doručenia dokumentov k svojmu účtovnému systému pomocou HTTPS webhookov.
Postup v UI: vlastník/koordinátor otvorí Integrácie → Spravovať webhooky → Nový webhook, zadá názov, HTTPS URL, token a vyberie udalosti. Pred uložením si endpoint overí tlačidlom Odoslať testovaciu udalosť. Webhook neskôr upraví alebo deaktivuje. Nastavenie patrí tenantovi a udalosti rozlišujú firmy pomocou account_id; formulár neposkytuje samostatný výber podmnožiny firiem.
| Udalosť | Čo prijímač spracuje |
|---|---|
manual_creation |
Vznik dokumentu v podporovanom používateľskom/importnom procese; nejde o doručenie. |
successfully_sent |
Úspešný prenos dokumentu. |
failed_delivery |
Zlyhané doručenie; skontrolovať chybu a aktuálny stav. |
mls_received | MLS k obchodnému dokumentu, popis a dostupné chyby. |
tdd_mls_received | Odpoveď (MLS) Finančnej správy na daňový dátový dokument (TDD) k faktúre; obsahuje údaje dokumentu, TDD aj MLS. |
document_received |
Prijatý dokument vrátane serializovaných údajov a xml_file_content. |
Čo musí pripraviť zákazník: prijímač HTTP POST, kontrolu Bearer tokenu z konfigurácie, bezpečné uloženie udalosti, spracovanie firmy/ID/typu udalosti a odpoveď 2xx. Odporúčané je uložiť udalosť do vlastného frontu a účtovné spracovanie dokončiť asynchrónne. Prijímač má zvládnuť duplicity a udalosť spracovať idempotentne; dokument si môže dočítať cez API V1.
Opakovanie: ak je pri webhooku zapnuté Opakovať neúspešné doručenia a váš endpoint je nedostupný alebo neodpovie stavom 2xx, udalosť sa zopakuje po 5 minútach, 30 minútach, 2 hodinách, 5 hodinách, 10 hodinách a potom každých 12 hodín, najviac 3 dni od prvého pokusu. Ak posledné opakovanie zlyhá pri 3 udalostiach za sebou, webhook sa automaticky deaktivuje. Komu prídu e-maily o zlyhaní (vlastníkom, na zadané adresy alebo nikomu), nastavíte pri každom webhooku; vlastníci dostávajú aj denný súhrn zlyhaní. Deaktivovaný webhook znovu zapnete tlačidlom Aktivovať. Udalosti, ktoré vznikli počas deaktivácie alebo pozastaveného predplatného, sa dodatočne neodošlú.
Ako chrániť proces pred medzerami: popri webhookoch pravidelne načítavajte dokumenty cez API so stránkovaním a porovnávajte ich s vlastnou evidenciou. Pri dočasnom výpadku vášho prijímača použite toto zosúladenie. Verejný zákaznícky endpoint na opätovné prehratie webhooku nie je publikovaný.

Stavy dokumentov v UI, API a webhookoch
Sledujte prípravu, odoslanie, doručenie a odpovede k dokumentom v jednom prehľade alebo vo svojom systéme.
UI: Odoslané dokumenty ponúkajú filtre a rýchle prehľady čakajúcich na kontrolu/odoslanie. Detail obsahuje údaje dokladu, stav, MLS, súbory a časovú os. V Prijaté dokumenty môžete podľa oprávnení schvaľovať, rušiť schválenie alebo označiť dokumenty ako dokončené.
| Stav | Čo znamená | Čo urobí zákazník |
|---|---|---|
draft — Koncept |
Rozpracovaný doklad | Doplniť a skontrolovať údaje, dokončiť dokument. |
new — Nová |
Pri odosielanom doklade pripravený záznam pred zaradením; pri prijatom nový dokument | Odosielaný skontrolovať a odoslať; prijatý prevziať/spracovať. |
ready_to_send — Pripravená na odoslanie |
Dokument je pripravený vo fronte | Čakať na výsledok, nezakladať duplicitu. |
sent — Odoslaná |
Prenos bol úspešný | Sledujte aj prípadnú MLS. Neznamená úhradu. |
retrying_delivery — Opakované doručovanie |
Prebiehajú opakovateľné pokusy | Skontrolovať históriu a neskorší výsledok. |
failed_delivery — Odosielanie zlyhalo |
Odosielanie sa skončilo neúspešne | V detaile dokumentu skontrolovať chybu a po odstránení príčiny zvoliť Zopakovať odoslanie. |
sent_via_email — Odoslaná e-mailom | Príjemca nie je v sieti Peppol, preto sme mu dokument do konca roka 2026 poslali e-mailom ako XML s PDF náhľadom. | Nič. Od 1. 1. 2027 dokument vždy odchádza cez Peppol. |
sent_without_recipient — Odoslaná bez príjemcu | Od 1. 1. 2027: dokument sme odoslali cez Peppol, ale príjemca v sieti Peppol nie je registrovaný. Vašu povinnosť odoslať e-faktúru ste tým splnili. | Ak by mal byť príjemca v sieti Peppol, skontrolujte jeho DIČ na dokumente a zopakujte odoslanie. Dokument mu môžete poslať aj e-mailom. |
accepted — Akceptovaná |
Dokument má akceptovaný stav podľa spracovania | Pri odoslanom pozrieť aj konkrétny MLS kód. |
rejected — Zamietnutá |
Zamietnutý dokument | Prečítať dôvod a vyriešiť opravu s protistranou. |
completed — Dokončená |
Prijatý dokument označený ako dokončený | Znamená lokálne vybavenie, nie automaticky účtovné alebo bankové potvrdenie. |
API: GET /api/v1/sent-documents a GET /api/v1/received-documents vracajú stránkované prehľady; detail načítate cez /{id} s X-Account-Id. Podľa potreby filtrujte stav/dátumy podľa dokumentácie. V1 používa limit najviac 100 a offset; sledujte next. Na detaile kontrolujte status, mls_status, error_code, downloaded a dostupné URL súborov.
Prevzatie verzus spracovanie: PATCH /api/v1/received-documents/{id} s {"downloaded":true} zaznamená prevzatie integračným systémom. Ide o iný údaj než lokálny dokumentový stav. SAPI používa /acknowledge a stav prevzatia ACKNOWLEDGED. Samotné stiahnutie, potvrdenie prevzatia, schválenie v UI a dokončenie procesu nie sú zameniteľné. V1 aktualizácia odoslaného dokumentu umožňuje meniť príznak downloaded a obmedzene stav new → ready_to_send; neumožňuje ľubovoľne nastaviť sent alebo accepted. Samotný tento PATCH neplánuje doručovaciu úlohu, preto ho nepoužívajte ako náhradu zdokumentovaného odosielacieho endpointu alebo tlačidla Odoslať.
Webhooky: upozorňujú na vybrané udalosti podľa bodu 26, nie na každý interný prechod stavu. Pri potrebe aktuálneho jednoznačného výsledku načítajte detail cez API.

API integrácie
Pred prvým volaním si pripravte API kľúč alebo OAuth2 prístup a podľa operácie aj X-Account-ID firmy. Zmenu režimu podľa stavu účtu vysvetľuje návod Zmena režimu firmy cez API.
Príklady používajú curl a pri príprave JSON z XML aj jq. Nastavte API_BASE na schválený endpoint svojho prostredia, napr. testovací https://test.postarflowis.sk/api/v1. TOKEN, ACCOUNT_ID, USER_ID, DOCUMENT_ID a ostatné premenné sú zástupné hodnoty. Každý príklad s POST/PATCH môže po doplnení reálnych údajov vytvoriť záznam, poslať pozvánku alebo spustiť odosielanie; príklady neboli vykonané proti externým službám.
Získanie OAuth2 tokenu
Súbor oauth-request.json:
{
"client_id": "<CLIENT_ID>",
"client_secret": "<CLIENT_SECRET>",
"grant_type": "client_credentials"
}
curl --request POST "$API_BASE/auth/token" \
--header 'Content-Type: application/json' \
--data-binary @oauth-request.json
Access token z odpovede použite v TOKEN; refresh token uložte osobitne. Pri jednoduchom API tokene tento krok vynechajte.
Zoznam a založenie firmy
curl "$API_BASE/accounts?limit=20&offset=0" \
--header "Authorization: Bearer $TOKEN"
Súbor account.json — ilustračné údaje nahraďte vlastnou firmou:
{
"name": "Ukážková firma s.r.o.",
"tax_id": "0000000000",
"country_code": "SK",
"document_mode": "both",
"company_email": "uctaren@example.invalid"
}
curl --request POST "$API_BASE/accounts" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data-binary @account.json
Uložte id z odpovede; čakajte na overenie. participant_id sa pri jeho vynechaní vytvorí podľa pravidiel aplikácie. Chyba missing_owner_user znamená, že tenant nemá vlastníka potrebného na založenie firmy.
Pridanie používateľa a zmena firemných rolí
Súbor user.json:
{
"name": "Ukážkový účtovník",
"email_address": "uctovnik@example.invalid",
"accounts": [
{"id": "<ACCOUNT_UUID>", "role": "processor"}
]
}
curl --request POST "$API_BASE/users" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data-binary @user.json
Pri následnom PATCH vytvorte access.json s úplným požadovaným zoznamom, nie iba zmenenou firmou:
{
"accounts": [
{"id": "<ALFA_UUID>", "role": "processor"},
{"id": "<BETA_UUID>", "role": "reader"}
]
}
curl --request PATCH "$API_BASE/users/$USER_ID" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data-binary @access.json
Vyhľadanie a samostatná validácia
curl --get "$API_BASE/peppol-lookup" \
--header "Authorization: Bearer $TOKEN" \
--data-urlencode "participant_id=$PARTICIPANT_ID"
curl --request POST "$API_BASE/document-validation" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/xml' \
--data-binary @invoice.xml
Pri validácii overte valid, nie iba návratový HTTP status. invoice.xml musí byť skutočný podporovaný dokument, nie ukážka s tromi bodkami.
Dávkové odoslanie dvoch XML
jq -n --rawfile first invoice-1.xml --rawfile second invoice-2.xml \
'[{xml:$first,xml_file_name:"invoice-1.xml"},
{xml:$second,xml_file_name:"invoice-2.xml"}]' > batch.json
curl --request POST "$API_BASE/send-documents" \
--header "Authorization: Bearer $TOKEN" \
--header "X-Account-Id: $ACCOUNT_ID" \
--header 'Content-Type: application/json' \
--data-binary @batch.json
Uložte ID z results[*].sent_document.id. Dávka môže byť čiastočne úspešná; znovu spracujte len položky, ktoré to podľa výsledku potrebujú. Správne escapovanie XML zabezpečuje JSON nástroj.
Stav dokumentu a prevzatie prijatého XML
curl "$API_BASE/sent-documents/$DOCUMENT_ID" \
--header "Authorization: Bearer $TOKEN" \
--header "X-Account-Id: $ACCOUNT_ID"
curl "$API_BASE/received-documents?limit=100&offset=0" \
--header "Authorization: Bearer $TOKEN" \
--header "X-Account-Id: $ACCOUNT_ID"
Načítajte detail prijatého dokumentu a bezpečne uložte súbor z dostupného xml_file_url. Potom potvrďte prevzatie:
curl --request PATCH "$API_BASE/received-documents/$DOCUMENT_ID" \
--header "Authorization: Bearer $TOKEN" \
--header "X-Account-Id: $ACCOUNT_ID" \
--header 'Content-Type: application/json' \
--data '{"downloaded":true}'
SAPI odoslanie a prevzatie
SAPI_BASE označuje základ, napr. https://test.postarflowis.sk/sapi. Pripravte sapi-metadata.json so šiestimi poliami z bodu 19 a skutočnými hodnotami z XML. DOCUMENT_TYPE_ID a PROCESS_ID musia zodpovedať bežnému alebo self-billing profilu; nepoužívajte vnútorné UUID aplikácie namiesto typového identifikátora.
{
"documentId": "<ID_V_ZDROJOVOM_SYSTEME>",
"documentTypeId": "<PEPPOL_DOCUMENT_TYPE_ID>",
"processId": "<PEPPOL_PROCESS_ID>",
"senderParticipantId": "<ODOSIELATEL_SCHEME:ID>",
"receiverParticipantId": "<PRIJEMCA_SCHEME:ID>",
"creationDateTime": "2026-10-28T10:00:00Z"
}
jq -n --slurpfile meta sapi-metadata.json --rawfile xml invoice.xml \
'{metadata:$meta[0],payload:$xml,payloadFormat:"XML",payloadEncoding:"UTF-8"}' \
> sapi-request.json
curl --request POST "$SAPI_BASE/document/send" \
--header "Authorization: Bearer $TOKEN" \
--header "X-Peppol-Participant-Id: $PARTICIPANT_ID" \
--header "Idempotency-Key: $IDEMPOTENCY_UUID" \
--header 'Content-Type: application/json' \
--data-binary @sapi-request.json
curl "$SAPI_BASE/document/receive?status=RECEIVED&limit=20" \
--header "Authorization: Bearer $TOKEN" \
--header "X-Peppol-Participant-Id: $PARTICIPANT_ID"
curl "$SAPI_BASE/document/receive/$DOCUMENT_ID" \
--header "Authorization: Bearer $TOKEN" \
--header "X-Peppol-Participant-Id: $PARTICIPANT_ID"
Po bezpečnom uložení prijatého obsahu:
curl --request POST "$SAPI_BASE/document/receive/$DOCUMENT_ID/acknowledge" \
--header "Authorization: Bearer $TOKEN" \
--header "X-Peppol-Participant-Id: $PARTICIPANT_ID"
Registrácia príjmu a migrácia
Máte globálny API credential, Bearer token a ID účtu, ktorý patrí pod váš fakturačný účet. Príklady používajú zástupné hodnoty {id}, <token> a EXAMPLE-CODE.
Krok 1 – Overte aktuálny stav účtu
Pred zmenou režimu si overte, aký má účet aktuálny document_mode a status. Endpointy pre SMP registráciu a migráciu používajú ID účtu v URL a nepoužívajú hlavičku X-Account-Id.
GET /api/v1/accounts/{id}
Authorization: Bearer <token>
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"document_mode": "sender",
"status": "verified_sending_only"
}Krok 2 – Ak účet čaká na overenie, zmeňte document_mode priamo
Kým má účet status: pending_verification, režim môžete zmeniť cez PATCH endpoint účtu. Po overení sa už režim nemení priamou editáciou účtu, ale cez SMP endpointy v ďalších krokoch.
PATCH /api/v1/accounts/{id}
Authorization: Bearer <token>
Content-Type: application/json
{ "document_mode": "both" }
=> { "document_mode": "both", "status": "pending_verification" }Krok 3 – Zapnite prijímanie pre Sender účet
Tento postup použite, keď účet má document_mode: sender a status: verified_sending_only. Výsledkom je účet v režime both so stavom verified.
Registrácia bez migračného kódu
POST /api/v1/accounts/{id}/smp-registration
Authorization: Bearer <token>
Content-Type: application/json
{}Registrácia s migračným kódom
POST /api/v1/accounts/{id}/smp-registration
Authorization: Bearer <token>
Content-Type: application/json
{ "sml_migration_code": "EXAMPLE-CODE" }
=> { "document_mode": "both", "status": "verified" }Dôležité: Migračný kód posiela pôvodný poskytovateľ, ak sa preberá existujúca registrácia. Ak účet ešte nebol registrovaný na prijímanie u iného poskytovateľa, použite prázdne body {}.
Krok 4 – Zistite alebo vyžiadajte migračný kód
Ak účet už prijíma dokumenty cez vaše SMP a má sa migrovať k inému poskytovateľovi, nový poskytovateľ potrebuje migračný kód. Tento postup použite pri účte s document_mode: receiver alebo both a so stavom verified alebo verified_transferable.
Kontrola aktuálneho stavu migrácie
GET /api/v1/accounts/{id}/smp-migration
Authorization: Bearer <token>
=> {
"status": "verified",
"document_mode": "both",
"migration_code": null
}Vyžiadanie migračného kódu
POST /api/v1/accounts/{id}/smp-migration
Authorization: Bearer <token>
=> {
"status": "verified_transferable",
"document_mode": "both",
"migration_code": "EXAMPLE-CODE"
}Dôležité: Vyžiadanie migračného kódu nemení document_mode. Účet ostáva prijímajúci, iba prejde do stavu verified_transferable a v odpovedi sa vráti migration_code.
Krok 5 – Zrušte aktívnu migráciu, ak už nemá pokračovať
Ak má účet status: verified_transferable, najprv zrušte aktívnu migráciu. Po úspechu sa odstráni migračný kód a účet sa vráti na status: verified.
DELETE /api/v1/accounts/{id}/smp-migration
Authorization: Bearer <token>
=> {
"status": "verified",
"document_mode": "both",
"migration_code": null
}Krok 6 – Vypnite prijímanie a ponechajte iba odosielanie
Tento postup použite, keď účet s document_mode: receiver alebo both a so stavom verified už nemá prijímať dokumenty cez naše SMP.
DELETE /api/v1/accounts/{id}/smp-registration
Authorization: Bearer <token>
=> { "document_mode": "sender", "status": "verified_sending_only" }Krok 7 – Vyberte správny endpoint podľa cieľa
Prehľad aktuálnych stavov a príslušných endpointov nájdete v návode Zmena režimu firmy cez API. Ak endpoint vráti validačnú chybu stavu, účet nie je v požadovanom vstupnom stave pre daný scenár.
Pravidlo pre API volania: Všetky endpointy v tomto návode používajú globálny API credential. SMP endpointy nepoužívajú X-Account-Id; účet sa vyberá podľa {id} v URL a musí patriť pod billing account použitého credentialu.
Príklad dokumentového webhooku
Zjednodušený ilustračný payload pre prijatú MLS k faktúre:
{
"event_type": "mls_received",
"account_id": "<ACCOUNT_UUID>",
"id": "<DOCUMENT_UUID>",
"invoice_id": "FV-2026-001",
"document_type": "invoice",
"is_self_billing": false,
"status": "accepted",
"error_code": null,
"mls_response": {"status": "AP_accepted", "description": "Accepted"}
}
Payloady a voliteľné polia sa líšia podľa udalosti. Autentifikáciu prijímača kontrolujte proti tokenu, ktorý ste nastavili pri tomto webhooku; nejde automaticky o rovnaký token ako pre API V1. Úplné schémy sú v definícii Webhook Docs.
Výsledky a chybné hlášky
| Situácia | Ako postupovať |
|---|---|
401 pri bežnom API volaní |
Overiť Bearer token, jeho platnosť a správne prostredie. Pri account_not_verified dokončiť overenie firmy. |
403 |
Skontrolovať rozsah kľúča, firmu/participant hlavičku, globálny prístup a stav predplatného. |
404 |
Skontrolovať UUID a firmu; používať ID vrátené rovnakým prostredím. |
409 v SAPI |
Zistiť konflikt idempotency kľúča alebo ešte prebiehajúce spracovanie. Opakovať iba podľa retryable. |
415 |
Opraviť Content-Type podľa endpointu. |
422 |
Prečítať konkrétne chyby polí, validácie, kvóty alebo stavu účtu. Opraviť príčinu pred novým pokusom. |
429 |
Spomaliť volania a použiť postupne predlžované oneskorenie. |
5xx alebo timeout |
Nevyhodnotiť ako úspech. Pri operácii s vedľajším účinkom najprv overiť existujúci výsledok a idempotenciu. |
V1 dávka 207 |
Spracovať výsledok každej položky; nesprávať sa k celej dávke ako k úplnému zlyhaniu. |
Validácia HTTP 200 a valid: false |
Dokument nie je validný. Riešiť chyby z odpovede. |
SAPI 202 |
Požiadavka bola technicky prijatá. Čakať na výsledok doručenia. |
| Webhook neprišiel | Skontrolujte, či je webhook aktívny a či má zapnuté opakovanie. Chýbajúce údaje načítajte cez API; spätné prehratie udalostí z obdobia deaktivácie nie je dostupné. |
Slovník
| Pojem | Význam |
|---|---|
| Tenant / fakturačný účet | Zastrešujúci klientsky priestor s predplatným, integráciami a správou osôb. |
| Účet firmy | Konkrétna firma s dokumentmi a Peppol identifikátorom. |
| Participant ID | Sieťový identifikátor, napr. slovenský 0245:<DIČ>. |
| UUID účtu/dokumentu | Interné ID API objektu; nie je to DIČ ani číslo faktúry. |
| SMP | Služba zverejňujúca metadáta účastníka a podporovaných služieb. |
| SML | Vyhľadávacia vrstva pre lokalizáciu registrácie účastníka. |
| BIS3 / UBL | Profil a štruktúra elektronickej faktúry alebo dobropisu. |
| SAPI | Štandardizované rozhranie medzi softvérom a prístupovým bodom. |
| MLS | Odpoveď na úrovni správy; vyhodnocujte konkrétny kód a kontext. |
| TDD | Daňový dátový dokument oznamujúci údaje faktúry. |
| Webhook | HTTP oznámenie udalosti z Flowisu na zákazníkovu adresu. |
| Idempotencia | Opakovanie rovnakej operácie bez nechceného duplicitného účinku v rámci definovaných pravidiel. |

