Jak propojit vlastní aplikaci s iÚčto přes API
Chcete, aby e-shop, CRM nebo vlastní program sám zapisoval a četl doklady v iÚčto. K tomu slouží REST API, rozhraní, přes které si programy předávají data, a webhooky: API klíč si vygenerujete v nastavení iÚčto a předáte ho vývojáři, ten podle dokumentace API napíše propojení. Webhooky pak vaší aplikaci samy oznámí, že se doklad změnil.
Než začnete
- Oprávnění. Klíč patří uživateli, který ho vygeneroval, a jedné firmě.
- Limity. API je součástí tarifů Fakturace (3 000 volání za měsíc), Firma (5 000 volání za den), Max (10 000 volání za den) a zkušebního tarifu Start (2 000 volání za den). Tarif Sólo API nemá (během kampaně Firma na zkoušku ho má jako Firma, s jejím koncem přestane fungovat), změnu tarifu popisuje Jak změnit tarif na vyšší nebo nižší. Volání se počítají za celou firmu. Počítadlo se vynuluje každý den, u tarifu Fakturace každý měsíc.
1 Vygenerujte API klíč
Otevřete Nastavení → Automatizace → API. Tabulka Přiřazené účty vypíše všechny firmy, ke kterým máte přístup. U firmy, kterou chcete propojit, klikněte na Vygenerovat klíč a klíč ze sloupce API klíč zkopírujte ikonou vedle něj. Pro každou další firmu je potřeba vlastní klíč.
Kdo klíč zná, dostane se přes API k datům firmy. Vývojáři ho předejte bezpečnou cestou a chraňte ho jako heslo.
Zeleně je firma, ve které jste právě přihlášení. První firma klíč má, u druhé ho vytvoří tlačítko Vygenerovat klíč. Ikona vedle klíče ho zkopíruje do schránky.
Vygenerovat klíč znovu vytvoří nový klíč a dosavadní okamžitě přestane platit. Aplikace, které ho používají, přestanou fungovat, dokud do nich nový klíč nevložíte. Akci nejde vrátit.
2 Předejte vývojáři dokumentaci API
Podrobný popis všech zdrojů, polí a příkladů je v dokumentaci API. Otevřete Nastavení → Automatizace a ve skupině Pro vývojáře klikněte na Dokumentace API. Dokumentace (adresa iucto.docs.apiary.io) se otevře v nové záložce. Co API umí, shrnuje také stránka API na www.iucto.cz. Základní údaje pro vývojáře:
- Adresa. https://online.iucto.cz/api/<verze>/<zdroj>, běží verze 1.0 až 1.3. Pro nové propojení použijte nejnovější 1.3.
- Přihlášení. API klíč v hlavičce X-Auth-Key u každého požadavku. Jiný způsob přihlášení API nemá.
- Formát. Požadavky v JSON, nahrání souboru (příloha, doklad k vytěžení) jako multipart/form-data. Odpovědi ve formátu HAL+JSON.
- Co jde přenášet. Faktury vydané a přijaté, zálohové faktury, dobropisy, objednávky, platby, bankovní pohyby, odběratelé, dodavatelé, ceník a přílohy, v tarifech se skladovým hospodářstvím (Start, Firma, Max) i sklady, číst i zapisovat. Doklad jde také nahrát k vytěžení.
- Knihovna pro PHP. iucto/iucto-api-php-sdk, instalace příkazem composer require iucto/iucto-api-php-sdk.
3 Nastavte webhooky
Webhook je automatické oznámení, které iÚčto pošle na zadanou adresu, když se ve firmě vytvoří, upraví, smaže nebo uhradí doklad. Vaše aplikace se tak o změně dozví hned a nemusí se do iÚčto pravidelně dotazovat. Krok je nepovinný.
Na stránce API klikněte u firmy na Webhooky, pak na + Přidat webhook. Do sloupce URL zadejte adresu, kterou vám dá vývojář, ve sloupci Akce nechte vybrané události, o kterých má aplikace vědět (Vytvoření dokladu, Úprava dokladu, Smazání dokladu, Úhrada dokladu; nový řádek je má vybrané všechny), a klikněte na Uložit.
U firmy jste webhook ještě nenastavili. Odkaz + Přidat webhook pod tabulkou přidá první řádek.
Oznámení přijde ve formátu JSON a chodí u faktur, zálohových faktur, dobropisů, objednávek, plateb, interních předpisů nákladů a bankovních pohybů. Nese druh změny, typ dokladu a jeho identifikátor v API, u úhrady částky dokladu a platby. Podrobnosti si aplikace načte přes API. Adresa má odpovědět kódem 2xx, jinak iÚčto doručení několikrát zopakuje a pak ho vzdá. Oznámení není podepsané, adresu proto nikomu nesdílejte.
4 Ověřte propojení
Požádejte vývojáře, ať nejdřív zkusí jednoduchý dotaz, třeba načtení seznamu faktur. Výsledek porovnejte s tím, co vidíte v iÚčto. Odpověď s kódem 401 znamená chybějící nebo neplatný klíč. Zapisuje-li aplikace doklady, zkontrolujte první z nich v iÚčto dřív, než ji pustíte naostro.
Hotové propojení přes službu Make bez programování popisuje Jak propojit iÚčto se službou Make.
Když se něco nepovede
| Hláška | Co znamená a co s tím |
|---|---|
| API je součástí tarifů … | Na stránce API místo klíče: tarif firmy API nemá (stránka může napsat i API není součástí vašeho tarifu.). Tarif změníte podle návodu Jak změnit tarif na vyšší nebo nižší. Bez aktivního tarifu stránka napíše Bez aktivního tarifu API nefunguje. |
| Limit počtu dotazů do API pro aktivní tarif byl překročen. Dnešní využití: …, měsíční využití: …. | Odpověď API s kódem 402: firma vyčerpala volání za den nebo měsíc (viz Limity v části Než začnete), nebo její tarif API nemá či skončil. Vyčerpaný limit se obnoví s novým dnem nebo měsícem. Bez API v tarifu pomůže jen tarif s API. |
| Zdroj je dostupný pouze ve vyšším tarifu. | Odpověď API s kódem 402: tarif firmy tuto část dat nezahrnuje, například sklady. Pomůže vyšší tarif. |
| Verze API nebo zdroj nejsou platné. | Odpověď API s kódem 400: adresa požadavku nemá verzi nebo název zdroje. Vývojář ji opraví podle dokumentace. |
| Adresa webhooku „…“ není platná. Zadejte adresu ve tvaru https://www.example.cz. | Adresa ve sloupci URL je neúplná nebo prázdná. Takový řádek se neuloží. Přidejte webhook znovu a adresu od vývojáře zkopírujte celou, včetně https://. |
Časté dotazy
Proč propojení nefunguje?
Nejčastěji proto, že někdo klíč vygeneroval znovu (nový klíč vložte do aplikace, která API volá), firma přešla na tarif bez API (pomůže tarif s API), nebo vyčerpala volání za den či měsíc. Odpověď API pak najdete v tabulce Když se něco nepovede.
Jak webhook zrušit?
Na stránce Webhooky klikněte u adresy na ikonu koše (Smazat) a smazání potvrďte. Smažete tím jen svůj webhook. Zadal-li stejnou adresu u firmy i jiný uživatel, oznámení chodí dál, dokud ji nesmaže i on.
Chodí webhook i při změně, kterou udělal jiný uživatel?
Ano. Oznámení o dokladech vyjmenovaných v kroku 3 chodí, ať změnu udělal kdokoli, i přes API. Dostanou ho adresy webhooků všech uživatelů firmy, ne jen vaše.
Nedaří se vám něco? Napište nám na info@iucto.cz.
Byl tento článek užitečný?
To je skvělé!
Děkujeme Vám za zpětnou vazbu
Je nám líto, že jsme vám nepomohli
Děkujeme Vám za zpětnou vazbu
Zpětná vazba odeslána
Oceňujeme vaši snahu a pokusíme se článek opravit