# 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.