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) a Peppol stavov/prijatých dokladov — `GET /agent/invoices`, `/agent/invoices/{id}`, `/agent/peppol/status`, `/agent/peppol/received`.
`invoice:create`	Vystavenie faktúry — `POST /agent/invoices`.
`invoice:update`	Zmena stavu faktúry (`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.
`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:send
contact:read
contact:create
receipt:read
report:read
org:provision

Na čo si dať pozor

Predvolený kľúč nemá invoice:update ani invoice:download. Ak potrebujete meniť stav faktúry (PATCH …/status), sťahovať PDF/XML alebo spravovať prílohy, vyžiadajte si tieto scopes pri vytváraní kľúča — inak tieto volania vrátia 403 FORBIDDEN.

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.