API kľúče a scopes

Každý partnerský kľúč nesie množinu scopes (oprávnení) podľa princípu least‑privilege. Agent endpoint vyžaduje konkrétny scope: ak ho kľúč nemá, volanie vráti 403 FORBIDDEN. Scopes vyberáte pri vytváraní kľúča v partnerskom portáli.

Katalóg scopes

Toto je úplný zoznam scopes, ktoré vie partner priradiť kľúču (v poradí zdroj → akcia). Endpoint odmietne volanie, ak kľúču chýba uvedený scope.

Scope	Čo umožňuje
`invoice:read`	Čítanie faktúr (zoznam, detail), Peppol stavov/prijatých dokladov a vozidiel:`GET /agent/invoices`, `/agent/invoices/{id}`, `/agent/peppol/status`, `/agent/peppol/received` a celá skupina `/agent/vehicles/*` (zoznam, detail, by‑plate).
`invoice:create`	Vystavenie faktúry: `POST /agent/invoices`.
`invoice:update`	Úprava obsahu faktúry (`PATCH /agent/invoices/{id}`: položky, dátumy, poznámky; camelCase payload), zmena stavu (`PATCH /agent/invoices/{id}/status`) a správa príloh: pridanie/odstránenie (`POST`/`DELETE` `/agent/invoices/{id}/attachments`).
`invoice:send`	Odoslanie cez Peppol (`POST /agent/peppol/send`, `/send/batch`), Peppol `enroll`, upomienka, a `POST /agent/organizations/{id}/peppol-claim` (re‑send FS potvrdenia).
`invoice:download`	Stiahnutie PDF a XML faktúry: `GET /agent/invoices/{id}/pdf`, `/agent/invoices/{id}/xml`.
`contact:read`	Čítanie odberateľov (zoznam, detail): `GET /agent/customers`.
`contact:create`	Vytvorenie odberateľa: `POST /agent/customers`.
`receipt:read`	Čítanie prijatých dokladov / dodávateľov (zoznam, detail, štatistiky, QR): `GET /agent/expenses`, `/agent/vendors`.
`receipt:create`	Nahranie prijatého dokladu a vytvorenie dodávateľa: `POST /agent/expenses/upload`, `/agent/vendors`.
`receipt:update`	Úprava / reklasifikácia prijatého dokladu vrátane hromadných operácií (`bulk`).
`receipt:approve`	Schválenie prijatého dokladu.
`contract:read`	Čítanie zmlúv: `GET /agent/contracts`, detail, harmonogram platieb, naviazané faktúry, štatistiky a sťahovanie príloh.
`contract:create`	Vytvorenie zmluvy (`POST /agent/contracts`) a AI extrakcia z PDF (`POST /agent/contracts/extract`).
`contract:update`	Úprava zmluvy a jej platieb (`PATCH /agent/contracts/{id}`, `PATCH /agent/contracts/payments/{paymentId}`), generovanie harmonogramu a nahrávanie/mazanie príloh.
`contract:delete`	Zmazanie zmluvy: `DELETE /agent/contracts/{id}`.
`report:read`	Čítanie reportov / dashboard súhrnu: `GET /agent/dashboard/summary`.
`org:provision`	Založenie klientskej organizácie (`POST /agent/organizations`) a odoslanie FS aktivačného tokenu (`POST /agent/organizations/{id}/activation-token`).

Predvolená množina scopes

Čerstvo vytvorený partnerský kľúč (cez admin „registráciu partnera" aj cez self‑service v portáli) dostane read + create naprieč agent plochou. Predvolene to sú:

invoice:read
invoice:create
invoice:update
invoice:send
invoice:download
contact:read
contact:create
receipt:read
report:read
contract:read
contract:create
contract:update
org:provision

Na čo si dať pozor

Predvolený kľúč nemá contract:delete. Ak potrebujete mazať zmluvy, vyžiadajte si tento scope pri vytváraní kľúča. Inak volanie vráti 403 FORBIDDEN. Kľúče vytvorené pred zavedením zmlúv (august 2026) contract scopes nemajú. Vytvorte nový kľúč.

POST /agent/organizations/{id}/peppol-claim vyžaduje invoice:send, nie org:provision. Iba (re)posiela firme potvrdzovací e‑mail pre org, ktorú kľúč už vlastní; nezakladá organizáciu. Detaily v Onboarding na produkciu.

Scope 403 ošetrite ako konfiguračnú chybu: kľúč pregenerujte so správnou množinou scopes, neopakujte volanie v slučke. Viac v Chybové kódy.