Přihlášení a API klíče

Veřejné API na https://api.damedoklad.cz/v1 se ověřuje API klíčem nebo přístupovým tokenem OAuth. MCP server na https://api.damedoklad.cz/mcp přijímá obojí, o OAuth píšeme v části MCP server.

API klíč

Klíč pošlete v hlavičce Authorization:

curl https://api.damedoklad.cz/v1/series \
  -H "Authorization: Bearer secret_…"

• Klíč začíná secret_ a patří jedné firmě. Na /v1 neposíláte hlavičku X-Tenant: firma vyplývá z klíče.
• Celý klíč uvidíte jen jednou, při založení. Ukládáme jen jeho otisk SHA-256, takže ho už nejde znovu zobrazit.
• Zacházejte s ním jako s heslem: nepatří do kódu v prohlížeči ani do repozitáře.

Rozsahy

Klíč má jeden ze dvou rozsahů a k tomu může mít zvláštní oprávnění odesílat:

Každému napojení dejte nejužší rozsah, se kterým si vystačí. Připojení přes OAuth má stejné rozsahy, vyberete je při schválení; zápis pak omezuje i vaše vlastní role ve firmě. Klíč i připojení člověka s vlastní rolí smí jen to, co jeho role, a to i klíč read.

Odesílání přes API a MCP

Klíč s plným přístupem příkaz k úhradě a podání připraví, ale neodešle. Dostane 403 s kódem send_scope_required. Odeslat smí jen když platí všechno z tohoto seznamu:

• Vlastník firmy to zapnul v Nastavení > Další > API a MCP a nastavil limity. Ve výchozím stavu je to vypnuté.
• Klíč nebo připojení má oprávnění odesílat. Klíč s ním založí jen vlastník přímo v aplikaci. Připojení přes OAuth o send musí samo požádat a na stránce souhlasu to uvidíte.
• Člověk, kterému klíč patří, je ve firmě dnes vlastník.
• Částka se vejde do limitu na jeden příkaz i do denního limitu, podání do denního počtu.

Požadavek musí uvést otisk přesných dat, který vrátila příprava. Provozovatel musí mít odesílání povolené stejně jako v aplikaci a banka dál chce svůj vlastní podpis. Každé odeslání se zapíše do auditu s názvem klíče a vlastník dostane upozornění a e-mail.

Limity jsou v korunách, takže příkaz v jiné měně přes API neodejde. Klíč může odesílání jen vypnout nebo limit snížit, zapnout ho a limit zvýšit lze jen v aplikaci.

Založení klíče

Klíč založíte v aplikaci v Nastavení > API a MCP nebo přes API. Může to vlastník nebo účetní a tarif firmy musí zahrnovat API; jinak dostanete 402 s kódem plan_limit.

curl https://api.damedoklad.cz/v1/api-keys \
  -H "Authorization: Bearer $DAMEDOKLAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Napojení e-shopu", "scope": "read" }'

{
  "object": "api_key",
  "id": "key_…",
  "name": "Napojení e-shopu",
  "scope": "read",
  "hint": "secret_abcdefg…",
  "secret": "secret_abcdefg…celý klíč"
}

Klíč odvoláte na stejném místě nebo přes DELETE /v1/api-keys/{id}. Všechno, co ho používá, okamžitě přestane fungovat.

API aplikace

Samotná aplikace používá /app/v1 s krátkodobým přístupovým tokenem (15 minut), obnovovacím tokenem v cookie a hlavičkou X-Tenant s ID firmy. Nabízí stejné operace jako /v1, s právy podle role přihlášeného uživatele, a pár dalších jen pro aplikaci. Pro napojení používejte /v1 a API klíč.

Chyby přihlášení

Ostatní chyby najdete na stránce Chyby a limity.