7+1 API pro online podnikání a lepší webové aplikace

1. dubna 2014

Programování

Ve svém okolí jsem známý svou nechutí k používání všelijakých „hotových” řešení a frameworků – rád mám věci podle sebe a zcela pod svou kontrolou. Nechci být závislý na rozhodnutí jiných lidí, ať už se to týká nabízených funkcí (a dalšího rozvoje), bezpečnosti, nebo v extrémních případech i samotného zachování existence použitého hotového řešení (spousta věcí je poskytována v režimu „ber jak je a dokud je”, tedy bez garance, že server, ke kterému se připojujete, bude fungovat i zítra).

Přesto jsou oblasti, ve kterých se mi dlouhodobě vyplácí spoléhat na externí řešení. Jedná se zejména o oblasti, které netvoří můj „core business”, v případě nouze se bez nich obejdu (nebo je mohu snadno nahradit), ale dokud jsou, šetří mně i mým zákazníkům práci, čas a ve výsledku i peníze. Díky těmto externím řešením (a mnoha automaticky spouštěným úlohám řešícím rutinní práce) mohu na Vyplňto.cz pracovat i po šesti letech stále sám, a ještě vedle toho tvořit weby na zakázku, protože na to jednoduše „mám čas”.

V tomto článku jsem se s Vámi rozhodl podělit o 7 šikovných API, která mi velmi pomáhají (+ jedno vlastní). Budiž Vám článek inspirací i pro zlepšení Vašich webových aplikací a stránek :-)

1.) Informace o ekonomických subjektech - ARES

Vyplňování fakturačních údajů v rámci objednávky bývá pro zákazníky zbytečně zdlouhavé, a tu a tam se také stane, že se dotyčný třeba přepíše v identifikačním čísle (IČ) nebo udělá překlep v adrese. Následuje obvykle výměna alespoň jednoho e-mailu, případně se problém řeší také po telefonu, a celé to stojí zbytečně moc času (nehledě na to, že to často prodlužuje dobu splatnosti).

Výše uvedený problém lze poměrně efektivně řešit veřejným API databáze ARES, které po zavolání jednoduché adresy s parametrem IČO vrátí XML dokument s veškerými informacemi o nalezeneném ekonomickém subjektu (na základě těchto údajů lze nejen snadno zjistit, zda daný subjekt existuje, ale také předvyplnit všechny ostatní kolonky).

Pozor: V databázi ARES jsou k nalezení pouze subjekty s českým identifikačním číslem. Pokud očekáváte i objednávky např. ze Slovenska, je nutné s tímto počítat a apriori nezakazovat vytvoření objednávky s nenalezeným identifikačním číslem.

2.) Informace o plátcích DPH - VIES

API k databázi ARES je vynikající pro vyhledávání údajů o českých podnikatelských subjektech, zejména těch, které nejsou plátci DPH. Co když však prodáváte i cizincům v rámci Evropské unie a potřebujete řešit, zda máte fakturovat celou částku vč. českého DPH, nebo naopak fakturovat částku bez DPH a nechat samotné odvedení DPH na příjemci služby v režimu „reverse charge”?

V takovém případě je zapotřebí jít „o úroveň výše”, a obrátit se na evropskou webovou službu VIES. Tato služba je schopna zjistit, zda zadané DIČ náleží plátci DPH registrovaného v některé ze zemí EU, a pokud ano, tak také poskytne jeho fakturační údaje (je možné je automaticky předvyplnit do objednávkového formuláře).

Poznámka: Minimálně v ČR a SR jsou ekonomickým subjektům jaksi automaticky po registraci na finančních úřadech přidělována DIČ. Přestože se v rámci daných států jedná o platná DIČ, do databáze VIES jsou tato DIČ zařazena pouze v případě, že je dotyčný zároveň registrovaný k platbě DPH. Neexistuje žádný důvod zakázat lidem dát na fakturu jejich DIČ v případě, kdy nejsou plátci DPH, takže případné nenalezení DIČ v databázi VIES by mělo pouze znamenat fakt, že budete jako plátci DPH za každých okolností fakturovat zboží a služby vč. DPH.
Pozor: Pokud poskytujete služby na dálku v režimu B2B i B2C, mějte na paměti, že nalézt na webu cizí platné evropské DIČ není vůbec žádný problém a že zejména v případě poskytování online služeb a licencí může být pro někoho možnost ušetření DPH vhodnou motivací pro zfalšování fakturačních údajů. Poté může nastat  poměrně zapeklitá situace, kdy Vy vyfakturujete službu bez DPH, skutečný příjemce zaplatí cenu bez DPH a DPH nezaplatí nikdo. Při případné kontrole bude platba vyžádána po vlastníkovi DIČ, kterého uvedete v souhrnném hlášení, ten však o objednávce nebude mít samozřejmě vůbec ponětí... Jak celá záležitost nakonec dopadne mi na kurzu o plátcovství DPH přednášející nesdělil, protože jde o opravdu extrémní případ, se kterým legislativa zřejmě příliš nepočítá. Problémy by z toho ale mohly být velké, proto doporučuji věnovat objednávkám v režimu reverse charge zvýšenou pozornost, a ideálně alespoň vyžadovat potvrzení objednávky z e-mailu na doméně firemních stránek odběratele. 

3.) Informace o přijatých platbách – API FIO banky a další

Kdysi dávno, někdy na začátku roku 2008, se mi začalo při podnikání natolik dařit, že jsem si řekl „Dost bylo prasáren, od teď nebudu dělat ty tři faktury do měsíce ve Wordu, je čas podívat se po něčem lepším”.

Už tehdy jsem řešil, zda by nebylo nejlepší si naprogramovat nějaký vlastní fakturační systém, ale při představě, jak by to bylo složité, jsem se nakonec spokojil se softwarem Fakturky od Milana Bánovského. Dva roky jsem se opájel tím, jak je ten software skvěle funkční a jak to byla za tehdejší pětistovku super výhodná koupě. Následně jsem přešel na Macintosh a mé nadšení začalo trochu opadávat – vystavení faktury znamenalo spustit Windows ve virtualizačním nástroji, a jelikož jsem tehdy ještě rozhodně neměl SSD disk, trvalo mi vytvoření faktury zhruba 10 minut. A faktury postupně přibývaly (ve špičkách až na několik desítek měsíčně), začal jsem mít bordel v tom, která faktura je zaplacená, kterou mám ještě urgovat a kterou již vzdát, tedy stornovat...

Zjistil jsem, že vlastně některé dny neřeším nic jiného, než že vystavuji faktury za uplynulý týden, posílám je zákazníkům e-mailem, odškrtávám zaplacené faktury, píšu si poznámky k fakturám po splatnosti a po čase tyto faktury ruším z důvodu nevymožitelnosti. Začal jsem proces fakturace postupně nesnášet.

Posledním impulzem pro napsání vlastního fakturačního systému byl fakt, že jsem se kvůli expanzi Vyplňto.cz na Slovensko rozhodl stát plátcem DPH. Zvládnout DPH, reverse charge, zálohové faktury, daňové doklady a pravidelné čtvrtletní přiznání k DPH jsem si s aplikací Fakturky již představit nedokázal, zaměstnat člověka na řešení účetnictví by stálo strašně moc peněz, takže jsem si na to sednul, a přepsal objednávkový a fakturační proces úplně od nuly:

  1. Okamžikem vytvoření objednávky se automaticky vytvoří zálohová faktura (údaje se validují přes výše uvedené služby ARES a VIES)
  2. Zálohová faktura se ihned objeví v zákaznickém profilu na Vyplňto.cz a zašle se současně zákazníkovi i na jeho e-mail
  3. Zákazník má možnost fakturu zaplatit buď převodem na účet (s možností využití QR kódu), nebo některým ze zprostředkovatelů online plateb
  4. Na některé nabízené služby poskytuji zkušební období a garanci spokojenosti – v takových případech má možnost zákazník zálohovou fakturu kdykoli zrušit
  5. Po zaplacení se automaticky na základě zálohové faktury vytvoří finální daňový doklad

Nejlepší na celém výše uvedeném procesu je fakt, že do něj v ideálním případě nemusím vůbec zasahovat (řeším jen individuální problémy). Pro spárování plateb využívám API Fio banky (pokud nemáte pro podnikání účet ve Fio, tak si ho zařiďte, lepší účet pro online podnikání v ČR/SR neexistuje!), případně notifikační služby platebních zprostředkovatelů GoPay a Paypal. Druhou výhodou samozřejmě je, že mám data o fakturaci kdykoli k dispozici v podobě SQL tabulek, a tak si mohu snadno tvořit různé reporty s vývojem tržeb, a zejména snadno získávat podklady pro Finanční úřad.

Poznámky k API Fio banky: Rozhraní bohužel nefunguje v režimu „push”, na přijaté platby se tak musíte pravidelně dotazovat. Mezi každým voláním API je nutné mít prodlevu zhruba 20 sekund, jinak má API tendenci vyhazovat chyby (je tam agresivní ochrana proti zahlcení). API tím pádem nepatří k nejrychlejším – doporučuji jej volat třeba jen jednou za 30 minut, ať se zbytečně neplýtvá prostředky na serveru (pro bezpečné stažení plateb je potřeba dvou volání API, tedy trvá to ve výsledku cca 20 sekund na dávku).

4.) Poskytování slev studentům – API GTS Alive a CKM SYTS (ISIC)

Studenti jsou zvláštní a velmi zajímavou cílovou skupinou zákazníků, která se vyznačuje vyšší citlivostí na cenu a velkým potenciálem do budoucna. V mnoha případech (na Vyplňto.cz určitě) má smysl tuto skupinu nějak cenově zvýhodnit, protože jakmile se student během studia naučí s nějakým nástrojem pracovat, je šance, že s tímto nástrojem bude rád pracovat i po úspěšném dokončení studia v rámci svého zaměstnání (nejen Microsoft by mohl povídat :-)).

Jenže jak efektivně zprocesovat přiznání rozdílných cen pro studenty a ty ostatní?

Řešením číslo jedna může být poskytnutí slevy na základě vložení školního e-mailu – to s sebou nese především nevýhodu v podobě nutnosti znát pokud možno všechny domény škol, na kterých mají studenti své e-maily. Druhým problémem pak je, že na některých školách studenti jednoduše školní e-maily nepoužívají (tuším, že např. na některých fakultách Masarykovy univerzity v Brně).

Poskytovat slevu studentům tedy bohužel jednoduše nejde, zato je možné relativně jednoduše poskytovat slevu držitelům karet ISIC, ITIC, ALIVE (jen CZ) a EURO<26 (jen SK).

V rámci České republiky není nic snazšího než kontaktovat společnost GTS Alive, stát se oficiálním poskytovatelem slevy a oproti podpisu smlouvy získat přístup do jednoduchého API pro ověření platnosti karty na základě jména a čísla karty (lze ověřit mezinárodní karty ISIC a ITIC vydané v libovolném státě + kartu ALIVE, která je lokálním produktem v rámci ČR). Bonusem je následně také určitá (byť poměrně omezená) marketingová podpora ze strany poskytovatele karet.

Pokud chcete fungovat na Slovensku, zkuste podepsat smlouvu s CKM SYTS – komunikace s nimi je sice trochu „na dlouhé lokte”, ale nakonec to nějak funguje, a získáte přístup k ověření mezinárodních karet ISIC a ITIC + slovenské EURO<26.

Poznámka: Připravte se na to, že kontrola průkazů nebude neprůstřelná – nabídnete-li zajímavou slevu, stane se, že si budou studenti mezi sebou karty ISIC půjčovat, a tu a tam ji budou chtít využít i pro své podnikání (příp. firma využije ISIC syna jednatele). Řešením je asi jen mít radost z toho, jak má někdo jiný radost z toho, jak se mu podařilo vše krásně „ochcat” (popravdě: osvědčilo se mi v případě využití studentské slevy vystavovat faktury jen na soukromé osoby, nikoli na firemní údaje). Dále počítejte s tím, že někteří studenti si kartu ISIC pořídí na začátku studia, a vůbec nijak je netrápí, že po roce musí na průkaz nalepit revalidační známku – mnozí „kamenní” prodejci jsou rádi za každý kšeft, a tak revalidační známku nekontrolují, čímž pádem se investice do revalidační známky nemusí jevit jako racionální volba. Kontrola přes API však v takových případech vždy skončí neúspěchem, jelikož bez revalidační známky je karta neplatná. Budete tak muset řešit e-maily lidí, kteří Vám budou posílat naskenované karty s tím, že jim všude jinde slevu normálně poskytují, a jen Vy děláte problémy (přestože dle smlouvy nesmíte slevu na neplatný průkaz poskytnout).

5.) Volá mi zákazník, nebo nějaký otrava telemarketér? Google Contacts API prozradí!

Podnikat bez uvedení telefonního čísla na stránkách je blbost – lidé, kteří potřebují něco urgentně vyřešit, málokdy použijí e-mail. Vždy se budou primárně pídit po telefonním čísle. Jenže jak odlišit zrno (zákazníky) od plev (otravů), např. v momentě, kdy poskytujete technickou podporu k nějaké placené službě, kterou využívají stovky lidí?

Řešení je v podstatě jednoduché – je zapotřebí od zákazníků již v okamžiku učinění objednávky získat telefonní číslo (s příslibem snazší telefonické technické podpory) a toto telefonní číslo nějakým způsobem dostat se jménem a ideálně také e-mailem do mobilního telefonu. Můžete to dělat ručně, ale nemusíte: většina mobilních telefonů (iPhone, Android i Windows Phone) podporuje synchronizaci kontaktů s Googlem, a Google... poskytuje na kontakty výborné Google Contacts API!

Díky Google Contacts API lze téměř okamžitě a absolutně bez rutinní lidské práce dostat kontakty z webu do telefonu, takže ihned vidíte, kdo Vám ze stávajících klientů zrovna volá, můžete jej oslovit přímo jménem a nemusíte se ho na jeho jméno ptát (často lidé své jméno jen zamumlají, protože to berou jako naučenou frázi, kterou vyslovují automaticky a bez důrazu na správnou artikulaci – dohledat potom objednávku takového člověka je někdy obtížné...).

Poznámka: Pokud nemáte stejně jako já úplně rádi Google a chtěli byste radši využít služeb Microsoftu, tak vězte, že má na první pohled docela pěkné Live Contacts API, ale po několika hodinách testování zjistíte, že kontakty můžete pouze vytvářet, nikoli číst (není přístup k e-mailovým adresám a telefonním číslům), upravovat nebo dokonce mazat = Microsoft dává do placu API, které je dobré leda tak k tomu, aby se na něj dalo nadávat. V případě Applu není API ke kontaktům k dispozici pro jistotu vůbec, respektivě jediná možná cesta k integraci by mohla vést přes protokol CardDav (což je cesta značně trnitá, a navíc delší než do Santiaga de Compostely).

6.) Kdo o mně kde píše? Prozradí Google Custom Search API, Google+ API a Twitter Search API

Zadali jste někdy do Googlu své jméno nebo název svého projektu, abyste zjistili, co se o Vás píše? Pokud zatím ne, zkuste to, možná budete až překvapeni, kolik konstruktivní kritiky, povzbudivých slov uznání a v některých případech i potenciálních dlouhodobých partnerů takto můžete nalézt. Monitoring zmínek na internetu nabízí za úplatu celá řada specializovaných firem, prozačátek si však můžete vystačit i se základními službami, které jsou k dispozici prostřednictvím volně dostupných API.

Pro sledování zmínek na internetu je naprosto klíčové Google Custom Search API, které Vám dává zdarma k dispozici vyhledávání 100 frází denně. Nenechte se zmást tím, že Google na stránkách popisuje, jak s pomocí této webové služby můžete snadno prohledávat své vlastní stránky – při vytváření vlastního vyhledávače, který budete s Custom Search API využívat, si prostě a jednoduše zaškrtněte volbu „prohledávat celý internet, ale s důrazem na zahrnuté weby”, a v samotném vyhledávacím řetězci Váš vlastní web odeberte operátorem „-site:mojedomena.tld” (dále je vhodné do vyhledávacího dotazu dát omezení jen na dostatečně čerstvé odkazy, ať nestahujete jen první stránku s nejrelevantnějšími výsledky). Jediným skutečným omezením tohoto API je limit na 100 volání (frází) denně, což je limit více než dostatečný pro zjišťování novinek o Vašem projektu třeba každé dvě hodiny (záleží na tom, jak dobře se Vám podaří vytvořit vyhledávací dotazy a jak moc jednoznačný máte název firmy / webu).

Přestože pomocí Google Custom Search můžete nalézt i mnoho obsahu ze sociálních sítí (vč. některých Facebookových statusů, tweetů a příspěvků na Google+), doporučuji Vám pro vyhledávání na sociálních sítích použít jejich samostatná API: Google+ API a Twitter Search API (Facebook jednoduché vyhledávání přes API podle všeho nemá, resp. nenašel jsem zatím žádný ekvivalent k dvěma předchozím API).

7.) Facebook Graph API pro monitoring sdíleného obsahu

Facebook je bohužel poměrně uzavřená sociální síť, kterou nelze dost dobře automaticky vytěžovat – případné statusy o Vaší firmě se v mnoha případech zobrazují jen v rámci určité komunity kamarádů, a tak se Vy nemáte jak k těmto příspěvkům dostat nebo na ně dokonce reagovat. Nicméně nějaké API Facebook má, a nejvíce z něj asi má smysl sledovat počty sdílení určitého obsahu z Vašeho webu (víte, o co je největší zájem, co má virální potenciál a co má tedy největší smysl na sociálních sítích propagovat – blbé je, že do toho musíte postupně nasypat všechny adresy, o kterých si myslíte, že by mohly mít úspěch). 

Pokud si na stránky přidáte sdílecí tlačítka AddThis (umožní sdílet Vaši stránku na prakticky libovolnou sociální síť), můžete pro sledování úspěšnosti Vašeho obsahu použít také jejich pokročilejší Analytics API.

Bonus: Dotazníky z Vyplňto.cz zpracovávané v reálném čase

Určitým nepsaným standardem dnešní doby je, že se zákazníkům automaticky po uskutečnění plnění zašle dotazník spokojenosti, ve kterém mohou ohodnotit, jak byli s poskytnutými službami (nebo zbožím) spokojeni, případně zda mají nějaké připomínky nebo doporučení pro budoucí zákazníky. Jako provozovatel dotazníkové služby samozřejmě nemůžu zůstat stranou, a za poslední rok jsem takto získal téměř 800 ohlasů.

Ze začátku jsem na tyto dotazníky odpovídal vždy, když jsem si na ně vzpomněl (vyjel jsem si export za posledních několik týdnů a odpověděl na ta hodnocení, kde to dávalo smysl). Jenže to vnášelo přílišný prvek náhody, který někdy neúnosně prodlužoval mou reakční dobu. Vytvořil jsem proto jednoduché REST API, které umožní v reálném čase předávat vyplněné dotazníky do dalších systémů – okamžikem odeslání dotazníku se data uloží nejen do databáze na Vyplňto.cz, ale také se celý obsah dotazníku přepošle v POST parametrech na uživatelsky definovanou webovou adresu (vstupní brána do jiného systému).

Funkci zatím využívám pouze pro sebe (dotazníky si transformuji do e-mailové zprávy, na kterou mohu rovnou odpovědět – můžete namítnout, že by bylo jednodušší respondenty požádat, aby mi své hodnocení poslali rovnou e-mailem, ale tím bych přišel o možnost se zákazníků ptát strukturovaně na otázky, které mě zajímají, a přišel bych také o souhrnná „kvantitativní” /měřitelná/ data, která v hodnotícím dotazníku zjišťuji) a v rámci projektu Paridea.cz, kde takto zjišťuji, kteří z oslovených respondentů již zodpověděli určitý dotazník a které je vhodné požádat o vyplnění znovu (Vyplňto.cz umožňuje každému oslovenému respondentovi přiřadit unikátní kód, kterým se jeho vyplnění stane neanonymním – díky tomu, že se v API předává i tento unikátní kód, je možné snadno zjistit, kdo z oslovených respondentů již který dotazník vyplnil a jak).

REST API na Vyplňto.cz plánuji zcela zveřejnit v průběhu jara pro všechny uživatele s licencí PREMIUM a KOMPLET – do té doby poskytnu nastavení této funkce na vyžádání e-mailem (ve finále se možnosti API ještě velmi pravděpodobně rozšíří o další funkce).

A jaké API Vám ulehčují život? Podělte se o ně prosím v diskusi – odkazy na vlastní (i komerční) projekty s API povoleny ;-)

Publikováno dne 01. 04. 2014 v kategorii Programování

O kategorii Programování

V nejodbornější kategorii tohoto blogu jsou zařazeny články s mými programátorskými zkušenostmi získanými několikaletou praxí tvorby stránek a java aplikací pro mobilní telefony.

Komentáře k článku

Ondřej - [email schován] - web (dne 22. 11. 2014 v 15.43)
Velice příjemné čtení, těším se na aktualizaci!

Tomas - [email schován] - web (dne 01. 02. 2016 v 15.35)
Rád bych upozornil ja API českých firem a živností: https://www.merk.cz/api-strojovy-pristup/

Přidat vlastní komentář:
Jméno:
E-mail:
Sledovat diskusi:
Web:
Kontrolní kód:

Komentáře jsou v prvé řadě určeny ke kladení dotazů k tématu, upozornění na chybu, rozšíření obsahu článku a vůbec ke zpětné reakci na obsah těchto stránek. Mé reakce jsou barevně odlišeny.

V současné době není umožněno vkládat HTML tagy - pokud vložíte HTML kód, bude převeden na entity. K Vašemu komentáři se do databáze uloží čas vložení a Vaše aktuální IP adresa (54.161.40.41). IP adresa se nebude zobrazovat čtenářům, nicméně v případě, že bude Váš odkaz shledán právně závadným, může být Vaše IP adresa předána příslušným státním orgánům. Emailové adresy jsou ochráněny před běžnými spam roboty.

© Marek Demčák 2007 - 2018
Všechna práva dle Autorského zákona (č. 121/2000 Sb.) vyhrazena.