Limity a kvóty

Počet dotazů do API je omezený tarifem firmy. Kvóta se počítá na straně iÚčta, ale API o ní neposílá žádnou informaci — kolik dotazů zbývá, si musí hlídat vaše integrace sama.

Kvóta dotazů podle tarifu

Kvóta je vázaná na firmu, ne na API klíč. Když má firma víc klíčů, sčítají se dotazy ze všech.

Tarif	Kvóta
Start (zkušební)	2 000 / den
Sólo	0 — API v tomhle tarifu nefunguje
Firma	5 000 / den
Max	10 000 / den
Fakturace	3 000 / měsíc

Firma bez aktivního tarifu má kvótu 0, stejně jako tarif Sólo — dotazy skončí kódem 402.

Starší tarify

Firmy na tarifech, které se dnes už neprodávají, mají kvótu podle původního zařazení: Start (old) 0, Standard (old) 2 000 / den, Pokročilý (old) 5 000 / den, Premium (old) 10 000 / den.

Jak se dotazy počítají

Do kvóty se počítá každý požadavek, který projde ověřením klíče — tedy i ten, který pak skončí chybou 400 nebo 404. Neúspěšný dotaz kvótu ubírá stejně jako úspěšný.

• Denní počitadlo se nuluje o půlnoci v čase Evropa/Praha.
• Měsíční počitadlo se nuluje prvního dne v měsíci.
• Odmítnutý dotaz s kódem 401 (neplatný klíč) se do kvóty nepočítá.

Vyčerpaná kvóta

Po vyčerpání kvóty vrací API kód 402 Payment Required s holým textem v těle. Hláška zní Překročen limit na počet dotazů v API, zkontrolujte aktivní tarif. a za ní jsou dvě čísla: dnešní využití a využití za měsíc.

"Překročen limit na počet dotazů v API, zkontrolujte aktivní tarif. Dnešní využití: 2001, za měsíc: 14320"

Backoff si spočítejte podle vlastního počitadla

API neposílá X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset ani Retry-After a nikdy nevrací kód 429. Backoff řízený hlavičkami odpovědi tedy postavit nejde — jediný signál je 402 a číslo v textu hlášky, které se pro rozhodování používat nemá. Kolik dotazů zbývá, si musí integrace počítat sama a plánovat podle časů nulování počitadel.

Opakovat požadavek hned nemá smysl. Do resetu počitadla nebo do změny tarifu bude odpověď stejná.

Limit dokladů na zkušebním tarifu

Kvóta dotazů není jediný strop, na který se dá na tarifu Start narazit. Zkušební tarif má navíc limit počtu zaúčtovaných dokladů — ve výchozím nastavení 50. Jakmile jich firma tolik má, vrátí POST i PUT na kterýkoli dokladový zdroj kód 402 s hláškou:

"Využíváte verzi zdarma s limitem 50 dokladů. Chcete-li pokračovat, zvolte některou z placených variant provozu iÚčta."

Počítají se jen doklady zaúčtované, napříč všemi typy. Nezaúčtované se do limitu nepočítají, takže dokladů může být víc, dokud je nezaúčtujete.

Týká se to i testování

Zkušební firma, kterou doporučujeme na testování, běží právě na tarifu Start. Zátěžový test na dvě stě dokladů tedy neprojde — na padesátém prvním zaúčtovaném dokladu začne API vracet 402, i když má kvóta dotazů daleko do vyčerpání. Ta hláška vypadá jako problém s tarifem, ale je to tenhle strop.

Kontrola běží na dvou místech: při vytvoření a editaci dokladu a znovu při jeho zaúčtování. Limit patří tarifu, ne API — stejně se chová i zakládání dokladů v aplikaci.

Zkušební tarif má ještě jedno omezení, které se přes API projeví až chybou: zaúčtovat na něm jde jen doklad s datem vystavení v aktuálním roce. Doklad loňským datem projde při vytvoření, ale /account ho odmítne.

Limity požadavků

Co	Limit	Při překročení
pageSize u seznamů	výchozí 50, maximum 200	chyba 400
Velikost přílohy	5 MB	chyba 413
Velikost skenu došlého dokladu	4 MB	chyba 400
Počet upomínek na faktuře	4	chyba 400

Limity příloh a skenů se liší a chovají se jinak — příloha nad limit vrací 413, sken nad limit vrací 400 s tělem tvaru {"file": "…"}. Není to překlep, jsou to dvě různé cesty v aplikaci.

Detaily k upomínkám jsou v sekci Upomínky, k parametrům seznamů v Stránkování, řazení a filtry.

Jak dotazy šetřit

Kvóta se nejrychleji vyčerpá na dotazech, které nic nepřinesou. Čtyři opatření, která obvykle stačí:

• Číselníky cachujte. Načtěte je jednou při startu aplikace, ne před každým dokladem — které se dají zapsat rovnou do kódu a které se musí číst z API, rozebírají Číselníky.
• Listujte po dvou stech. Průchod 10 000 fakturami po padesáti stojí 200 dotazů, po dvou stech 50. page a pageSize ale musí dorazit spolu, jinak se úspora nekoná — viz Stránkování.
• Nestahujte detail, když stačí seznam. Seznamy vrací podmnožinu polí detailu; když integrace potřebuje jen číslo dokladu, částku a stav úhrady, je dotaz na GET /invoice_issued/{id} zbytečný. Která pole navíc detail přidává, je u každého zdroje v referenci.
• Stahujte jen změněné záznamy. S ?sort=-modified jde přestat listovat, jakmile narazíte na záznam starší než vaše poslední synchronizace. Které zdroje to umí, vyjmenovává Podle čeho jde řadit.

Kam dál

• Chyby a jak je číst — tvary chybových odpovědí a stavové kódy
• Stránkování, řazení a filtry — parametry page, pageSize a sort
• Řešení potíží — kontrolní seznamy k častým chybám