# Fintoro Public API v1

Stabilné API pre integrácie tretích strán napojené na konkrétnu firmu vo Fintoro. Nájdete tu aj read-only lookup endpointy pre číselníky a banky, plus referenčné tabuľky pre rýchle overenie stabilných ID hodnôt.

Version: 1.0.0

## Servers

Produkčné Public API.
```
https://app.fintoro.sk/api/public/v1
```

Relatívny prefix pre preview prostredie.
```
/api/public/v1
```

## Security

### bearerAuth

Bearer token vytvorený pre konkrétnu firmu v Integrácie → API.

Type: http
Scheme: bearer
Bearer Format: Token

## Download OpenAPI description

[Fintoro Public API v1](https://docs.fintoro.sk/_bundle/openapi.yaml)

## Lookupy

Read-only lookup endpointy pre integračné dáta. Tieto endpointy vracajú číselníky so stabilnými ID, ktoré môžete bezpečne cachovať na svojej strane. Banky sa priebežne synchronizujú z open banking zdroja a zvyčajne sa len dopĺňajú o nové záznamy; existujúce ID ostávajú zachované kvôli kompatibilite. V praxi odporúčame banky synchronizovať približne raz týždenne.

### Zoznam bánk

 - [GET /banks](https://docs.fintoro.sk/openapi/lookupy/listbanks.md): Vráti aktuálny zoznam bánk, ktoré môžete použiť pri vytváraní alebo aktualizácii bankového účtu. Endpoint nepodporuje filtrovanie ani stránkovanie a vracia celý aktuálny dataset. Zoznam bánk sa priebežne synchronizuje z open banking zdroja, ale existujúce ID ostávajú zachované kvôli kompatibilite s uloženými bankovými účtami. V praxi odporúčame banky synchronizovať približne raz týždenne.

### Zoznam krajín

 - [GET /countries](https://docs.fintoro.sk/openapi/lookupy/listcountries.md): Vráti fixný číselník krajín používaný naprieč public API. Endpoint nepodporuje filtrovanie ani stránkovanie a vracia celý dataset. ID krajín sú stabilné v rámci tejto verzie API a rovnaké hodnoty nájdete aj v referenčnej tabuľke krajín.

### Zoznam jazykov

 - [GET /languages](https://docs.fintoro.sk/openapi/lookupy/listlanguages.md): Vráti fixný číselník jazykov používaný naprieč public API. Endpoint nepodporuje filtrovanie ani stránkovanie a vracia celý dataset. ID jazykov sú stabilné v rámci tejto verzie API a rovnaké hodnoty nájdete aj v referenčnej tabuľke jazykov.

### Zoznam mien

 - [GET /currencies](https://docs.fintoro.sk/openapi/lookupy/listcurrencies.md): Vráti fixný číselník mien používaný naprieč public API. Endpoint nepodporuje filtrovanie ani stránkovanie a vracia celý dataset. ID mien sú stabilné v rámci tejto verzie API a rovnaké hodnoty nájdete aj v referenčnej tabuľke mien.

### Zoznam spôsobov dodania

 - [GET /delivery-methods](https://docs.fintoro.sk/openapi/lookupy/listdeliverymethods.md): Vráti fixný číselník spôsobov dodania používaný naprieč public API. Endpoint nepodporuje filtrovanie ani stránkovanie a vracia celý dataset. ID spôsobov dodania sú stabilné v rámci tejto verzie API a rovnaké hodnoty nájdete aj v referenčnej tabuľke spôsobov dodania.

### Zoznam spôsobov úhrady

 - [GET /payment-methods](https://docs.fintoro.sk/openapi/lookupy/listpaymentmethods.md): Vráti fixný číselník spôsobov úhrady používaný naprieč public API. Endpoint nepodporuje filtrovanie ani stránkovanie a vracia celý dataset. ID spôsobov úhrady sú stabilné v rámci tejto verzie API a rovnaké hodnoty nájdete aj v referenčnej tabuľke spôsobov úhrady.

### Zoznam QR typov

 - [GET /qr-types](https://docs.fintoro.sk/openapi/lookupy/listqrtypes.md): Vráti fixný číselník QR typov používaný naprieč public API. Endpoint nepodporuje filtrovanie ani stránkovanie a vracia celý dataset. ID QR typov sú stabilné v rámci tejto verzie API a rovnaké hodnoty nájdete aj v referenčnej tabuľke QR typov.

### Zoznam jednotiek

 - [GET /units](https://docs.fintoro.sk/openapi/lookupy/listunits.md): Vráti fixný číselník jednotiek používaný naprieč public API. Endpoint nepodporuje filtrovanie ani stránkovanie a vracia celý dataset. ID jednotiek sú stabilné v rámci tejto verzie API a rovnaké hodnoty nájdete aj v referenčnej tabuľke jednotiek.

## Subjekty

Vyhľadanie a overenie údajov o subjekte ešte pred vytvorením klienta.

### Vyhľadávanie subjektov

 - [GET /subjects](https://docs.fintoro.sk/openapi/subjekty/searchsubjects.md): Tento endpoint použite, keď potrebujete dohľadať údaje o firme alebo živnostníkovi podľa názvu či IČO.

### Detail subjektu

 - [GET /subjects/{subject}](https://docs.fintoro.sk/openapi/subjekty/showsubject.md): Vráti jeden konkrétny subjekt z referenčného registra podľa jeho ID.

## Klienti

Správa klientov aktuálnej firmy. Táto sekcia pokrýva zoznam, detail, vytvorenie, úpravu aj zmazanie klienta vrátane fakturačnej adresy, dodacej adresy a klientských predvolených hodnôt použiteľných pri skladaní payloadov nových dokladov.

### Zoznam klientov

 - [GET /clients](https://docs.fintoro.sk/openapi/klienti/listclients.md): Vráti klientov patriacich aktuálnej firme. Endpoint je vhodný na synchronizáciu klientov do externého systému alebo vlastného frontendu a podporuje základné fulltextové vyhľadávanie, filtrovanie a triedenie.

### Vytvoriť klienta

 - [POST /clients](https://docs.fintoro.sk/openapi/klienti/createclient.md): Vytvorí nového klienta pre aktuálnu firmu. V requeste posielate business dáta klienta a voliteľné klientské predvolené hodnoty, ktoré sa ukladajú pri klientovi a pri tvorbe nových dokladov sa používajú ako fallback defaulty, ak explicitnú hodnotu nepošlete v payloade. Ak pošlete Idempotency-Key, rovnaký key s rovnakým payloadom vráti pôvodnú odpoveď bez druhého vytvorenia klienta.

### Detail klienta

 - [GET /clients/{client}](https://docs.fintoro.sk/openapi/klienti/showclient.md): Vráti detail jedného klienta aktuálnej firmy vrátane vnorených krajín a klientských predvolených hodnôt, ktoré môžete použiť pri tvorbe nových dokladov.

### Upraviť klienta

 - [PUT /clients/{client}](https://docs.fintoro.sk/openapi/klienti/updateclient.md): Aktualizuje klienta aktuálnej firmy. Pošlite len polia, ktoré chcete zmeniť. Pri dodacej adrese a inferred poliach platí rovnaké správanie ako pri vytvorení klienta.

### Zmazať klienta

 - [DELETE /clients/{client}](https://docs.fintoro.sk/openapi/klienti/deleteclient.md): Zmaže klienta aktuálnej firmy. Po úspešnom spracovaní endpoint nevracia response body.

## Bankové účty

Správa bankových účtov aktuálnej firmy. Táto sekcia pokrýva zoznam, detail, vytvorenie, úpravu aj zmazanie účtu vrátane údajov o banke, primárnom účte a stave open banking napojenia.

### Zoznam bankových účtov

 - [GET /bank-accounts](https://docs.fintoro.sk/openapi/bankove-ucty/listbankaccounts.md): Vráti všetky bankové účty aktuálnej firmy v jednom zozname. Endpoint nepodporuje filtrovanie ani stránkovanie, preto je vhodný najmä na synchronizáciu účtov do externého systému alebo vlastného frontendu.

### Vytvoriť bankový účet

 - [POST /bank-accounts](https://docs.fintoro.sk/openapi/bankove-ucty/createbankaccount.md): Vytvorí nový bankový účet aktuálnej firmy. V requeste posielate len business dáta účtu. Response vráti výsledný uložený objekt vrátane informácie, či je účet aktuálne vedený ako primárny a či je napojený na open banking.

### Detail bankového účtu

 - [GET /bank-accounts/{bankAccount}](https://docs.fintoro.sk/openapi/bankove-ucty/showbankaccount.md): Vráti detail jedného bankového účtu aktuálnej firmy. Okrem samotných údajov o účte vracia aj vnorený objekt banky, stav primárneho účtu a open banking metadata, ak sú dostupné.

### Upraviť bankový účet

 - [PUT /bank-accounts/{bankAccount}](https://docs.fintoro.sk/openapi/bankove-ucty/updatebankaccount.md): Aktualizuje bankový účet aktuálnej firmy. Pošlite len polia, ktoré chcete zmeniť.
Ak pošlete isPrimary: true, účet sa nastaví ako primárny účet firmy.

### Zmazať bankový účet

 - [DELETE /bank-accounts/{bankAccount}](https://docs.fintoro.sk/openapi/bankove-ucty/deletebankaccount.md): Zmaže bankový účet aktuálnej firmy. Po úspešnom spracovaní endpoint nevracia response body.

## Faktúry

CRUD operácie nad faktúrami aktuálnej firmy.

### Zoznam faktúr

 - [GET /invoices](https://docs.fintoro.sk/openapi/faktury/listinvoices.md): Vráti paginovaný zoznam faktúr aktuálnej firmy v zjednodušenom preview tvare. Tento endpoint je určený na listy, synchronizáciu a rýchly prehľad nad dokladmi. Na detail jedného dokladu použite detail endpoint faktúry.

### Vytvoriť faktúru

 - [POST /invoices](https://docs.fintoro.sk/openapi/faktury/createinvoice.md): Vytvorí novú faktúru aktuálnej firmy.

### Odporúčaný flow

Odporúčaný happy path je poslať clientId a items. To je najjednoduchší spôsob, ak klient už vo Fintoro existuje.

Ak klienta ešte vo Fintoro nemáte alebo nechcete robiť samostatný krok na jeho vytvorenie, pošlite objekt client bez clientId. Backend sa pokúsi klienta dopárovať k existujúcemu záznamu a ak nič nenájde, vytvorí nového klienta.

Ak pošlete clientId aj objekt client, objekt client sa správa ako sparse override snapshotu klienta pre tento konkrétny doklad. Môžete tak upraviť napríklad adresu dodania alebo kontaktné údaje len na tejto faktúre bez zmeny klienta v databáze.

### Ako fungujú defaulty

Väčšina dokladových polí je voliteľná. Backend ich vyhodnocuje v tomto poradí:

1. explicitná hodnota z payloadu,
2. klientské predvolené hodnoty,
3. firemné document settings,
4. systémový resolver.

V praxi to znamená napríklad:

- deliveryMethodId, paymentMethodId, currencyId a languageId sa môžu dopočítať z klienta alebo z firemných nastavení,
- number a numericalSeriesId sa doplnia z primárneho číselného radu, ak ich nepošlete,
- variableSymbol sa bez explicitnej hodnoty odvodí z finálneho čísla dokladu,
- bankAccountId sa bez explicitnej hodnoty vezme z primárneho bankového účtu firmy,
- currencyRate sa dopočíta podľa meny a dátumu dodania,
- issueDate a deliveryDate defaultujú na dnešný deň.

### Ako funguje client resolution

Ak clientId nepošlete, objekt client sa používa na dopárovanie alebo vytvorenie klienta. Matching prebieha deterministicky v tomto poradí:

- pri firmách: vatId, potom countryId + subjectId, potom name + email, potom name + street,
- pri fyzických osobách: name + email, potom name + street.

Ak matching nič nenájde, vytvorí sa nový klient. Ak matching nájde viac klientov, backend použije prvý záznam v stabilnom poradí.

Ak pošlete explicitné clientId alebo bankAccountId a taký záznam neexistuje alebo nepatrí aktuálnej firme, endpoint vráti 404.

Ak bankAccountId nepošlete a firma nemá nastavený žiadny primárny bankový účet, endpoint vráti 422.

### Ako fungujú položky

Položka môže byť vytvorená tromi spôsobmi:

1. ako manuálna položka s vlastným názvom, jednotkou, cenou a DPH,
2. cez priceListItemId a quantity,
3. cez priceListItemId a sparse override vybraných polí, napríklad ceny alebo názvu.

Ak pošlete zľavu bez discountName, backend doplní lokalizovaný názov zľavy podľa jazyka dokladu.

### Príklady requestov

Existujúci klient a manuálna položka:

json
{
  "clientId": 101,
  "issueDate": "2026-03-04",
  "items": [
    {
      "name": "Mesačný paušál",
      "quantity": 1,
      "unitId": 1,
      "unitPrice": 120.0,
      "vatRate": 23
    }
  ]
}


Inline klient bez clientId:

json
{
  "client": {
    "type": "company",
    "name": "Acme s.r.o.",
    "email": "faktury@acme.test",
    "countryId": 703,
    "subjectId": "12345678",
    "street": "Hlavná 1",
    "city": "Bratislava",
    "zip": "81101"
  },
  "items": [
    {
      "name": "Implementácia API",
      "quantity": 10,
      "unitId": 7,
      "unitPrice": 80.0,
      "vatRate": 23
    }
  ]
}


Cenníková položka s minimálnym payloadom:

json
{
  "clientId": 101,
  "items": [
    {
      "priceListItemId": 501,
      "quantity": 2
    }
  ]
}


Ak pošlete Idempotency-Key, rovnaký key s rovnakým payloadom vráti pôvodnú odpoveď bez druhého vytvorenia faktúry.

### Detail faktúry

 - [GET /invoices/{invoice}](https://docs.fintoro.sk/openapi/faktury/showinvoice.md): Vráti detail jednej faktúry aktuálnej firmy. Response obsahuje snapshot dodávateľa, historický snapshot klienta uložený priamo na doklade a naviazaný bankový účet použitý na faktúre. Snapshoty firmy a klienta reprezentujú stav údajov v čase práce s faktúrou kvôli auditovateľnosti a historickej perzistencii, bankový účet je live väzba načítaná aj cez soft delete.

### Upraviť faktúru

 - [PUT /invoices/{invoice}](https://docs.fintoro.sk/openapi/faktury/updateinvoice.md): Aktualizuje existujúcu faktúru aktuálnej firmy.

### Ako funguje update

- items sú povinné vždy.
- Ak pole nepošlete, zachová sa existujúca hodnota na faktúre.
- Ak nepošlete clientId ani objekt client, zachová sa aktuálny klient aj jeho snapshot na doklade.
- Ak pošlete clientId a/alebo objekt client, klient a snapshot sa prepočítajú rovnako ako pri create flowe.

### Chybové stavy

- 404, ak explicitne pošlete clientId alebo bankAccountId, ktoré neexistuje alebo nepatrí firme.
- 422, ak payload neprejde business validáciou, napríklad pri nevalidných položkách faktúry.

### Zmazať faktúru

 - [DELETE /invoices/{invoice}](https://docs.fintoro.sk/openapi/faktury/deleteinvoice.md): Zmaže faktúru aktuálnej firmy.