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
contact:read
contact:create
receipt:read
report:read
contract:read
contract:create
contract:update
org:provision

Na čo si dať pozor

Predvolený kľúč nemá invoice:download ani contract:delete. Ak potrebujete sťahovať PDF/XML faktúr alebo mazať zmluvy, vyžiadajte si tieto scopes pri vytváraní kľúča. Inak tieto volania vrátia 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.