# Fintoro Public API

Public API pre integrácie tretích strán napojené na konkrétnu firmu vo Fintoro.

## Čo tu nájdete

- OpenAPI referenciu pre `clients`, `bank-accounts`, `invoices`, `subjects` a vybrané lookup endpointy vrátane bánk
- statické referenčné tabuľky pre fixné číselníky
- bearer auth model pre company tokeny
- request/response kontrakt pre public API v1


## Základ

- Base path: `/api/public/v1`
- Auth: `Authorization: Bearer <company-token>`
- Scope model: `read` alebo `write`


## Odporúčaný integračný flow

Pre väčšinu integrácií odporúčame tento postup:

1. vytvorte alebo nájdite company token s vhodným scope,
2. načítajte si potrebné lookupy a referenčné tabuľky,
3. nájdite existujúceho klienta alebo vytvorte doklad cez `clientId` alebo inline `client` payload,
4. pri create operáciách používajte `Idempotency-Key`,
5. pri debugovaní si ukladajte `X-Request-Id` z response headera.


## Ako čítať túto dokumentáciu

- Zoznamové endpointy vracajú objekt s `data` a prípadne ďalšími metadátami, napríklad `paginator`.
- Detailné a create/update endpointy vracajú business objekt priamo bez wrappera.
- Fixné číselníky sú dostupné dvojako: ako read-only endpointy a ako referenčné tabuľky na rýchle overenie stabilných ID hodnôt.
- Ak je pole popísané ako predvolená hodnota, znamená to odporúčaný zdroj pre hydratáciu payloadu, nie automatické pravidlo, ktoré systém vynúti mimo konkrétneho flowu.


## Rýchle poznámky k faktúram

- Odporúčaný happy path pre `POST /invoices` je poslať `clientId` a `items`.
- Ak klient ešte vo Fintoro neexistuje, môžete poslať inline `client` objekt a backend klienta dopáruje alebo vytvorí.
- Väčšina dokladových polí je voliteľná a dopočíta sa z klienta, firemných nastavení alebo systémových resolverov.
- Položky na faktúre môžu byť manuálne, z cenníkovej položky alebo z cenníkovej položky so sparse override.


## Otvorte referenciu

[API referencia](/openapi)

## Fixné číselníky

Endpointy pre číselníky len na čítanie nájdete priamo v API referencii. Lookupy vracajú celý dataset bez filtrovania a stránkovania a ich ID môžete v rámci tejto verzie API považovať za stabilné. Ak si ich potrebujete rýchlo overiť očami, použite aj samostatné referenčné tabuľky.

Banky nie sú súčasťou statickej referenčnej tabuľky, lebo sa priebežne synchronizujú z open banking zdroja. Existujúce ID sa však zachovávajú kvôli kompatibilite, takže nejde o volatilný lookup v zmysle prepisovania identifikátorov. V praxi odporúčame banky synchronizovať približne raz týždenne.

[Referenčné tabuľky](/reference-tables)