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.

Tabulka Přiřazené účty: firma Demo účetnictví s.r.o. má API klíč b72e19d4c05a6f83e1d97a2c4b58f031 s ikonou kopírování a tlačítka Webhooky a Vygenerovat klíč znovu, firma Demo evidence má text Klíč zatím není vygenerovaný a tlačítka Webhooky a Vygenerovat klíč.

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.

Tabulka webhooků firmy Demo účetnictví s.r.o. bez jediného záznamu: sloupce URL a Akce, text o prázdném seznamu a odkaz + Přidat webhook.

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

Dejte nám vědět, jak můžeme tento článek vylepšit!

Vyberte alespoň jeden důvod
Je požadována verifikace pomocí CAPTCHA.

Zpětná vazba odeslána

Oceňujeme vaši snahu a pokusíme se článek opravit

Nenašli jste odpověď? Napište nám.

Napsat podpoře