# Vytvoriť faktúru

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.

Endpoint: POST /invoices
Version: 1.0.0
Security: bearerAuth

## Header parameters:

  - `Idempotency-Key` (string)
    Voliteľný identifikátor requestu pre bezpečné retry. Použite unikátnu hodnotu pre každé create volanie, ktoré chcete vedieť bezpečne zopakovať.
    Example: "invoice-create-2026-03-03-001"

## Request fields (application/json):

  - `number` (string,null)
    Manuálne číslo faktúry. Ak ho nepošlete, backend ho vygeneruje z číselného radu. Ak ho pošlete bez numericalSeriesId, faktúra môže zostať mimo číselného radu.
    Example: "20260001"

  - `proformaId` (integer,null)
    Voliteľné ID zálohovej faktúry, z ktorej sa faktúra vytvára.
    Example: 401

  - `orderId` (integer,null)
    Voliteľné ID objednávky, z ktorej sa faktúra vytvára.
    Example: 501

  - `quotationId` (integer,null)
    Voliteľné ID cenovej ponuky, z ktorej sa faktúra vytvára.
    Example: 601

  - `clientId` (integer,null)
    ID existujúceho klienta. Toto je odporúčaný spôsob tvorby faktúry. Ak zároveň pošlete objekt client, použije sa ako sparse override snapshotu klienta pre tento konkrétny doklad.
    Example: 101

  - `client` (object)
    Sparse klientský payload. Ak pošlete clientId, slúži ako override snapshotu pre tento doklad. Ak clientId nepošlete, backend podľa týchto údajov klienta dopáruje alebo vytvorí.

  - `client.name` (string)
    Názov firmy alebo meno osoby. Ak clientId neposielate, toto pole je povinné.
    Example: "Acme s.r.o."

  - `client.type` (string)
    Typ klienta. Povolené hodnoty sú person a company. Ak ho nepošlete, backend ho dopočíta z identifikačných údajov.
    Enum: "person", "company"

  - `client.subjectId` (string,null)
    IČO klienta alebo firmy. Pri slovenských firmách sa používa aj na párovanie existujúceho klienta.
    Example: "12345678"

  - `client.taxId` (string,null)
    DIČ klienta alebo firmy.
    Example: "2020123456"

  - `client.vatId` (string,null)
    IČ DPH klienta alebo firmy. Pri firmách ide o primárny matching údaj, ak je k dispozícii.
    Example: "SK2020123456"

  - `client.isVatPayer` (boolean)
    Voliteľná informácia, či je klient platca DPH. Ak ju nepošlete a vyplníte vatId, backend ju dopočíta automaticky.
    Example: true

  - `client.email` (string,null)
    Kontaktný e-mail klienta. Môže sa použiť aj na dopárovanie existujúceho klienta.
    Example: "billing@acme.test"

  - `client.street` (string,null)
    Fakturačná ulica klienta. Pri sparse override mení len snapshot na tomto doklade.
    Example: "Hlavná 1"

  - `client.city` (string,null)
    Fakturačné mesto klienta.
    Example: "Bratislava"

  - `client.zip` (string,null)
    Fakturačné PSČ klienta.
    Example: "81101"

  - `client.countryId` (integer,null)
    ID krajiny z [referenčnej tabuľky krajín](./reference-tables.md#krajiny). Pri firmách sa spolu so subjectId používa aj na dopárovanie existujúceho klienta.
    Example: 703

  - `client.hasDeliveryAddress` (boolean)
    Voliteľný príznak dodacej adresy. Ak ho nepošlete, backend ho vie odvodiť z dodacích polí.
    Example: true

  - `client.deliveryStreet` (string,null)
    Dodacia ulica klienta pre snapshot na tomto doklade.
    Example: "Skladová 5"

  - `client.deliveryCity` (string,null)
    Dodacie mesto klienta pre snapshot na tomto doklade.
    Example: "Trnava"

  - `client.deliveryZip` (string,null)
    Dodacie PSČ klienta pre snapshot na tomto doklade.
    Example: "91701"

  - `client.deliveryCountryId` (integer,null)
    ID krajiny dodacej adresy z [referenčnej tabuľky krajín](./reference-tables.md#krajiny).
    Example: 703

  - `numericalSeriesId` (integer,null)
    ID číselného radu. Ak ho nepošlete a nepošlete ani number, použije sa primárny číselný rad pre faktúry. Ak pošlete manuálne number bez tohto poľa, numericalSeriesId zostane null.
    Example: 12

  - `bankAccountId` (integer,null)
    ID bankového účtu, ktorý sa má použiť na faktúre. Ak ho nepošlete, použije sa primárny bankový účet firmy. Ak firma nemá nastavený žiadny primárny bankový účet, endpoint vráti 422 validation error s chybou pri bankAccountId.
    Example: 201

  - `issueDate` (string,null)
    Dátum vystavenia. Ak ho nepošlete, použije sa dnešný dátum.
    Example: "2026-03-03"

  - `dueDateDays` (integer,null)
    Počet dní splatnosti. Priorita je payload → klientská predvolená hodnota → document settings firmy.
    Example: 14

  - `deliveryDate` (string,null)
    Dátum dodania. Ak ho nepošlete, použije sa issueDate.
    Example: "2026-03-03"

  - `variableSymbol` (integer,null)
    Variabilný symbol. Ak ho nepošlete, backend ho odvodí z finálneho čísla faktúry.
    Example: 20260001

  - `constantSymbol` (integer,null)
    Konštantný symbol. Priorita je payload → klientská predvolená hodnota → null.
    Example: 308

  - `specificSymbol` (integer,null)
    Špecifický symbol. Priorita je payload → klientská predvolená hodnota → null.
    Example: 55

  - `discountType` (string,null)
    Typ zľavy na úrovni celého dokladu.
    Example: "percentage"

  - `discountValue` (number,null)
    Hodnota zľavy na úrovni celého dokladu.
    Example: 10

  - `transferTaxLiability` (boolean)
    Príznak prenesenej daňovej povinnosti. Ak ho nepošlete, použije sa false.

  - `deliveryMethodId` (integer,null)
    ID spôsobu dodania z [referenčnej tabuľky spôsobov dodania](./reference-tables.md#sposoby-dodania). Priorita je payload → klientská predvolená hodnota → document settings firmy.
    Example: 1

  - `paymentMethodId` (integer,null)
    ID spôsobu úhrady z [referenčnej tabuľky spôsobov úhrady](./reference-tables.md#sposoby-uhrady). Priorita je payload → klientská predvolená hodnota → document settings firmy.
    Example: 1

  - `currencyId` (integer,null)
    ID meny z [referenčnej tabuľky mien](./reference-tables.md#meny). Priorita je payload → klientská predvolená hodnota → document settings firmy.
    Example: 1

  - `currencyRate` (number,null)
    Kurz meny k EUR. Ak ho nepošlete, backend ho vyrieši server-side podľa currencyId a deliveryDate.
    Example: 1

  - `languageId` (integer,null)
    ID jazyka z [referenčnej tabuľky jazykov](./reference-tables.md#jazyky). Priorita je payload → klientská predvolená hodnota → document settings firmy.
    Example: 1

  - `qrTypeId` (integer,null)
    ID QR typu z [referenčnej tabuľky QR typov](./reference-tables.md#qr-typy). Ak ho nepošlete, použije sa document settings firmy.
    Example: 1

  - `note` (string,null)
    Poznámka na doklade. Priorita je payload → klientská predvolená hodnota → document settings firmy.
    Example: "Ďakujeme za objednávku."

  - `textAboveItems` (string,null)
    Text nad položkami. Priorita je payload → klientská predvolená hodnota → document settings firmy.
    Example: "Dakujeme za spoluprácu."

  - `items` (array, required)
    Položky faktúry. Toto pole je povinné aj vtedy, keď väčšinu ostatných hodnôt necháte dopočítať backendom.

  - `items.name` (string)
    Názov položky. Pri manuálnej položke je povinný. Pri použití priceListItemId môže slúžiť ako override názvu z cenníka.
    Example: "Konzultácia"

  - `items.description` (string,null)
    Voliteľný popis položky. Pri priceListItemId môže prepísať alebo doplniť popis z cenníkovej položky.
    Example: "Mesačný balík konzultácií"

  - `items.unitPrice` (number)
    Jednotková cena bez DPH. Pri manuálnej položke je povinná. Pri priceListItemId môže prepísať cenu načítanú z cenníka.
    Example: 100

  - `items.unitId` (integer)
    ID jednotky z [referenčnej tabuľky jednotiek](./reference-tables.md#jednotky). Pri manuálnej položke je povinné. Pri priceListItemId môže prepísať jednotku z cenníkovej položky.
    Example: 1

  - `items.quantity` (number, required)
    Množstvo položky. Toto pole je povinné vždy, bez ohľadu na to, či ide o manuálnu položku alebo o položku z cenníka.
    Example: 2

  - `items.vatRate` (number)
    Sadzba DPH v percentách. Pri manuálnej položke je povinná. Pri priceListItemId môže prepísať sadzbu z cenníkovej položky.
    Example: 20

  - `items.discountType` (string,null)
    Typ zľavy na úrovni položky. Povolené hodnoty sú percentage a fixed.
    Example: "percentage"

  - `items.discountValue` (number,null)
    Hodnota zľavy na úrovni položky. Ak pošlete discountType, musíte poslať aj toto pole.
    Example: 10

  - `items.discountName` (string,null)
    Názov zľavy na úrovni položky. Ak ho pri discountType a discountValue nepošlete, backend doplní lokalizované Zľava podľa jazyka dokladu.
    Example: "Vernostná zľava"

  - `items.uuid` (string,null)
    Voliteľný UUID identifikátor položky používaný pri interných sync scenároch. Pri bežnom public create ho neposielate.
    Example: "6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19"

  - `items.priceListItemId` (integer,null)
    ID cenníkovej položky. Ak ho pošlete, backend vie z tejto položky hydratovať názov, jednotku, cenu a sadzbu DPH a payload môže slúžiť len ako sparse override.
    Example: 501

  - `items.warehouseAllocations` (array)
    Voliteľné rozpisy množstiev po skladoch. Používajte ich len pri položkách, ktoré majú väzbu na skladové karty a potrebujete explicitne určiť pohyby po skladoch.

  - `items.warehouseAllocations.warehouseId` (integer)
    Example: 1

  - `items.warehouseAllocations.quantity` (number)
    Example: 2

## Response 201 fields (application/json):

  - `id` (integer)
    Example: 301

  - `uuid` (string)
    Example: "6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19"

  - `type` (string)
    Example: "invoice"

  - `number` (string)
    Example: "20260001"

  - `company` (object)
    Snapshot dodávateľa uložený priamo na tomto doklade.

  - `company.name` (string)
    Obchodné meno dodávateľa uložené na faktúre.
    Example: "Fintoro s.r.o."

  - `company.subjectId` (string)
    IČO dodávateľa uložené na faktúre.
    Example: "12345678"

  - `company.legalForm` (string)
    Právna forma dodávateľa uložená na faktúre.
    Example: "Spoločnosť s ručením obmedzeným"

  - `company.taxId` (string,null)
    DIČ dodávateľa uložené na faktúre, ak bolo k dispozícii.
    Example: "2020123456"

  - `company.vatId` (string,null)
    IČ DPH dodávateľa uložené na faktúre, ak bolo k dispozícii.
    Example: "SK2020123456"

  - `company.vatPayerTypeId` (integer)
    Typ platcu DPH dodávateľa uložený na faktúre.
    Example: 4

  - `company.country` (string)
    Krajina dodávateľa uložená na faktúre ako textová hodnota.
    Example: "Slovensko"

  - `company.city` (string)
    Mesto dodávateľa uložené na faktúre.
    Example: "Bratislava"

  - `company.street` (string)
    Ulica a číslo dodávateľa uložené na faktúre.
    Example: "Hlavná 1"

  - `company.zip` (string,null)
    PSČ dodávateľa uložené na faktúre.
    Example: "81101"

  - `company.logo` (string,null)
    URL alebo cesta k logu uloženému v snapshot-e, ak bolo k dispozícii.
    Example: "https://app.fintoro.sk/storage/company/logo.svg"

  - `company.signature` (string,null)
    URL alebo cesta k podpisu uloženému v snapshot-e, ak bol k dispozícii.
    Example: "https://app.fintoro.sk/storage/company/signature.png"

  - `company.registrationCourt` (string,null)
    Registrový súd dodávateľa uložený na faktúre, ak bol k dispozícii.
    Example: "Mestský súd Bratislava III"

  - `company.registrationNumber` (string,null)
    Registračné číslo dodávateľa uložené na faktúre, ak bolo k dispozícii.
    Example: "12345/B"

  - `company.email` (string,null)
    Kontaktný e-mail dodávateľa uložený na faktúre.
    Example: "support@fintoro.sk"

  - `company.phone` (string,null)
    Kontaktný telefón dodávateľa uložený na faktúre.
    Example: "+421900000000"

  - `company.web` (string,null)
    Web dodávateľa uložený na faktúre.
    Example: "https://fintoro.sk"

  - `client` (object)
    Historický snapshot klienta uložený priamo na tomto doklade.

  - `client.id` (integer)
    Interné ID snapshotu klienta uloženého na doklade.
    Example: 101

  - `client.name` (string)
    Meno osoby alebo obchodné meno klienta uložené na faktúre v danom čase.
    Example: "Acme s.r.o."

  - `client.type` (string)
    Typ klienta uložený na faktúre.
    Example: "company"

  - `client.subjectId` (string,null)
    IČO klienta alebo firmy. Pre slovenské subjekty túto hodnotu viete typicky dohľadať aj cez [referenčný register subjektov](#operation/searchSubjects).
    Example: "12345678"

  - `client.taxId` (string,null)
    DIČ klienta uložené na faktúre, ak bolo k dispozícii.
    Example: "2020123456"

  - `client.vatId` (string,null)
    IČ DPH klienta uložené na faktúre, ak bolo k dispozícii.
    Example: "SK2020123456"

  - `client.isVatPayer` (boolean)
    Informácia, či bol klient v čase uloženia snapshotu vedený ako platca DPH.
    Example: true

  - `client.email` (string,null)
    Kontaktný e-mail klienta uložený na faktúre.
    Example: "billing@acme.test"

  - `client.street` (string,null)
    Ulica a číslo fakturačnej adresy uložené na faktúre.
    Example: "Hlavná 1"

  - `client.city` (string,null)
    Mesto fakturačnej adresy uložené na faktúre.
    Example: "Bratislava"

  - `client.zip` (string,null)
    PSČ fakturačnej adresy uložené na faktúre.
    Example: "81101"

  - `client.countryId` (integer,null)
    ID krajiny z [referenčnej tabuľky krajín](./reference-tables.md#krajiny).
    Example: 703

  - `client.country` (any)
    Fakturačná krajina uložená na faktúre ako vnorený objekt.

  - `client.hasDeliveryAddress` (boolean)
    Informácia, či snapshot obsahuje samostatnú dodaciu adresu.
    Example: true

  - `client.deliveryStreet` (string,null)
    Ulica a číslo dodacej adresy uložené na faktúre.
    Example: "Skladová 9"

  - `client.deliveryCity` (string,null)
    Mesto dodacej adresy uložené na faktúre.
    Example: "Košice"

  - `client.deliveryZip` (string,null)
    PSČ dodacej adresy uložené na faktúre.
    Example: "04001"

  - `client.deliveryCountryId` (integer,null)
    ID krajiny z [referenčnej tabuľky krajín](./reference-tables.md#krajiny).
    Example: 703

  - `client.deliveryCountry` (any)
    Dodacia krajina uložená na faktúre ako vnorený objekt.

  - `bankAccount` (object)
    Bankový účet naviazaný na faktúru ako live väzba načítaná aj cez soft delete.

  - `bankAccount.id` (integer)
    Interné ID bankového účtu vo Fintoro.
    Example: 201

  - `bankAccount.bankId` (integer,null)
    ID banky z [lookup endpointu bánk](#operation/listBanks), ak je účet naviazaný na známu banku.
    Example: 1

  - `bankAccount.bank` (any)
    Vnorený objekt banky priradenej k účtu, ak je známa.

  - `bankAccount.name` (string)
    Názov bankového účtu v aktuálnom stave databázy.
    Example: "Hlavný účet"

  - `bankAccount.iban` (string)
    IBAN naviazaného bankového účtu.
    Example: "SK3111000000001234567890"

  - `bankAccount.swift` (string)
    SWIFT alebo BIC kód naviazaného bankového účtu.
    Example: "TATRSKBX"

  - `bankAccount.isPrimary` (boolean)
    Informácia, či je účet aktuálne vedený ako primárny účet firmy.
    Example: true

  - `bankAccount.autoPaymentMatching` (boolean)
    Informácia, či je účet aktuálne napojený na automatické párovanie platieb cez open banking.
    Example: true

  - `variableSymbol` (integer)
    Example: 20260001

  - `constantSymbol` (integer,null)
    Example: 308

  - `specificSymbol` (integer,null)
    Example: 55

  - `issueDate` (string)
    Example: "2026-03-03"

  - `dueDate` (string)
    Example: "2026-03-17"

  - `deliveryDate` (string)
    Example: "2026-03-03"

  - `discountType` (string,null)
    Example: "percentage"

  - `discountValue` (number,null)
    Example: 10

  - `transferTaxLiability` (boolean)

  - `numericalSeriesId` (integer,null)
    Example: 12

  - `deliveryMethodId` (integer)
    ID spôsobu dodania z [referenčnej tabuľky spôsobov dodania](./reference-tables.md#sposoby-dodania).
    Example: 1

  - `paymentMethodId` (integer)
    ID spôsobu úhrady z [referenčnej tabuľky spôsobov úhrady](./reference-tables.md#sposoby-uhrady).
    Example: 1

  - `currencyId` (integer)
    ID meny z [referenčnej tabuľky mien](./reference-tables.md#meny).
    Example: 1

  - `currencyRate` (number)
    Example: 1

  - `languageId` (integer)
    ID jazyka z [referenčnej tabuľky jazykov](./reference-tables.md#jazyky).
    Example: 1

  - `qrTypeId` (integer)
    ID QR typu z [referenčnej tabuľky QR typov](./reference-tables.md#qr-typy).
    Example: 1

  - `note` (string,null)
    Example: "Ďakujeme za objednávku."

  - `textAboveItems` (string,null)
    Example: "Dakujeme za spoluprácu."

  - `itemsTotal` (number)
    Example: 200

  - `itemsTotalWithVat` (number)
    Example: 240

  - `total` (number)
    Example: 200

  - `totalWithVat` (number)
    Example: 240

  - `toBePaid` (number)
    Example: 240

  - `status` (string)
    Example: "unpaid"

  - `hasVat` (boolean)
    Example: true

  - `creditNotesSumTotalWithVat` (number)

  - `items` (array)

  - `items.name` (string)
    Example: "Konzultácia"

  - `items.description` (string,null)
    Example: "Mesačný balík konzultácií"

  - `items.unitPrice` (number)
    Example: 100

  - `items.unitId` (integer)
    ID jednotky z [referenčnej tabuľky jednotiek](./reference-tables.md#jednotky).
    Example: 1

  - `items.quantity` (number)
    Example: 2

  - `items.vatRate` (number)
    Example: 20

  - `items.discountName` (string,null)
    Example: "Vernostná zľava"

  - `items.priceListItemId` (integer,null)
    Example: 501

## Response 404 fields (application/json):

  - `message` (string)
    Example: "No query results for model."

## Response 422 fields (application/json):

  - `message` (string)
    Example: "The given data was invalid."

  - `error` (string,null)
    Example: "Idempotency-Key reused with different request payload"

  - `errors` (object,null)

## Response 500 fields (application/json):

  - `message` (string)
    Example: "Server Error"

## Response 503 fields (application/json):

  - `message` (string)
    Example: "Service Unavailable"