Manuál pre vývojárov - e-faktúra (Peppol) cez API

Faktúru vytvorenú vo Faktúrach online (cez API alebo ručne) môžete cez API odoslať do siete Peppol ako elektronickú faktúru. Odoslanie prebieha v dvoch krokoch:

1. Zaradenie volaním /api/peppol-send. Systém faktúru ihneď skontroluje (údaje dodávateľa a odberateľa, oprávnenie, kredit, režimy DPH) a zvaliduje vytvorenú e-faktúru (formát UBL, pravidlá EN 16931 a Peppol BIS). Ak niečo chýba, dostanete chybu hneď v odpovedi a nič sa neodošle. Ak faktúra obsahuje len upozornenia, neodošle sa, kým ju neopravíte alebo nepošlete s parametrom ignore_warnings=1. Ak je všetko v poriadku, faktúra sa zaradí do fronty a odpoveď má stav queued.
2. Odoslanie vykoná server na pozadí zvyčajne do jednej až dvoch minút: vytvorí PDF prílohu (ak ju má firma zapnutú) a odovzdá e-faktúru certifikovanému digitálnemu poštárovi. Výsledok zistíte volaním /api/peppol-status.

Pozor na trvanie. Odoslanie e-faktúry nie je okamžité. Volanie /api/peppol-send trvá spravidla 1 až 5 sekúnd, pretože sa synchrónne generuje a validuje celá e-faktúra. Samotné odovzdanie poštárovi prebehne na pozadí zvyčajne do 1 až 2 minút od zaradenia (stav sent). Potvrdenie doručenia odberateľovi (stav accepted) môže trvať 10 až 20 minút. Nečakajte na výsledok v rámci jedného volania a neposielajte faktúru opakovane, ak stav ešte nie je konečný.

Stavy odoslania, ktoré vracia /api/peppol-status:

peppol_status	Význam
not_sent	Faktúra ešte nebola zaradená na odoslanie.
queued	Čaká vo fronte na odoslanie (spracúva sa priebežne, poradie podľa zaradenia).
sent	Digitálny poštár e-faktúru prevzal a odovzdáva ju do siete Peppol.
accepted	E-faktúra bola doručená na prístupový bod odberateľa. Konečný úspešný stav.
rejected	Poštár alebo sieť e-faktúru odmietli. Podrobnosti sú v peppol_error.
not_valid	E-faktúra neprešla validáciou v sieti. Opravte údaje a odošlite opravný doklad.
failed	Odoslanie zlyhalo (technická chyba alebo vyčerpané pokusy). Podrobnosti sú v peppol_error a error_code. Ak je error_code receiver_unregistered, faktúra bola odoslaná a nahlásená finančnej správe, znova ju neposielajte.

Stav accepted sa dopĺňa priebežne podľa informácií od poštára, spravidla 10 až 20 minút po odoslaní. Systém výsledok neposiela (žiadny webhook), stav si vyžiadate sami cez /api/peppol-status.

• Potrebujete API kľúč a inicializované sedenie volaním /api/init, rovnako ako pri ostatných volaniach API (pozri základný manuál API).
• Spoločnosť (DIČ dodávateľa na faktúre) musí mať vo Faktúrach online dokončenú aktiváciu e-faktúry a aktívny balík alebo kredit transakcií. Aktiváciu urobíte v aplikácii v sekcii E-faktúra, cez API sa aktivovať nedá.
• Konto, ktorým voláte API, musí byť vlastníkom aktivácie alebo mať od vlastníka povolené odosielanie (delegácia).
• Odoslať sa dá riadna faktúra, dobropis, ťarchopis a daňový doklad k prijatej platbe. Zálohová faktúra sa do siete Peppol neodosiela.
• Každá faktúra sa dá odoslať len raz. Opravu urobíte opravným dokladom (dobropis a nová faktúra).

Pred týmto volaním je potrebné inicializovať sedenie (/api/init). Volanie API pre odoslanie faktúry:

https://www.faktury-online.com/api/peppol-send?data={JSON}

Parametre:

Parameter	Atribút	Popis
key	povinný parameter	API kľúč.
email	povinný parameter	Email (alebo používateľské meno), ktorým sa prihlasujete do Faktúr online.
code	povinný parameter	Kód faktúry (získaný z odpovede API pri vytvorení faktúry).
validate_only	nepovinný parameter	Hodnota 1 faktúru len skontroluje a zvaliduje, nič neodošle a nespotrebuje kredit. Vhodné na overenie údajov pred ostrým odoslaním. Predvolená hodnota: 0
ignore_warnings	nepovinný parameter	Hodnota 1 odošle faktúru aj vtedy, keď má upozornenia (pole warnings). Pri hodnote 0 sa faktúra s upozornením neodošle a vráti sa stav 1622. Chyby odoslanie blokujú vždy. Predvolená hodnota: 0

Príklad požiadavky:

Array
(
    [key] => vJyMc*4@2754*wGhofIWi!QDcEEQUdmj
    [email] => name@example.com
    [code] => 26915945a67c8b7ba74dac59c5badfbf
    [validate_only] => 0
    [ignore_warnings] => 0
)

Odpoveď pri úspešnom zaradení:

Array
(
    [status] => 1
    [type] => OK
    [invoice_code] => 26915945a67c8b7ba74dac59c5badfbf
    [receiver_registered] => 1
    [warnings] => Array
        (
        )

    [test_mode] => 0
    [peppol_status] => queued
    [queue_id] => 1024
    [message] => Queued for sending. Poll /api/peppol-status for the result.
)

Pole	Popis
peppol_status	queued = zaradené do fronty; pri validate_only je to not_sent a pole validated má hodnotu 1.
queue_id	Číslo záznamu vo fronte (pri opakovanom volaní tej istej faktúry sa vráti ten istý).
receiver_registered	true = odberateľ je v sieti Peppol registrovaný, false = nie je, null = registráciu sa nepodarilo overiť. Faktúra sa odošle vo všetkých prípadoch, výsledok ukáže /api/peppol-status.
warnings	Zoznam upozornení (code, message). Sieť Peppol takú e-faktúru prijme, ale údaje môžu byť chybné. Zoznam kódov je nižšie.
test_mode	1 = spoločnosť odosiela cez testovacieho poštára (e-faktúra nejde do ostrej siete).

Odpoveď pri chybe:

Array
(
    [status] => 1618
    [type] => Error
    [error_code] => rezim_k_bez_icdph
    [message] => The e-invoice cannot be sent: the regime Intra-EU supply of goods requires the customer's VAT ID.
)

Odpoveď s upozorneniami (stav 1622):

Array
(
    [status] => 1622
    [type] => Error
    [error_code] => warnings
    [message] => The invoice has warnings. Check and fix the invoice, or send it again with ignore_warnings=1.
    [invoice_code] => 26915945a67c8b7ba74dac59c5badfbf
    [receiver_registered] => 1
    [warnings] => Array
        (
            [0] => Array
                (
                    [code] => issue_date_not_today
                    [message] => The issue date of an e-invoice should be the same as the day it is sent to the Peppol network. This invoice has the issue date 17.10.2026. We recommend changing the date.
                )

            [1] => Array
                (
                    [code] => buyer_vat_id_missing
                    [message] => The customer is a VAT payer (VAT ID SK2020123456), but the VAT ID is missing on the invoice.
                )

        )

)

Pole error_code je strojový kód chyby (pozri zoznam nižšie), message je popis v angličtine. Pri chybe validácie e-faktúry obsahuje pole errors zoznam porušených pravidiel. Pri kóde 1615 (faktúra už bola odoslaná) je v odpovedi aj peppol_document_id pôvodného odoslania.

Zoznam návratových kódov:

Status ID	Význam	Popis
1	OK	Faktúra bola zaradená do fronty (alebo pri validate_only prešla kontrolou).
1602	Chyba	Parameter data nebol odoslaný metódou GET.
1603	Chyba	API kľúč nie je zadaný alebo nie je platný počet reťazcov.
1604	Chyba	API kľúč nie je zadaný správne.
1605	Chyba	Nie je zadaný email alebo používateľské meno.
1606	Chyba	Sedenie nie je inicializované (najprv zavolajte /api/init).
1607	Chyba	Sedenie je neplatné.
1608	Chyba	Nesprávna kombinácia API kľúča a emailu.
1609	Chyba	Konto nie je aktívne alebo nezodpovedá sedeniu.
1610	Chyba	Nie je zadaný parameter code.
1611	Chyba	Faktúra so zadaným kódom neexistuje.
1612	Chyba	Tento typ dokladu sa do siete Peppol neodosiela (napríklad zálohová faktúra).
1613	Chyba	Nesprávne DPH údaje dodávateľa (platiteľ bez IČ DPH, rovnaké IČ DPH dodávateľa a odberateľa, chýbajúce alebo neplatné DIČ).
1614	Chyba	Spoločnosť nemá dokončenú aktiváciu e-faktúry, konto nemá oprávnenie odosielať alebo poštár nie je aktívny.
1615	Chyba	Faktúra už bola odoslaná, opakované odoslanie nie je možné.
1616	Chyba	Spoločnosť nemá aktívny balík alebo má vyčerpaný kredit transakcií.
1617	Chyba	Krajinu odberateľa sa nepodarilo rozpoznať.
1618	Chyba	Režim DPH na faktúre nie je pre e-faktúru prípustný (napríklad dodanie do EÚ bez IČ DPH odberateľa, kombinácia dodania do EÚ a vývozu).
1619	Chyba	E-faktúra neprešla validáciou (pole errors obsahuje porušené pravidlá).
1620	Chyba	Neočakávaná chyba.
1621	Chyba	Príliš veľa volaní, najviac 60 za minútu.
1622	Chyba	Faktúra má upozornenia a nebola odoslaná (pole warnings). Opravte ju alebo ju odošlite s ignore_warnings=1.

Pred týmto volaním je potrebné inicializovať sedenie (/api/init). Volanie API pre zistenie stavu odoslania:

https://www.faktury-online.com/api/peppol-status?data={JSON}

Parametre:

Parameter	Atribút	Popis
key	povinný parameter	API kľúč.
email	povinný parameter	Email (alebo používateľské meno), ktorým sa prihlasujete do Faktúr online.
code	povinný parameter	Kód faktúry.

Príklad požiadavky:

Array
(
    [key] => vJyMc*4@2754*wGhofIWi!QDcEEQUdmj
    [email] => name@example.com
    [code] => 26915945a67c8b7ba74dac59c5badfbf
)

Odpoveď:

Array
(
    [status] => 1
    [type] => OK
    [invoice_code] => 26915945a67c8b7ba74dac59c5badfbf
    [invoice_number] => 2026099
    [peppol_status] => accepted
    [peppol_document_id] => doc_5b1c9a2e-7f40-4c8a-9d21-3e8f0a6b7c1d
    [peppol_error] => 
    [error_code] => 
    [queue_attempts] => 1
    [peppol_queued_at] => 2026-10-01 10:12:05
    [peppol_sent_at] => 2026-10-01 10:13:02
    [peppol_status_checked_at] => 2026-10-01 10:28:00
)

Pole	Popis
peppol_status	Stav odoslania (pozri tabuľku stavov v prvej časti).
peppol_document_id	Identifikátor dokumentu pridelený digitálnym poštárom po prevzatí.
peppol_error	Popis chyby v angličtine pri stavoch rejected, not_valid a failed, inak null.
error_code	Strojový kód poslednej chyby (pozri zoznam nižšie), inak null.
queue_attempts	Počet pokusov o odoslanie (pri dočasnej chybe sa opakuje najviac trikrát).
peppol_queued_at	Čas zaradenia do fronty.
peppol_sent_at	Čas odovzdania poštárovi.
peppol_status_checked_at	Čas poslednej kontroly doručenia.

Odporúčaný postup zisťovania stavu: prvý dotaz pošlite asi 2 minúty po zaradení, potom sa pýtajte najviac raz za 10 minút, kým stav nie je accepted, rejected, not_valid alebo failed. Potvrdenie doručenia môže trvať 10 až 20 minút, častejšie dotazy nový stav neprinesú.

Zoznam návratových kódov:

Status ID	Význam	Popis
1	OK	Všetko prebehlo v poriadku.
1702	Chyba	Parameter data nebol odoslaný metódou GET.
1703	Chyba	API kľúč nie je zadaný alebo nie je platný počet reťazcov.
1704	Chyba	API kľúč nie je zadaný správne.
1705	Chyba	Nie je zadaný email alebo používateľské meno.
1706	Chyba	Sedenie nie je inicializované (najprv zavolajte /api/init).
1707	Chyba	Sedenie je neplatné.
1708	Chyba	Nesprávna kombinácia API kľúča a emailu.
1709	Chyba	Konto nie je aktívne alebo nezodpovedá sedeniu.
1710	Chyba	Nie je zadaný parameter code.
1711	Chyba	Faktúra so zadaným kódom neexistuje.
1712	Chyba	Príliš veľa volaní, najviac 60 za minútu.

• Každý z endpointov prijme najviac 60 volaní za minútu na jedno konto, ďalšie volania dostanú kód 1621 alebo 1712.
• Fronta sa spracúva každú minútu v poradí zaradenia. V jednom behu sa odošle najviac 20 faktúr a najviac 5 faktúr jedného konta, aby dávka jedného integrátora nezdržala ostatných. Pri väčšej dávke počítajte s tým, že posledné faktúry odídu o niekoľko minút neskôr; stav sledujte cez /api/peppol-status.
• Faktúry v štýle Dizajnér PRO sa renderujú dlhšie (niekoľko sekúnd na faktúru), ich odoslanie preto môže trvať o niečo dlhšie.
• Pri dočasnej chybe (nedostupný poštár, zlyhanie vytvorenia PDF) sa odoslanie automaticky zopakuje, najviac trikrát. Potom faktúra skončí v stave failed a môžete ju zaradiť znova.
• Kontroly a validácia v /api/peppol-send trvajú 2 až 4 sekundy, s tým počítajte pri časovom limite spojenia.

Pole error_code v odpovediach umožňuje chybu spracovať programovo. Najčastejšie hodnoty:

error_code	Význam
fa_not_found	Faktúra so zadaným kódom neexistuje.
unsupported_type	Typ dokladu sa neodosiela (zálohová faktúra).
vat_mismatch_platca_bez_icdph	Dodávateľ je platiteľ DPH, ale nemá IČ DPH.
rovnake_icdph	Dodávateľ a odberateľ majú rovnaké IČ DPH.
missing_dic, invalid_sk_dic	Chýbajúce alebo neplatné DIČ dodávateľa.
no_postar	Spoločnosť nemá dokončenú aktiváciu e-faktúry.
no_permission	Konto nemá oprávnenie odosielať za túto spoločnosť.
resend_blocked	Faktúra už bola odoslaná.
no_credit, no_credit_delegate	Vyčerpaný kredit alebo chýbajúci balík.
err_country_buyer	Nerozpoznaná krajina odberateľa.
receiver_unregistered	Odberateľ nie je registrovaný v sieti Peppol a e-faktúru nebolo možné doručiť. Odoslanie je zaznamenané, faktúra bola nahlásená finančnej správe a zaúčtovala sa ako odoslaná. Znova ju neposielajte, odberateľovi ju môžete poslať e-mailom.
warnings	Faktúra má upozornenia a nebola odoslaná (pole warnings). Opravte ju alebo ju odošlite s ignore_warnings=1.
rezim_k_bez_icdph, rezim_k_bez_datumu, rezim_k_krajina, rezim_k_kombinacia, rezim_mimo_eu_krajina, rezim_ae_krajina	Neprípustná kombinácia režimu DPH a údajov odberateľa.
validation_failed	E-faktúra neprešla validáciou pred odoslaním (pole errors).
dp_rejected	Poštár e-faktúru odmietol (stav rejected).
pdf_render_failed	Nepodarilo sa vytvoriť PDF prílohu.
api_error, api_error_with_detail, api_error_with_rules	Chyba na strane poštára alebo siete; podrobnosti v message alebo errors.
too_many_requests	Prekročený limit volaní za minútu.

Kódy upozornení (pole warnings):

code	Význam
missing_supplier_street, missing_supplier_city, missing_supplier_zip	Chýba adresa dodávateľa (ulica, mesto, PSČ).
missing_buyer_street, missing_buyer_city, missing_buyer_zip	Chýba adresa odberateľa.
missing_delivery_date	Chýba dátum dodania.
issue_date_not_today	Dátum vystavenia nie je dnešný.
buyer_tax_id_not_found	DIČ odberateľa nie je v registri finančnej správy.
buyer_tax_id_other_company	DIČ odberateľa patrí firme s iným IČO. E-faktúra sa doručuje podľa DIČ.
buyer_vat_id_not_registered	IČ DPH odberateľa nie je v zozname platiteľov DPH.
buyer_vat_id_other_company	IČ DPH odberateľa patrí firme s iným IČO.
buyer_vat_id_tax_id_mismatch	IČ DPH nezodpovedá DIČ.
buyer_vat_id_missing	Odberateľ je platiteľ DPH, ale IČ DPH na faktúre chýba.

Kontroly DIČ a IČ DPH sa robia len pri odberateľovi zo Slovenska.

Inicializácia sedenia, zaradenie faktúry na odoslanie a zistenie stavu:

<?php

// Príprava základných dát:
$data = [];

// Váš API kľúč:
$data['key'] = "dJyMc*53@687*wGhofIWi!WDcEEQUdmj";

// Váš email (príp. používateľské meno):
$data['email'] = "name@example.com";

// Inicializácia sedenia (cookie.txt musí byť zapisovateľný):
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.faktury-online.com/api/init?data=' . urlencode(json_encode($data)));
curl_setopt($ch, CURLOPT_COOKIESESSION, true);
curl_setopt($ch, CURLOPT_COOKIEJAR, 'cookie.txt');
curl_setopt($ch, CURLOPT_COOKIEFILE, 'cookie.txt');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
$result = json_decode(curl_exec($ch), true);
if ($result['status'] != 1) {
    throw new Exception("Vyskytla sa chyba č. " . $result['status']);
}

// Kód faktúry (z odpovede API pri jej vytvorení):
$data['code'] = "14915945a66c8b7be74dac59c5badfbf";
// Faktúru s upozorneniami (pole warnings) odoslať aj tak? 0 = nie (predvolené), 1 = áno:
$data['ignore_warnings'] = "0";

// Zaradenie na odoslanie do siete Peppol (kontroly a validácia prebehnú hneď):
curl_setopt($ch, CURLOPT_URL, 'https://www.faktury-online.com/api/peppol-send?data=' . urlencode(json_encode($data)));
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$result = json_decode(curl_exec($ch), true);
if ($result['status'] != 1) {
    // error_code = strojový kód chyby, message = popis
    // Pri stave 1622 obsahuje $result['warnings'] zoznam upozornení (code, message)
    throw new Exception("Odoslanie zamietnuté: " . $result['status'] . " " . $result['error_code'] . " (" . $result['message'] . ")");
}
// $result['peppol_status'] == 'queued'

// Stav odoslania (prvý dotaz asi po 2 minútach, potom najviac raz za 15 minút):
sleep(120);
curl_setopt($ch, CURLOPT_URL, 'https://www.faktury-online.com/api/peppol-status?data=' . urlencode(json_encode($data)));
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

// $result['peppol_status']: queued | sent | accepted | rejected | not_valid | failed
echo $result['peppol_status'], " ", $result['peppol_document_id'] ?? '', " ", $result['peppol_error'] ?? '';