EET pro eshop - EET API zdarma

K čemu je EET API dobré?

Standardně si vystavujete doklady tak, že se přihlásíte do svého účtu na internetové stránce www.zdarma-eet.cz, kliknete na "nový paragon" a po vyplnění popisu a ceny si paragon uložíte/vytisknete, příp. pošlete zákazníkovi. Jsou ovšem situace, kdy potřebujeme vystavit buď automaticky (např. po úspěšně autorizované platbě kartou v e-shopu), nebo třeba z nějakého svého objednávkového/zakázkového systému. V takovém případě je k dispozici toto jednoduché API, které umožňuje vystavení dokladu na základě předaných hodnot (cena, popis zboží/služby) v rámci zavolání jedné internetové adresy.

Jak to funguje?

Zvolili jsme jednoduchý systém zavolání URL stránky. Parametry mohou být předány buď metodou GET, nebo POST (např. z formuláře). Formát je uveden níže. Po uložení dokladu naším API skriptem je zavolána návratová URL, kterou si určíte při volání stránky jako jeden z parametrů. Návratová URL obsahuje jako parametr mj. i odkaz na URL s právě vystaveným paragonem. Paragon je tak vystaven během časově téměř nepostřehnutelného přesměrování (záleží na rychlosti připojení). Pokud to však není možné, můžeme paragon nechat vystavit např. v IFRAME (rámu uvnitř stránky). To je vhodné např. v případě, že nechceme/nemůžeme významně zasahovat např. do stránky s ukončenou transakcí a potřebujeme vyřešit vystavení paragonu v rámci jedné stránky. Ukážeme si na příkladech níže.

Jak začít?

Nejdříve je třeba si API zapnout vygenerováním tzv. API hesla. To provedeme v NASTAVENÍ, kde klikneme na API KOMUNIKACI. Tady získáme tzv. API heslo a druhý důležitý údaj-číslo partnera.

Vystavujeme paragony s EET pomocí API

- Pro vystavení dokladu se volá adresa https://www.zdarma-eet.cz/api.php s požadovanými parametry.
- Kódování textů je očekáváno ve znakové sadě UTF8

Nenechte se odradit níže uvedeným výčtem a popisem proměnných, většina je nepovinná a není to tak složité, jak to vypadá :-) Doporučujeme zejména kouknout na příklady níže.

Povinné parametry (proměnné):

kodobjednavky - POZOR, musí být vždy unikátní! Max. délka 20 znaků. Pokud je opakovaně zavoláno se stejnou hodnotou kodobjednavky, nedojde k vystavení nového paragonu, ale jen k vrácení již vystaveného s tímto kódem objednávky. Důvod je ochrana proti duplicitnímu vystavení stejného paragonu např. dvojím kliknutím, nebo obnovením obsahu stránky prohlížeče.

partner - Vaše uníkátní ID získané v nastavení API. Číselná hodnota.

rada - číselná řada, do které chceme vystavit doklad. RR nebo RRRR určuje dvoumístné, resp. čtyřmístné zobrazení roku, xxx pak automaticky dosazené pořadové číslo dokladu. Pokud tedy uvedeme jako hodnotu této proměné a aktuálně je rok 2019, tak např. RRRR9xxxxxx, bude mít první doklad číslo 2019900001, další 2019900002 atd. Další příklady řad a vystavovaných dokladů jsou (uvažujeme rok 2019):
RRxxx - 19001, 19002...
RR55xxxxx - 195500001, 195500002...
RRRRx - 20191, 20192... ale to není moc rozumné :-) Leda že byste měli max. 10 dokladů do roka a nikdy by to nepřesáhlo.
Ve vlastním zájmu si počet míst (tj. písmen xxx) v číselné řadě stanovte s dostatečnou rezervou, aby stačily na celý rok! Řada může být odlišná od té, v které vystavujete doklady přes webovou stránku. Doporučuje se však, aby čísla generovaná API byla nižší než ta, která vystavuje web (např. 2019800001 pro API a 2019900001 pro web). Při vystavování na webu totiž automaticky nabízí vždy nejvyšší uložené číslo+1.
Zároveň platí, že musí jít o posloupnou řadu. Musí proto začínat rokem (RR nebo RRRR) a končit čislem, tj. x.
Max.délka 10 znaků.

h - md5 hash vybraných hodnot, aby byla zaručena autorizace a zároveň nikdo neměnil důležité hodnoty. Podrobněji viz níže v příkladech.

soucetcen - součet cen všech položek na dokladu se zaokouhlením na dvě desetinná místa (=haléře). Ochrana proti falšování cen dokladů třetí stranou. Formát je s desetinnou tečkou. Tzn. pokud máme např. součet 112,23 Kč, hodnota je 112.23. Mějte prosím na paměti, že soucetcen je součásti MD5 hashe. Je tedy třeba podepisovat stejnou hodnotu, jako předáváme proměnnou soucetcen.

url - návratová URL. Stránka, na kterou bude vrácen klient po vystavení paragonu. Typicky nějaký jednoduchý skript, který např. pošle doklad e-mailem, a zobrazí odkaz na něj. POZOR! Pokud je předáváno metodou GET, proměnná url musí být vždy poslední, zejména pokud obsahuje nějaké parametry!

Nepovinné parametry (proměnné):

odbemail - e-mail odběratele. Máte-li k dispozici, doporučujeme vyplňovat, neboť je součástí md5 hashe. Kdybyste např. nesprávně poslali neunikátní kód objednávky, slouží to jako pojistka, aby nebyl jinému klientovi zobrazen cizí paragon (podotýkáme že jde o situaci kdy zavoláte API s nesprávným číslem objednávky a navíc stejnou uvedenou cenou, kde jste omylem neuhlídali unikátnost čísla objednávky).

uhrada - forma úhrady, textový řetězec max. 20 znaků v UTF8 (např. hotově, kartou). Při nevyplnění je automaticky dosazena hodnota "hotově". Případný řetězec delší než 20 znaků je automaticky oříznutý.

ft_popis[] - pole, obsahuje popis jednotlivých položek, resp. text jednotlivých řádků dokladu.

ft_cena[] - pole, obsahuje cenu všech položek na daném řádku dokladu (u plátců DPH včetně DPH). Max. dvě desetinná místa, např. 11.22 (max.hodnota 9999999.99)

ft_dph[] - pole, procentuelní výše DPH na daném řádku dokladu. Max. dvě desetinná místa, zpravidla ale celé číslo dle aktuální výše DPH.

ft_mj[] - název měrné jednotky na daném řádku. Při nevyplnění automaticky dosadí "ks"

ft_ks[] - pole, počet měrných jednotek na daném řádku. Při nevyplnění automaticky dosadí hodnotu "1" (hodnota v rozmezí 0.001-999999.999)

ft_cenabezdph[] - pole s cenou bez DPH (součet cen na daném řádku za všechny kusy). U paragonu má vliv pouze na sumarizaci DPH (netiskne se u něj na řádek), z této hodnoty nedochází k automatickému dopočítávání ostatních hodnot na řádku dokladu. Nedoporučujeme vyplňovat, bude dopočítáno z ft_cena a ft_dph metodou "shora". Použití pouze ve speciálních případech, např. jiná metoda zaokrouhlení na řádku. V takovém případě si prosím nezapomeňte sami hlídat součty! Max. dvě desetinná místa, např. 11.22

ft_cenaks[] - pole s cenou za ks (u plátců bez DPH), resp. jednotku zboží/služby. Rovněž nedoporučujeme vyplňovat, bude dopočítáno z ft_cena a ft_dph metodou "shora". Použití pouze ve speciálních případech, např. jiná metoda zaokrouhlení na řádku. V takovém případě si prosím nezapomeňte sami hlídat součty! Max. dvě desetinná místa, např. 11.22

zaokrouhlení - Pokud je uvedeno, není zaokrouhlení provedeno výpočtem z hodnot viz výše, ale je přímo vložena předaná hodnota. Nedoporučujeme vyplňovat, pouze pro speciální případy, např. jiná metoda zaokrouhlení. Pokud je hodnota zaokrouhleni předána, ale není předána hodnota celkcena (viz níže), je předaná hodnota zaokrouhlení ignorována a spočtena automaticky ze součtu položek.

celkcena - Pokud je uvedena, dosadí na doklad jako "cena celkem" bez ohledu na součet položek. Zároveň dopočítá zaokrouhlení vůči součtu všech položek, není-li zaokrouhlení předáno v proměnné zaokrouhleni (viz výše). Nedoporučujeme vyplňovat, pouze pro speciální případy, např. jiná metoda zaokrouhlení.

bezeet - pokud je vyplněna hodnota 1, nebude při vystavení paragonu prováděno hlášení EET. Bez vyplnění, nebo s jinou hodnotou EET proběhne.

nenidandoklad - pokud je hodnota 1, na paragon bude vytisknutý text "TOTO NENÍ DAŇOVÝ DOKLAD!". Vhodné pro případ, kdy používáte náš systém pouze k automatickému nahlášení EET, daňové doklady si však vystavujete jinak.

nazevdokladu - Název dokladu, např. PŘÍJMOVÝ POKLADNÍ DOKLAD, PPD, PRODEJKA ZA HOTOVÉ, PARAGON apod.. Při nevyplnění je automaticky dosazen jako název dokladu PARAGON. Textový řetězec max. 150 znaků v UTF8, řetězec delší než 150 znaků je automaticky oříznutý.

hlavickaparagon - Text, který se tiskne na záhlaví paragonu. Typicky jde o rozšiřující údaje, sdělení klientům apod. Textový řetězec UTF8, v případě překročení 1000 znaků je automaticky oříznutý. Pokud potřebujete odsadit text na nový řádek, vložte html znak pro odsazení <br />.

patickaparagon - Text, který se tiskne na konec paragonu. Typicky jde o poděkování za nákup, sdělení klientům apod. Textový řetězec UTF8, v případě překročení 1000 znaků je automaticky oříznutý. Pokud potřebujete odsadit text na nový řádek, vložte html znak pro odsazení <br />.

Příklady

Níže uvedené příklady jsou psány v PHP, nicméně jelikož jediným výpočtem je prakticky jen vytvoření MD5 hashe pro hodnotu proměnné h, není vůbec složité vytvořit prakticky v jakémkoliv jazyce.

Dle výše uvedeného návodu jsme si zapnuli API a získali následující dva údaje, s kterými budeme provádět příklady níže:

API heslo je
cs3QbUzmxJwbLGgXbCSYjIgmUzzmu3MGwPxHK74hR
Vaše ID (=proměnná partner):
27

Přiklad 1: Nejjednodušší vložení paragonu s jedním řádkem

<?php
$partner=27; #získáno v nastavení
$apiheslo='cs3QbUzmxJwbLGgXbCSYjIgmUzzmu3MGwPxHK74hR'; #získáno v nastavení
$kodobjednavky='ABC1'; #unikátní číslo objednávky. POZOR! Vždy musí být nové a nesmí se opakovat! 
$rada='RRRR9xxxxx'; #generuje doklady ve stejné řadě, jako je implicitní
$ft_popis[1]='Baterie AA'; #popis zboží na řádku 1
$ft_cena[1]='21.50'; #konečná cena (u neplátce DPH), nebo cena vč.DPH (u plátce DPH) 
$url=urlencode('http://www.mojedomena.cz/vystaveno.php'); #stranka, ktera bude otevřena po vystavení paragonu. URLENCODE viz níže.

$soucetcen=array_sum($ft_cena); #secte ceny vsech radku dokladu, v našem případě tedy jen jednu=výsledek bude 21.5 (příp. 21.50) 

# Výpočet hodnoty h je provedeen takto:      
$h=$partner.$kodobjednavky.$rada.$odbemail.$soucetcen.$apiheslo;
# 1.textovým spojením výše uvedených proměnných (bez mezer a vždy v tomto pořadí!) 
# V tomto příkladě nám tedy vznikne hodnota 27ABC1RRRR9xxxxx21.5cs3QbUzmxJwbLGgXbCSYjIgmUzzmu3MGwPxHK74hR
# 2. MD5 daného textového řetězce:
$h=md5($h);
# Výsledkem je v tomto případě hodnota c1027545c07aece2ae16f014a8a98548

echo '<a href="https://www.zdarma-eet.cz/api.php?partner='.$partner.'&kodobjednavky='.$kodobjednavky.'&rada='.$rada.'&h='.$h.'&ft_cena[1]='.$ft_cena[1].'&ft_popis[1]='.$ft_popis[1].'&url='.$url.'">vystavit paragon</a>';
?> 

Zavoláním tohoto skriptu je vytvořen odkaz "vystavit paragon" (jde i bez kliknutí, viz příklad 2 níže). Prakticky tedy výše uvedený skript pouze vytvoří tuto URL, která obsahuje vše potřebné:

https://www.zdarma-eet.cz/api.php?partner=27&kodobjednavky=ABC1&rada=RRRR9xxxxx&h=c1027545c07aece2ae16f014a8a98548&ft_cena[1]=21.50&ft_popis[1]=Baterie AA&url=http%3A%2F%2Fwww.mojedomena.cz%2Fvystaveno.php

Po zavolání (v tomto případě kliknutí na odkaz) API skript vystaví doklad a ihned zavolá (resp. přesměruje klienta) na požadovanou $url. V tomto případě http://www.mojedomena.cz/vystaveno.php s příslušými proměnnými:

Cílová URL, na kterou byl v tomto jednoduchém příkladu uživatel přesměrován:

  
http://www.mojedomena.cz/vystaveno.php?faweb=https%3A%2F%2Fwww.zdarma-eet.cz%2Fparagon-tisk.php%3Ff%3D2017900064%26p%3D27%26h%3D5e4f892897351e99022ffb2e06abbf04&f=2017900064&kodobjednavky=ABC1

Vrácené proměnné přidané k $url (příklad jejich zpracování u návratové stránky je popsán za příkladem 2 níže):

faweb - obsahuje kompletní URL s odkazem na vystavený doklad (URL endoded), v tomto případě po dekódování URL www.zdarma-eet.cz/paragon-tisk.php?f=2017900064&p=27&h=5e4f892897351e99022ffb2e06abbf04&f=2017900064

f - číslo vystaveného dokladu

kodobjednavky - kód objednávky

$opakovane - pokud zavoláte skript se stejným číslem objednávky a správnými parametry, je to považované za reload stránky a zároveň ochrana proti duplicitnímu vystavení paragonu k jedné objednávce. V takovém případě je zobrazen již jednou vystavený paragon. Cílová adresa je pak zavolána s proměnnou opakovane=1 (bez této hodnoty jde o první zavolání).

+jakékoliv Vaše proměnné předané v rámci návratové URL (proměnná $url výše) - typicky kód objednávky, e-mail či cokoliv si předáte v rámci návratové URL (ukážeme si v následujícím příkladu). Můžete si ostatně přidat i nějakou vlastní proměnnou, která zaručí, že Vám nebude nikdo falšovat návratové URL. Typicky např. unikátní číslo objednávky+své tajné heslo, to celé "zahashované" třeba MD5, nebo nějakým jiným algoritmem.
POZOR! Návratová URL, tj. proměnná $url výše by měla být "url encoded", aby nedocházelo ke kolizi s ostatními proměnnými. Zejména u metody GET je to duležité.

Výsledkem příkladu 1 je vystavení následujícího paragonu (hlavičku a patičku neuvádíme):

Přiklad 2: Víceřádkový paragon, unikátnost uživatele mimo čísla objednávky jištěna i e-mailem
(komentáře pouze ke změněným / přidaným věcem)

<?php
$partner=27;
$apiheslo='cs3QbUzmxJwbLGgXbCSYjIgmUzzmu3MGwPxHK74hR';
$kodobjednavky='ABC2'; #nové unikátní číslo objednávky
$rada='RRRR9xxxxx';
$odbemail='test@zdarma-eet.cz';
$ft_popis[1]='Baterie AA';
$ft_cena[1]='64.50'; #celková cena za všechny 3 kusy na prvním řádku
$ft_ks[1]='3'; #počet kusů na prvním řádku
$ft_popis[2]='Baterie AAA';#popis zboží na druhém řádku
$ft_cena[2]='44'; #celková cena na druhém řádku
$ft_ks[2]='2'; #počet kusů na druhém řádku
$ft_popis[3]='máslo';#popis zboží na třetím řádku
$ft_cena[3]='33'; #celková cena na druhém řádku
$ft_dph[3]='10'; #sazba dph na řádku 3, jelikož je jiná než základní, vyplňujeme (neplátci DPH vždy 0%)
$url=urlencode('http://www.mojedomena.cz/vystaveno.php?parametr1=jedna&parametr2=dva'); #návratová stránka, tentokrát i s parametry

$soucetcen=array_sum($ft_cena);

$h=$partner.$kodobjednavky.$rada.$odbemail.$soucetcen.$apiheslo;
$h=md5($h);

#Při spuštění skriptu rovnou přesměrování na API bez kliknutí:
$apiurl='https://www.zdarma-eet.cz/api.php?partner='.$partner.'&kodobjednavky='.$kodobjednavky.'&rada='.$rada.'&odbemail='.$odbemail.'&h='.$h.'&ft_cena[1]='.$ft_cena[1].'&ft_popis[1]='.$ft_popis[1].'&ft_ks[1]='.$ft_ks[1].'&ft_cena[2]='.$ft_cena[2].'&ft_popis[2]='.$ft_popis[2].'&ft_ks[2]='.$ft_ks[2].'&ft_cena[3]='.$ft_cena[3].'&ft_popis[3]='.$ft_popis[3].'&ft_dph[3]='.$ft_dph[3].'&url='.$url;
header("HTTP/1.1 301 Moved Permanently"); 
header("Location: ".$apiurl); 
header("Connection: close");
?> 

Takto vypadá tělo vystaveného paragonu:

Po vystavení pak bude ihned zavolána požadovaná URL s příslušnými parametry:

    http://www.mojedomena.cz/vystaveno.php?faweb=https%3A%2F%2Fwww.zdarma-eet.cz%2Fparagon-tisk.php%3Ff%3D2017900065%26p%3D27%26h%3D15858d1129ccd445ada7b73945c263e9&f=2017900065&kodobjednavky=ABC2&parametr1=jedna&parametr2=dva

Příklad zpracování návratové stránky

Pro úplnost uveďme příklad zpracování návratové stránky (soubor vystaveno.php). Ta je zavolána v našem příkladu po vystavení dokladu.

<?php
$dokladurl=urldecode($_GET["faweb"]); #odkaz na vystaveny doklad (url decode)
echo '<a href="'.$dokladurl.'" target="_blank">TISK DOKLADU</a>';
?>

Tento skript tedy pouze přečte předanou hodnotu proměnné faweb která obsahuje url vystaveného dokladu a zobrazí odkaz na něj. Berte jako nejjednodušší příklad, samozřejmě v rámci proměnných které API předává si např. můžeme jako jeden z parametrů předat e-mail a poslat klientovi odkaz na doklad e-mailem, nebo třeba ošetřit vlastní kontrolní proměnnou zajišťující neměnnost apod.

Automatické vystavování EET pro e-shop pomocí API (platba kartou)

Výše uvedené příklady, zejména příklad 2 je možné velmi jednoduše použít pro vystavování dokladů pro e-shop. Potřebujeme zpravidla vystavit ihned po úspěšně autorizované transakci kartou. Prakticky vše probíhá tak, že klient si vybere zboží, zvolí platbu kartou a je přesměrován na platební bránu (karetní brána banky, nebo např. Paypal). Po úspěšně autorizované transakci je zákazník přesměrován zpátky na návratovou stránku e-shopu. Na ní už víme výsledek transakce. V případě úspěšné platby je nyní na místě vystavení dokladu s EET.

Jednou variantou je z této stránky provést ještě jedno automatické přesměrování na vystavení dokladu (viz příklad 2), zpět je poté klient vrácen na stránku kde poděkujeme za platbu a zobrazíme odkaz na doklad (+pošleme např. e-mail).

Druhou možností je už klienta nepřesměrovávat, ale na stránce kde nám banka potvrdila transakci pomocí malého IFRAME otevřít stránku, která zavolá API, vystaví EET doklad a v tom samém malém rámu zobrazí jen odkaz na doklad+pošle e-mail (viz opět příklad 2). Tato varianta je vhodná pro případy, kdy nemůžeme moc zasahovat do funkční struktury e-shopu a potřebujeme doklad vystavit v rámci jedné návratové stránky.

TIP: Vystavený doklad nemusí být nutně daňovým dokladem. Pokud si vystavujte daňové doklady při platbě kartou jinde, typicky např. fakturu přiloženou ke zboží při zaslání, tak přes API si pouze vystavte (nedaňový) doklad sloužící čistě jen pro nahlášení elektronické evidence tržeb. Při zavolání API přidejte hodnotu nenidandoklad=1 (viz výše). Můžete si ostatně pojmenovat doklad i jinak než paragon, viz výše.

Vystavování EET dokladů ze svého informačního nebo fakturačního systému

Tady zpravidla chceme vystavit doklad na kliknutí. Podle příkladu 1 tedy pouze vytvoříme URL a po jejím nakliknutí zavoláme API, čímž vystavíme doklad. Pokud by bylo položek více nebo z nějakého důvodu nevyhovovala metoda GET, je samozřejmě možno použít i klasický HTML formulář metodou POST. Pro úplnost tedy uvádím výše uvedený příklad 1 provedený metodou POST:

<?php
$partner=27;
$apiheslo='cs3QbUzmxJwbLGgXbCSYjIgmUzzmu3MGwPxHK74hR';
$kodobjednavky='3';
$rada='RRRR9xxxxx';
#$ft_popis[1]='Baterie AA';
$ft_cena[1]='21.50';
#$url=urlencode('http://www.mojedomena.cz/vystaveno.php');

$soucetcen=array_sum($ft_cena);
$h=$partner.$kodobjednavky.$rada.$odbemail.$soucetcen.$apiheslo;
$h=md5($h);
?> 
<form action="https://www.zdarma-eet.cz/api.php" method="post">
<input type="hidden" name="partner" value="27" />
<input type="hidden" name="kodobjednavky" value="3" />
<input type="hidden" name="rada" value="RRRR9xxxxx" />
<input type="hidden" name="h" value="<?php echo $h;?>" />
<input type="hidden" name="ft_popis[1]" value="Baterie AA" />
<input type="hidden" name="ft_cena[1]" value="21.50" />
<input type="hidden" name="url" value="http://www.mojedomena.cz/vystaveno.php" />
<input type="submit" value="vystavit doklad" />
</form>

Pro přehlednost do formuláře vepisujeme přímo hodnoty jednotlivých proměnných (mimo $h), v praxi budou hodnoty spíše předávané z proměnných.

Závěrem

Zvolené řešení s přesměrováním bylo zvoleno s ohledem na jednoduchost (zavolání jedné URL s parametry), přiměřenou bezpečnost (MD5 hash) a slučitelnost se stávajícími systémy (např. e-shop s limitem použitých funkcí, kde třeba nejde použít CURL). Provoz je zdarma coby doplňková funkce k www.zdarma-eet.cz.