eFaktúra

Recept na odosielanie a príjem eFaktúr cez sieť Peppol z vášho fakturačného systému — bez toho, aby ste sa museli stať certifikovaným poskytovateľom prístupového bodu (digitálnym poštárom) Peppol. Ktoré endpointy volať, v akom poradí a čo zatiaľ API nepokrýva.

Čo tento scenár rieši

Váš systém faktúry vystavuje ďalej po svojom a do KROSu ich zapisuje cez API s príznakom eFaktúry. KROS sa postará o napojenie na sieť Peppol — formát Peppol BIS Billing 3.0, doručenie odberateľovi aj sledovanie stavu. O zmene stavu vás upozorní webhook a stav si prečítate priamo z faktúry. Opačným smerom prichádzajú do KROSu eFaktúry od vašich dodávateľov a váš systém si ich aj s prílohami prečíta cez API.

Tok dát

Odosielanie eFaktúr

1. Autorizácia

   Samostatný fakturačný systém mimo KROS aplikácie použije Integration Consent. Ak beží vnútri KROS aplikácie ako doplnok, získa token cez Token Broker.

2. Zápis faktúry ako eFaktúry

   Faktúru pošlite cez POST /api/invoices, prípadne dávkovo cez POST /api/invoices/batch, s vlastnosťou isEInvoice: true. Odberateľ musí mať vyplnené DIČ (partner.taxId) a firma v KROSe musí mať eFaktúru zapnutú — inak príznak nastaviť nejde.

3. Potvrdenie spracovania

   API odpovie 202 Accepted s poľom requestId — to znamená len prijaté, nie spracované. Výsledok zápisu príde na váš webhook.

4. Odoslanie odberateľovi

   Samotné odoslanie eFaktúry do siete Peppol (alebo e-mailom) zatiaľ spúšťa používateľ v aplikácii KROS. Odoslanie cez API pripravujeme.

5. Sledovanie stavu v sieti Peppol

   Pri vytvorení eFaktúry aj pri každej jej zmene — vrátane zmeny stavu v sieti Peppol — pošle KROS webhook. Webhook nesie hlavičku dokladu (id, číslo, rad); samotný stav si potom prečítate cez GET /api/invoices/{id} v objekte eInvoice:

   • isEInvoice — či je faktúra označená na odoslanie ako eFaktúra,
   • status — stav v sieti Peppol, prázdny, kým faktúra neodišla,
   • sentAt — kedy faktúra odišla do siete Peppol (UTC),
   • peppolId — identifikátor eFaktúry v sieti Peppol,
   • errorMessage — prečo eFaktúra neprešla validáciou,
   • xmlLink — odkaz na odoslané XML vo formáte Peppol BIS 3.0.

   Zoznam GET /api/invoices vracia eInvoice tiež, ale peppolId a errorMessage sú v ňom vždy prázdne — tie nájdete len v detaile.

6. XML eFaktúry

   Ak potrebujete samotný XML dokument eFaktúry — napríklad na archiváciu vo vašom systéme — stiahnete ho cez GET /api/invoices/{id}/reports/einvoiceBis3. Rovnakú adresu nájdete v eInvoice.xmlLink; kým eFaktúra neodíde do siete Peppol, je odkaz prázdny.

Príjem eFaktúr

1. Načítanie prijatých dokladov

   Prijaté eFaktúry čítate cez GET /api/expenses. Endpoint vracia všetky druhy výdavkov, preto ak vás zaujímajú len faktúry, filtrujte parametrom DocumentType — napríklad DocumentType=10 pre prijaté faktúry. Pri pravidelnej synchronizácii pridajte LastModifiedTimestamp, aby ste stiahli len to, čo sa od posledného behu zmenilo.

2. Prílohy

   Ak má doklad hasAttachments: true, zoznam príloh získate cez GET /api/attachments/expenses/{documentId} a obsah každej z nich cez GET /api/attachments/expenses/{documentId}/{attachmentId}/content.

Odporúčané endpointy

Na čo si dať pozor

isEInvoice posielajte pri každej úprave

POST /api/invoices faktúru vytvára aj aktualizuje. Pri úprave existujúcej faktúry treba isEInvoice: true poslať vždy znova — vynechaná hodnota sa považuje za false a príznak eFaktúry z faktúry zmizne.

Odberateľ musí mať DIČ

Príznak eFaktúry sa dá nastaviť len vtedy, keď má partner na faktúre vyplnené DIČ (taxId) a firma má v KROSe eFaktúru zapnutú. Ak jedna z podmienok chýba, faktúra sa ako eFaktúra nezapíše — výsledok si overte vo webhooku.

Odoslaná eFaktúra je zamknutá

Faktúru, ktorá už odišla ako eFaktúra, už prepísať nemožno. Opakovaný POST na ňu skončí problémom v notifikácii namiesto prepisu — pozri Čo API umožňuje.

Stavy eFaktúry v sieti Peppol

Pole eInvoice.status nadobúda tieto hodnoty:

• pending — eFaktúra čaká na odoslanie,
• sent — odišla do siete Peppol,
• confirmed — doručenie je potvrdené,
• validationFailed — neprešla validáciou; dôvod je v errorMessage (len v detaile faktúry), faktúru opravte a odošlite znova,
• sendingFailed — odoslanie do siete Peppol zlyhalo,
• deliveryFailed — sieť Peppol eFaktúru príjemcovi nedoručila.

Kým nie je stav sent alebo confirmed, nepovažujte eFaktúru za odoslanú. Staršie pole sentStatus stav eFaktúry tiež odráža, no pre novú integráciu čítajte eInvoice.status.

Pripravujeme

• Odoslanie eFaktúry cez API. Dnes eFaktúru cez API vytvoríte, ale odoslať ju odberateľovi — do siete Peppol aj e-mailom — treba v aplikácii KROS. Pracujeme na tom, aby sa dalo odoslanie spustiť priamo z vášho systému.
• Vlastné prílohy k faktúre. K faktúre aj eFaktúre bude možné pripojiť vlastný vizuál v PDF alebo ďalšie prílohy, napríklad súpis prác či dodací list. Takto pridané prílohy sa prenesú cez sieť Peppol až k vášmu odberateľovi.

Ak od eFaktúry v API potrebujete niečo ďalšie, napíšte nám na integracie@kros.sk — konkrétne požiadavky od integrátorov zohľadníme pri návrhu.