Přeskočit na hlavní obsah

Začínáme

Cesta k prvnímu úspěšnému volání. S hotovým účtem to trvá dvě minuty, bez něj počítejte s dvaceti — registrace znamená založit účetní jednotku, ne jen e-mail.

1. Získejte API klíč​

Klíč vygenerujete v aplikaci v Nastavení → Nastavení API (online.iucto.cz/settings/api).

Klíč je vázaný na uživatele v jedné firmě a má stejná oprávnění jako ten uživatel ve webovém rozhraní. Podrobnosti v Autentizaci.

Účet ještě nemáte? Založte si ho — 14 dní zdarma. Projdete přitom založením účetní jednotky: IČO, typ subjektu, účetní období a plátcovství DPH.

2. Zavolejte profil firmy​

První dotaz veďte na /company_profile. Neověří jen to, že klíč funguje — řekne vám i do které firmy jste se trefili a jak je nastavená, což určuje polovinu dalších rozhodnutí v integraci.

curl -s https://online.iucto.cz/api/1.3/company_profile \
  -H "X-Auth-Key: $IUCTO_API_KEY"
{
  "name": "ACME s.r.o.",
  "comid": "12345679",
  "vatid": "CZ12345679",
  "vat_type": "monthly",
  "accounting_type": "accountancy",
  "oss_status": false
}

Odpověď je zkrácená — profil vrací i adresu, kontakty, subject_type a další pole, celý tvar je v referenci.

Tři pole si přečtěte hned na začátku, protože mění, co bude na dokladech povinné:

PoleCo z toho plyne
vat_typenonpayer = neplátce DPH → nevyplňujete date_vat ani sazby, viz Co platí pro všechny doklady
accounting_typeaccountancy účetnictví, tax_registration daňová evidence, invoicing fakturace bez účtování — u posledních dvou nedávají zaúčtování a účtová osnova smysl
oss_statuszda je zapnutý režim One Stop Shop

Odpověď 401 znamená neplatný klíč nebo klíč jiné firmy.

3. Vystavte první doklad​

Celý postup od zákazníka po odeslané PDF je v návodu První faktura krok za krokem.

Vlastnosti, které určí návrh integrace​

Přečtěte si to teď — každá z nich se špatně vrací, když se na ni přijde v půlce práce:

  • Ostré API nejde volat z prohlížeče. Neposílá hlavičky CORS, takže požadavek z frontendu prohlížeč zablokuje. Klíč patří na server. Na zkoušení použijte terminál nebo kolekci pro API klienty.
  • Není sandbox. Testuje se proti reálné firmě. Založte si na to druhou, zkušební.
  • Klíč je plný přístup k účetnictví jedné firmy. Žádný OAuth, žádné scopy. Kdo staví aplikaci pro víc klientů, vybírá klíč od každého zvlášť.
  • Denní kvóta se ohlásí jako 402, ne 429, a API neposílá žádné hlavičky se zbývajícím limitem — počítání dotazů je na vás. Zkušební tarif má navíc strop na počet zaúčtovaných dokladů, viz Limity a kvóty.
  • Zápis nemá pojistku proti duplicitě. Neexistuje Idempotency-Key ani If-Match, takže zopakovaný POST po vypršení spojení založí druhý doklad a dva souběžné zápisy rozsoudí pořadí. U vydaných dokladů navíc není pole pro váš vlastní identifikátor, kterým by se to dalo dohledat — jak s tím pracovat, je v Datových typech.
  • Doklad vystavený přes API neodepíše sklad. Skladový pohyb je samostatná operace.

Zkušební firma​

Veřejné testovací prostředí neexistuje — na skutečné chování aplikace (číslování dokladů, dopočty DPH, párování plateb) potřebujete druhou firmu, oddělenou od produkčního účetnictví.

Jistá je jen tahle cesta: projděte znovu registraci stejně jako u té první — vznikne samostatná účetní jednotka s vlastním 14denním zkušebním obdobím a vlastním API klíčem, nezávislým na produkčním.

Kudy dál​