Přihlášení, klíče a oprávnění

Osobní API klíč

Klíč pošlete v hlavičce X-API-Key, nebo jako Bearer token v hlavičce Authorization. Obě varianty fungují stejně.

curl -H "X-API-Key: $SALDO_API_KEY" https://techtools.cz/ucetnictvi-api/entities
curl -H "Authorization: Bearer $SALDO_API_KEY" https://techtools.cz/ucetnictvi-api/entities

• Klíč začíná saldo_ a pokračuje 40 znaky (písmena, číslice, - a _). Saldo ukládá jen jeho otisk SHA-256, celý klíč uvidíte jen jednou při vytvoření.
• Klíč jedná jménem uživatele, který ho vytvořil, se stejnou rolí ve všech firmách, kde je přijatým členem. Firmu vybírá entity_id v cestě.
• Klíč Jen čtení smí jen GET a HEAD. Jiná metoda vrátí 403 s kódem READ_ONLY_KEY, ještě před kontrolou role. Stejně odmítne i stažení XML hlášení JMHZ, protože zakládá podání.
• Jeden uživatel může mít nejvýš 20 aktivních klíčů. Zrušený klíč přestane fungovat okamžitě a vrací 401 s kódem INVALID_API_KEY.
• Jeden klíč smí poslat nejvýš 600 požadavků za minutu do každé skupiny cest zvlášť (například /documents… a /bank_transactions… mají každá vlastní limit). Víc vrátí 429 s kódem RATE_LIMITED.
• Klíče se vytvářejí a ruší jen v přihlášeném prohlížeči (Nastavení → API a integrace). Operace nad klíči volané API klíčem vrátí 403, klíč s právem zápisu s textem „API klíče se spravují jen po přihlášení v prohlížeči“.

Přihlášení v prohlížeči

Aplikace Saldo volá stejné API s přihlášením účtem TechTools. Relaci nese cookie _techtools4_session (SameSite=Lax), takže požadavky fetch z cizích webů ji nenesou. Ze stránky na techtools.cz ji posílejte s credentials: 'include'.

• Čtení (GET) stačí se session cookie.
• Každý zápis se session cookie musí mít hlavičku X-Saldo: 1, jinak skončí 403 s kódem CROSS_SITE.
• Zápis z jiného webu Saldo odmítne vždy, i s API klíčem. Pokud požadavek nese hlavičku Origin, musí se shodovat s adresou Salda, a pokud nese Sec-Fetch-Site, musí mít hodnotu same-origin. Hlavičku Sec-Fetch-Site kontrolují i dvě stahování přes GET, balíček pro účetní a XML hlášení JMHZ.
• Požadavek bez cookie, například z curl s API klíčem, hlavičku X-Saldo nepotřebuje.

const response = await fetch('/ucetnictvi-api/entities/1/documents/42/issue', {
  method: 'POST',
  credentials: 'include',
  headers: { 'X-Saldo': '1' }
});

Přístup k firmám

Operace jedné firmy mají v cestě /entities/{entity_id}. Saldo hledá firmu jen mezi těmi, kde jste přijatým členem. Cizí firma nebo firma, do které máte jen nepřijatou pozvánku, vrátí 404 „Záznam nebyl nalezen“, ne 403. API tak neprozrazuje, jestli firma s daným ID existuje.

Operace bez firmy v cestě (například seznam firem, pozvánky nebo fronta úkolů) pracují s vaším účtem napříč firmami. Veřejné operace přihlášení nepotřebují vůbec.

Role a co smějí

Roli přidělí vlastník nebo účetní při přizvání a může ji později změnit (Nastavení → Uživatelé). V odpovědích najdete roli v poli role a její důsledky v příznacích can_write a can_manage.

Nedostatečná role vrátí 403, většinou s textem „Máte přístup jen pro čtení“ nebo „Tuto akci smí provést jen vlastník nebo účetní“. Některé operace mají vlastní pravidlo, třeba schválení výdaje nebo odebrání člena. Reference je uvádí u operace v řádku Pravidlo.