EET a změny v API (pro vývojáře)

Aktuální

EET bylo plošně zrušeno 1. 1. 2023.

Fakturoid nabízí Elektronickou evidenci tržeb (EET) ve dvou variantách:

  • interní - Fakturoid komunikuje s MF ČR a obstarává údaje pro zobrazení na fakturách (pravděpodobně budete využívat tuto variantu)
  • externí - pouze zobrazíme údaje o zaevidování externím systémem

Pro obě varianty platí, že rozhodnutí o zaevidování do EET pro konkrétní fakturu je plně na straně volajícího API.

Celkový přehled změn

Změny v API se dotknou faktur a šablon. Do šablon i faktur přidáme atribut eet. Může nabývat dvou hodnot

  • true - Vystavená faktura se zaeviduje do EET
  • false - Vystavená faktura se nezaeviduje do EET

U faktur přibude kromě atributu eet ještě atribut eet_store (číslo provozovny), eet_cash_register (označení pokladny) a pole objektů komunikace s EET nazvané eet_records.

Atributy eet_store a cash_register slouží pro případy, kdy si přes API budete chtít nastavit jiné hodnoty, než které jsou nastaveny v účtu.

Příklad zaevidované faktury

GET https://app.fakturoid.cz/api/v2/accounts/appleinc/invoices/9.json

{
    "id": 9,
    "proforma": false,
    "number": "2017-0004",
    ...
    "lines": [...],
    "eet": true,
    "eet_cash_register": nil,
    "eet_store": nil,
    "eet_records": [
        {
            "id": 56,
            "vat_no": "CZ1234567890",
            "number": "2017-0004",
            "store": 1,
            "cash_register": "Fakturoid",
            "paid_at": "2017-01-25T14:04:50+01:00",
            "vat_base0": null,
            "vat1": "8400.0",
            "vat_base1": "40000.0",
            "vat2": null,
            "vat_base2": null,
            "vat3": null,
            "vat_base3": null,
            "total": "48400.0",
            "fik": "b3a09b52-7c87-4014-a496-4c7a53cf9125-03",
            "bkp": "0fc4df2f-e99392a1-883c2901-6b46af8e-f7b98994",
            "pkp": "KhcgUDEVfMY...wfJtg==",
            "status": "fik",
            "fik_received_at": "2017-01-25T13:54:50+01:00",
            "external": false,
            "attempts": 1,
            "last_attempt_at": "2017-01-25T13:54:50+01:00",
            "last_uuid": "d7383d5d-c34f-4288-94b9-52b2838515e2",
            "playground": false,
            "invoice_id": 9,
            "created_at": "2017-01-25T14:04:50+01:00",
            "updated_at": "2017-01-25T13:54:50+01:00"
        }
    ],
    "html_url": "https://app.fakturoid.cz/applecorp/invoices/9",
    ...
}

Popis eet_record objektu

AtributPopis
id ID záznamu
vat_no DIČ účtu ve Fakturoidu
number Pořadové číslo dokladu
store ID provozovny
cash_register Číslo pokladny
paid_at Datum a čas tržby
vat_base0 Základ nepodléhající DPH
vat_base1 Základ pro základní sazbu DPH (21 %)
vat1 DPH pro základní sazbu
vat_base2 Základ pro 1. sníženou sazbu DPH (15 %)
vat2 DPH pro 1. sníženou sazbu DPH
vat_base3 Základ pro 2. sníženou sazbu DPH (10 %)
vat3 DPH pro 2. sníženou sazbu DPH
total Celková částka tržby
fik FIK kód
bkp BKP kód
pkp PKP kód
status Stav zaevidování:
  • waiting - čeká se na první odpověď serveru EET
  • pkp - na faktuře se zobrazí PKP kód
  • fik - na faktuře se zobrazí FIK kód
fik_received_at Datum a čas získání FIK ze serverů EET
external
  • true - Tržba je zaevidována mimo Fakturoid a potřebné kódy jsou zadány přes API
  • false - Fakturoid se stará o zaevidování tržby
attempts Počet pokusů o zaevidování tržby
last_attempt_at Datum a čas posledního pokusu o zaevidování tržby
last_uuid UUID posledního pokusu o zaevidování tržby
playground Evidováno v EET Playground prostředí
invoice_id ID faktury, ke které EET záznam patří
created_at Datum a čas vytvoření záznamu
updated_at Datum a čas poslední úpravy záznamu

Jak bude technicky probíhat evidence do EET

Veškerá komunikace se servery EET probíhá asynchronně mimo probíhající request. Například při vystavování nové faktury se vytvoří objekt eet_records, který bude mít nastavený status na waiting. Faktura se následně zařadí do fronty a ta se postará o zaslání tržby na servery EET.

Odeslat fakturu nebo stáhnout její PDF půjde až po první proběhlé komunikaci, kdy bude jasné, jestli se na faktuře má zobrazit FIK nebo PKP.

Samotné stažení PDF přes API bude stále probíhat podle aktuální dokumentace. Může se pouze stát, že díky komunikaci se servery EET bude generování PDF trvat o 1 až 2 vteřiny déle.

Nová faktura

Evidence v interním režimu

Při evidenci v interní variantě stačí poslat atribut eet nastavený na hodnotu true. Fakturoid se sám postará o zaevidování dokladu.

POST https://app.fakturoid.cz/api/v2/accounts/:slug/invoices.json

{
    "number": "2017-0001",
    "subject_id": "28",
    "currency": "CZK",
    ...
    "eet": true,
    "lines": ...
}

Pokud atribut eet nezadáte, vezme se výchozí nastavení z účtu. Kromě atributu eet můžete také nastavit eet_cash_register a eet_store pro pokladnu resp. provozovnu.

{
    "number": "2017-0001",
    "subject_id": "28",
    "currency": "CZK",
    ...
    "eet": true,
    "eet_cash_register": "Pokladna1",
    "eet_store": 15,
    "lines": ...
}

Do EET se následně zašlou vámi zaslané údaje. Pokud tyto údaje nenastavíte, použije se provozovna nastavená v účtu a pokladna se nastaví na Fakturoid.

Evidence v externím režimu

Pokud se rozhodnete doklady evidovat na své straně (v externím režimu), musíte nám kromě atributu eet poslat i kompletní informace o zaevidované platbě.

POST https://app.fakturoid.cz/api/v2/accounts/:slug/invoices.json

{
    "number": "2017-0001",
    "subject_id": "28",
    "currency": "CZK",
    ...
    "eet": true,
    "eet_records": [
        {
            "vat_no": "CZ1234567890",
            "number": "2017-0004",
            "store": 1,
            "cash_register": "Pokladna1",
            "paid_at": "2017-01-25T14:04:50+01:00",
            "vat_base0": null,
            "vat1": "8400.0",
            "vat_base1": "40000.0",
            "vat2": null,
            "vat_base2": null,
            "vat3": null,
            "vat_base3": null,
            "total": "48400.0",
            "fik": "b3a09b52-7c87-4014-a496-4c7a53cf9125-03",
            "bkp": "0fc4df2f-e99392a1-883c2901-6b46af8e-f7b98994",
            "pkp": "KhcgUDEVfMY...wfJtg==",
            "status": "fik",
            "fik_received_at": "2017-01-25T13:54:50+01:00",
            "external": false,
            "attempts": 1,
            "last_attempt_at": "2017-01-25T13:54:50+01:00",
            "last_uuid": "d7383d5d-c34f-4288-94b9-52b2838515e2"
        }
    ],
    "lines": ...
}

Externí zaevidování do EET má oproti internímu několik omezení:

  1. Stav musíte nastavit na hodnotu pkp nebo fik. Stav waiting je určený pouze pro evidenci v interním režimu Fakturoidu.
  2. Podle stavu musíte vyplnit buď PKP nebo FIK, aby se mohl zobrazit na faktuře.
  3. Musíte explicitně zadat veškeré údaje o zaevidování včetně čísla dokladu, DIČ a jednotlivých částek v evidenci. Nic se nebude automaticky doplňovat z faktury ani z účtu.
  4. Všechny atributy v eet_records, u kterých to dává smysl, se validují na správný formát zadaný podle technické specifikace EET
Popis validací
Atribut Popis
vat_no Formát /^CZ[0-9]{8,10}$/ Povinné
number Formát /^[0-9a-zA-Z\.,:;\/#\-_ ]{1,25}$/ Povinné
store Musí být celé číslo Povinné
cash_register Formát: /^[0-9a-zA-Z\.,:;\/#\-_ ]{1,20}$/ Povinné
paid_at Datum a čas Povinné
total Decimal s dvěma desetinnými místy Povinné
vat_baseX Decimal s dvěma desetinnými místy Volitelné
vatX Decimal s dvěma desetinnými místy Volitelné
status Musí nabývat hodnot pkp nebo fik Povinné
pkp String dlouhý přesně 344 znaků Povinné, pokud je status pkp
bkp Formát /^([0-9a-fA-F]{8}\-){4}[0-9a-fA-F]{8}$/. Pokud je zadán PKP, provádí se i kontrola výpočtu BKP kódu z PKP kódu. Povinné
fik Formát /^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-4[0-9a-fA-F]{3}\-[89abAB][0-9a-fA-F]{3}\-[0-9a-fA-F]{12}\-[0-9a-fA-F]{2}$/. Povinné, pokud je status fik

Nová zálohová faktura

Zálohové faktury se evidovat nebudou. Bude se u nich dát nastavit atribut eet na hodnotu true. Toto nastavení říká, aby se do EET poslala až faktura vystavená po zaplacení zálohy.

Dále se dají nastavit atributy eet_cash_register a eet_store, aby se do výsledné faktury nastavila jiná pokladna (případně provozovna), než je výchozí nastavení účtu.

EET není povoleno v tarifu účtu

Pokud není EET povoleno ve vašem tarifu a pokusíte se jej zapnout, server vám nedovolí fakturu vytvořit a zpátky se vrátí validační chyba:

{
  "errors": {
    "eet": [
      "Funkce EET není ve Vašem tarifu přístupná"
    ]
  }
}

Úprava faktury

Pokud budete chtít zaevidovat už vystavenou fakturu, stačí fakturu upravit a poslat jí eet atribut nastavený na true, případně data z externího zaevidování stejně jako u nové faktury.

Faktura se po zaevidování do EET automaticky uzamkne a už ji nepůjde měnit. Budete-li chtít fakturu upravit, jedinou možností bude ji stornovat (u plátců DPH vystavit opravný doklad) a vystavit fakturu novou.

Stornování faktury

Při stornování zaevidované faktury dojde i k jejímu automatickému stornu v EET. Zaznamenat stornování v externím režimu momentálně není možné.

Zaplacení faktury

Pokud zjistíte až při placení, že fakturu musíte zaevidovat do EET, musíte fakturu nejdříve upravit, poslat nám informaci o tom, že se má faktura zaevidovat do EET, a až následně fakturu zaplatit.

Na čem ještě pracujeme

Zaevidování FIK kódu

Při externí evidenci EET mimo Fakturoid se vám může stát, že se nepodaří navázat komunikaci se servery EET a nepošlete nám FIK. Pro tyto případy přidáme do API nový endpoint, který vám umožní poslat FIK dodatečně spolu s časem, kdy se vám podařilo FIK získat.

Zaslání času není povinné. Pokud necháte čas prázdný, automaticky doplníme aktuální čas při přijetí požadavku.

PATCH https://app.fakturoid.cz/api/v2/accounts/:slug/invoices/:invoice_id/eet/:id.json

{
    "fik": "b3a09b52-7c87-4014-a496-4c7a53cf9125-03",
    "fik_received_at": "2017-01-25T13:54:50+01:00",
    "last_attempt_at": "2017-01-25T13:54:50+01:00",
    "last_uuid": "d7383d5d-c34f-4288-94b9-52b2838515e2"
}

Doposlaný kód už se nebude zobrazovat na faktuře. Bude sloužit jen pro úplnost - jako záznam, že komunikace se servery EET proběhla v pořádku.

Zaslat FIK půjde jen u záznamů, které mají nastaveno "external": true, a kde ještě není vyplněn. Nepůjde znovu editovat už jednou zaslané údaje.

Zařazení do tarifů a testování napojení na EET

Funkce EET je dostupná v placených tarifech. Platí to pro oba způsoby - jak pro externí, tak interní evidenci.

Pro zapnutí EET pro testování nám napište na email podpora@fakturoid.cz.

Playground prostředí

Pro testování integrací je možné EET používat v testovacím Playground prostředí. Z bezpečnostních důvodů nepovolujeme Playground prostředí zapnout v běžném účtu. Pro jeho povolení nám musíte napsat na email podpora@fakturoid.cz.

Certifikáty pro Playground prostředí si můžete stáhnout na adrese http://www.etrzby.cz/cs/technicka-specifikace. Dole na stránce najdete odkaz Sada certifikátů certifikační autority EET CA1 Playground. Heslo ke všem certifikátům je eet.

Každý ze stažených certifikátů má ve svém názvu i DIČ, se kterým je svázán. Toto DIČ musíte zadat v "Nastavení > Fakturační údaje" a následně zapnete EET a nahrajete certifikát v "Nastavení > EET".

Prohledat Podporu

Nenašli jste? Napište nám email nebo využijte povídátko v pravém dolním rohu.