# iÚčto API

> Veřejné REST API českého účetního systému online.iucto.cz. 161 operací nad
> doklady, platbami, adresářem, sklady a účetnictvím. Base URL
> https://online.iucto.cz/api/1.3/, autentizace hlavičkou X-Auth-Key,
> odpovědi v HAL+JSON.

## Co API pokrývá

Jedenáct skupin, 47 zdrojů, 161 operací. Co která skupina obsahuje:

- **Seznamy:** číselníky měn, metod plateb a způsobů zaokrouhlení.
- **Firma:** profil firmy, bankovní účty, pokladny, střediska, zakázky,
  provozovny, stavy dokladů.
- **Adresář:** zákazníci a dodavatelé včetně skupin, země, preferované metody
  platby.
- **Doklady vydané:** objednávky přijaté, zálohové faktury, faktury a opravné
  daňové doklady — vystavení, editace, PDF, odeslání e-mailem, zaúčtování.
- **Doklady přijaté:** došlé doklady (sken s rozpoznáním), objednávky vydané,
  zálohové faktury, faktury, opravné daňové doklady, interní předpisy nákladů.
- **Platby:** platby vydané i přijaté, bankovní pohyby a jejich zaúčtování.
- **Účetnictví:** účetní deník, přímé zaúčtování, sazby DPH, typy účetních
  položek, typy DPH, účty účetní osnovy, účty DPH.
- **EET:** seznam a správa EET záznamů (historická data, evidence skončila
  1. 1. 2023).
- **Ceník a sklady:** ceník, sklady, skladové karty a pohyby (vyžaduje tarif
  se skladovým modulem).
- **Přílohy:** soubory k dokladům a kontaktům — nahrání, seznam, detail,
  stažení, smazání.
- **Webhooky:** odchozí oznámení o změně a o úhradě dokladu (volá je iÚčto
  vám, nejsou to endpointy API).

## Než začneš psát kód

Pět věcí, na kterých integrace nejčastěji padá:

- **Tělo POST/PUT není tvar odpovědi GET.** Vnořené objekty se při zápisu
  posílají jako ID (`customer` → `customer_id`, `bank_account` objekt → ID)
  a dopočtené částky (`price`, `price_czk`, `to_be_paid`) se neposílají vůbec.
  Kdo pošle zpátky, co dostal, dostane 400.
- **PUT je úplná náhrada, ne patch.** Server vyžaduje všechna povinná pole
  stejně jako při vytvoření a neexistuje `If-Match` — poslední zápis vyhrává.
  Před editací si načti detail, ne položku seznamu.
- **Z prohlížeče to nejde.** API neposílá hlavičky CORS, takže volání
  z frontendu prohlížeč zablokuje. Klíč patří na server.
- **Vyčerpaná kvóta vrací 402, ne 429**, a bez hlaviček `X-RateLimit-*`
  nebo `Retry-After`. Backoff podle hlaviček tedy nejde postavit.
- **Chybová odpověď má pět různých tvarů** — `{"errors": {...}}` u validace,
  `{"error_code", "message"}` u zamítnutí s kódem, holý JSON řetězec
  u ostatních, mapa bez obálky `errors` u parametrů seznamů a holé pole hlášek
  u validace akcí. Uvnitř `errors` je hodnota **řetězec, když je hláška
  jediná**, a pole až od dvou výš; jediná hláška je běžný případ. Větvi podle
  stavového kódu, ne podle textu hlášky.

## Specifikace

- [OpenAPI 3.1, YAML](https://developers.iucto.cz/spec/openapi.yaml): všech 161
  operací včetně schémat, příkladů a popisů. Jeden soubor.
- [Totéž v JSON](https://developers.iucto.cz/spec/openapi.json) pro nástroje,
  které YAML neumí.

## Reference

Stránka pro každou operaci a každé schéma. Operace žijí pod `/api/`, schémata
pod `/api/schemas/`. Rozcestník po skupinách a zdrojích:

- [Přehled reference](https://developers.iucto.cz/api/iucto-api)
- příklad zdroje: [Faktury vydané](https://developers.iucto.cz/api/faktury-vydane)
- příklad operace: [Vytvoření faktury vydané](https://developers.iucto.cz/api/create-invoice-issued)
- příklad schématu: [InvoiceIssuedParams](https://developers.iucto.cz/api/schemas/invoiceissuedparams)

Serverem vykreslené HTML stránky operace nese popis, parametry dotazu a odkazy
na schémata; tabulky polí se skládají až v prohlížeči. Tvar dat je celý
ve specifikaci výš — pro strojové čtení sáhni radši po ní.

## Začátek

- [Začínáme](https://developers.iucto.cz/zaciname): klíč, první volání na
  `/company_profile`, vlastnosti určující návrh integrace
- [Úvod](https://developers.iucto.cz/uvod): base URL, povolené HTTP metody,
  formát odpovědí
- [Autentizace](https://developers.iucto.cz/autentizace): hlavička X-Auth-Key,
  jeden klíč = jedna firma, žádný OAuth

## Koncepty

- [Chyby a jak je číst](https://developers.iucto.cz/chyby)
- [Limity a kvóty](https://developers.iucto.cz/limity)
- [Stránkování, řazení a filtry](https://developers.iucto.cz/strankovani-razeni):
  řadit jde jen podle `modified`
- [Datové typy](https://developers.iucto.cz/datove-typy)
- [Co platí pro všechny doklady](https://developers.iucto.cz/doklady-spolecne):
  neplátci DPH, zaúčtování položek, upomínky, EET, One Stop Shop
- [Zálohové faktury](https://developers.iucto.cz/zalohove-faktury)
- [Životní cyklus dokladu a zaúčtování](https://developers.iucto.cz/zauctovani)
- [Webhooky](https://developers.iucto.cz/webhooky): bez podpisu a bez opakování
- [Číselníky](https://developers.iucto.cz/ciselniky): které pole čerpá odkud
- [Slovníček pojmů](https://developers.iucto.cz/slovnicek): české účetní pojmy
  namapované na pole API

## Návody

- [První faktura krok za krokem](https://developers.iucto.cz/navody/prvni-faktura)
- [Synchronizace adresáře](https://developers.iucto.cz/navody/synchronizace-adresare)
- [Řešení potíží](https://developers.iucto.cz/navody/reseni-potizi)

## Nástroje

- [Přehled nástrojů](https://developers.iucto.cz/nastroje/prehled): co si vybrat
  podle jazyka a úlohy, kolekce pro Postman, hotové importy do iÚčta
- [PHP SDK](https://developers.iucto.cz/nastroje/php-sdk): `iucto/iucto-api-php-sdk`;
  verzi 1.3 předej třetím parametrem `IUctoFactory::create()`, výchozí je 1.2
- [MCP server](https://developers.iucto.cz/nastroje/mcp-server):
  `@iucto/iucto-mcp-server` pro AI asistenty; 97 nástrojů generovaných ze
  specifikace, jen čtení a zakládání

## Ostatní

- [Přehled změn](https://developers.iucto.cz/changelog): co se v API měnilo
  a odkdy