openapi: 3.1.0
info:
  title: Fintoro API v1
  version: "1.0.0"
  description: |
    Fintoro API v1 je REST API pre integráciu Fintoro fakturácie, CRM a skladového systému do systémov tretích strán.

    Produkčné aj sandboxové firmy používajú rovnakú základnú URL `https://app.fintoro.sk/api/public/v1`. O tom, s ktorou firmou pracujete, rozhoduje bearer token.

    Voliteľný request header `Accept-Language` lokalizuje systémové názvy v lookupoch, v súvisiacich objektoch v odpovediach aj vo validačných chybách. Response header `Content-Language` vracia jazyk použitý v odpovedi.

    Pre onboarding a prevádzkové pravidlá si pozrite aj:
    - [Začíname](/getting-started)
    - [Autentifikácia](/authentication)
    - [Webhooky](/webhooks)
    - [Testovanie v sandboxe](/sandbox-testing)
    - [Konvencie API](/conventions)
    - [Chyby a idempotencia](/errors-and-idempotency)
servers:
  - url: https://app.fintoro.sk/api/public/v1
    description: Produkčné Fintoro API.
security:
  - bearerAuth: []
x-tagGroups:
  - name: Základy integrácie
    tags:
      - Identita tokenu
      - Lookupy
      - Číselné rady
      - Subjekty
      - Klienti
      - Dodávatelia
      - Bankové účty
  - name: Webhooky
    tags:
      - Webhooky
  - name: CRM
    tags:
      - Stavy obchodných prípadov
      - Obchodné prípady
      - CRM udalosti
  - name: Sklady a katalóg
    tags:
      - Sklady
      - Skladové príjemky
      - Skladové výdajky
      - Skladové a cenníkové položky
  - name: Doklady
    tags:
      - Faktúry
      - Dobropisy
      - Zálohové faktúry
      - Objednávky
      - Cenové ponuky
      - Úhrady dokladov
      - Dokladové e-maily
tags:
  - name: Identita tokenu
    description: Technický read-only endpoint na overenie, ku ktorej firme bearer token aktuálne patrí.
  - name: Lookupy
    description: Endpointy len na čítanie pre integračné dáta. Tieto endpointy vracajú číselníky so stabilnými ID, ktoré môžete bezpečne ukladať do cache na svojej strane. Pri doplnení nových lookup hodnôt sa existujúce ID nemenia ani neprepisujú.
  - name: Číselné rady
    description: Endpointy len na čítanie nad číselnými radmi. Vracia sa aktuálna konfigurácia použitá pri tvorbe dokladov vrátane ďalšieho vygenerovaného čísla a variabilného symbolu.
  - name: Subjekty
    description: Vyhľadanie a overenie údajov o subjekte ešte pred vytvorením klienta.
  - name: Klienti
    description: Správa klientov vrátane fakturačnej adresy, dodacej adresy a klientských predvolených hodnôt použiteľných pri tvorbe nových dokladov. Create, update a delete operácie môžu emitovať webhook eventy `clients.created`, `clients.updated` a `clients.deleted`.
  - name: Dodávatelia
    description: Správa dodávateľov vrátane fakturačnej adresy a identifikačných údajov použiteľných aj pri resolve-or-create flowe skladových príjemiek. Create, update a delete operácie môžu emitovať webhook eventy `suppliers.created`, `suppliers.updated` a `suppliers.deleted`.
  - name: Stavy obchodných prípadov
    description: Správa stavov obchodných prípadov. Stavy reprezentujú stĺpce pipeline. Endpoint na zmenu poradia v tejto verzii dostupný nie je; pri zmazaní stavu sa naviazané obchodné prípady odviažu na `null`. Create, update a delete operácie môžu emitovať webhook eventy `business-case-statuses.created`, `business-case-statuses.updated` a `business-case-statuses.deleted`.
  - name: Obchodné prípady
    description: Správa obchodných prípadov vrátane vnoreného klienta alebo dodávateľa a voliteľného stavu. Zmena poradia ani zmena naviazaného kontaktu cez update v tejto verzii dostupné nie sú. Create, update a delete operácie môžu emitovať webhook eventy `business-cases.created`, `business-cases.updated` a `business-cases.deleted`.
  - name: CRM udalosti
    description: Správa CRM udalostí pre typy `note`, `email`, `phone_call` a `document_linked`. Attachmenty používajú dvojkrokový upload cez samostatný endpoint. Create, update a delete operácie môžu emitovať webhook eventy `contact-activity-logs.created`, `contact-activity-logs.updated` a `contact-activity-logs.deleted`.
  - name: Bankové účty
    description: Správa bankových účtov vrátane údajov o banke, primárnom účte a stave open banking napojenia. Create, update a delete operácie môžu emitovať webhook eventy `bank-accounts.created`, `bank-accounts.updated` a `bank-accounts.deleted`.
  - name: Webhooky
    description: Správa odberov webhookov pre Fintoro API. Táto sekcia pokrýva CRUD operácie nad odbermi, manuálnu rotáciu secretu a payload kontrakt pre integrácie riadené udalosťami. Kontrakt doručenia, overenie podpisu, retry mechanizmus a podrobný katalóg eventov nájdete v [príručke Webhooky](/webhooks).
  - name: Sklady
    description: CRUD operácie nad skladmi vrátane inbound a outbound číselných radov. Create, update a delete operácie môžu emitovať webhook eventy `warehouses.created`, `warehouses.updated` a `warehouses.deleted`.
  - name: Skladové príjemky
    description: CRUD operácie nad skladovými príjemkami vrátane detailu skladu, dodávateľského snapshotu, položiek a `pdfDownloadUrl`. Create, update a delete operácie môžu emitovať webhook eventy `warehouse-inbound-receipts.created`, `warehouse-inbound-receipts.updated` a `warehouse-inbound-receipts.deleted`.
  - name: Skladové výdajky
    description: CRUD operácie nad skladovými výdajkami vrátane detailu skladu, klientského snapshotu, položiek a `pdfDownloadUrl`. Create a update flow používajú rovnakú stock availability validáciu ako web. Create, update a delete operácie môžu emitovať webhook eventy `warehouse-outbound-receipts.created`, `warehouse-outbound-receipts.updated` a `warehouse-outbound-receipts.deleted`.
  - name: Skladové a cenníkové položky
    description: >-
      CRUD operácie nad skladovými a cenníkovými položkami. Endpointy vracajú jednotku ako vnorený objekt,
      podporujú filtrovanie podľa názvu, EANu, skladového kódu, ceny a stavu skladu a používajú rovnaký business kontrakt ako
      administrácia Fintoro pre warehouse evidenciu, EAN a nákupné ceny. Create, update a delete operácie môžu emitovať webhook eventy
      `price-list-items.created`, `price-list-items.updated` a `price-list-items.deleted`. Zmeny skladového stavu vyvolané
      skladovými príjemkami a výdajkami môžu emitovať webhook event `price-list-items.stock-updated`.
  - name: Úhrady dokladov
    description: >-
      Evidencia úhrad pre podporované doklady. Táto sekcia pokrýva zoznam úhrad konkrétneho dokladu, vytvorenie novej úhrady,
      detail jednej úhrady a jej zmazanie. Podporované typy dokladov sú `invoice`, `proforma`, `credit-note`,
      `received-invoice` a `received-receipt`. Create a delete operácie môžu emitovať webhook eventy
      `document-payments.created` a `document-payments.deleted`. Ak nová úhrada spôsobí, že podporovaný
      doklad sa stane plne uhradeným, môže sa navyše vyemitovať aj zodpovedajúci `*.paid` event pre daný resource dokladu.
  - name: Dokladové e-maily
    description: >-
      Odosielanie podporovaných public dokumentov emailom. Endpoint používa jednotný kontrakt nad kombináciou
      `documentType` + `documentId`, validuje vlastníctvo dokladu a podporuje typy `invoice`, `proforma`, `order`,
      `credit-note` a `quotation`.
  - name: Faktúry
    description: CRUD operácie nad faktúrami. Create, update a delete operácie môžu emitovať webhook eventy `invoices.created`, `invoices.updated` a `invoices.deleted`. Keď sa faktúra po zaevidovaní úhrady stane plne uhradenou, môže sa vyemitovať aj `invoices.paid`.
  - name: Dobropisy
    description: >-
      CRUD operácie nad dobropismi. Kontrakt používa camelCase payloady, plný `PUT` update flow a explicitnú väzbu
      na pôvodnú faktúru cez `invoiceId`. Klient dobropisu sa vždy odvodzuje zo zvolenej zdrojovej faktúry; `clientId` nie je súčasťou
      request kontraktu a inline client resolution ani create flow sa tu nepoužívajú. Create, update a delete operácie môžu emitovať
      webhook eventy `credit-notes.created`, `credit-notes.updated` a `credit-notes.deleted`. Keď sa dobropis po zaevidovaní úhrady
      stane plne uhradeným, môže sa vyemitovať aj `credit-notes.paid`.
  - name: Zálohové faktúry
    description: >-
      CRUD operácie nad zálohovými faktúrami. Kontrakt je navrhnutý rovnakou filozofiou ako Fintoro API faktúry:
      camelCase payloady, deterministický resolve/create klienta, create-like defaulty a plný `PUT` update flow bez patch fallbacku
      na pôvodný stav dokladu. Create, update a delete operácie môžu emitovať webhook eventy `proformas.created`, `proformas.updated`,
      `proformas.deleted` a pri plnom uhradení po zaevidovaní úhrady aj `proformas.paid`.
  - name: Objednávky
    description: >-
      CRUD operácie nad objednávkami. Kontrakt používa camelCase payloady, deterministický resolve/create klienta,
      create-like defaulty a plný `PUT` update flow bez patch fallbacku na pôvodný stav dokladu. Create, update a delete operácie môžu
      emitovať webhook eventy `orders.created`, `orders.updated` a `orders.deleted`.
  - name: Cenové ponuky
    description: >-
      CRUD operácie nad cenovými ponukami. Kontrakt používa camelCase payloady, deterministický resolve/create
      klienta, create-like defaulty a plný `PUT` update flow bez patch fallbacku na pôvodný stav dokladu.
      Create, update a delete operácie môžu emitovať webhook eventy `quotations.created`, `quotations.updated` a `quotations.deleted`.
paths:
  /whoami:
    get:
      tags: [Identita tokenu]
      summary: Identita aktuálnej firmy
      operationId: showWhoami
      description: Vráti minimálnu identitu firmy priradenej k bearer tokenu. Endpoint je vhodný na rýchle overenie, že integrácia pracuje so správnou produkčnou alebo sandbox firmou, bez potreby sťahovať ďalšie business dáta.
      responses:
        '200':
          description: Identita aktuálnej firmy.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Whoami'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /banks:
    get:
      tags: [Lookupy]
      summary: Zoznam bánk
      operationId: listBanks
      description: Vráti 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ý lookup dataset. Banky považujte za stabilný číselník; nové záznamy môžu pribúdať, no existujúce ID ostávajú zachované kvôli kompatibilite s uloženými bankovými účtami.
      responses:
        '200':
          description: Zoznam bánk.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Celý aktuálny zoznam bánk dostupných pre bankové účty.
                    type: array
                    items:
                      $ref: '#/components/schemas/Bank'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /countries:
    get:
      tags: [Lookupy]
      summary: Zoznam krajín
      operationId: listCountries
      description: Vráti fixný číselník krajín. Endpoint nepodporuje filtrovanie ani stránkovanie a vracia celý dataset. ID krajín sú stabilné v rámci tejto verzie API a nájdete ich aj v [referenčnej tabuľke krajín](/reference-tables#krajiny). Názvy sa dajú lokalizovať cez `Accept-Language`.
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      responses:
        '200':
          description: Zoznam krajín.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Celý zoznam krajín dostupných v tejto verzii API.
                    type: array
                    items:
                      $ref: '#/components/schemas/Country'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /languages:
    get:
      tags: [Lookupy]
      summary: Zoznam jazykov
      operationId: listLanguages
      description: Vráti fixný číselník jazykov. Endpoint nepodporuje filtrovanie ani stránkovanie a vracia celý dataset. ID jazykov sú stabilné v rámci tejto verzie API a nájdete ich aj v [referenčnej tabuľke jazykov](/reference-tables#jazyky). Názvy sa dajú lokalizovať cez `Accept-Language`.
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      responses:
        '200':
          description: Zoznam jazykov.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Celý zoznam jazykov dostupných v tejto verzii API.
                    type: array
                    items:
                      $ref: '#/components/schemas/Language'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /currencies:
    get:
      tags: [Lookupy]
      summary: Zoznam mien
      operationId: listCurrencies
      description: Vráti fixný číselník mien. Endpoint nepodporuje filtrovanie ani stránkovanie a vracia celý dataset. ID mien sú stabilné v rámci tejto verzie API a nájdete ich aj v [referenčnej tabuľke mien](/reference-tables#meny). Názvy sa dajú lokalizovať cez `Accept-Language`.
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      responses:
        '200':
          description: Zoznam mien.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Celý zoznam mien dostupných v tejto verzii API.
                    type: array
                    items:
                      $ref: '#/components/schemas/Currency'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /delivery-methods:
    get:
      tags: [Lookupy]
      summary: Zoznam spôsobov dodania
      operationId: listDeliveryMethods
      description: Vráti fixný číselník spôsobov dodania. Endpoint nepodporuje filtrovanie ani stránkovanie a vracia celý dataset. ID spôsobov dodania sú stabilné v rámci tejto verzie API a nájdete ich aj v [referenčnej tabuľke spôsobov dodania](/reference-tables#sposoby-dodania). Názvy sa dajú lokalizovať cez `Accept-Language`.
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      responses:
        '200':
          description: Zoznam spôsobov dodania.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Celý zoznam spôsobov dodania dostupných v tejto verzii API.
                    type: array
                    items:
                      $ref: '#/components/schemas/DeliveryMethod'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /payment-methods:
    get:
      tags: [Lookupy]
      summary: Zoznam spôsobov úhrady
      operationId: listPaymentMethods
      description: Vráti fixný číselník spôsobov úhrady. Endpoint nepodporuje filtrovanie ani stránkovanie a vracia celý dataset. ID spôsobov úhrady sú stabilné v rámci tejto verzie API a nájdete ich aj v [referenčnej tabuľke spôsobov úhrady](/reference-tables#sposoby-uhrady). Názvy sa dajú lokalizovať cez `Accept-Language`.
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      responses:
        '200':
          description: Zoznam spôsobov úhrady.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Celý zoznam spôsobov úhrady dostupných v tejto verzii API.
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentMethod'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /qr-types:
    get:
      tags: [Lookupy]
      summary: Zoznam QR typov
      operationId: listQrTypes
      description: Vráti fixný číselník QR typov. Endpoint nepodporuje filtrovanie ani stránkovanie a vracia celý dataset. ID QR typov sú stabilné v rámci tejto verzie API a nájdete ich aj v [referenčnej tabuľke QR typov](/reference-tables#qr-typy). Názvy sa dajú lokalizovať cez `Accept-Language`.
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      responses:
        '200':
          description: Zoznam QR typov.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Celý zoznam QR typov dostupných v tejto verzii API.
                    type: array
                    items:
                      $ref: '#/components/schemas/QrType'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /units:
    get:
      tags: [Lookupy]
      summary: Zoznam jednotiek
      operationId: listUnits
      description: Vráti fixný číselník jednotiek. Endpoint nepodporuje filtrovanie ani stránkovanie a vracia celý dataset. ID jednotiek sú stabilné v rámci tejto verzie API a nájdete ich aj v [referenčnej tabuľke jednotiek](/reference-tables#jednotky). Názvy sa dajú lokalizovať cez `Accept-Language`.
      parameters:
        - $ref: '#/components/parameters/AcceptLanguage'
      responses:
        '200':
          description: Zoznam jednotiek.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Celý zoznam jednotiek dostupných v tejto verzii API.
                    type: array
                    items:
                      $ref: '#/components/schemas/Unit'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /numerical-series:
    get:
      tags: [Číselné rady]
      summary: Zoznam číselných radov
      operationId: listNumericalSeries
      description: Vráti číselné rady používané pri tvorbe public dokumentov. Endpoint nepoužíva stránkovanie; vracia celý relevantný dataset pre podporovaný document typ zadaný v povinnom query parametri `documentType`. Podporované hodnoty sú `invoice`, `proforma`, `credit-note`, `order` a `quotation`. Okrem interného počítadla `nextNumber` response vracia aj `nextDocumentNumber` a `nextVariableSymbol`, takže integrátor vie dopredu zistiť, aké číslo dokladu a variabilný symbol z konkrétneho radu vzniknú.
      parameters:
        - in: query
          name: documentType
          required: true
          description: Povinný document typ, pre ktorý sa má vrátiť relevantný dataset číselných radov.
          schema:
            type: string
            enum: [invoice, proforma, credit-note, order, quotation]
          example: invoice
      responses:
        '200':
          description: Zoznam číselných radov.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Celý zoznam číselných radov pre zadaný document typ.
                    type: array
                    items:
                      $ref: '#/components/schemas/NumericalSeries'
        '422':
          description: Query parameter neprešiel validačnými pravidlami.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /numerical-series/{numericalSeries}:
    parameters:
      - $ref: '#/components/parameters/NumericalSeriesId'
    get:
      tags: [Číselné rady]
      summary: Detail číselného radu
      operationId: showNumericalSeries
      description: Vráti detail jedného číselného radu v rovnakom tvare ako list endpoint. Endpoint je vhodný vtedy, keď si chcete uložiť konkrétne `numericalSeriesId` a neskôr si ho overiť alebo znovu načítať pred vytvorením dokladu.
      responses:
        '200':
          description: Detail jedného číselného radu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumericalSeries'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /subjects:
    get:
      tags: [Subjekty]
      summary: Vyhľadávanie subjektov
      operationId: searchSubjects
      description: Tento endpoint použite, keď potrebujete dohľadať údaje o firme alebo živnostníkovi podľa názvu či IČO.
      parameters:
        - name: searchQuery
          in: query
          required: true
          description: Hľadaný reťazec. Môže to byť názov subjektu alebo IČO. Minimum sú 3 znaky.
          schema:
            type: string
            minLength: 3
            example: acme
        - name: legalForm
          in: query
          required: false
          description: Voliteľný filter podľa právnej formy, ak chcete výsledky zúžiť len na firmy alebo živnostníkov.
          schema:
            type: string
            enum: [freelancer, company]
            example: company
        - name: limit
          in: query
          required: false
          description: Maximálny počet výsledkov, ktoré endpoint vráti.
          schema:
            type: integer
            minimum: 1
            maximum: 20
            example: 5
      responses:
        '200':
          description: Vracia zodpovedajúce subjekty z referenčného registra.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Zoznam nájdených subjektov.
                    type: array
                    items:
                      $ref: '#/components/schemas/Subject'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /subjects/{subject}:
    parameters:
      - $ref: '#/components/parameters/SubjectId'
    get:
      tags: [Subjekty]
      summary: Detail subjektu
      operationId: showSubject
      description: Vráti jeden konkrétny subjekt z referenčného registra podľa jeho ID.
      responses:
        '200':
          description: Vracia detail požadovaného subjektu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subject'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /clients:
    get:
      tags: [Klienti]
      summary: Zoznam klientov
      operationId: listClients
      description: Vráti klientov. 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.
      parameters:
        - name: search
          in: query
          required: false
          description: Fulltextové vyhľadávanie podľa názvu, mesta, PSČ alebo krajiny.
          schema:
            type: string
            example: bratislava
        - name: sortBy
          in: query
          required: false
          description: Pole, podľa ktorého sa majú klienti zoradiť.
          schema:
            type: string
            enum: [name, city, zip, countryId, createdAt, updatedAt]
            example: name
            default: name
        - name: sortDirection
          in: query
          required: false
          description: Smer zoradenia.
          schema:
            type: string
            enum: [asc, desc]
            example: desc
            default: asc
        - name: type
          in: query
          required: false
          description: Filter podľa typu klienta.
          schema:
            type: string
            enum: [person, company]
            example: company
        - name: subjectId
          in: query
          required: false
          description: Filter podľa IČO klienta alebo firmy.
          schema:
            type: string
            example: '12345678'
        - name: taxId
          in: query
          required: false
          description: Filter podľa DIČ klienta alebo firmy.
          schema:
            type: string
            example: '2020123456'
        - name: vatId
          in: query
          required: false
          description: Filter podľa IČ DPH klienta alebo firmy.
          schema:
            type: string
            example: SK2020123456
        - name: countryId
          in: query
          required: false
          description: "Filter podľa fakturačnej krajiny klienta z [referenčnej tabuľky krajín](/reference-tables#krajiny)."
          schema:
            type: integer
            example: 703
      responses:
        '200':
          description: Zoznam klientov.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Zoznam klientov.
                    type: array
                    items:
                      $ref: '#/components/schemas/Client'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Klienti]
      summary: Vytvoriť klienta
      operationId: createClient
      description: Vytvorí nového klienta. V requeste posielate business údaje klienta a voliteľné klientské predvolené hodnoty, ktoré sa ukladajú pri klientovi a pri tvorbe nových dokladov sa používajú ako fallback predvolené hodnoty, 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.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientCreateInput'
      responses:
        '201':
          description: Klient bol vytvorený.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotency-Key:
              description: Pôvodný idempotency key, ak bol poslaný v requeste.
              schema:
                type: string
            Idempotency-Status:
              description: '`Original` pri prvom spracovaní alebo `Repeated` pri vrátení pôvodnej odpovede.'
              schema:
                type: string
                enum: [Original, Repeated]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
        '422':
          description: Idempotency key bol znovu použitý s iným payloadom.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Idempotency-Key reused with different request payload
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /clients/{client}:
    parameters:
      - $ref: '#/components/parameters/ClientId'
    get:
      tags: [Klienti]
      summary: Detail klienta
      operationId: showClient
      description: Vráti detail jedného klienta vrátane vnorených krajín a klientských predvolených hodnôt, ktoré môžete použiť pri tvorbe nových dokladov.
      responses:
        '200':
          description: Detail klienta.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      tags: [Klienti]
      summary: Upraviť klienta
      operationId: updateClient
      description: Aktualizuje klienta cez plnohodnotný `PUT` payload. Pošlite rovnaké polia ako pri vytvorení klienta. Endpoint nehydratuje chýbajúce polia z existujúcich dát klienta; ak optional pole vynecháte, uloží sa jeho create default alebo `null` podľa create kontraktu. Polia dodacej adresy a inferované hodnoty sa správajú rovnako ako pri vytvorení klienta.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientCreateInput'
      responses:
        '200':
          description: Klient bol aktualizovaný.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [Klienti]
      summary: Zmazať klienta
      operationId: deleteClient
      description: Zmaže klienta. Po úspešnom zmazaní endpoint nevracia response body.
      responses:
        '204':
          description: Klient bol zmazaný.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /suppliers:
    get:
      tags: [Dodávatelia]
      summary: Zoznam dodávateľov
      operationId: listSuppliers
      description: Vráti dodávateľov. Endpoint je vhodný na synchronizáciu dodávateľov do externého systému alebo vlastného frontendu a podporuje základné fulltextové vyhľadávanie aj triedenie.
      parameters:
        - name: search
          in: query
          required: false
          description: Fulltextové vyhľadávanie podľa názvu, mesta, PSČ alebo krajiny.
          schema:
            type: string
            example: bratislava
        - name: sortBy
          in: query
          required: false
          description: Pole, podľa ktorého sa majú dodávatelia zoradiť.
          schema:
            type: string
            enum: [name, city, zip, createdAt, updatedAt]
            example: name
            default: name
        - name: sortDirection
          in: query
          required: false
          description: Smer zoradenia.
          schema:
            type: string
            enum: [asc, desc]
            example: desc
            default: asc
      responses:
        '200':
          description: Zoznam dodávateľov.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Zoznam dodávateľov.
                    type: array
                    items:
                      $ref: '#/components/schemas/Supplier'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Dodávatelia]
      summary: Vytvoriť dodávateľa
      operationId: createSupplier
      description: Vytvorí nového dodávateľa. Ak nepošlete `type`, backend ho inferuje z identifikačných polí `subjectId`, `taxId` a `vatId`. Ak nepošlete `isVatPayer`, backend ho inferuje z prítomnosti `vatId`. Ak pošlete `Idempotency-Key`, rovnaký key s rovnakým payloadom vráti pôvodnú odpoveď bez druhého vytvorenia dodávateľa.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplierCreateInput'
      responses:
        '201':
          description: Dodávateľ bol vytvorený.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotency-Key:
              description: Pôvodný idempotency key, ak bol poslaný v requeste.
              schema:
                type: string
            Idempotency-Status:
              description: '`Original` pri prvom spracovaní alebo `Repeated` pri vrátení pôvodnej odpovede.'
              schema:
                type: string
                enum: [Original, Repeated]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Supplier'
        '422':
          description: Validation error alebo opätovné použitie idempotency key s iným payloadom.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  error:
                    type: [string, 'null']
                    example: Idempotency-Key reused with different request payload
                  errors:
                    type: [object, 'null']
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /suppliers/{supplier}:
    parameters:
      - $ref: '#/components/parameters/SupplierId'
    get:
      tags: [Dodávatelia]
      summary: Detail dodávateľa
      operationId: showSupplier
      description: Vráti detail jedného dodávateľa vrátane vnoreného objektu krajiny.
      responses:
        '200':
          description: Detail dodávateľa.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Supplier'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      tags: [Dodávatelia]
      summary: Upraviť dodávateľa
      operationId: updateSupplier
      description: Aktualizuje dodávateľa cez full `PUT` payload. Pošlite celý payload v rovnakom tvare ako pri vytvorení. Backend pri update nedoťahuje vynechané polia z existujúcich dát. Pri inferred poliach `type` a `isVatPayer` platí rovnaké správanie ako pri vytvorení dodávateľa.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplierCreateInput'
      responses:
        '200':
          description: Dodávateľ bol aktualizovaný.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Supplier'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [Dodávatelia]
      summary: Zmazať dodávateľa
      operationId: deleteSupplier
      description: Zmaže dodávateľa. Endpoint po úspešnom spracovaní nevracia response body.
      responses:
        '204':
          description: Dodávateľ bol zmazaný.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /business-case-statuses:
    get:
      tags: [Stavy obchodných prípadov]
      summary: Zoznam stavov obchodných prípadov
      operationId: listBusinessCaseStatuses
      description: Vráti všetky statusy obchodných prípadov v poradí podľa ich pozície v pipeline. Endpoint nepodporuje filtrovanie ani stránkovanie a je vhodný najmä na synchronizáciu pipeline stĺpcov do externého CRM alebo vlastného frontendu.
      responses:
        '200':
          description: Zoznam stavov obchodných prípadov.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Zoznam všetkých statusov.
                    type: array
                    items:
                      $ref: '#/components/schemas/BusinessCaseStatus'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Stavy obchodných prípadov]
      summary: Vytvoriť stav obchodného prípadu
      operationId: createBusinessCaseStatus
      description: Vytvorí nový stav obchodného prípadu. Nový stav sa zaradí na koniec existujúcej pipeline. Ak pošlete `Idempotency-Key`, opakované create volanie s rovnakým kľúčom a rovnakým payloadom vráti pôvodnú odpoveď bez druhého vytvorenia stavu.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessCaseStatusInput'
      responses:
        '201':
          description: Stav obchodného prípadu bol vytvorený.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotency-Key:
              description: Pôvodný idempotency key, ak bol poslaný v requeste.
              schema:
                type: string
            Idempotency-Status:
              description: '`Original` pri prvom spracovaní alebo `Repeated` pri vrátení pôvodnej odpovede.'
              schema:
                type: string
                enum: [Original, Repeated]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessCaseStatus'
        '422':
          description: Validačná chyba alebo opätovné použitie idempotency key s iným payloadom.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      message:
                        type: string
                        example: The given data was invalid.
                      errors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                  - type: object
                    properties:
                      error:
                        type: string
                        example: Idempotency-Key reused with different request payload
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /business-case-statuses/{businessCaseStatus}:
    parameters:
      - $ref: '#/components/parameters/BusinessCaseStatusId'
    get:
      tags: [Stavy obchodných prípadov]
      summary: Detail stavu obchodného prípadu
      operationId: showBusinessCaseStatus
      description: Vráti detail jedného stavu obchodného prípadu.
      responses:
        '200':
          description: Detail stavu obchodného prípadu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessCaseStatus'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      tags: [Stavy obchodných prípadov]
      summary: Upraviť stav obchodného prípadu
      operationId: updateBusinessCaseStatus
      description: Aktualizuje jeden stav obchodného prípadu. Payload je plný `PUT` kontrakt a vyžaduje `name` aj `color`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessCaseStatusInput'
      responses:
        '200':
          description: Stav obchodného prípadu bol aktualizovaný.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessCaseStatus'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: Validačná chyba request payloadu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [Stavy obchodných prípadov]
      summary: Zmazať stav obchodného prípadu
      operationId: deleteBusinessCaseStatus
      description: Zmaže stav obchodného prípadu. Po úspešnom spracovaní endpoint nevracia response body. Naviazané obchodné prípady zostanú zachované a ich `statusId` sa automaticky nastaví na `null`.
      responses:
        '204':
          description: Stav obchodného prípadu bol zmazaný.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /business-cases:
    get:
      tags: [Obchodné prípady]
      summary: Zoznam obchodných prípadov
      operationId: listBusinessCases
      description: Vráti obchodné prípady aktuálnej firmy. Endpoint podporuje filtrovanie podľa klienta, dodávateľa, stavu a fulltextové vyhľadávanie v názve alebo popise. Response vždy vracia vnorený objekt klienta alebo dodávateľa podľa reality záznamu, voliteľný vnorený stav a paginator pre stránkovanie.
      parameters:
        - name: clientId
          in: query
          required: false
          description: "Filter podľa klienta patriaceho. Pole je vzájomne exkluzívne so `supplierId`."
          schema:
            type: integer
            example: 101
        - name: supplierId
          in: query
          required: false
          description: "Filter podľa dodávateľa patriaceho. Pole je vzájomne exkluzívne s `clientId`."
          schema:
            type: integer
            example: 151
        - name: statusId
          in: query
          required: false
          description: Filter podľa stavu obchodného prípadu.
          schema:
            type: [integer, 'null']
            example: 41
        - name: search
          in: query
          required: false
          description: Fulltextové vyhľadávanie podľa názvu alebo popisu obchodného prípadu.
          schema:
            type: string
            maxLength: 255
            example: keyword
        - name: sortBy
          in: query
          required: false
          description: Pole, podľa ktorého sa majú obchodné prípady zoradiť.
          schema:
            type: string
            enum: [name, createdAt, updatedAt, boardPosition]
            example: updatedAt
            default: id
        - name: sortDirection
          in: query
          required: false
          description: Smer zoradenia.
          schema:
            type: string
            enum: [asc, desc]
            example: desc
            default: desc
        - name: perPage
          in: query
          required: false
          description: Počet výsledkov na stránku. Maximum je 200.
          schema:
            type: integer
            minimum: 1
            maximum: 200
            example: 10
            default: 10
        - name: page
          in: query
          required: false
          description: Číslo stránky, ktorá sa má vrátiť.
          schema:
            type: integer
            minimum: 1
            example: 1
            default: 1
      responses:
        '200':
          description: Zoznam obchodných prípadov.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Zoznam obchodných prípadov.
                    type: array
                    items:
                      $ref: '#/components/schemas/BusinessCase'
                  paginator:
                    description: Paginator pre aktuálny výsledkový set.
                    $ref: '#/components/schemas/Paginator'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: Validačná chyba query parametrov.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Obchodné prípady]
      summary: Vytvoriť obchodný prípad
      operationId: createBusinessCase
      description: Vytvorí nový obchodný prípad. V requeste musíte poslať presne jedno z polí `clientId` alebo `supplierId`. `statusId` je voliteľné a môže byť `null`. Ak pošlete `Idempotency-Key`, opakované create volanie s rovnakým key a rovnakým payloadom vráti pôvodnú odpoveď bez druhého vytvorenia prípadu.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessCaseCreateInput'
      responses:
        '201':
          description: Obchodný prípad bol vytvorený.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotency-Key:
              description: Pôvodný idempotency key, ak bol poslaný v requeste.
              schema:
                type: string
            Idempotency-Status:
              description: '`Original` pri prvom spracovaní alebo `Repeated` pri vrátení pôvodnej odpovede.'
              schema:
                type: string
                enum: [Original, Repeated]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessCase'
        '422':
          description: Validačná chyba alebo opätovné použitie idempotency key s iným payloadom.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      message:
                        type: string
                        example: The given data was invalid.
                      errors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                  - type: object
                    properties:
                      error:
                        type: string
                        example: Idempotency-Key reused with different request payload
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /business-cases/{businessCase}:
    parameters:
      - $ref: '#/components/parameters/BusinessCaseId'
    get:
      tags: [Obchodné prípady]
      summary: Detail obchodného prípadu
      operationId: showBusinessCase
      description: Vráti detail jedného obchodného prípadu vrátane vnoreného klienta alebo dodávateľa a voliteľného stavu.
      responses:
        '200':
          description: Detail obchodného prípadu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessCase'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    patch:
      tags: [Obchodné prípady]
      summary: Upraviť obchodný prípad
      operationId: updateBusinessCase
      description: Čiastočne aktualizuje obchodný prípad. Môžete meniť `name`, `description` a `statusId`, pričom `statusId` môže byť aj `null`. Väzbu na klienta alebo dodávateľa tento endpoint nemení; polia `clientId` a `supplierId` sú pri update zakázané a vrátia validačnú chybu.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessCaseUpdateInput'
      responses:
        '200':
          description: Obchodný prípad bol aktualizovaný.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessCase'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: Validačná chyba request payloadu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [Obchodné prípady]
      summary: Zmazať obchodný prípad
      operationId: deleteBusinessCase
      description: Zmaže obchodný prípad. Po úspešnom spracovaní endpoint nevracia response body.
      responses:
        '204':
          description: Obchodný prípad bol zmazaný.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /contact-activity-attachments:
    post:
      tags: [CRM udalosti]
      summary: Nahrať prílohy CRM udalosti
      operationId: uploadContactActivityAttachments
      description: Nahraje jednu alebo viac príloh do temporary storage a vráti `uploadToken` hodnoty použiteľné v `attachmentUploadTokens[]` pri create alebo update `contact-activity-logs`. Tento endpoint používa `multipart/form-data` a neberie Filepond server IDs.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [files]
              properties:
                files:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    format: binary
      responses:
        '201':
          description: Temporary upload tokeny pre nahraté prílohy.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContactActivityLogAttachmentUpload'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: Validačná chyba multipart payloadu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /contact-activity-logs:
    get:
      tags: [CRM udalosti]
      summary: Zoznam CRM udalostí
      operationId: listContactActivityLogs
      description: Vráti CRM udalosti. Query musí obsahovať presne jedno target pole z `businessCaseId`, `clientId` alebo `supplierId`. Voliteľne môžete filtrovať podľa `type` a stránkovať pomocou `perPage` a `page`.
      parameters:
        - name: businessCaseId
          in: query
          required: false
          description: ID obchodného prípadu patriaceho. Pole je vzájomne exkluzívne s `clientId` a `supplierId`.
          schema:
            type: integer
            example: 501
        - name: clientId
          in: query
          required: false
          description: ID klienta patriaceho. Pole je vzájomne exkluzívne s `businessCaseId` a `supplierId`.
          schema:
            type: integer
            example: 101
        - name: supplierId
          in: query
          required: false
          description: ID dodávateľa patriaceho. Pole je vzájomne exkluzívne s `businessCaseId` a `clientId`.
          schema:
            type: integer
            example: 151
        - name: type
          in: query
          required: false
          description: Voliteľný filter podľa typu CRM udalosti.
          schema:
            type: string
            enum: [note, email, phone_call, document_linked]
            example: note
        - name: perPage
          in: query
          required: false
          description: Počet výsledkov na stránku. Maximum je 200.
          schema:
            type: integer
            minimum: 1
            maximum: 200
            example: 10
            default: 10
        - name: page
          in: query
          required: false
          description: Číslo stránky, ktorá sa má vrátiť.
          schema:
            type: integer
            minimum: 1
            example: 1
            default: 1
      responses:
        '200':
          description: Zoznam CRM udalostí.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContactActivityLog'
                  paginator:
                    $ref: '#/components/schemas/Paginator'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: Validačná chyba query parametrov.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [CRM udalosti]
      summary: Vytvoriť CRM udalosť
      operationId: createContactActivityLog
      description: >-
        Vytvorí novú CRM udalosť. Musíte poslať presne jeden target z `businessCaseId`, `clientId`
        alebo `supplierId`, `type`, `metadata` a voliteľne `attachmentUploadTokens[]`. Pre `document_linked`
        použite `metadata.documentType` a `metadata.documentId`; attachmenty sa pri tomto type nepodporujú.
        Ak pošlete `Idempotency-Key`, opakované create volanie s rovnakým key a rovnakým payloadom vráti
        pôvodnú odpoveď bez druhého vytvorenia udalosti. Dostupnosť jednotlivých metadata polí je popísaná
        priamo pri `metadata.content`, `metadata.email`, `metadata.personName`, `metadata.phoneNumber`,
        `metadata.documentType` a `metadata.documentId`.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactActivityLogCreateInput'
      responses:
        '201':
          description: CRM udalosť bola vytvorená.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotency-Key:
              description: Pôvodný idempotency key, ak bol poslaný v requeste.
              schema:
                type: string
            Idempotency-Status:
              description: '`Original` pri prvom spracovaní alebo `Repeated` pri vrátení pôvodnej odpovede.'
              schema:
                type: string
                enum: [Original, Repeated]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactActivityLog'
        '422':
          description: Validačná chyba alebo opätovné použitie idempotency key s iným payloadom.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      message:
                        type: string
                        example: The given data was invalid.
                      errors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                  - type: object
                    properties:
                      error:
                        type: string
                        example: Idempotency-Key reused with different request payload
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /contact-activity-logs/{contactActivityLog}:
    parameters:
      - $ref: '#/components/parameters/ContactActivityLogId'
    get:
      tags: [CRM udalosti]
      summary: Detail CRM udalosti
      operationId: showContactActivityLog
      description: Vráti detail jednej CRM udalosti vrátane metadata payloadu a zoznamu príloh.
      responses:
        '200':
          description: Detail CRM udalosti.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactActivityLog'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    patch:
      tags: [CRM udalosti]
      summary: Upraviť CRM udalosť
      operationId: updateContactActivityLog
      description: >-
        Čiastočne aktualizuje CRM udalosť. Meniteľné sú iba `metadata`, `attachmentUploadTokens[]`
        a `deletedAttachmentIds[]`; `type` a target polia sú pri update zakázané. Pri `document_linked`
        type sa attachmenty nepodporujú. Dostupnosť jednotlivých metadata polí je popísaná priamo pri
        `metadata.content`, `metadata.email`, `metadata.personName`, `metadata.phoneNumber`,
        `metadata.documentType` a `metadata.documentId`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactActivityLogUpdateInput'
      responses:
        '200':
          description: CRM udalosť bola aktualizovaná.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactActivityLog'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: Validačná chyba request payloadu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [CRM udalosti]
      summary: Zmazať CRM udalosť
      operationId: deleteContactActivityLog
      description: Zmaže CRM udalosť. Po úspešnom spracovaní endpoint nevracia response body.
      responses:
        '204':
          description: CRM udalosť bola zmazaná.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /contact-activity-logs/{contactActivityLog}/attachments:
    parameters:
      - $ref: '#/components/parameters/ContactActivityLogId'
    get:
      tags: [CRM udalosti]
      summary: Stiahnuť prílohy CRM udalosti
      operationId: downloadContactActivityLogAttachments
      description: Vráti ZIP stream príloh danej CRM udalosti. Ak udalosť prílohy nemá, endpoint vráti `404`.
      responses:
        '200':
          description: ZIP archív príloh CRM udalosti.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /bank-accounts:
    get:
      tags: [Bankové účty]
      summary: Zoznam bankových účtov
      operationId: listBankAccounts
      description: Vráti všetky bankové účty 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.
      responses:
        '200':
          description: Zoznam bankových účtov.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Zoznam všetkých bankových účtov.
                    type: array
                    items:
                      $ref: '#/components/schemas/BankAccount'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Bankové účty]
      summary: Vytvoriť bankový účet
      operationId: createBankAccount
      description: Vytvorí nový bankový účet. V requeste posielate len business údaje účtu. Novovytvorený účet sa v aktuálnej implementácii vždy nastaví ako primárny účet firmy, preto sa tento stav v create payloade neposiela. Odpoveď 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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankAccountCreateInput'
      responses:
        '201':
          description: Bankový účet bol vytvorený.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /bank-accounts/{bankAccount}:
    parameters:
      - $ref: '#/components/parameters/BankAccountId'
    get:
      tags: [Bankové účty]
      summary: Detail bankového účtu
      operationId: showBankAccount
      description: Vráti detail jedného bankového účtu. Okrem samotných údajov o účte vracia aj vnorený objekt banky, stav primárneho účtu a open banking metadata, ak sú dostupné.
      responses:
        '200':
          description: Detail bankového účtu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    patch:
      tags: [Bankové účty]
      summary: Upraviť bankový účet
      operationId: updateBankAccount
      description: |
        Aktualizuje bankový účet. Pošlite len polia, ktoré chcete zmeniť.
        Ak pošlete `isPrimary: true`, účet sa nastaví ako primárny účet firmy.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BankAccountUpdateInput'
      responses:
        '200':
          description: Bankový účet bol aktualizovaný.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccount'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [Bankové účty]
      summary: Zmazať bankový účet
      operationId: deleteBankAccount
      description: Zmaže bankový účet. Po úspešnom spracovaní endpoint nevracia response body.
      responses:
        '204':
          description: Bankový účet bol zmazaný.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /warehouses:
    get:
      tags: [Sklady]
      summary: Zoznam skladov
      operationId: listWarehouses
      description: Vráti všetky sklady v jednom zozname. Endpoint nepodporuje filtrovanie ani stránkovanie, preto je vhodný najmä na synchronizáciu skladov do externého systému alebo vlastného frontendu.
      responses:
        '200':
          description: Zoznam skladov.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Zoznam všetkých skladov.
                    type: array
                    items:
                      $ref: '#/components/schemas/Warehouse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Sklady]
      summary: Vytvoriť sklad
      operationId: createWarehouse
      description: Vytvorí nový sklad vrátane inbound a outbound číselného radu. Response vracia výsledný uložený warehouse objekt.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WarehouseCreateInput'
      responses:
        '201':
          description: Sklad bol vytvorený.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Warehouse'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /warehouses/{warehouse}:
    parameters:
      - $ref: '#/components/parameters/WarehouseId'
    get:
      tags: [Sklady]
      summary: Detail skladu
      operationId: showWarehouse
      description: Vráti detail jedného skladu vrátane kompletnej konfigurácie inbound a outbound číselného radu.
      responses:
        '200':
          description: Detail skladu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Warehouse'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      tags: [Sklady]
      summary: Upraviť sklad
      operationId: updateWarehouse
      description: Aktualizuje sklad. Fintoro API používa plný `PUT` kontrakt, preto pošlite celý payload skladu vrátane číselných radov.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WarehouseUpdateInput'
      responses:
        '200':
          description: Sklad bol aktualizovaný.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Warehouse'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [Sklady]
      summary: Zmazať sklad
      operationId: deleteWarehouse
      description: Zmaže sklad. Posledný sklad firmy nie je možné zmazať; v takom prípade endpoint vráti `422`.
      responses:
        '204':
          description: Sklad bol zmazaný.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /warehouse-inbound-receipts:
    get:
      tags: [Skladové príjemky]
      summary: Zoznam skladových príjemiek
      operationId: listWarehouseInboundReceipts
      description: Vráti paginovaný zoznam skladových príjemiek. Endpoint podporuje filtrovanie podľa skladu, dodávateľa a čísla dokladu.
      parameters:
        - in: query
          name: warehouseId
          required: false
          description: Voliteľný filter podľa skladu.
          schema:
            type: integer
          example: 301
        - in: query
          name: supplierId
          required: false
          description: Voliteľný filter podľa dodávateľa.
          schema:
            type: integer
          example: 401
        - in: query
          name: number
          required: false
          description: Voliteľný substring filter podľa čísla príjemky.
          schema:
            type: string
          example: PRI-2026
        - in: query
          name: sortBy
          required: false
          description: Pole, podľa ktorého sa zoradí výsledok.
          schema:
            type: string
            enum: [number, issue_date, created_at, updated_at]
          example: number
        - in: query
          name: sortDirection
          required: false
          description: Smer radenia.
          schema:
            type: string
            enum: [asc, desc]
          example: asc
        - in: query
          name: perPage
          required: false
          description: Počet výsledkov na stránku.
          schema:
            type: integer
            minimum: 1
            maximum: 200
          example: 25
        - in: query
          name: page
          required: false
          description: Číslo strany.
          schema:
            type: integer
            minimum: 1
          example: 2
      responses:
        '200':
          description: Zoznam skladových príjemiek.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Zoznam skladových príjemiek v detailnom resource tvare.
                    type: array
                    items:
                      $ref: '#/components/schemas/WarehouseInboundReceipt'
                  paginator:
                    description: Paginator pre aktuálny výsledkový set.
                    $ref: '#/components/schemas/Paginator'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Skladové príjemky]
      summary: Vytvoriť skladovú príjemku
      operationId: createWarehouseInboundReceipt
      description: >-
        Vytvorí novú skladovú príjemku. Ak pošlete `supplierId`, použije sa existujúci dodávateľ.
        Ak `supplierId` nepošlete a pošlete objekt `supplier`, backend podľa týchto údajov dodávateľa dopáruje
        alebo vytvorí. Ak pošlete `Idempotency-Key`, opakované create volanie s rovnakým payloadom vráti
        pôvodnú odpoveď.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WarehouseInboundReceiptCreateInput'
      responses:
        '201':
          description: Skladová príjemka bola vytvorená.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotency-Key:
              description: Pôvodný idempotency key, ak bol poslaný v requeste.
              schema:
                type: string
            Idempotency-Status:
              description: '`Original` pri prvom spracovaní alebo `Repeated` pri vrátení pôvodnej odpovede.'
              schema:
                type: string
                enum: [Original, Repeated]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WarehouseInboundReceipt'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /warehouse-inbound-receipts/{warehouseInboundReceipt}:
    parameters:
      - $ref: '#/components/parameters/WarehouseInboundReceiptId'
    get:
      tags: [Skladové príjemky]
      summary: Detail skladovej príjemky
      operationId: showWarehouseInboundReceipt
      description: Vráti detail jednej skladovej príjemky vrátane skladu, dodávateľského snapshotu, položiek a `pdfDownloadUrl`.
      responses:
        '200':
          description: Detail skladovej príjemky.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WarehouseInboundReceipt'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      tags: [Skladové príjemky]
      summary: Upraviť skladovú príjemku
      operationId: updateWarehouseInboundReceipt
      description: >-
        Aktualizuje existujúcu skladovú príjemku. Fintoro API používa plný `PUT` kontrakt, preto
        pošlite celé hlavičkové aj položkové dáta príjemky. Partner flow je rovnaký ako pri create:
        `supplierId` použije existujúceho dodávateľa, objekt `supplier` bez `supplierId` spustí resolve-or-create
        flow.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WarehouseInboundReceiptUpdateInput'
      responses:
        '200':
          description: Skladová príjemka bola aktualizovaná.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WarehouseInboundReceipt'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [Skladové príjemky]
      summary: Zmazať skladovú príjemku
      operationId: deleteWarehouseInboundReceipt
      description: Zmaže skladovú príjemku. Endpoint po úspešnom spracovaní nevracia response body.
      responses:
        '204':
          description: Skladová príjemka bola zmazaná.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /warehouse-inbound-receipts/{warehouseInboundReceipt}/pdf:
    parameters:
      - $ref: '#/components/parameters/WarehouseInboundReceiptId'
    get:
      tags: [Skladové príjemky]
      summary: Stiahnuť skladovú príjemku ako pdf
      operationId: downloadWarehouseInboundReceiptPdf
      description: Stiahne PDF export skladovej príjemky ako prílohu (`application/pdf`). URL tohto endpointu nájdete aj v poli `pdfDownloadUrl` v detaile príjemky.
      responses:
        '200':
          description: PDF export skladovej príjemky.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /warehouse-outbound-receipts:
    get:
      tags: [Skladové výdajky]
      summary: Zoznam skladových výdajok
      operationId: listWarehouseOutboundReceipts
      description: Vráti paginovaný zoznam skladových výdajok. Endpoint podporuje filtrovanie podľa skladu, klienta a čísla dokladu.
      parameters:
        - in: query
          name: warehouseId
          required: false
          description: Voliteľný filter podľa skladu.
          schema:
            type: integer
          example: 301
        - in: query
          name: clientId
          required: false
          description: Voliteľný filter podľa klienta.
          schema:
            type: integer
          example: 101
        - in: query
          name: number
          required: false
          description: Voliteľný substring filter podľa čísla výdajky.
          schema:
            type: string
          example: VYD-2026
        - in: query
          name: sortBy
          required: false
          description: Pole, podľa ktorého sa zoradí výsledok.
          schema:
            type: string
            enum: [number, issue_date, created_at, updated_at]
          example: number
        - in: query
          name: sortDirection
          required: false
          description: Smer radenia.
          schema:
            type: string
            enum: [asc, desc]
          example: asc
        - in: query
          name: perPage
          required: false
          description: Počet výsledkov na stránku.
          schema:
            type: integer
            minimum: 1
            maximum: 200
          example: 25
        - in: query
          name: page
          required: false
          description: Číslo strany.
          schema:
            type: integer
            minimum: 1
          example: 2
      responses:
        '200':
          description: Zoznam skladových výdajok.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Zoznam skladových výdajok v detailnom resource tvare.
                    type: array
                    items:
                      $ref: '#/components/schemas/WarehouseOutboundReceipt'
                  paginator:
                    description: Paginator pre aktuálny výsledkový set.
                    $ref: '#/components/schemas/Paginator'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Skladové výdajky]
      summary: Vytvoriť skladovú výdajku
      operationId: createWarehouseOutboundReceipt
      description: >-
        Vytvorí novú skladovú výdajku. Ak pošlete `clientId`, použije sa existujúci klient.
        Ak `clientId` nepošlete a pošlete objekt `client`, backend podľa týchto údajov klienta dopáruje alebo
        vytvorí. Request používa rovnakú stock availability validáciu ako web, preto pri nedostatočnom stave
        skladu endpoint vráti `422`.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WarehouseOutboundReceiptCreateInput'
      responses:
        '201':
          description: Skladová výdajka bola vytvorená.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotency-Key:
              description: Pôvodný idempotency key, ak bol poslaný v requeste.
              schema:
                type: string
            Idempotency-Status:
              description: '`Original` pri prvom spracovaní alebo `Repeated` pri vrátení pôvodnej odpovede.'
              schema:
                type: string
                enum: [Original, Repeated]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WarehouseOutboundReceipt'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /warehouse-outbound-receipts/{warehouseOutboundReceipt}:
    parameters:
      - $ref: '#/components/parameters/WarehouseOutboundReceiptId'
    get:
      tags: [Skladové výdajky]
      summary: Detail skladovej výdajky
      operationId: showWarehouseOutboundReceipt
      description: Vráti detail jednej skladovej výdajky vrátane skladu, klientského snapshotu, položiek a `pdfDownloadUrl`.
      responses:
        '200':
          description: Detail skladovej výdajky.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WarehouseOutboundReceipt'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      tags: [Skladové výdajky]
      summary: Upraviť skladovú výdajku
      operationId: updateWarehouseOutboundReceipt
      description: >-
        Aktualizuje existujúcu skladovú výdajku. Fintoro API používa plný `PUT` kontrakt a zachováva
        rovnakú stock availability validáciu ako create flow. Partner flow je rovnaký ako pri create:
        `clientId` použije existujúceho klienta, objekt `client` bez `clientId` spustí resolve-or-create flow.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WarehouseOutboundReceiptUpdateInput'
      responses:
        '200':
          description: Skladová výdajka bola aktualizovaná.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WarehouseOutboundReceipt'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [Skladové výdajky]
      summary: Zmazať skladovú výdajku
      operationId: deleteWarehouseOutboundReceipt
      description: Zmaže skladovú výdajku. Endpoint po úspešnom spracovaní nevracia response body.
      responses:
        '204':
          description: Skladová výdajka bola zmazaná.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /warehouse-outbound-receipts/{warehouseOutboundReceipt}/pdf:
    parameters:
      - $ref: '#/components/parameters/WarehouseOutboundReceiptId'
    get:
      tags: [Skladové výdajky]
      summary: Stiahnuť skladovú výdajku ako pdf
      operationId: downloadWarehouseOutboundReceiptPdf
      description: Stiahne PDF export skladovej výdajky ako prílohu (`application/pdf`). URL tohto endpointu nájdete aj v poli `pdfDownloadUrl` v detaile výdajky.
      responses:
        '200':
          description: PDF export skladovej výdajky.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /price-list-items:
    get:
      tags: [Skladové a cenníkové položky]
      summary: Zoznam skladových a cenníkových položiek
      operationId: listPriceListItems
      description: >-
        Vráti skladové a cenníkové položky patriace. Endpoint podporuje fulltextové vyhľadávanie podľa názvu,
        skladového kódu a EANu, filtrovanie podľa ceny a stavu skladu a stránkovanie. Response vracia celkový stock položky,
        nie detailný rozpad po jednotlivých skladoch.
      parameters:
        - name: name
          in: query
          required: false
          description: Fulltextové vyhľadávanie podľa názvu položky, skladového kódu alebo EANu.
          schema:
            type: string
            maxLength: 255
            example: match
        - name: priceFrom
          in: query
          required: false
          description: Minimálna jednotková cena bez DPH.
          schema:
            type: number
            format: float
            example: 10
        - name: priceTo
          in: query
          required: false
          description: Maximálna jednotková cena bez DPH.
          schema:
            type: number
            format: float
            example: 100
        - name: stockFrom
          in: query
          required: false
          description: Minimálny aktuálny stav skladu položky.
          schema:
            type: number
            format: float
            example: 1
        - name: stockTo
          in: query
          required: false
          description: Maximálny aktuálny stav skladu položky.
          schema:
            type: number
            format: float
            example: 50
        - name: onlyWarehouseItems
          in: query
          required: false
          description: Ak pošlete `true`, endpoint vráti len položky so zapnutou skladovou evidenciou.
          schema:
            type: boolean
            default: false
            example: true
        - name: sortBy
          in: query
          required: false
          description: Pole, podľa ktorého sa zoznam zoradí.
          schema:
            type: string
            enum: [name, unit_price, stock]
            default: name
            example: stock
        - name: sortDirection
          in: query
          required: false
          description: Smer zoradenia.
          schema:
            type: string
            enum: [asc, desc]
            default: asc
            example: desc
        - name: perPage
          in: query
          required: false
          description: Počet položiek na jednu stránku. Maximum je 200.
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
            example: 50
        - name: page
          in: query
          required: false
          description: Číslo stránky, ktorá sa má vrátiť.
          schema:
            type: integer
            minimum: 1
            default: 1
            example: 2
      responses:
        '200':
          description: Zoznam skladových a cenníkových položiek.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Položky aktuálnej stránky.
                    type: array
                    items:
                      $ref: '#/components/schemas/PriceListItem'
                  paginator:
                    description: Metadata stránkovania pre aktuálny výsledok.
                    $ref: '#/components/schemas/Paginator'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Skladové a cenníkové položky]
      summary: Vytvoriť skladovú alebo cenníkovú položku
      operationId: createPriceListItem
      description: >-
        Vytvorí novú skladovú alebo cenníkovú položku. Ak pošlete `Idempotency-Key`, opakované create volanie
        s rovnakým key a rovnakým payloadom vráti pôvodnú odpoveď bez druhého vytvorenia položky.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceListItemCreateInput'
      responses:
        '201':
          description: Položka bola vytvorená.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotency-Key:
              description: Pôvodný idempotency key, ak bol poslaný v requeste.
              schema:
                type: string
            Idempotency-Status:
              description: '`Original` pri prvom spracovaní alebo `Repeated` pri vrátení pôvodnej odpovede.'
              schema:
                type: string
                enum: [Original, Repeated]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceListItem'
        '422':
          description: Validačná chyba alebo opätovné použitie idempotency key s iným payloadom.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      message:
                        type: string
                        example: The given data was invalid.
                      errors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                  - type: object
                    properties:
                      error:
                        type: string
                        example: Idempotency-Key reused with different request payload
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /price-list-items/{priceListItem}:
    parameters:
      - $ref: '#/components/parameters/PriceListItemId'
    get:
      tags: [Skladové a cenníkové položky]
      summary: Detail skladovej alebo cenníkovej položky
      operationId: showPriceListItem
      description: Vráti detail jednej skladovej alebo cenníkovej položky.
      responses:
        '200':
          description: Detail položky.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceListItem'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      tags: [Skladové a cenníkové položky]
      summary: Upraviť skladovú alebo cenníkovú položku
      operationId: updatePriceListItem
      description: >-
        Aktualizuje skladovú alebo cenníkovú položku. Fintoro API používa plný `PUT` kontrakt, preto pošlite celý
        výsledný stav položky vrátane required business polí.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceListItemUpdateInput'
      responses:
        '200':
          description: Položka bola aktualizovaná.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceListItem'
        '422':
          description: Validačná chyba.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [Skladové a cenníkové položky]
      summary: Zmazať skladovú alebo cenníkovú položku
      operationId: deletePriceListItem
      description: Zmaže skladovú alebo cenníkovú položku. Po úspešnom spracovaní endpoint nevracia response body.
      responses:
        '204':
          description: Položka bola zmazaná.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /webhook-subscriptions:
    get:
      tags: [Webhooky]
      summary: Zoznam odberov webhookov
      operationId: listWebhookSubscriptions
      description: Vráti všetky odbery webhookov aktuálnej firmy. Endpoint nepodporuje filtrovanie ani stránkovanie a je vhodný na synchronizáciu subscription konfigurácie do Vášho integračného rozhrania alebo administračného panelu integrácie.
      responses:
        '200':
          description: Zoznam odberov webhookov.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Zoznam odberov webhookov aktuálnej firmy.
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookSubscription'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Webhooky]
      summary: Vytvoriť odber webhookov
      operationId: createWebhookSubscription
      description: Vytvorí nový odber webhookov. `plainTextSecret` sa v odpovedi zobrazí iba pri vytvorení a musíte si ho bezpečne uložiť. Ak pošlete `Idempotency-Key`, opakované create volanie s rovnakým kľúčom a rovnakým payloadom vráti pôvodnú odpoveď bez druhého vytvorenia odberu. Pred uvedením do produkcie odporúčame mať pripraveného prijímača webhookov s overením podpisu, deduplikáciou podľa `webhook-id` a internou frontou na následné načítanie detailu resource-u.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscriptionInput'
      responses:
        '201':
          description: Odber webhookov bol vytvorený.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotency-Key:
              description: Pôvodný idempotency key, ak bol poslaný v requeste.
              schema:
                type: string
            Idempotency-Status:
              description: '`Original` pri prvom spracovaní alebo `Repeated` pri vrátení pôvodnej odpovede.'
              schema:
                type: string
                enum: [Original, Repeated]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionWithSecret'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: Validačná chyba alebo opätovné použitie idempotency key s iným payloadom.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              examples:
                idempotencyConflict:
                  summary: Idempotency key použitý s iným payloadom
                  value:
                    error: Idempotency-Key reused with different request payload
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  error:
                    type: [string, 'null']
                    example: Idempotency-Key reused with different request payload
                  errors:
                    type: [object, 'null']
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /webhook-subscriptions/{webhookSubscription}:
    parameters:
      - $ref: '#/components/parameters/WebhookSubscriptionId'
    get:
      tags: [Webhooky]
      summary: Detail odberu webhookov
      operationId: showWebhookSubscription
      description: Vráti detail jedného odberu webhookov aktuálnej firmy. Secret v otvorenej podobe sa v detaile už nikdy nevracia.
      responses:
        '200':
          description: Detail odberu webhookov.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      tags: [Webhooky]
      summary: Aktualizovať odber webhookov
      operationId: updateWebhookSubscription
      description: Aktualizuje odber webhookov cez plný `PUT` payload. Ak meníte `url` alebo `subscribedEvents`, existujúci secret sa nemení. Secret rotujte samostatne cez rotate-secret endpoint. Zmena konfigurácie odberu neprehráva historické udalosti spätne.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscriptionInput'
      responses:
        '200':
          description: Odber webhookov bol aktualizovaný.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [Webhooky]
      summary: Zmazať odber webhookov
      operationId: deleteWebhookSubscription
      description: Zmaže odber webhookov. Endpoint po úspešnom spracovaní nevracia response body.
      responses:
        '204':
          description: Odber webhookov bol zmazaný.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /webhook-subscriptions/{webhookSubscription}/rotate-secret:
    parameters:
      - $ref: '#/components/parameters/WebhookSubscriptionId'
    post:
      tags: [Webhooky]
      summary: Rotovať webhook secret
      operationId: rotateWebhookSubscriptionSecret
      description: Vygeneruje nový secret pre existujúci odber webhookov. Nový `plainTextSecret` sa v odpovedi zobrazí iba pri tejto rotácii; starý secret po úspešnej rotácii prestáva platiť.
      responses:
        '200':
          description: Secret odberu webhookov bol zrotovaný.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscriptionWithSecret'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /document-payments:
    get:
      tags: [Úhrady dokladov]
      summary: Zoznam úhrad dokladu
      operationId: listDocumentPayments
      description: Vráti zoznam úhrad konkrétneho public dokladu. Zoznam je nefiltrovaný a nepaginuje sa; vždy vracia všetky úhrady daného dokladu v poradí od najnovšej.
      parameters:
        - in: query
          name: documentType
          required: true
          description: Typ dokladu, pre ktorý chcete úhrady načítať. Podporované sú len `invoice`, `proforma` a `credit-note`.
          schema:
            type: string
            enum: [invoice, proforma, credit-note]
          example: invoice
        - in: query
          name: documentId
          required: true
          description: ID dokladu patriaceho.
          schema:
            type: integer
          example: 301
      responses:
        '200':
          description: Zoznam úhrad dokladu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Zoznam úhrad vybraného dokladu.
                    type: array
                    items:
                      $ref: '#/components/schemas/DocumentPayment'
        '422':
          description: Query parametre neprešli validačnými pravidlami.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Úhrady dokladov]
      summary: Vytvoriť úhradu dokladu
      operationId: createDocumentPayment
      description: |
        Vytvorí novú úhradu pre public doklad.

        ### Podporované typy dokladov

        Endpoint podporuje len `invoice`, `proforma` a `credit-note`.

        ### Business správanie

        - Úhrada sa vždy viaže na konkrétny doklad cez kombináciu `documentType` + `documentId`.
        - Minimálny create payload je len `documentType` + `documentId`; ostatné polia môžete vynechať a server ich dopočíta.
        - Ak `paymentDate` nepošlete, použije sa dnešný dátum.
        - Ak `paymentMethodId` nepošlete, použije sa spôsob úhrady zo zdrojového dokladu.
        - Ak `currencyId` nepošlete, použije sa mena zo zdrojového dokladu.
        - Ak `amount` nepošlete, použije sa aktuálna zostávajúca suma `toBePaid` zo zdrojového dokladu. Tento shortcut funguje len pri doklade s nenulovým `toBePaid`; inak endpoint vráti `422`.
        - Ak `amount` pošlete explicitne, môže mať najviac 2 desatinné miesta.
        - Ak `amount` pošlete explicitne, nesmie svojou veľkosťou presiahnuť aktuálne `toBePaid` a musí rešpektovať jeho znamienko, aby nevznikla preplatková úhrada alebo opačný smer platby.
        - Ak `currencyRate` nepošlete, systém ho odvodí z finálneho `paymentDate` kurzom z predchádzajúceho dňa.
        - Ak pošlete `currencyRate` pre inú menu než `EUR`, použije sa presne táto override hodnota.
        - Ak je finálna mena úhrady `EUR`, backend vždy uloží a vráti `currencyRate = 1.0`, aj keď pošlete inú hodnotu.
        - Pri vytvorení sa prepočíta stav úhrady dokladu rovnako ako vo web a mobile flowe.
        - Ak pošlete úhradu pre proformu a neskôr k nej vytvoríte daňový doklad k prijatej platbe, response úhrady vie obsahovať aj `receiptInvoice`.

        Ak pošlete `Idempotency-Key`, rovnaký key s rovnakým payloadom vráti pôvodnú odpoveď bez druhého vytvorenia úhrady.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentPaymentInput'
      responses:
        '201':
          description: Úhrada bola vytvorená.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotency-Key:
              description: Pôvodný idempotency key, ak bol poslaný v requeste.
              schema:
                type: string
            Idempotency-Status:
              description: '`Original` pri prvom spracovaní alebo `Repeated` pri vrátení pôvodnej odpovede.'
              schema:
                type: string
                enum: [Original, Repeated]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentPayment'
        '422':
          description: Request payload neprešiel validačnými pravidlami alebo business pravidlu úhrady.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  error:
                    type: [string, 'null']
                    example: Idempotency-Key reused with different request payload
                  errors:
                    type: [object, 'null']
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /document-mails:
    post:
      tags: [Dokladové e-maily]
      summary: Odoslať doklad emailom
      operationId: sendDocumentMail
      description: |
        Odošle podporovaný public doklad emailom.

        ### Podporované typy dokladov

        Endpoint podporuje `invoice`, `proforma`, `order`, `credit-note` a `quotation`.

        ### Business správanie

        - Cieľový doklad sa určuje cez kombináciu `documentType` + `documentId`.
        - Pole `to` akceptuje pole jednej alebo viacerých e-mailových adries.
        - Pole `type` je povinné kvôli jednotnému kontraktu. Pri `invoice` a `proforma` ovplyvňuje predmet a typ mailu (`regular`, `reminder`, `overdue_reminder`, `confirmation`). Pri `order`, `credit-note` a `quotation` sa aktuálne správa rovnako ako bežné odoslanie.
        - Endpoint nevracia response body; úspech potvrdzuje status `202 Accepted`.

        Ak pošlete `Idempotency-Key`, rovnaký key s rovnakým payloadom vráti pôvodnú odpoveď bez druhého odoslania emailu.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentMailInput'
      responses:
        '202':
          description: Požiadavka na odoslanie dokladu bola prijatá.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotency-Key:
              description: Pôvodný idempotency key, ak bol poslaný v requeste.
              schema:
                type: string
            Idempotency-Status:
              description: '`Original` pri prvom spracovaní alebo `Repeated` pri vrátení pôvodnej odpovede.'
              schema:
                type: string
                enum: [Original, Repeated]
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: Request payload neprešiel validačnými pravidlami.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  error:
                    type: [string, 'null']
                    example: Idempotency-Key reused with different request payload
                  errors:
                    type: [object, 'null']
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /document-payments/{documentPayment}:
    parameters:
      - $ref: '#/components/parameters/DocumentPaymentId'
    get:
      tags: [Úhrady dokladov]
      summary: Detail úhrady dokladu
      operationId: showDocumentPayment
      description: Vráti detail jednej úhrady. Response obsahuje typ a ID zdrojového dokladu, použitú menu, spôsob úhrady a prípadne aj preview daňového dokladu k prijatej platbe.
      responses:
        '200':
          description: Detail úhrady dokladu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentPayment'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [Úhrady dokladov]
      summary: Zmazať úhradu dokladu
      operationId: deleteDocumentPayment
      description: Zmaže úhradu dokladu. Ak je úhrada naviazaná na invoice typu `payment_receipt`, endpoint vráti `422` a zmazanie neprebehne.
      responses:
        '204':
          description: Úhrada bola zmazaná.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '422':
          description: Úhradu nie je možné zmazať kvôli business pravidlu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /invoices:
    get:
      tags: [Faktúry]
      summary: Zoznam faktúr
      operationId: listInvoices
      description: Vráti paginovaný zoznam faktúr 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.
      parameters:
        - in: query
          name: number
          required: false
          description: Filter podľa čísla dokladu.
          schema:
            type: string
          example: 2026
        - in: query
          name: clientId
          required: false
          description: Filter podľa klienta.
          schema:
            type: integer
          example: 101
        - in: query
          name: paymentStatus
          required: false
          description: Filter podľa stavu úhrady.
          schema:
            type: string
            enum: [paid, unpaid, partially_paid, overdue, will_not_be_paid]
          example: overdue
        - in: query
          name: issueDateFrom
          required: false
          description: Dátum vystavenia od.
          schema:
            type: string
            format: date
          example: '2026-02-01'
        - in: query
          name: issueDateTo
          required: false
          description: Dátum vystavenia do.
          schema:
            type: string
            format: date
          example: '2026-02-28'
        - in: query
          name: dueDateFrom
          required: false
          description: Dátum splatnosti od.
          schema:
            type: string
            format: date
          example: '2026-03-01'
        - in: query
          name: dueDateTo
          required: false
          description: Dátum splatnosti do.
          schema:
            type: string
            format: date
          example: '2026-03-31'
        - in: query
          name: deliveryDateFrom
          required: false
          description: Dátum dodania od.
          schema:
            type: string
            format: date
          example: '2026-02-01'
        - in: query
          name: deliveryDateTo
          required: false
          description: Dátum dodania do.
          schema:
            type: string
            format: date
          example: '2026-02-28'
        - in: query
          name: totalFrom
          required: false
          description: Minimálna celková suma s DPH v mene firmy.
          schema:
            type: number
            format: float
          example: 100
        - in: query
          name: totalTo
          required: false
          description: Maximálna celková suma s DPH v mene firmy.
          schema:
            type: number
            format: float
          example: 1000
        - in: query
          name: sortBy
          required: false
          description: Pole pre triedenie. Podporované sú len hodnoty, ktoré podporuje interný list filter faktúr.
          schema:
            type: string
            enum: [number, issueDate, dueDate, deliveryDate, totalWithVatEur]
            default: issueDate
          example: issueDate
        - in: query
          name: sortDirection
          required: false
          description: Smer triedenia.
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          example: desc
        - in: query
          name: perPage
          required: false
          description: Počet výsledkov na stránku.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 10
          example: 10
        - in: query
          name: page
          required: false
          description: Číslo stránky.
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 2
      responses:
        '200':
          description: Paginovaný zoznam faktúr v preview tvare.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Zoznam náhľadový objektov faktúr pre aktuálnu stránku.
                    type: array
                    items:
                      $ref: '#/components/schemas/InvoicePreview'
                  paginator:
                    description: Informácie o stránkovaní aktuálneho výsledku.
                    $ref: '#/components/schemas/Paginator'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Faktúry]
      summary: Vytvoriť faktúru
      operationId: createInvoice
      description: |
        Vytvorí novú faktúru.

        ### 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,
        - ak je finálna mena dokladu `EUR`, backend vždy uloží a vráti `currencyRate = 1.0`, aj keď pošlete inú hodnotu,
        - `issueDate` a `deliveryDate` defaultujú na dnešný deň.

        ### Ako funguje client resolution

        Client resolution je striktne deterministický:

        - ak pošlete `clientId`, backend načíta klienta podľa ID v rámci,
        - ak `clientId` nepošlete, objekt `client` sa používa na dopárovanie alebo vytvorenie klienta,
        - ak pošlete `clientId` aj objekt `client`, objekt `client` sa použije iba ako snapshot override pre doklad.

        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`, ktoré neexistuje alebo nepatrí, endpoint vráti `422` validačnú chybu pre pole `clientId`.

        Ak pošlete explicitné `bankAccountId` a taký záznam neexistuje alebo nepatrí, endpoint vráti `422` validačnú chybu pre pole `bankAccountId`.

        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.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceInput'
      responses:
        '201':
          description: Faktúra bola vytvorená.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotency-Key:
              description: Pôvodný idempotency key, ak bol poslaný v requeste.
              schema:
                type: string
            Idempotency-Status:
              description: '`Original` pri prvom spracovaní alebo `Repeated` pri vrátení pôvodnej odpovede.'
              schema:
                type: string
                enum: [Original, Repeated]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: Request je syntakticky validný, ale nedá sa spracovať kvôli business pravidlu alebo konfliktu idempotency key.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              examples:
                missingPrimaryBankAccount:
                  summary: Chýba primárny bankový účet firmy
                  value:
                    message: The given data was invalid.
                    errors:
                      bankAccountId:
                        - Company has no primary bank account configured.
                idempotencyConflict:
                  summary: Idempotency key použitý s iným payloadom
                  value:
                    error: Idempotency-Key reused with different request payload
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  error:
                    type: [string, 'null']
                    example: Idempotency-Key reused with different request payload
                  errors:
                    type: [object, 'null']
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /invoices/{invoice}:
    parameters:
      - $ref: '#/components/parameters/InvoiceId'
    get:
      tags: [Faktúry]
      summary: Detail faktúry
      operationId: showInvoice
      description: Vráti detail faktúry. Response obsahuje snapshot dodávateľa, historický snapshot klienta uložený priamo na doklade, naviazaný bankový účet použitý na faktúre a aj zoznam `payments` patriacich k tejto 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 živá väzba načítaná aj cez soft delete. Response zároveň vracia `webDokladUrl` pre verejný web doklad a `pdfDownloadUrl` pre priame stiahnutie PDF tej istej faktúry. V položkách faktúry nájdete aj ich `uuid`, ktoré môžete použiť pri update flowe na zachovanie väzieb na skladové alokácie a výdajky.
      responses:
        '200':
          description: Detail faktúry.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      tags: [Faktúry]
      summary: Upraviť faktúru
      operationId: updateInvoice
      description: |-
        Aktualizuje existujúcu faktúru.

        ### Ako funguje update

        - Update používa rovnaký payload kontrakt a rovnaké defaulty ako create flow.
        - Musíte poslať buď `clientId`, alebo objekt `client`.
        - `items` sú povinné vždy.
        - Ak pole nepošlete, backend nedrží pôvodnú hodnotu z faktúry, ale vyrieši ho rovnako ako pri create flowe z payloadu, klientských predvolieb a nastavenia dokladov firmy.
        - Pri update položiek môžete poslať pôvodné `uuid` existujúcich riadkov faktúry. Tieto UUID máte k dispozícii v detaile faktúry. Backend ich používa na udržanie väzieb na skladové výdajky pri synchronizácii alokácií. Pri create flowe `uuid` nie je súčasťou item request kontraktu; ak ho pošlete, backend ho ignoruje a vygeneruje vlastné UUID.

        ### Chybové stavy

        - `422`, ak explicitne pošlete `clientId`, ktoré neexistuje alebo nepatrí firme.
        - `422`, ak explicitne pošlete `bankAccountId`, ktoré neexistuje alebo nepatrí firme.
        - `422`, ak payload neprejde business validáciou, napríklad pri nevalidných položkách faktúry.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceUpdateInput'
      responses:
        '200':
          description: Faktúra bola aktualizovaná.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
        '422':
          description: Request payload neprešiel validačnými pravidlami.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [Faktúry]
      summary: Zmazať faktúru
      operationId: deleteInvoice
      description: Zmaže faktúru.
      responses:
        '204':
          description: Faktúra bola zmazaná.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /invoices/{invoice}/credit-notes:
    parameters:
      - $ref: '#/components/parameters/InvoiceId'
    post:
      tags: [Dobropisy]
      summary: Vytvoriť dobropis z faktúry
      operationId: createInvoiceCreditNote
      description: |
        Vytvorí dobropis priamo zo zvolenej faktúry.

        ### Kedy použiť tento endpoint

        Tento endpoint je DX shortcut pre bežný full-credit flow, keď už máte `invoiceId` a nechcete skladať celý payload ručne. Nenahrádza kanonický `POST /credit-notes`; ten je stále určený pre explicitný create flow s plným payloadom.

        ### Čo backend preberie zo zdrojovej faktúry

        - klienta vždy odvodí zo zvolenej faktúry,
        - prekopíruje položky ako záporné kreditné riadky vrátane skladových alokácií,
        - zachová bankový účet, menu, jazyk, spôsob úhrady, prenesenú daňovú povinnosť a document-level zľavu,
        - zachová `note`, `textAboveItems`, `constantSymbol` a `specificSymbol`, pokiaľ ich explicitne neoverride-nete tam, kde je to povolené.

        ### Defaulty a override polia

        - `issueDate` defaultuje na dnešný dátum.
        - `dueDate` defaultuje na finálny `issueDate`.
        - `deliveryDate` defaultuje na finálny `issueDate`.
        - Ak nepošlete `number`, backend vygeneruje číslo z primárneho číselného radu dobropisov. Ak pošlete `numericalSeriesId` bez `number`, číslo sa vygeneruje z tohto radu.
        - `variableSymbol` sa dopočíta server-side z finálneho čísla dobropisu.
        - Povolené overrides sú len polia definované v request schéme nižšie.

        Ak pošlete `Idempotency-Key`, rovnaký key s rovnakým payloadom vráti pôvodnú odpoveď bez druhého vytvorenia dobropisu.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceCreditNoteInput'
      responses:
        '201':
          description: Dobropis bol vytvorený zo zvolenej faktúry.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotency-Key:
              description: Pôvodný idempotency key, ak bol poslaný v requeste.
              schema:
                type: string
            Idempotency-Status:
              description: '`Original` pri prvom spracovaní alebo `Repeated` pri vrátení pôvodnej odpovede.'
              schema:
                type: string
                enum: [Original, Repeated]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditNote'
        '422':
          description: Request payload neprešiel validačnými pravidlami shortcut endpointu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /invoices/{invoice}/pdf:
    parameters:
      - $ref: '#/components/parameters/InvoiceId'
    get:
      tags: [Faktúry]
      summary: Stiahnuť faktúru ako pdf
      operationId: downloadInvoicePdf
      description: Stiahne PDF export faktúry ako prílohu (`application/pdf`). URL tohto endpointu nájdete aj v poli `pdfDownloadUrl` v detaile faktúry.
      responses:
        '200':
          description: PDF export faktúry.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /credit-notes:
    get:
      tags: [Dobropisy]
      summary: Zoznam dobropisov
      operationId: listCreditNotes
      description: Vráti paginovaný zoznam dobropisov v zjednodušenom preview tvare. Endpoint je vhodný na listy, synchronizáciu a rýchly prehľad nad stavom dobropisov; pre detail použite detail endpoint dobropisu.
      parameters:
        - in: query
          name: number
          required: false
          description: Filter podľa čísla dokladu.
          schema:
            type: string
          example: 2026
        - in: query
          name: clientId
          required: false
          description: Filter podľa klienta.
          schema:
            type: integer
          example: 101
        - in: query
          name: paymentStatus
          required: false
          description: Filter podľa stavu dobropisu.
          schema:
            type: string
            enum: [paid, unpaid, partially_paid, overdue, will_not_be_paid]
          example: overdue
        - in: query
          name: issueDateFrom
          required: false
          description: Dátum vystavenia od.
          schema:
            type: string
            format: date
          example: '2026-02-01'
        - in: query
          name: issueDateTo
          required: false
          description: Dátum vystavenia do.
          schema:
            type: string
            format: date
          example: '2026-02-28'
        - in: query
          name: dueDateFrom
          required: false
          description: Dátum splatnosti od.
          schema:
            type: string
            format: date
          example: '2026-03-01'
        - in: query
          name: dueDateTo
          required: false
          description: Dátum splatnosti do.
          schema:
            type: string
            format: date
          example: '2026-03-31'
        - in: query
          name: deliveryDateFrom
          required: false
          description: Dátum dodania od.
          schema:
            type: string
            format: date
          example: '2026-02-01'
        - in: query
          name: deliveryDateTo
          required: false
          description: Dátum dodania do.
          schema:
            type: string
            format: date
          example: '2026-02-28'
        - in: query
          name: totalFrom
          required: false
          description: Minimálna celková suma bez DPH.
          schema:
            type: number
            format: float
          example: -500
        - in: query
          name: totalTo
          required: false
          description: Maximálna celková suma bez DPH.
          schema:
            type: number
            format: float
          example: 0
        - in: query
          name: sortBy
          required: false
          description: Pole pre triedenie.
          schema:
            type: string
            enum: [number, issueDate, dueDate, deliveryDate, total, totalWithVat]
            default: issueDate
          example: issueDate
        - in: query
          name: sortDirection
          required: false
          description: Smer triedenia.
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          example: desc
        - in: query
          name: perPage
          required: false
          description: Počet výsledkov na stránku.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 10
          example: 10
        - in: query
          name: page
          required: false
          description: Číslo stránky.
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 2
      responses:
        '200':
          description: Paginovaný zoznam dobropisov v preview tvare.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Zoznam náhľadový objektov dobropisov pre aktuálnu stránku.
                    type: array
                    items:
                      $ref: '#/components/schemas/CreditNotePreview'
                  paginator:
                    description: Informácie o stránkovaní aktuálneho výsledku.
                    $ref: '#/components/schemas/Paginator'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Dobropisy]
      summary: Vytvoriť dobropis
      operationId: createCreditNote
      description: |
        Vytvorí nový dobropis.

        ### Business pravidlá

        - Dobropis musí byť naviazaný na existujúcu faktúru cez `invoiceId`.
        - Klient dobropisu sa vždy preberá zo zvolenej zdrojovej faktúry; `clientId` neposielajte.
        - Tento endpoint nepodporuje inline `client` payload, client resolution ani automatické vytváranie klienta.
        - Výsledná celková suma dobropisu musí zostať záporná; ak payload vyprodukuje kladný doklad, endpoint vráti `422`.

        ### Payload kontrakt

        Na rozdiel od Fintoro API faktúr a zálohových faktúr ide o explicitný create flow bez smart defaultov. Pošlite kompletný business payload dokladu vrátane dátumov, bankového účtu, symbolov, meny a položiek.

        Ak používate skladové alokácie na položkách, backend ich spracuje ako príjemové pohyby naviazané na dobropis.

        Ak pošlete `Idempotency-Key`, rovnaký key s rovnakým payloadom vráti pôvodnú odpoveď bez druhého vytvorenia dobropisu.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditNoteInput'
      responses:
        '201':
          description: Dobropis bol vytvorený.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotency-Key:
              description: Pôvodný idempotency key, ak bol poslaný v requeste.
              schema:
                type: string
            Idempotency-Status:
              description: '`Original` pri prvom spracovaní alebo `Repeated` pri vrátení pôvodnej odpovede.'
              schema:
                type: string
                enum: [Original, Repeated]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditNote'
        '422':
          description: Request payload neprešiel validačnými alebo business pravidlami dobropisu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /credit-notes/{creditNote}:
    parameters:
      - $ref: '#/components/parameters/CreditNoteId'
    get:
      tags: [Dobropisy]
      summary: Detail dobropisu
      operationId: showCreditNote
      description: Vráti detail dobropisu. Response obsahuje snapshot dodávateľa, historický snapshot klienta uložený na dobropise, live väzbu na bankový účet použitý na doklade, `invoiceId` pôvodnej faktúry a aj zoznam `payments` patriacich k tomuto dobropisu. Nájdete tu aj `webDokladUrl` a `pdfDownloadUrl` pre ďalšie integračné flowy.
      responses:
        '200':
          description: Detail dobropisu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditNote'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      tags: [Dobropisy]
      summary: Upraviť dobropis
      operationId: updateCreditNote
      description: |-
        Aktualizuje existujúci dobropis.

        ### Ako funguje update

        - Update používa plný `PUT` kontrakt; položky sú povinné vždy.
        - `invoiceId` zostáva povinné a klient dobropisu sa vždy preberá zo zvolenej faktúry.
        - Omitted polia sa nedoťahujú z aktuálneho dobropisu, preto pošlite celý business payload.
        - Pri položkách môžete poslať existujúce `uuid`, aby backend vedel zachovať väzby na skladové príjemky pri synchronizácii. Pri create flowe `uuid` nie je súčasťou item request kontraktu; ak ho pošlete, backend ho ignoruje a vygeneruje vlastné UUID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditNoteUpdateInput'
      responses:
        '200':
          description: Dobropis bol aktualizovaný.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditNote'
        '422':
          description: Request payload neprešiel validačnými alebo business pravidlami dobropisu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [Dobropisy]
      summary: Zmazať dobropis
      operationId: deleteCreditNote
      description: Zmaže dobropis.
      responses:
        '204':
          description: Dobropis bol zmazaný.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /credit-notes/{creditNote}/pdf:
    parameters:
      - $ref: '#/components/parameters/CreditNoteId'
    get:
      tags: [Dobropisy]
      summary: Stiahnuť dobropis ako pdf
      operationId: downloadCreditNotePdf
      description: Stiahne PDF export dobropisu ako prílohu (`application/pdf`). URL tohto endpointu nájdete aj v poli `pdfDownloadUrl` v detaile dobropisu.
      responses:
        '200':
          description: PDF export dobropisu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /proformas:
    get:
      tags: [Zálohové faktúry]
      summary: Zoznam zálohových faktúr
      operationId: listProformas
      description: Vráti paginovaný zoznam zálohových faktúr v zjednodušenom preview tvare. Endpoint je vhodný na listy, synchronizáciu a rýchly prehľad nad stavom úhrad; pre detail použite detail endpoint zálohovej faktúry.
      parameters:
        - in: query
          name: number
          required: false
          description: Filter podľa čísla dokladu.
          schema:
            type: string
          example: 2026
        - in: query
          name: clientId
          required: false
          description: Filter podľa klienta.
          schema:
            type: integer
          example: 101
        - in: query
          name: paymentStatus
          required: false
          description: Filter podľa stavu úhrady.
          schema:
            type: string
            enum: [paid, unpaid, partially_paid, overdue, will_not_be_paid]
          example: overdue
        - in: query
          name: issueDateFrom
          required: false
          description: Dátum vystavenia od.
          schema:
            type: string
            format: date
          example: '2026-02-01'
        - in: query
          name: issueDateTo
          required: false
          description: Dátum vystavenia do.
          schema:
            type: string
            format: date
          example: '2026-02-28'
        - in: query
          name: dueDateFrom
          required: false
          description: Dátum splatnosti od.
          schema:
            type: string
            format: date
          example: '2026-03-01'
        - in: query
          name: dueDateTo
          required: false
          description: Dátum splatnosti do.
          schema:
            type: string
            format: date
          example: '2026-03-31'
        - in: query
          name: totalFrom
          required: false
          description: Minimálna celková suma bez DPH.
          schema:
            type: number
            format: float
          example: 100
        - in: query
          name: totalTo
          required: false
          description: Maximálna celková suma bez DPH.
          schema:
            type: number
            format: float
          example: 1000
        - in: query
          name: withoutInvoice
          required: false
          description: Ak je `true`, vrátia sa len zálohové faktúry, ktoré ešte nemajú naviazanú finálnu faktúru.
          schema:
            type: boolean
          example: true
        - in: query
          name: sortBy
          required: false
          description: Pole pre triedenie.
          schema:
            type: string
            enum: [number, issueDate, dueDate, total, totalWithVat]
            default: issueDate
          example: issueDate
        - in: query
          name: sortDirection
          required: false
          description: Smer triedenia.
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          example: desc
        - in: query
          name: perPage
          required: false
          description: Počet výsledkov na stránku.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 10
          example: 10
        - in: query
          name: page
          required: false
          description: Číslo stránky.
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 2
      responses:
        '200':
          description: Paginovaný zoznam zálohových faktúr v preview tvare.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Zoznam náhľadový objektov zálohových faktúr pre aktuálnu stránku.
                    type: array
                    items:
                      $ref: '#/components/schemas/ProformaPreview'
                  paginator:
                    description: Informácie o stránkovaní aktuálneho výsledku.
                    $ref: '#/components/schemas/Paginator'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Zálohové faktúry]
      summary: Vytvoriť zálohovú faktúru
      operationId: createProforma
      description: |
        Vytvorí novú zálohovú faktúru.

        ### Odporúčaný flow

        Odporúčaný happy path je poslať `clientId` a `items`.

        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 túto konkrétnu zálohovú faktúru.

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

        - `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,
        - `dueDateDays` sa môže dopočítať z klientských preferencií alebo z nastavenia dokladov firmy,
        - `deliveryMethodId`, `paymentMethodId`, `currencyId`, `languageId`, `qrTypeId`, `note` a `textAboveItems` sa môžu dopočítať z klienta alebo z firemných nastavení,
        - `issueDate` defaultuje na dnešný deň.

        ### Ako funguje client resolution

        Client resolution je striktne deterministický:

        - ak pošlete `clientId`, backend načíta klienta podľa ID v rámci,
        - ak `clientId` nepošlete, objekt `client` sa používa na dopárovanie alebo vytvorenie klienta,
        - ak pošlete `clientId` aj objekt `client`, objekt `client` sa použije iba ako snapshot override pre doklad.

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

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

        Ak pošlete `Idempotency-Key`, rovnaký key s rovnakým payloadom vráti pôvodnú odpoveď bez druhého vytvorenia zálohovej faktúry.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProformaInput'
      responses:
        '201':
          description: Zálohová faktúra bola vytvorená.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotency-Key:
              description: Pôvodný idempotency key, ak bol poslaný v requeste.
              schema:
                type: string
            Idempotency-Status:
              description: '`Original` pri prvom spracovaní alebo `Repeated` pri vrátení pôvodnej odpovede.'
              schema:
                type: string
                enum: [Original, Repeated]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proforma'
        '422':
          description: Request payload neprešiel validačnými pravidlami alebo sa nedá spracovať kvôli business pravidlu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              examples:
                missingPrimaryBankAccount:
                  summary: Chýba primárny bankový účet firmy
                  value:
                    message: The given data was invalid.
                    errors:
                      bankAccountId:
                        - Company has no primary bank account configured.
                idempotencyConflict:
                  summary: Idempotency key použitý s iným payloadom
                  value:
                    error: Idempotency-Key reused with different request payload
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  error:
                    type: [string, 'null']
                    example: Idempotency-Key reused with different request payload
                  errors:
                    type: [object, 'null']
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /proformas/{proforma}:
    parameters:
      - $ref: '#/components/parameters/ProformaId'
    get:
      tags: [Zálohové faktúry]
      summary: Detail zálohovej faktúry
      operationId: showProforma
      description: Vráti detail zálohovej faktúry. Response obsahuje snapshot dodávateľa, historický snapshot klienta uložený priamo na doklade, naviazaný bankový účet použitý na doklade a aj zoznam `payments` patriacich k tejto zálohovej faktúre. Response zároveň vracia `webDokladUrl` pre verejný web doklad a `pdfDownloadUrl` pre priame stiahnutie PDF.
      responses:
        '200':
          description: Detail zálohovej faktúry.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proforma'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      tags: [Zálohové faktúry]
      summary: Aktualizovať zálohovú faktúru
      operationId: updateProforma
      description: Zálohovú faktúru aktualizuje cez plný `PUT` kontrakt. Update používa rovnaké polia, rovnaké validačné pravidlá a rovnaké defaulty ako create flow. Omitted polia sa nepreberajú z pôvodného dokladu; backend ich vyrieši rovnako ako pri create.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProformaUpdateInput'
      responses:
        '200':
          description: Zálohová faktúra bola aktualizovaná.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proforma'
        '422':
          description: Request payload neprešiel validačnými pravidlami.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [Zálohové faktúry]
      summary: Zmazať zálohovú faktúru
      operationId: deleteProforma
      description: Zmaže zálohovú faktúru.
      responses:
        '204':
          description: Zálohová faktúra bola zmazaná.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /proformas/{proforma}/pdf:
    parameters:
      - $ref: '#/components/parameters/ProformaId'
    get:
      tags: [Zálohové faktúry]
      summary: Stiahnuť zálohovú faktúru ako pdf
      operationId: downloadProformaPdf
      description: Stiahne PDF export zálohovej faktúry ako prílohu (`application/pdf`). URL tohto endpointu nájdete aj v poli `pdfDownloadUrl` v detaile zálohovej faktúry.
      responses:
        '200':
          description: PDF export zálohovej faktúry.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /orders:
    get:
      tags: [Objednávky]
      summary: Zoznam objednávok
      operationId: listOrders
      description: Vráti paginovaný zoznam objednávok v zjednodušenom preview tvare. Endpoint je vhodný na listy, synchronizáciu a rýchly prehľad nad rozpracovanými dokladmi; pre detail použite detail endpoint objednávky.
      parameters:
        - in: query
          name: number
          required: false
          description: Filter podľa prefixu čísla dokladu. Backend používa prefix match, nie fulltext ani contains.
          schema:
            type: string
          example: 2026
        - in: query
          name: clientId
          required: false
          description: Filter podľa klienta.
          schema:
            type: integer
          example: 101
        - in: query
          name: issueDateFrom
          required: false
          description: Dátum vystavenia od.
          schema:
            type: string
            format: date
          example: '2026-02-01'
        - in: query
          name: issueDateTo
          required: false
          description: Dátum vystavenia do.
          schema:
            type: string
            format: date
          example: '2026-02-28'
        - in: query
          name: totalFrom
          required: false
          description: Minimálna celková suma bez DPH po zľavách.
          schema:
            type: number
            format: float
          example: 100
        - in: query
          name: totalTo
          required: false
          description: Maximálna celková suma bez DPH po zľavách.
          schema:
            type: number
            format: float
          example: 1000
        - in: query
          name: withoutInvoice
          required: false
          description: Ak je `true`, vrátia sa len objednávky, ktoré ešte nemajú naviazanú finálnu faktúru.
          schema:
            type: boolean
          example: true
        - in: query
          name: withoutProforma
          required: false
          description: Ak je `true`, vrátia sa len objednávky, ktoré ešte nemajú naviazanú zálohovú faktúru.
          schema:
            type: boolean
          example: true
        - in: query
          name: sortBy
          required: false
          description: Pole pre triedenie.
          schema:
            type: string
            enum: [number, issueDate, total, totalWithVat]
            default: issueDate
          example: issueDate
        - in: query
          name: sortDirection
          required: false
          description: Smer triedenia.
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          example: desc
        - in: query
          name: perPage
          required: false
          description: Počet výsledkov na stránku.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 10
          example: 10
        - in: query
          name: page
          required: false
          description: Číslo stránky.
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 2
      responses:
        '200':
          description: Paginovaný zoznam objednávok v preview tvare.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Zoznam náhľadový objektov objednávok pre aktuálnu stránku.
                    type: array
                    items:
                      $ref: '#/components/schemas/OrderPreview'
                  paginator:
                    description: Informácie o stránkovaní aktuálneho výsledku.
                    $ref: '#/components/schemas/Paginator'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Objednávky]
      summary: Vytvoriť objednávku
      operationId: createOrder
      description: |
        Vytvorí novú objednávku.

        ### Odporúčaný flow

        Odporúčaný happy path je poslať `clientId` a `items`.

        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 túto konkrétnu objednávku.

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

        V praxi to znamená napríklad:

        - `number` a `numericalSeriesId` sa doplnia z primárneho číselného radu, ak ich nepošlete,
        - `issueDate` defaultuje na dnešný deň,
        - `transferTaxLiability` defaultuje na `false`,
        - `deliveryMethodId`, `paymentMethodId`, `currencyId`, `languageId`, `note` a `textAboveItems` sa môžu dopočítať z klienta alebo z firemných nastavení.

        ### Ako funguje client resolution

        Client resolution je striktne deterministický:

        - ak pošlete `clientId`, backend načíta klienta podľa ID v rámci,
        - ak `clientId` nepošlete, objekt `client` sa používa na dopárovanie alebo vytvorenie klienta,
        - ak pošlete `clientId` aj objekt `client`, objekt `client` sa použije iba ako snapshot override pre doklad.

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

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

        `priceListItemId` slúži len na input hydratáciu. Response objednávky vracia už finálnu kanonickú položku a neponecháva tento cenníkový odkaz ako samostatné pole.

        ### Väzba na cenovú ponuku

        Voliteľné `quotationId` môžete použiť na napojenie objednávky na existujúcu cenovú ponuku, ktorá ešte nie je priradená k inej objednávke.

        Ak pošlete `Idempotency-Key`, rovnaký key s rovnakým payloadom vráti pôvodnú odpoveď bez druhého vytvorenia objednávky.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderInput'
      responses:
        '201':
          description: Objednávka bola vytvorená.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotency-Key:
              description: Pôvodný idempotency key, ak bol poslaný v requeste.
              schema:
                type: string
            Idempotency-Status:
              description: '`Original` pri prvom spracovaní alebo `Repeated` pri vrátení pôvodnej odpovede.'
              schema:
                type: string
                enum: [Original, Repeated]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '422':
          description: Request payload neprešiel validačnými pravidlami alebo sa nedá spracovať kvôli business pravidlu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              examples:
                idempotencyConflict:
                  summary: Idempotency key použitý s iným payloadom
                  value:
                    error: Idempotency-Key reused with different request payload
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  error:
                    type: [string, 'null']
                    example: Idempotency-Key reused with different request payload
                  errors:
                    type: [object, 'null']
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /orders/{order}:
    parameters:
      - $ref: '#/components/parameters/OrderId'
    get:
      tags: [Objednávky]
      summary: Detail objednávky
      operationId: showOrder
      description: Vráti detail objednávky. Response obsahuje snapshot dodávateľa, historický snapshot klienta uložený priamo na doklade, finálne vypočítané položky objednávky a URL na verejný web doklad aj PDF download endpoint.
      responses:
        '200':
          description: Detail objednávky.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      tags: [Objednávky]
      summary: Aktualizovať objednávku
      operationId: updateOrder
      description: |-
        Aktualizuje existujúcu objednávku cez plný `PUT` kontrakt.

        - Update používa rovnaké polia, rovnaké validačné pravidlá a rovnaké defaulty ako create flow.
        - Musíte poslať buď `clientId`, alebo objekt `client`.
        - `items` sú povinné vždy.
        - Ak pole nepošlete, backend nedrží pôvodnú hodnotu z objednávky, ale vyrieši ho rovnako ako pri create flowe z payloadu, klientských predvolieb a nastavenia dokladov firmy.
        - Ak pri update vynecháte `quotationId`, existujúca väzba objednávky na cenovú ponuku sa odstráni. To isté platí, ak pošlete explicitné `null`.
        - Order update nepoužíva per-item `uuid`; ak ho pošlete, backend ho ignoruje a položky sa pri update skladajú z finálneho payloadu znova.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderUpdateInput'
      responses:
        '200':
          description: Objednávka bola aktualizovaná.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '422':
          description: Request payload neprešiel validačnými pravidlami.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [Objednávky]
      summary: Zmazať objednávku
      operationId: deleteOrder
      description: Zmaže objednávku.
      responses:
        '204':
          description: Objednávka bola zmazaná.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /orders/{order}/pdf:
    parameters:
      - $ref: '#/components/parameters/OrderId'
    get:
      tags: [Objednávky]
      summary: Stiahnuť objednávku ako pdf
      operationId: downloadOrderPdf
      description: Stiahne PDF export objednávky ako prílohu (`application/pdf`). URL tohto endpointu nájdete aj v poli `pdfDownloadUrl` v detaile objednávky.
      responses:
        '200':
          description: PDF export objednávky.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /quotations:
    get:
      tags: [Cenové ponuky]
      summary: Zoznam cenových ponúk
      operationId: listQuotations
      description: Vráti paginovaný zoznam cenových ponúk v zjednodušenom preview tvare. Endpoint je vhodný na listy, synchronizáciu a rýchly prehľad nad rozpracovanými ponukami; pre detail použite detail endpoint cenovej ponuky.
      parameters:
        - in: query
          name: number
          required: false
          description: Filter podľa čísla dokladu. Backend používa contains match, nie prefix match.
          schema:
            type: string
          example: 2026
        - in: query
          name: clientId
          required: false
          description: Filter podľa klienta.
          schema:
            type: integer
          example: 101
        - in: query
          name: issueDateFrom
          required: false
          description: Dátum vystavenia od.
          schema:
            type: string
            format: date
          example: '2026-02-01'
        - in: query
          name: issueDateTo
          required: false
          description: Dátum vystavenia do.
          schema:
            type: string
            format: date
          example: '2026-02-28'
        - in: query
          name: validityDateFrom
          required: false
          description: Dátum platnosti od.
          schema:
            type: string
            format: date
          example: '2026-03-01'
        - in: query
          name: validityDateTo
          required: false
          description: Dátum platnosti do.
          schema:
            type: string
            format: date
          example: '2026-03-31'
        - in: query
          name: status
          required: false
          description: Filter podľa stavu cenovej ponuky.
          schema:
            type: string
            enum: [waiting, accepted, rejected]
          example: waiting
        - in: query
          name: totalFrom
          required: false
          description: Minimálna celková suma s DPH po zľavách.
          schema:
            type: number
            format: float
          example: 100
        - in: query
          name: totalTo
          required: false
          description: Maximálna celková suma s DPH po zľavách.
          schema:
            type: number
            format: float
          example: 1000
        - in: query
          name: withoutInvoice
          required: false
          description: Ak je `true`, vrátia sa len cenové ponuky, ktoré ešte nemajú naviazanú finálnu faktúru.
          schema:
            type: boolean
          example: true
        - in: query
          name: withoutProforma
          required: false
          description: Ak je `true`, vrátia sa len cenové ponuky, ktoré ešte nemajú naviazanú zálohovú faktúru.
          schema:
            type: boolean
          example: true
        - in: query
          name: withoutOrder
          required: false
          description: Ak je `true`, vrátia sa len cenové ponuky, ktoré ešte nemajú naviazanú objednávku.
          schema:
            type: boolean
          example: true
        - in: query
          name: sortBy
          required: false
          description: Pole pre triedenie.
          schema:
            type: string
            enum: [number, issueDate, validityDate, total, totalWithVat]
            default: issueDate
          example: validityDate
        - in: query
          name: sortDirection
          required: false
          description: Smer triedenia.
          schema:
            type: string
            enum: [asc, desc]
            default: desc
          example: desc
        - in: query
          name: perPage
          required: false
          description: Počet výsledkov na stránku.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 10
          example: 10
        - in: query
          name: page
          required: false
          description: Číslo stránky.
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 2
      responses:
        '200':
          description: Paginovaný zoznam cenových ponúk v preview tvare.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Zoznam náhľadový objektov cenových ponúk pre aktuálnu stránku.
                    type: array
                    items:
                      $ref: '#/components/schemas/QuotationPreview'
                  paginator:
                    description: Informácie o stránkovaní aktuálneho výsledku.
                    $ref: '#/components/schemas/Paginator'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Cenové ponuky]
      summary: Vytvoriť cenovú ponuku
      operationId: createQuotation
      description: |
        Vytvorí novú cenovú ponuku.

        ### Odporúčaný flow

        Odporúčaný happy path je poslať `clientId` a `items`.

        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 túto konkrétnu cenovú ponuku.

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

        V praxi to znamená napríklad:

        - `number` a `numericalSeriesId` sa doplnia z primárneho číselného radu, ak ich nepošlete,
        - `issueDate` defaultuje na dnešný deň,
        - `validityDate` defaultuje na `issueDate + 30 dní`,
        - `transferTaxLiability` defaultuje na `false`,
        - `currencyId`, `languageId`, `note` a `textAboveItems` sa môžu dopočítať z klienta alebo z firemných nastavení.

        ### Ako funguje client resolution

        Client resolution je striktne deterministický:

        - ak pošlete `clientId`, backend načíta klienta podľa ID v rámci,
        - ak `clientId` nepošlete, objekt `client` sa používa na dopárovanie alebo vytvorenie klienta,
        - ak pošlete `clientId` aj objekt `client`, objekt `client` sa použije iba ako snapshot override pre doklad.

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

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

        `priceListItemId` slúži len na input hydratáciu. Response cenovej ponuky vracia už finálnu kanonickú položku a neponecháva tento cenníkový odkaz ako samostatné pole.

        Cenové ponuky nepoužívajú per-item `uuid`; ak ho pošlete, backend ho ignoruje. `warehouseAllocations` pri cenových ponukách nie sú podporované.

        Stav novej cenovej ponuky sa vytvára ako `waiting`.

        Ak pošlete `Idempotency-Key`, rovnaký key s rovnakým payloadom vráti pôvodnú odpoveď bez druhého vytvorenia cenovej ponuky.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuotationInput'
      responses:
        '201':
          description: Cenová ponuka bola vytvorená.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotency-Key:
              description: Pôvodný idempotency key, ak bol poslaný v requeste.
              schema:
                type: string
            Idempotency-Status:
              description: '`Original` pri prvom spracovaní alebo `Repeated` pri vrátení pôvodnej odpovede.'
              schema:
                type: string
                enum: [Original, Repeated]
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quotation'
        '422':
          description: Request payload neprešiel validačnými pravidlami alebo sa nedá spracovať kvôli business pravidlu.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              examples:
                idempotencyConflict:
                  summary: Idempotency key použitý s iným payloadom
                  value:
                    error: Idempotency-Key reused with different request payload
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  error:
                    type: [string, 'null']
                    example: Idempotency-Key reused with different request payload
                  errors:
                    type: [object, 'null']
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /quotations/{quotation}:
    parameters:
      - $ref: '#/components/parameters/QuotationId'
    get:
      tags: [Cenové ponuky]
      summary: Detail cenovej ponuky
      operationId: showQuotation
      description: Vráti detail cenovej ponuky. Response obsahuje snapshot dodávateľa, historický snapshot klienta uložený priamo na doklade, finálne vypočítané položky cenovej ponuky a URL na verejný web doklad aj PDF download endpoint.
      responses:
        '200':
          description: Detail cenovej ponuky.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quotation'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    put:
      tags: [Cenové ponuky]
      summary: Aktualizovať cenovú ponuku
      operationId: updateQuotation
      description: |-
        Aktualizuje existujúcu cenovú ponuku cez plný `PUT` kontrakt.

        - Update používa rovnaké polia, rovnaké validačné pravidlá a rovnaké defaulty ako create flow.
        - Musíte poslať buď `clientId`, alebo objekt `client`.
        - `items` sú povinné vždy.
        - Ak pole nepošlete, backend nedrží pôvodnú hodnotu z cenovej ponuky, ale vyrieši ho rovnako ako pri create flowe z payloadu, klientských predvolieb a nastavenia dokladov firmy.
        - Update cenovej ponuky nepoužíva per-item `uuid`; ak ho pošlete, backend ho ignoruje a položky sa pri update skladajú z finálneho payloadu znova.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuotationUpdateInput'
      responses:
        '200':
          description: Cenová ponuka bola aktualizovaná.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quotation'
        '422':
          description: Request payload neprešiel validačnými pravidlami.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The given data was invalid.
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [Cenové ponuky]
      summary: Zmazať cenovú ponuku
      operationId: deleteQuotation
      description: Zmaže cenovú ponuku.
      responses:
        '204':
          description: Cenová ponuka bola zmazaná.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /quotations/{quotation}/pdf:
    parameters:
      - $ref: '#/components/parameters/QuotationId'
    get:
      tags: [Cenové ponuky]
      summary: Stiahnuť cenovú ponuku ako pdf
      operationId: downloadQuotationPdf
      description: Stiahne PDF export cenovej ponuky ako prílohu (`application/pdf`). URL tohto endpointu nájdete aj v poli `pdfDownloadUrl` v detaile cenovej ponuky.
      responses:
        '200':
          description: PDF export cenovej ponuky.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Token
      description: Bearer token vytvorený pre konkrétnu firmu v Integrácie → API.
  parameters:
    ClientId:
      name: client
      in: path
      required: true
      description: ID klienta.
      schema:
        type: integer
        example: 101
    SupplierId:
      name: supplier
      in: path
      required: true
      description: ID dodávateľa.
      schema:
        type: integer
        example: 151
    BusinessCaseStatusId:
      name: businessCaseStatus
      in: path
      required: true
      description: ID stavu obchodného prípadu.
      schema:
        type: integer
        example: 41
    BusinessCaseId:
      name: businessCase
      in: path
      required: true
      description: ID obchodného prípadu.
      schema:
        type: integer
        example: 501
    ContactActivityLogId:
      name: contactActivityLog
      in: path
      required: true
      description: ID kontaktnej aktivity.
      schema:
        type: integer
        example: 551
    BankAccountId:
      name: bankAccount
      in: path
      required: true
      description: ID bankového účtu.
      schema:
        type: integer
        example: 201
    WarehouseId:
      name: warehouse
      in: path
      required: true
      description: ID skladu.
      schema:
        type: integer
        example: 301
    WarehouseInboundReceiptId:
      name: warehouseInboundReceipt
      in: path
      required: true
      description: ID skladovej príjemky.
      schema:
        type: integer
        example: 901
    WarehouseOutboundReceiptId:
      name: warehouseOutboundReceipt
      in: path
      required: true
      description: ID skladovej výdajky.
      schema:
        type: integer
        example: 951
    PriceListItemId:
      name: priceListItem
      in: path
      required: true
      description: ID skladovej alebo cenníkovej položky.
      schema:
        type: integer
        example: 701
    WebhookSubscriptionId:
      name: webhookSubscription
      in: path
      required: true
      description: ID odberu webhookov.
      schema:
        type: integer
        example: 801
    InvoiceId:
      name: invoice
      in: path
      required: true
      description: ID faktúry.
      schema:
        type: integer
        example: 301
    CreditNoteId:
      name: creditNote
      in: path
      required: true
      description: ID dobropisu.
      schema:
        type: integer
        example: 351
    NumericalSeriesId:
      name: numericalSeries
      in: path
      required: true
      description: ID číselného radu.
      schema:
        type: integer
        example: 901
    DocumentPaymentId:
      name: documentPayment
      in: path
      required: true
      description: ID úhrady dokladu.
      schema:
        type: integer
        example: 801
    ProformaId:
      name: proforma
      in: path
      required: true
      description: ID zálohovej faktúry.
      schema:
        type: integer
        example: 401
    OrderId:
      name: order
      in: path
      required: true
      description: ID objednávky.
      schema:
        type: integer
        example: 501
    QuotationId:
      name: quotation
      in: path
      required: true
      description: ID cenovej ponuky.
      schema:
        type: integer
        example: 601
    SubjectId:
      name: subject
      in: path
      required: true
      description: ID subjektu z referenčného registra.
      schema:
        type: integer
        example: 12345678
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: 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ť.
      schema:
        type: string
        example: invoice-create-2026-03-03-001
    AcceptLanguage:
      name: Accept-Language
      in: header
      required: false
      description: Voliteľný jazyk response. Lokalizuje systémové názvy v lookupoch, v súvisiacich objektoch v odpovediach aj vo validačných chybách. User-generated dáta tým nemeníte.
      schema:
        type: string
        example: en
  headers:
    XRequestId:
      description: Unikátny identifikátor requestu pre traceovanie, audit a support diagnostiku.
      schema:
        type: string
        example: req_public_api_01
    ContentLanguage:
      description: Jazyk vybraný pre request podľa headera `Accept-Language`.
      schema:
        type: string
        example: en
  responses:
    Unauthorized:
      description: Chýba, je neplatný alebo bol revokovaný bearer token pre Fintoro API.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
        Content-Language:
          $ref: '#/components/headers/ContentLanguage'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthenticated.
    NotFound:
      description: Požadovaný zdroj sa nenašiel.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
        Content-Language:
          $ref: '#/components/headers/ContentLanguage'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: No query results for model.
    Forbidden:
      description: Prístup k zdroju nie je povolený alebo scope.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
        Content-Language:
          $ref: '#/components/headers/ContentLanguage'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: This action is unauthorized.
    ValidationError:
      description: Request payload alebo query parametre neprešli validačnými pravidlami.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
        Content-Language:
          $ref: '#/components/headers/ContentLanguage'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: The given data was invalid.
              errors:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
    TooManyRequests:
      description: Firma prekročila Fintoro API rate limit. Táto 429 odpoveď nesie tie isté `X-RateLimit-Limit` a `X-RateLimit-Remaining` hlavičky ako ostatné throttled odpovede a navyše pridáva `Retry-After` a `X-RateLimit-Reset`. Ak potrebujete vyšší limit, kontaktujte info@fintoro.sk pre individuálne enterprise nastavenie.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
        X-RateLimit-Limit:
          description: Maximálny počet requestov povolený pre firmu v aktuálnom 60-sekundovom okne. Túto hlavičku vraciame na všetkých throttled odpovediach, nielen pri 429.
          schema:
            type: integer
            example: 120
        X-RateLimit-Remaining:
          description: Počet requestov, ktoré ešte firme ostávajú v aktuálnom 60-sekundovom okne. Túto hlavičku vraciame na všetkých throttled odpovediach, nielen pri 429.
          schema:
            type: integer
            example: 0
        Retry-After:
          description: Počet sekúnd, po ktorých môžete request bezpečne zopakovať. Túto hlavičku posielame len pri 429.
          schema:
            type: integer
            example: 60
        X-RateLimit-Reset:
          description: Unix timestamp, kedy sa aktuálne rate-limit okno resetuje. Túto hlavičku posielame len pri 429.
          schema:
            type: integer
            example: 1774810800
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Too Many Attempts.
    InternalServerError:
      description: Nastala neočakávaná interná chyba. Tento stav by sa nemal vyskytovať pri bežnej prevádzke a automaticky ho reportujeme.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
        Content-Language:
          $ref: '#/components/headers/ContentLanguage'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Server Error
    ServiceUnavailable:
      description: API je dočasne nedostupné počas riadenej údržby. Plánovaný výpadok oznamujeme minimálne 24 hodín vopred.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
        Content-Language:
          $ref: '#/components/headers/ContentLanguage'
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Service Unavailable
  schemas:
    WebhookEventType:
      description: Typ webhook udalosti, ktorú môžete subscribnuť a ktorú Fintoro následne doručuje na Váš endpoint.
      type: string
      enum:
        - clients.created
        - clients.updated
        - clients.deleted
        - suppliers.created
        - suppliers.updated
        - suppliers.deleted
        - bank-accounts.created
        - bank-accounts.updated
        - bank-accounts.deleted
        - business-case-statuses.created
        - business-case-statuses.updated
        - business-case-statuses.deleted
        - business-cases.created
        - business-cases.updated
        - business-cases.deleted
        - contact-activity-logs.created
        - contact-activity-logs.updated
        - contact-activity-logs.deleted
        - price-list-items.created
        - price-list-items.updated
        - price-list-items.deleted
        - price-list-items.stock-updated
        - warehouses.created
        - warehouses.updated
        - warehouses.deleted
        - warehouse-inbound-receipts.created
        - warehouse-inbound-receipts.updated
        - warehouse-inbound-receipts.deleted
        - warehouse-outbound-receipts.created
        - warehouse-outbound-receipts.updated
        - warehouse-outbound-receipts.deleted
        - invoices.created
        - invoices.updated
        - invoices.deleted
        - invoices.paid
        - credit-notes.created
        - credit-notes.updated
        - credit-notes.deleted
        - credit-notes.paid
        - received-invoices.paid
        - received-receipts.paid
        - proformas.created
        - proformas.updated
        - proformas.deleted
        - proformas.paid
        - orders.created
        - orders.updated
        - orders.deleted
        - quotations.created
        - quotations.updated
        - quotations.deleted
        - document-payments.created
        - document-payments.deleted
      example: invoices.updated
    WebhookSubscription:
      description: Jeden odber webhookov aktuálnej firmy.
      type: object
      properties:
        id:
          description: Interné ID odberu webhookov.
          type: integer
          example: 801
        companyId:
          description: ID firmy, ku ktorej subscription patrí.
          type: integer
          example: 15
        name:
          description: Voliteľný interný názov subscription pre Vašu orientáciu.
          type: [string, 'null']
          maxLength: 255
          example: ERP sync
        url:
          description: HTTPS URL, na ktorú Fintoro doručuje webhook requesty. Hostname musí smerovať na verejnú IP adresu; `localhost`, `.local`, privátne rozsahy a rezervované adresy backend odmietne.
          type: string
          format: uri
          maxLength: 2048
          example: https://example.com/webhooks/fintoro
        isActive:
          description: Ak je `true`, subscription je aktívny a môže prijímať delivery requesty.
          type: boolean
          example: true
        subscribedEvents:
          description: Zoznam event typov, ktoré sa majú pre tento subscription doručovať.
          type: array
          items:
            $ref: '#/components/schemas/WebhookEventType'
          example:
            - invoices.created
            - invoices.updated
        lastSuccessAt:
          description: ISO 8601 čas posledného úspešného doručenia, ak už k nemu došlo.
          type: [string, 'null']
          format: date-time
          example: '2026-03-18T15:04:05Z'
        lastFailureAt:
          description: ISO 8601 čas posledného neúspešného doručenia, ak už k nemu došlo.
          type: [string, 'null']
          format: date-time
          example: '2026-03-18T15:05:42Z'
        disabledAt:
          description: ISO 8601 čas deaktivácie subscription. V tejto verzii ostáva `null`, pokiaľ subscription manuálne nevypnete alebo budúce verzie nepridajú auto-disable flow.
          type: [string, 'null']
          format: date-time
          example: null
        disabledReason:
          description: Dôvod deaktivácie subscription, ak je známy.
          type: [string, 'null']
          example: null
        createdAt:
          description: ISO 8601 čas vytvorenia subscription.
          type: [string, 'null']
          format: date-time
          example: '2026-03-18T14:59:12Z'
        updatedAt:
          description: ISO 8601 čas poslednej zmeny subscription.
          type: [string, 'null']
          format: date-time
          example: '2026-03-18T15:01:33Z'
    WebhookSubscriptionWithSecret:
      allOf:
        - $ref: '#/components/schemas/WebhookSubscription'
        - type: object
          properties:
            plainTextSecret:
              description: Secret na podpisovanie zobrazený iba pri create alebo rotate-secret flowe v otvorenej podobe. Bezpečne si ho uložte; v ďalších odpovediach sa už nevracia.
              type: string
              example: whsec_fintoro_8b5d7c9f4f6549f7a3e8c4fd5f55ab91
    WebhookSubscriptionInput:
      description: Payload pre create alebo update odberu webhookov. Používajte iba HTTPS endpoint, ktorý vie prijať JSON `POST` requesty od Fintoro a ktorého hostname sa resolvne na verejnú IP adresu.
      type: object
      required:
        - url
        - isActive
        - subscribedEvents
      properties:
        name:
          description: Voliteľný interný názov subscription pre Vašu orientáciu vo Fintoro alebo v integračnom tíme.
          type: [string, 'null']
          maxLength: 255
          example: ERP sync
        url:
          description: HTTPS URL prijímača webhookov. Backend odmietne nezabezpečené `http://` adresy, endpointy s používateľským menom alebo heslom a hosty, ktoré sa resolvnu na `localhost`, `.local`, privátne, loopback, link-local alebo iné rezervované IP adresy. Rovnaká kontrola prebehne znovu aj tesne pred samotným odoslaním webhooku.
          type: string
          format: uri
          maxLength: 2048
          example: https://example.com/webhooks/fintoro
        isActive:
          description: Určuje, či je subscription aktívny hneď po uložení.
          type: boolean
          example: true
        subscribedEvents:
          description: Zoznam event typov, ktoré má Fintoro na tento endpoint posielať. Pole musí obsahovať aspoň jednu udalosť.
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/WebhookEventType'
          example:
            - invoices.created
            - invoices.updated
    Country:
      description: Krajina dostupná v lookup endpointoch Fintoro API a vo vnorených objektoch, kde sa krajina vracia priamo v response.
      type: object
      properties:
        id:
          description: Stabilné ID krajiny používané v API.
          type: integer
          example: 703
        name:
          description: Lokalizovaný názov krajiny. Ak pošlete `Accept-Language`, backend podľa neho preloží systémový label.
          type: string
          example: Slovensko
        code:
          description: Dvojpísmenový ISO kód krajiny.
          type: string
          example: SK
        eu:
          description: Informácia, či krajina patrí do Európskej únie.
          type: boolean
          example: true
    Language:
      description: Jazyk dostupný v lookup endpointoch Fintoro API.
      type: object
      properties:
        id:
          description: Stabilné ID jazyka používané v API.
          type: integer
          example: 1
        name:
          description: Lokalizovaný názov jazyka. Ak pošlete `Accept-Language`, backend podľa neho preloží systémový label.
          type: string
          example: Slovenčina
        code:
          description: Krátky jazykový kód.
          type: string
          example: sk
    Currency:
      description: Mena dostupná v lookup endpointoch Fintoro API.
      type: object
      properties:
        id:
          description: Stabilné ID meny používané v API.
          type: integer
          example: 1
        symbol:
          description: ISO alebo interný symbol meny.
          type: string
          example: EUR
        name:
          description: Lokalizovaný názov meny. Ak pošlete `Accept-Language`, backend podľa neho preloží systémový label.
          type: string
          example: Euro
        mark:
          description: Skrátená značka meny zobrazovaná vo Fintoro.
          type: string
          example: €
    DeliveryMethod:
      description: Spôsob dodania dostupný v lookup endpointoch Fintoro API.
      type: object
      properties:
        id:
          description: Stabilné ID spôsobu dodania používané v API.
          type: integer
          example: 1
        name:
          description: Lokalizovaný názov spôsobu dodania. Ak pošlete `Accept-Language`, backend podľa neho preloží systémový label.
          type: string
          example: Nezadaný
    PaymentMethod:
      description: Spôsob úhrady dostupný v lookup endpointoch Fintoro API.
      type: object
      properties:
        id:
          description: Stabilné ID spôsobu úhrady používané v API.
          type: integer
          example: 1
        name:
          description: Lokalizovaný názov spôsobu úhrady. Ak pošlete `Accept-Language`, backend podľa neho preloží systémový label.
          type: string
          example: Platba prevodom
    DocumentPayment:
      description: Jedna úhrada public dokladu.
      type: object
      properties:
        id:
          description: Interné ID úhrady.
          type: integer
          example: 801
        documentType:
          description: Typ dokladu, ku ktorému úhrada patrí.
          type: string
          enum: [invoice, proforma, credit-note]
          example: invoice
        documentId:
          description: ID dokladu, ku ktorému úhrada patrí.
          type: integer
          example: 301
        paymentMethod:
          description: Použitý spôsob úhrady ako vnorený lookup objekt.
          $ref: '#/components/schemas/PaymentMethod'
        currency:
          description: Mena úhrady ako vnorený lookup objekt.
          $ref: '#/components/schemas/Currency'
        paymentDate:
          description: Dátum úhrady vo formáte `Y-m-d`.
          type: string
          format: date
          example: '2026-03-07'
        amount:
          description: Suma úhrady v mene úhrady.
          type: number
          format: float
          example: 15.5
        currencyRate:
          description: Kurz meny úhrady voči EUR. Ak je mena úhrady `EUR`, backend vždy vráti `1.0`.
          type: number
          format: float
          example: 1.0
        receiptInvoice:
          description: Preview daňového dokladu k prijatej platbe, ak existuje.
          anyOf:
            - $ref: '#/components/schemas/InvoicePreview'
            - type: 'null'
    DocumentPaymentInput:
      description: >-
        Payload pre vytvorenie úhrady dokladu. Podporované sú len dokumenty `invoice`, `proforma` a `credit-note`, pričom cieľový doklad
        musí byť dostupný pre token.
      type: object
      required:
        - documentType
        - documentId
      properties:
        documentType:
          description: Typ dokladu, ku ktorému úhradu vytvárate.
          type: string
          enum: [invoice, proforma, credit-note]
          example: invoice
        documentId:
          description: ID dokladu, ku ktorému úhradu vytvárate.
          type: integer
          example: 301
        currencyId:
          description: "Voliteľné ID meny z [referenčnej tabuľky mien](/reference-tables#meny). Ak ho nepošlete, použije sa mena zo zdrojového dokladu."
          type: integer
          example: 1
        currencyRate:
          description: Kurz meny úhrady voči EUR. Ak ho nepošlete, systém ho dopočíta z finálneho `paymentDate` kurzom z predchádzajúceho dňa. Ak ho pošlete pre inú menu než `EUR`, použije sa presne táto override hodnota. Ak je finálna mena úhrady `EUR`, backend vždy uloží `1.0`.
          type: number
          format: float
          example: 1.0
        paymentDate:
          description: Dátum úhrady vo formáte `Y-m-d`. Ak ho nepošlete, použije sa dnešný dátum.
          type: string
          format: date
          example: '2026-03-07'
        paymentMethodId:
          description: "Voliteľné ID spôsobu úhrady z [referenčnej tabuľky spôsobov úhrady](/reference-tables#sposoby-uhrady). Ak ho nepošlete, použije sa spôsob úhrady zo zdrojového dokladu."
          type: integer
          example: 1
        amount:
          description: Suma úhrady v mene úhrady. Ak ju nepošlete, použije sa aktuálna zostávajúca suma `toBePaid` zo zdrojového dokladu. Toto odvodenie funguje len pri doklade s nenulovým `toBePaid`; inak endpoint vráti `422`. Ak ju pošlete explicitne, môže mať najviac 2 desatinné miesta, nesmie svojou veľkosťou presiahnuť aktuálne `toBePaid` a musí rešpektovať jeho znamienko. Backend akceptuje aj záporné sumy, napríklad pri vysporiadaní dobropisu.
          type: number
          format: float
          multipleOf: 0.01
          example: 15.5
    DocumentMailInput:
      description: >-
        Payload pre odoslanie podporovaného dokladu emailom. Cieľový doklad sa určuje cez kombináciu `documentType` + `documentId`
        a musí byť dostupný pre token.
      type: object
      required:
        - documentType
        - documentId
        - to
        - type
      properties:
        documentType:
          description: Typ dokladu, ktorý chcete odoslať emailom.
          type: string
          enum: [invoice, proforma, order, credit-note, quotation]
          example: invoice
        documentId:
          description: ID podporovaného dokladu patriaceho.
          type: integer
          example: 301
        to:
          description: Pole jednej alebo viacerých cieľových e-mailových adries.
          type: array
          minItems: 1
          items:
            type: string
            format: email
            example: billing@example.test
          example:
            - billing@example.test
            - owner@example.test
        body:
          description: Voliteľný vlastný text vložený do tela emailu.
          type: [string, 'null']
          maxLength: 1000
          example: V prílohe nájdete doklad.
        type:
          description: >-
            Typ odosielaného mailu. Pri `invoice` a `proforma` ovplyvňuje predmet a typ šablóny; pri `order`, `credit-note`
            a `quotation` sa momentálne správa rovnako ako `regular`.
          type: string
          enum: [regular, reminder, overdue_reminder, confirmation]
          example: reminder
    QrType:
      description: QR typ dostupný v lookup endpointoch Fintoro API.
      type: object
      properties:
        id:
          description: Stabilné ID QR typu používané v API.
          type: integer
          example: 1
        name:
          description: Lokalizovaný názov QR typu. Ak pošlete `Accept-Language`, backend podľa neho preloží systémový label.
          type: string
          example: Negenerovať
    Unit:
      description: Jednotka dostupná v lookup endpointoch Fintoro API.
      type: object
      properties:
        id:
          description: Stabilné ID jednotky používané v API.
          type: integer
          example: 1
        name:
          description: Lokalizovaný názov jednotky. Ak pošlete `Accept-Language`, backend podľa neho preloží systémový label.
          type: string
          example: ks
    Subject:
      description: Subjekt z referenčného registra. Typicky ho použijete ako podklad pri vytváraní klienta.
      type: object
      properties:
        id:
          description: IČO klienta alebo firmy. Pre slovenské subjekty túto hodnotu zvyčajne viete nájsť aj cez referenčný register subjektov.
          type: integer
          example: 12345678
        name:
          description: Obchodné meno alebo názov subjektu.
          type: string
          example: Acme s.r.o.
        taxId:
          description: DIČ subjektu, ak je dostupné.
          type: [string, 'null']
          example: '2020123456'
        vatId:
          description: IČ DPH subjektu, ak je dostupné.
          type: [string, 'null']
          example: SK2020123456
        legalForm:
          description: Právna forma subjektu.
          type: string
          enum: [freelancer, company]
          example: company
        city:
          description: Mesto sídla alebo miesta podnikania.
          type: [string, 'null']
          example: Bratislava
        street:
          description: Ulica a číslo sídla alebo miesta podnikania.
          type: [string, 'null']
          example: Hlavná 1
        zip:
          description: PSČ sídla alebo miesta podnikania.
          type: [string, 'null']
          example: '81101'
    Client:
      description: Klient vrátane klientských predvolených hodnôt. Tieto hodnoty neaplikuje API automaticky, ale môžete ich použiť ako odporúčaný default pri skladaní payloadov nových dokladov.
      type: object
      properties:
        id:
          description: Interné ID klienta vo Fintoro.
          type: integer
          example: 101
        name:
          description: Meno osoby alebo obchodné meno klienta.
          type: string
          example: Acme s.r.o.
        type:
          description: Typ klienta. Hodnota `person` reprezentuje fyzickú osobu, hodnota `company` firmu alebo živnostníka evidovaného ako podnikateľský subjekt.
          type: string
          enum: [person, company]
          example: company
        subjectId:
          type: [string, 'null']
          description: "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'
        taxId:
          description: DIČ klienta, ak je dostupné.
          type: [string, 'null']
          example: '2020123456'
        vatId:
          description: IČ DPH klienta, ak je dostupné.
          type: [string, 'null']
          example: SK2020123456
        isVatPayer:
          description: Informácia, či je klient aktuálne evidovaný ako platca DPH.
          type: boolean
          example: true
        email:
          description: Kontaktný e-mail klienta.
          type: [string, 'null']
          example: billing@acme.test
        street:
          description: Ulica a číslo fakturačnej adresy.
          type: [string, 'null']
          example: Hlavná 1
        city:
          description: Mesto fakturačnej adresy.
          type: [string, 'null']
          example: Bratislava
        zip:
          description: PSČ fakturačnej adresy.
          type: [string, 'null']
          example: '81101'
        country:
          description: Fakturačná krajina klienta ako vnorený objekt.
          anyOf:
            - $ref: '#/components/schemas/Country'
            - type: 'null'
        hasDeliveryAddress:
          description: Informácia, či má klient uloženú samostatnú dodaciu adresu odlišnú od fakturačnej adresy.
          type: boolean
          example: true
        deliveryStreet:
          description: Ulica a číslo dodacej adresy.
          type: [string, 'null']
          example: Skladová 9
        deliveryCity:
          description: Mesto dodacej adresy.
          type: [string, 'null']
          example: Košice
        deliveryZip:
          description: PSČ dodacej adresy.
          type: [string, 'null']
          example: '04001'
        deliveryCountry:
          description: Dodacia krajina klienta ako vnorený objekt.
          anyOf:
            - $ref: '#/components/schemas/Country'
            - type: 'null'
        createdAt:
          description: Dátum a čas vytvorenia klienta.
          type: [string, 'null']
          format: date-time
          example: '2026-03-03T12:00:00+01:00'
        updatedAt:
          description: Dátum a čas poslednej úpravy klienta.
          type: [string, 'null']
          format: date-time
          example: '2026-03-03T15:45:00+01:00'
        preferredDeliveryMethodId:
          type: [integer, 'null']
          description: "Predvolená hodnota spôsobu dodania pre klienta. Ukladá sa pri klientovi a používa sa ako fallback default pri tvorbe nových dokladov pre tohto klienta, ak explicitnú hodnotu nepošlete v payloade. Hodnota pochádza z [referenčnej tabuľky spôsobov dodania](/reference-tables#sposoby-dodania)."
          example: 1
        preferredPaymentMethodId:
          type: [integer, 'null']
          description: "Predvolená hodnota spôsobu úhrady pre klienta. Ukladá sa pri klientovi a používa sa ako fallback default pri tvorbe nových dokladov pre tohto klienta, ak explicitnú hodnotu nepošlete v payloade. Hodnota pochádza z [referenčnej tabuľky spôsobov úhrady](/reference-tables#sposoby-uhrady)."
          example: 1
        preferredCurrencyId:
          type: [integer, 'null']
          description: "Predvolená hodnota meny pre klienta. Ukladá sa pri klientovi a používa sa ako fallback default pri tvorbe nových dokladov pre tohto klienta, ak explicitnú hodnotu nepošlete v payloade. Hodnota pochádza z [referenčnej tabuľky mien](/reference-tables#meny)."
          example: 1
        preferredLanguageId:
          type: [integer, 'null']
          description: "Predvolená hodnota jazyka pre klienta. Ukladá sa pri klientovi a používa sa ako fallback default pri tvorbe nových dokladov pre tohto klienta, ak explicitnú hodnotu nepošlete v payloade. Hodnota pochádza z [referenčnej tabuľky jazykov](/reference-tables#jazyky)."
          example: 1
        preferredDueDays:
          description: Predvolený počet dní splatnosti. Ukladá sa pri klientovi a používa sa ako fallback default pri tvorbe nových dokladov pre tohto klienta, ak explicitnú hodnotu nepošlete v payloade.
          type: [integer, 'null']
          example: 14
        preferredNote:
          description: Predvolená poznámka. Ukladá sa pri klientovi a používa sa ako fallback default pri tvorbe nových dokladov pre tohto klienta, ak explicitnú hodnotu nepošlete v payloade.
          type: [string, 'null']
          example: Splatnosť 14 dní.
        preferredVariableSymbol:
          description: Predvolený variabilný symbol. Ukladá sa pri klientovi a používa sa ako fallback default pri tvorbe nových dokladov pre tohto klienta, ak explicitnú hodnotu nepošlete v payloade.
          type: [integer, 'null']
          example: 2026001
        preferredConstantSymbol:
          description: Predvolený konštantný symbol. Ukladá sa pri klientovi a používa sa ako fallback default pri tvorbe nových dokladov pre tohto klienta, ak explicitnú hodnotu nepošlete v payloade.
          type: [integer, 'null']
          example: 308
        preferredSpecificSymbol:
          description: Predvolený špecifický symbol. Ukladá sa pri klientovi a používa sa ako fallback default pri tvorbe nových dokladov pre tohto klienta, ak explicitnú hodnotu nepošlete v payloade.
          type: [integer, 'null']
          example: 55
        preferredTextAboveItems:
          description: Predvolený text nad položkami. Ukladá sa pri klientovi a používa sa ako fallback default pri tvorbe nových dokladov pre tohto klienta, ak explicitnú hodnotu nepošlete v payloade.
          type: [string, 'null']
          example: Dakujeme za spoluprácu.
    ClientCreateInput:
      description: Payload pre vytvorenie klienta. Pošlite business dáta klienta a voliteľné klientské predvolené hodnoty, ktoré sa uložia ako fallback defaulty pre tvorbu nových dokladov.
      type: object
      required: [name]
      properties:
        name:
          description: Meno osoby alebo obchodné meno klienta. Pole je pri vytvorení povinné.
          type: string
          maxLength: 255
          example: Acme s.r.o.
        type:
          description: "Voliteľný typ klienta. Povolené hodnoty sú `person` a `company`. Ak ho nepošlete, použije sa `person`, prípadne `company`, ak pošlete `subjectId`, `taxId` alebo `vatId`."
          type: string
          enum: [person, company]
          example: company
          default: person
        subjectId:
          type: [string, 'null']
          maxLength: 40
          description: "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'
        taxId:
          type: [string, 'null']
          maxLength: 40
          description: DIČ klienta.
          example: '2020123456'
        vatId:
          type: [string, 'null']
          maxLength: 40
          description: IČ DPH klienta.
          example: SK2020123456
        isVatPayer:
          description: "Voliteľná informácia, či je klient platca DPH. Ak ju nepošlete a vyplníte `vatId`, nastaví sa automaticky na `true`."
          type: boolean
          example: true
        email:
          description: Kontaktný e-mail klienta.
          type: [string, 'null']
          format: email
          maxLength: 255
          example: billing@acme.test
        street:
          description: Ulica a číslo fakturačnej adresy.
          type: [string, 'null']
          maxLength: 255
          example: Hlavná 1
        city:
          description: Mesto fakturačnej adresy.
          type: [string, 'null']
          maxLength: 255
          example: Bratislava
        zip:
          description: PSČ fakturačnej adresy.
          type: [string, 'null']
          maxLength: 10
          example: '81101'
        countryId:
          type: [integer, 'null']
          description: "ID fakturačnej krajiny z [referenčnej tabuľky krajín](/reference-tables#krajiny)."
          example: 703
        deliveryStreet:
          description: "Ulica a číslo dodacej adresy. Ak pošlete ktorúkoľvek hodnotu z dodacej adresy, `hasDeliveryAddress` sa nastaví automaticky."
          type: [string, 'null']
          maxLength: 255
          example: Skladová 9
        deliveryCity:
          description: "Mesto dodacej adresy. Ak pošlete ktorúkoľvek hodnotu z dodacej adresy, `hasDeliveryAddress` sa nastaví automaticky."
          type: [string, 'null']
          maxLength: 255
          example: Košice
        deliveryZip:
          description: "PSČ dodacej adresy. Ak pošlete ktorúkoľvek hodnotu z dodacej adresy, `hasDeliveryAddress` sa nastaví automaticky."
          type: [string, 'null']
          maxLength: 10
          example: '04001'
        deliveryCountryId:
          type: [integer, 'null']
          description: "ID krajiny dodacej adresy z [referenčnej tabuľky krajín](/reference-tables#krajiny). Ak pošlete ktorúkoľvek hodnotu z dodacej adresy, `hasDeliveryAddress` sa nastaví automaticky."
          example: 703
        preferredDeliveryMethodId:
          type: [integer, 'null']
          description: "Predvolená hodnota spôsobu dodania pre klienta. Ukladá sa pri klientovi a pri tvorbe nových dokladov pre tohto klienta sa používa ako fallback default, ak explicitnú hodnotu nepošlete v payloade. Hodnota pochádza z [referenčnej tabuľky spôsobov dodania](/reference-tables#sposoby-dodania)."
          example: 1
        preferredPaymentMethodId:
          type: [integer, 'null']
          description: "Predvolená hodnota spôsobu úhrady pre klienta. Ukladá sa pri klientovi a pri tvorbe nových dokladov pre tohto klienta sa používa ako fallback default, ak explicitnú hodnotu nepošlete v payloade. Hodnota pochádza z [referenčnej tabuľky spôsobov úhrady](/reference-tables#sposoby-uhrady)."
          example: 1
        preferredCurrencyId:
          type: [integer, 'null']
          description: "Predvolená hodnota meny pre klienta. Ukladá sa pri klientovi a pri tvorbe nových dokladov pre tohto klienta sa používa ako fallback default, ak explicitnú hodnotu nepošlete v payloade. Hodnota pochádza z [referenčnej tabuľky mien](/reference-tables#meny)."
          example: 1
        preferredLanguageId:
          type: [integer, 'null']
          description: "Predvolená hodnota jazyka pre klienta. Ukladá sa pri klientovi a pri tvorbe nových dokladov pre tohto klienta sa používa ako fallback default, ak explicitnú hodnotu nepošlete v payloade. Hodnota pochádza z [referenčnej tabuľky jazykov](/reference-tables#jazyky)."
          example: 1
        preferredDueDays:
          description: Predvolený počet dní splatnosti. Ukladá sa pri klientovi a pri tvorbe nových dokladov pre tohto klienta sa používa ako fallback default, ak explicitnú hodnotu nepošlete v payloade.
          type: [integer, 'null']
          minimum: 0
          maximum: 365
          example: 14
        preferredNote:
          description: Predvolená poznámka. Ukladá sa pri klientovi a pri tvorbe nových dokladov pre tohto klienta sa používa ako fallback default, ak explicitnú hodnotu nepošlete v payloade.
          type: [string, 'null']
          example: Splatnosť 14 dní.
        stripeCustomerId:
          description: Externé ID zákazníka v Stripe, ak si ho pri klientovi evidujete.
          type: [string, 'null']
          maxLength: 255
          example: cus_public_api_123
        systemeioContactId:
          description: Externé ID kontaktu v Systeme.io, ak si ho pri klientovi evidujete.
          type: [integer, 'null']
          example: 123456
        preferredVariableSymbol:
          description: Predvolený variabilný symbol. Povolené sú hodnoty s dĺžkou 1 až 10 číslic.
          type: [integer, 'null']
          minimum: 0
          maximum: 9999999999
          example: 2026001
        preferredConstantSymbol:
          description: Predvolený konštantný symbol. Povolené sú hodnoty s dĺžkou 1 až 4 číslic.
          type: [integer, 'null']
          minimum: 0
          maximum: 9999
          example: 308
        preferredSpecificSymbol:
          description: Predvolený špecifický symbol. Povolené sú hodnoty s dĺžkou 1 až 10 číslic.
          type: [integer, 'null']
          minimum: 0
          maximum: 9999999999
          example: 55
        preferredTextAboveItems:
          description: Predvolený text nad položkami. Ukladá sa pri klientovi a pri tvorbe nových dokladov pre tohto klienta sa používa ako fallback default, ak explicitnú hodnotu nepošlete v payloade.
          type: [string, 'null']
          maxLength: 3000
          example: Dakujeme za spoluprácu.
    Supplier:
      description: Dodávateľ v rozsahu, v akom sa vracia ako vnorený objekt pri obchodnom prípade.
      type: object
      properties:
        id:
          description: Interné ID dodávateľa vo Fintoro.
          type: integer
          example: 151
        type:
          description: Typ dodávateľa.
          type: string
          example: company
        name:
          description: Obchodné meno alebo meno dodávateľa.
          type: string
          example: Supplier s.r.o.
        subjectId:
          description: IČO dodávateľa, ak je dostupné.
          type: [string, 'null']
          example: '12345678'
        taxId:
          description: DIČ dodávateľa, ak je dostupné.
          type: [string, 'null']
          example: '2020202020'
        vatId:
          description: IČ DPH dodávateľa, ak je dostupné.
          type: [string, 'null']
          example: SK2020202020
        isVatPayer:
          description: Informácia, či je dodávateľ aktuálne evidovaný ako platca DPH.
          type: boolean
          example: true
        email:
          description: Kontaktný e-mail dodávateľa.
          type: [string, 'null']
          example: billing@supplier.test
        street:
          description: Ulica a číslo adresy dodávateľa.
          type: [string, 'null']
          example: Supplier Street 1
        city:
          description: Mesto adresy dodávateľa.
          type: [string, 'null']
          example: Bratislava
        zip:
          description: PSČ adresy dodávateľa.
          type: [string, 'null']
          example: '81101'
        country:
          description: Krajina dodávateľa ako vnorený objekt.
          anyOf:
            - $ref: '#/components/schemas/Country'
            - type: 'null'
    SupplierCreateInput:
      description: Payload pre vytvorenie dodávateľa. Ak nepošlete `type`, backend ho inferuje z `subjectId`, `taxId` a `vatId`. Ak nepošlete `isVatPayer`, backend ho inferuje z `vatId`.
      type: object
      required: [name]
      properties:
        type:
          description: Typ dodávateľa. Ak pole vynecháte, backend ho inferuje podľa identifikačných polí.
          type: string
          enum: [person, company]
          example: company
        name:
          description: Obchodné meno alebo meno dodávateľa.
          type: string
          maxLength: 255
          example: Supplier s.r.o.
        subjectId:
          description: IČO dodávateľa, ak je dostupné.
          type: [string, 'null']
          maxLength: 40
          example: '12345678'
        taxId:
          description: DIČ dodávateľa, ak je dostupné.
          type: [string, 'null']
          maxLength: 40
          example: '2020123456'
        vatId:
          description: IČ DPH dodávateľa, ak je dostupné.
          type: [string, 'null']
          maxLength: 40
          example: SK2020123456
        isVatPayer:
          description: Informácia, či je dodávateľ platca DPH. Ak pole vynecháte, backend hodnotu inferuje z `vatId`.
          type: boolean
          example: true
        email:
          description: Kontaktný e-mail dodávateľa.
          type: [string, 'null']
          format: email
          maxLength: 255
          example: billing@supplier.test
        street:
          description: Ulica a číslo fakturačnej adresy dodávateľa.
          type: [string, 'null']
          maxLength: 255
          example: Supplier Street 1
        city:
          description: Mesto fakturačnej adresy dodávateľa.
          type: [string, 'null']
          maxLength: 255
          example: Bratislava
        zip:
          description: PSČ fakturačnej adresy dodávateľa.
          type: [string, 'null']
          maxLength: 10
          example: '81101'
        countryId:
          description: "ID fakturačnej krajiny z [referenčnej tabuľky krajín](/reference-tables#krajiny)."
          type: [integer, 'null']
          example: 703
    BusinessCaseStatus:
      description: Stav obchodného prípadu. Reprezentuje jeden pipeline stĺpec.
      type: object
      properties:
        id:
          description: Interné ID stavu obchodného prípadu.
          type: integer
          example: 41
        name:
          description: Názov stavu obchodného prípadu.
          type: string
          example: Negotiation
        color:
          description: Farba statusu vo formáte hex.
          type: string
          maxLength: 7
          example: '#22aa44'
    BusinessCaseStatusInput:
      description: Payload pre vytvorenie alebo aktualizáciu stavu obchodného prípadu.
      type: object
      required: [name, color]
      properties:
        name:
          description: Názov stavu obchodného prípadu.
          type: string
          maxLength: 255
          example: Negotiation
        color:
          description: Farba statusu vo formáte hex.
          type: string
          maxLength: 7
          example: '#22aa44'
    BusinessCase:
      description: Obchodný prípad vrátane vnoreného klienta alebo dodávateľa a voliteľného stavu.
      type: object
      properties:
        id:
          description: Interné ID obchodného prípadu vo Fintoro.
          type: integer
          example: 501
        contactType:
          description: Typ naviazaného kontaktu. Hodnota `client` znamená klienta, hodnota `supplier` dodávateľa.
          type: string
          enum: [client, supplier]
          example: client
        contactId:
          description: Interné ID naviazaného kontaktu zodpovedajúce `contactType`.
          type: integer
          example: 101
        client:
          description: Vnorený objekt klienta, ak je obchodný prípad naviazaný na klienta.
          anyOf:
            - $ref: '#/components/schemas/Client'
            - type: 'null'
        supplier:
          description: Vnorený objekt dodávateľa, ak je obchodný prípad naviazaný na dodávateľa.
          anyOf:
            - $ref: '#/components/schemas/Supplier'
            - type: 'null'
        name:
          description: Názov obchodného prípadu.
          type: string
          example: Client pipeline
        description:
          description: Voliteľný popis obchodného prípadu.
          type: [string, 'null']
          example: Opportunity description
        status:
          description: Aktuálny stav obchodného prípadu ako vnorený objekt. Môže byť `null`, ak prípad nie je zaradený do žiadneho statusu.
          anyOf:
            - $ref: '#/components/schemas/BusinessCaseStatus'
            - type: 'null'
        boardPosition:
          description: Interná pozícia obchodného prípadu v rámci jeho aktuálneho statusu alebo bezstatusového stĺpca.
          type: integer
          example: 2
        createdAt:
          description: Dátum a čas vytvorenia obchodného prípadu.
          type: [string, 'null']
          format: date-time
          example: '2026-03-10T10:00:00+01:00'
        updatedAt:
          description: Dátum a čas poslednej úpravy obchodného prípadu.
          type: [string, 'null']
          format: date-time
          example: '2026-03-10T10:30:00+01:00'
    BusinessCaseCreateInput:
      description: Payload pre vytvorenie obchodného prípadu. Musíte poslať presne jedno z polí `clientId` alebo `supplierId`.
      type: object
      required: [name]
      properties:
        clientId:
          description: ID klienta. Pole je vzájomne exkluzívne so `supplierId`.
          type: [integer, 'null']
          example: 101
        supplierId:
          description: ID dodávateľa. Pole je vzájomne exkluzívne s `clientId`.
          type: [integer, 'null']
          example: 151
        statusId:
          description: ID stavu obchodného prípadu. Pole môže byť aj `null`.
          type: [integer, 'null']
          example: 41
        name:
          description: Názov obchodného prípadu.
          type: string
          maxLength: 255
          example: Client pipeline
        description:
          description: Voliteľný popis obchodného prípadu.
          type: [string, 'null']
          example: Opportunity description
    BusinessCaseUpdateInput:
      description: Payload pre aktualizáciu obchodného prípadu. Pošlite iba polia, ktoré chcete meniť. Polia `clientId` a `supplierId` nie sú pri update povolené.
      type: object
      properties:
        statusId:
          description: ID stavu obchodného prípadu. Pole môže byť aj `null`.
          type: [integer, 'null']
          example: 41
        name:
          description: Názov obchodného prípadu.
          type: string
          maxLength: 255
          example: Updated business case
        description:
          description: Voliteľný popis obchodného prípadu.
          type: [string, 'null']
          example: Updated description
    ContactActivityLogAttachmentUpload:
      description: Temporary upload token pre prílohu kontaktnej aktivity. `uploadToken` pošlite neskôr v `attachmentUploadTokens[]` pri create alebo update kontaktnej aktivity.
      type: object
      properties:
        uploadToken:
          description: Opaque token reprezentujúci jednu nahratú prílohu.
          type: string
          example: eyJpdiI6Ik9wYXF1ZS1Ub2tlbiIsInZhbHVlIjoiLi4uIn0=
        fileName:
          description: Pôvodný názov nahratého súboru.
          type: string
          example: note.pdf
        mimeType:
          description: Detegovaný MIME type nahratého súboru.
          type: string
          example: application/pdf
        size:
          description: Veľkosť súboru v bajtoch.
          type: integer
          example: 12288
    ContactActivityLogAttachment:
      description: Jedna príloha naviazaná na CRM udalosť.
      type: object
      properties:
        id:
          description: Interné ID prílohy kontaktnej aktivity.
          type: integer
          example: 9001
        name:
          description: Pôvodný názov súboru.
          type: string
          example: note.pdf
        mimeType:
          description: MIME type prílohy.
          type: string
          example: application/pdf
        url:
          description: Priama URL adresa prílohy, ak je dostupná.
          type: string
          example: https://cdn.fintoro.sk/contact-activity-attachments/note.pdf
    RelatedDocument:
      description: Live naviazaný doklad vyrátaný backendom z `relatedEntity`.
      type: object
      properties:
        documentType:
          description: Typ naviazaného dokladu.
          type: string
          enum: [invoice, proforma, order, quotation, credit-note, received-invoice, received-receipt, warehouse-inbound-receipt, warehouse-outbound-receipt]
          example: invoice
        documentId:
          description: ID naviazaného dokladu.
          type: integer
          example: 301
        name:
          description: Ľudsky čitateľný názov dokladu.
          type: string
          example: Faktúra 20260001
        number:
          description: Číslo dokladu.
          type: string
          example: '20260001'
        issueDate:
          description: Dátum vystavenia dokladu, ak je dostupný.
          type: string
          example: '2026-03-10'
        totalWithVat:
          description: Aktuálna live suma dokladu s DPH, ak je dostupná.
          type: [number, 'null']
          format: float
          example: 121.0
        currency:
          description: Aktuálna mena dokladu, ak je dostupná.
          anyOf:
            - $ref: '#/components/schemas/Currency'
            - type: 'null'
    ContactActivityLogMetadata:
      description: >-
        Response metadata CRM udalosti prispôsobené pre Fintoro API. Pri dokladových typoch obsahujú live
        naviazaný doklad priamo v `relatedDocument` a pri snapshot sumách aj snapshot menu v
        `documentCurrencySnapshot`.
      type: object
      properties:
        content:
          description: Text poznámky, e-mailu alebo súhrn telefonátu uložený v CRM udalosti. Dostupné iba pre response typy `note`, `email` a `phone_call`.
          type: [string, 'null']
          example: Follow-up call summary
        email:
          description: E-mailová adresa použitá pri CRM udalosti. Dostupné iba pre response typ `email`.
          type: [string, 'null']
          format: email
          example: crm@example.test
        personName:
          description: Meno osoby, s ktorou prebehol telefonát. Dostupné iba pre response typ `phone_call`.
          type: [string, 'null']
          example: John Caller
        phoneNumber:
          description: Telefónne číslo osoby, ak bolo zadané. Dostupné iba pre response typ `phone_call`.
          type: [string, 'null']
          example: '+421900000000'
        documentNumberSnapshot:
          description: Snapshot čísla dokladu uložený pri lifecycle eventoch `document_created`, `document_updated` a `document_deleted`.
          type: [string, 'null']
          example: '20260001'
        documentPriceSnapshot:
          description: Snapshot sumy s DPH uložený pri lifecycle eventoch `document_created` a `document_updated`.
          type: [number, 'null']
          format: float
          example: 121.0
        documentCurrencySnapshot:
          description: Snapshot meny použitej pri snapshot sumách v metadata payload-e. Dostupné pri lifecycle eventoch, ktoré vracajú snapshot sumu alebo snapshot úhradu.
          anyOf:
            - $ref: '#/components/schemas/Currency'
            - type: 'null'
        paidAmount:
          description: Výška pridanej úhrady uložená pri evente `document_payment_added`.
          type: [number, 'null']
          format: float
          example: 25.5
        relatedDocument:
          description: Naviazaný doklad. Dostupné iba pre typy `document_linked`, `document_created`, `document_updated`, `document_deleted` a `document_payment_added`. `null`, ak naviazaný doklad už neexistuje.
          anyOf:
            - $ref: '#/components/schemas/RelatedDocument'
            - type: 'null'
    ContactActivityLog:
      description: Unified CRM udalosť.
      type: object
      properties:
        id:
          description: Interné ID CRM udalosti.
          type: integer
          example: 551
        type:
          description: Typ CRM udalosti.
          type: string
          enum: [note, email, phone_call, document_linked, document_created, document_updated, document_deleted, document_payment_added]
          example: note
        metadata:
          description: Metadata CRM udalosti pripravené pre Fintoro API response.
          $ref: '#/components/schemas/ContactActivityLogMetadata'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/ContactActivityLogAttachment'
        businessCaseId:
          description: ID obchodného prípadu, ak je aktivita naviazaná na obchodný prípad.
          type: [integer, 'null']
          example: 501
        clientId:
          description: ID klienta, ak je aktivita naviazaná priamo na klienta mimo obchodného prípadu.
          type: [integer, 'null']
          example: 101
        supplierId:
          description: ID dodávateľa, ak je aktivita naviazaná priamo na dodávateľa mimo obchodného prípadu.
          type: [integer, 'null']
          example: 151
        createdAt:
          description: Dátum a čas vytvorenia CRM udalosti.
          type: [string, 'null']
          format: date-time
          example: '2026-03-10T10:00:00+01:00'
        updatedAt:
          description: Dátum a čas poslednej úpravy CRM udalosti.
          type: [string, 'null']
          format: date-time
          example: '2026-03-10T10:30:00+01:00'
    ContactActivityLogCreateInput:
      description: >-
        Payload pre vytvorenie CRM udalosti. Musíte poslať presne jedno z `businessCaseId`, `clientId`, `supplierId`,
        plus `type` a `metadata`. Voliteľné `attachmentUploadTokens[]` očakávajú tokeny z endpointu `contact-activity-attachments`.
        Pri `document_linked` type sa attachmenty nepodporujú.
      type: object
      required: [type, metadata]
      properties:
        businessCaseId:
          type: [integer, 'null']
          example: 501
        clientId:
          type: [integer, 'null']
          example: 101
        supplierId:
          type: [integer, 'null']
          example: 151
        type:
          type: string
          enum: [note, email, phone_call, document_linked]
          example: note
        metadata:
          description: Variabilný payload podľa `type`. Do requestu neposielajte snapshot polia ani `relatedDocument`; tie backend vypočíta alebo uloží sám.
          type: object
          properties:
            content:
              description: Text poznámky, tela e-mailu alebo súhrnu telefonátu. Dostupné iba pre payload typy `note`, `email` a `phone_call`. Povinné, ak je `type` jeden z týchto troch.
              type: [string, 'null']
              example: Follow-up call summary
            email:
              description: E-mailová adresa príjemcu alebo odosielateľa. Dostupné iba pre payload typ `email`. Povinné, ak je `type=email`.
              type: [string, 'null']
              format: email
              example: crm@example.test
            personName:
              description: Meno osoby, s ktorou prebehol telefonát. Dostupné iba pre payload typ `phone_call`. Povinné, ak je `type=phone_call`.
              type: [string, 'null']
              example: John Caller
            phoneNumber:
              description: Telefónne číslo osoby. Dostupné iba pre payload typ `phone_call`. Pole je voliteľné.
              type: [string, 'null']
              example: '+421900000000'
            documentType:
              description: Typ dokladu, ktorý sa má naviazať. Dostupné iba pre payload typ `document_linked`. Povinné, ak je `type=document_linked`.
              type: [string, 'null']
              enum: [invoice, proforma, order, quotation, credit-note]
              example: invoice
            documentId:
              description: ID dokladu, ktorý sa má naviazať. Dostupné iba pre payload typ `document_linked`. Povinné, ak je `type=document_linked`.
              type: [integer, 'null']
              example: 301
        attachmentUploadTokens:
          type: array
          items:
            type: string
          example:
            - eyJpdiI6Ik9wYXF1ZS1Ub2tlbi0xIn0=
            - eyJpdiI6Ik9wYXF1ZS1Ub2tlbi0yIn0=
    ContactActivityLogUpdateInput:
      description: >-
        Payload pre aktualizáciu CRM udalosti. Meniteľné sú iba `metadata`, voliteľné nové `attachmentUploadTokens[]`
        a `deletedAttachmentIds[]`. Polia `type`, `businessCaseId`, `clientId` a `supplierId` sú pri update zakázané.
      type: object
      required: [metadata]
      properties:
        metadata:
          description: Variabilný payload podľa typu existujúcej CRM udalosti. Do requestu neposielajte snapshot polia ani `relatedDocument`; tie backend vypočíta alebo uloží sám.
          type: object
          properties:
            content:
              description: Text poznámky, tela e-mailu alebo súhrnu telefonátu. Dostupné iba pre existujúce typy `note`, `email` a `phone_call`. Povinné, ak je existujúci typ jeden z týchto troch.
              type: [string, 'null']
              example: Follow-up call summary
            email:
              description: E-mailová adresa príjemcu alebo odosielateľa. Dostupné iba pre existujúci typ `email`. Povinné, ak je existujúci typ `email`.
              type: [string, 'null']
              format: email
              example: crm@example.test
            personName:
              description: Meno osoby, s ktorou prebehol telefonát. Dostupné iba pre existujúci typ `phone_call`. Povinné, ak je existujúci typ `phone_call`.
              type: [string, 'null']
              example: John Caller
            phoneNumber:
              description: Telefónne číslo osoby. Dostupné iba pre existujúci typ `phone_call`. Pole je voliteľné.
              type: [string, 'null']
              example: '+421900000000'
            documentType:
              description: Typ naviazaného dokladu. Dostupné iba pre existujúci typ `document_linked`. Povinné, ak je existujúci typ `document_linked`.
              type: [string, 'null']
              enum: [invoice, proforma, order, quotation, credit-note]
              example: invoice
            documentId:
              description: ID naviazaného dokladu. Dostupné iba pre existujúci typ `document_linked`. Povinné, ak je existujúci typ `document_linked`.
              type: [integer, 'null']
              example: 301
        attachmentUploadTokens:
          type: array
          items:
            type: string
          example:
            - eyJpdiI6Ik9wYXF1ZS1Ub2tlbi0xIn0=
        deletedAttachmentIds:
          type: array
          items:
            type: integer
          example: [9001]
    BankAccount:
      description: Bankový účet. Objekt spája business údaje účtu, informáciu o banke a stav napojenia na open banking.
      type: object
      properties:
        id:
          description: Interné ID bankového účtu vo Fintoro.
          type: integer
          example: 201
        bankId:
          description: "ID banky z [lookup endpointu bánk](#operation/listBanks). Ak je `null`, účet nie je naviazaný na konkrétnu banku z lookupu."
          type: [integer, 'null']
          example: 1
        bank:
          description: Vnorený objekt banky zodpovedajúci `bankId`, ak je banka známa a stále dostupná v lookup datasete.
          anyOf:
            - $ref: '#/components/schemas/Bank'
            - type: 'null'
        isPrimary:
          description: Označuje, či je tento účet aktuálne vedený ako primárny bankový účet firmy.
          type: boolean
          example: true
        autoPaymentMatching:
          description: Označuje, či je účet aktuálne napojený na automatické párovanie platieb cez open banking. Hodnota je odvodená od existencie open banking napojenia, neposiela sa v requeste.
          type: boolean
          example: true
        name:
          description: Používateľský názov bankového účtu zobrazený vo Fintoro.
          type: string
          example: Hlavný účet
        iban:
          description: IBAN bankového účtu.
          type: string
          example: SK3111000000001234567890
        swift:
          description: SWIFT alebo BIC kód bankového účtu.
          type: string
          example: TATRSKBX
        autoPairingStrategy:
          description: Stratégia automatického párovania platieb pre tento účet.
          type: string
          enum:
            - none
            - by_variable_symbol
            - by_price
            - by_variable_symbol_and_price
            - by_all_symbols
            - by_all_symbols_and_price
          example: by_variable_symbol
        balance:
          description: Posledný známy zostatok účtu, ak je dostupný z open banking napojenia.
          type: [number, 'null']
          format: float
          example: 1234.56
        lastSyncedAt:
          description: Dátum a čas poslednej úspešnej synchronizácie účtu cez open banking, ak je dostupný.
          type: [string, 'null']
          example: '2026-03-01 10:15:16'
        openBankingValidUntil:
          description: Dátum, do ktorého je platný aktuálny open banking súhlas, ak existuje.
          type: [string, 'null']
          format: date
          example: '2026-04-30'
        createdAt:
          description: Dátum a čas vytvorenia bankového účtu.
          type: [string, 'null']
          example: '2026-03-03 12:00:00'
        updatedAt:
          description: Dátum a čas poslednej zmeny bankového účtu.
          type: [string, 'null']
          example: '2026-03-03 15:45:00'
    Whoami:
      description: Minimálna identita firmy, v kontexte ktorej bearer token vykonáva requesty.
      type: object
      required: [name]
      properties:
        name:
          description: Obchodné meno firmy priradenej k aktuálnemu bearer tokenu.
          type: string
          example: Acme s.r.o.
    Bank:
      description: Banka dostupná v lookup endpointoch Fintoro API. Ide o stabilný lookup dataset, v ktorom sa existujúce ID bánk nemenia ani neprepisujú.
      type: object
      properties:
        id:
          description: Stabilné ID banky používané vo Fintoro. Po doplnení nových bánk sa existujúce ID nemenia ani neprepisujú.
          type: integer
          example: 23
        name:
          description: Názov banky.
          type: string
          example: Tatra Banka
        swift:
          description: SWIFT kód banky, ak je dostupný.
          type: string
          example: TATRSKBX
    BankAccountCreateInput:
      description: Payload pre vytvorenie bankového účtu. Posielate iba business dáta účtu. Polia, ktoré nepošlete a majú backendový default, sa dopočítajú na strane servera.
      type: object
      required: [name, iban, swift]
      properties:
        bankId:
          description: "Voliteľné ID banky z [lookup endpointu bánk](#operation/listBanks). Použite ho, ak chcete účet naviazať na konkrétnu banku z verejného lookupu."
          type: [integer, 'null']
          example: 1
        name:
          description: Názov bankového účtu, pod ktorým ho budete identifikovať vo Fintoro.
          type: string
          maxLength: 255
          example: Hlavný účet
        iban:
          description: IBAN bankového účtu. Musí byť validný a unikátny.
          type: string
          example: SK3111000000001234567890
        swift:
          description: SWIFT alebo BIC kód bankového účtu.
          type: string
          maxLength: 255
          example: TATRSKBX
        autoPairingStrategy:
          description: Stratégia automatického párovania platieb pre tento účet. Ak pole nepošlete, použije sa predvolená hodnota `by_variable_symbol`.
          type: string
          enum:
            - none
            - by_variable_symbol
            - by_price
            - by_variable_symbol_and_price
            - by_all_symbols
            - by_all_symbols_and_price
          default: by_variable_symbol
          example: by_variable_symbol
    BankAccountUpdateInput:
      description: Payload pre aktualizáciu bankového účtu. Pošlite len polia, ktoré chcete zmeniť. Polia, ktoré vynecháte, zostanú bez zmeny.
      type: object
      properties:
        bankId:
          description: "Voliteľné ID banky z [lookup endpointu bánk](#operation/listBanks). Pošlite `null`, ak chcete väzbu na banku odstrániť."
          type: [integer, 'null']
          example: 1
        name:
          description: Nový názov bankového účtu.
          type: string
          maxLength: 255
          example: Hlavný účet
        iban:
          description: Nový IBAN bankového účtu. Musí zostať validný a unikátny.
          type: string
          example: SK3111000000001234567890
        swift:
          description: Nový SWIFT alebo BIC kód bankového účtu.
          type: string
          maxLength: 255
          example: TATRSKBX
        autoPairingStrategy:
          description: Nová stratégia automatického párovania platieb pre tento účet. Ak pole vynecháte, zostane zachovaná existujúca hodnota.
          type: string
          enum:
            - none
            - by_variable_symbol
            - by_price
            - by_variable_symbol_and_price
            - by_all_symbols
            - by_all_symbols_and_price
          example: by_price
        isPrimary:
          description: Pošlite `true`, ak chcete účet nastaviť ako primárny účet firmy. Ak pole vynecháte alebo pošlete `false`, aktuálne priradenie primárneho účtu zostane bez zmeny a účet sa touto operáciou neprepne na neprimárny.
          type: boolean
          example: true
    Warehouse:
      description: Sklad vrátane inbound a outbound číselného radu.
      type: object
      properties:
        id:
          description: Interné ID skladu vo Fintoro.
          type: integer
          example: 301
        name:
          description: Názov skladu zobrazený vo Fintoro.
          type: string
          example: Hlavný sklad
        code:
          description: Interný kód skladu. Musí byť unikátny.
          type: string
          example: MAIN-WH
        inboundNumericalSeriesPattern:
          description: Vzor číselného radu pre skladové príjemky tohto skladu.
          type: string
          example: PRI-(RR)-(CCCC)
        inboundNumericalSeriesNextNumber:
          description: Ďalšie poradové číslo, ktoré sa použije pri automatickom generovaní skladovej príjemky.
          type: integer
          example: 12
        outboundNumericalSeriesPattern:
          description: Vzor číselného radu pre skladové výdajky tohto skladu.
          type: string
          example: VYD-(RR)-(CCCC)
        outboundNumericalSeriesNextNumber:
          description: Ďalšie poradové číslo, ktoré sa použije pri automatickom generovaní skladovej výdajky.
          type: integer
          example: 8
    WarehouseCreateInput:
      description: Payload pre vytvorenie skladu. Všetky business polia sú povinné.
      type: object
      required:
        - name
        - code
        - inboundNumericalSeriesPattern
        - inboundNumericalSeriesNextNumber
        - outboundNumericalSeriesPattern
        - outboundNumericalSeriesNextNumber
      properties:
        name:
          description: Názov skladu.
          type: string
          maxLength: 255
          example: Hlavný sklad
        code:
          description: Interný kód skladu. Musí byť unikátny.
          type: string
          maxLength: 255
          example: MAIN-WH
        inboundNumericalSeriesPattern:
          description: Vzor číselného radu pre skladové príjemky. Musí obsahovať counter token.
          type: string
          maxLength: 255
          example: PRI-(RR)-(CCCC)
        inboundNumericalSeriesNextNumber:
          description: Ďalšie poradové číslo pre inbound rad. Minimálna hodnota je `1`.
          type: integer
          minimum: 1
          example: 1
        outboundNumericalSeriesPattern:
          description: Vzor číselného radu pre skladové výdajky. Musí obsahovať counter token.
          type: string
          maxLength: 255
          example: VYD-(RR)-(CCCC)
        outboundNumericalSeriesNextNumber:
          description: Ďalšie poradové číslo pre outbound rad. Minimálna hodnota je `1`.
          type: integer
          minimum: 1
          example: 1
    WarehouseUpdateInput:
      description: Payload pre aktualizáciu skladu. Fintoro API používa plný `PUT` kontrakt, preto sú required všetky business polia rovnako ako pri create.
      allOf:
        - $ref: '#/components/schemas/WarehouseCreateInput'
    SupplierSnapshot:
      description: Historický snapshot dodávateľa uložený priamo na doklade.
      type: object
      properties:
        name:
          description: Obchodné meno alebo meno dodávateľa uložené na doklade.
          type: string
          example: Supply s.r.o.
        type:
          description: Typ dodávateľa uložený v snapshot-e.
          type: string
          example: company
        subjectId:
          description: IČO dodávateľa uložené v snapshot-e, ak bolo k dispozícii.
          type: [string, 'null']
          example: '12345678'
        taxId:
          description: DIČ dodávateľa uložené v snapshot-e, ak bolo k dispozícii.
          type: [string, 'null']
          example: '2020123456'
        vatId:
          description: IČ DPH dodávateľa uložené v snapshot-e, ak bolo k dispozícii.
          type: [string, 'null']
          example: SK2020123456
        isVatPayer:
          description: Informácia, či bol dodávateľ v čase uloženia snapshotu vedený ako platca DPH.
          type: boolean
          example: true
        email:
          description: Kontaktný e-mail dodávateľa uložený v snapshot-e.
          type: [string, 'null']
          example: billing@supply.test
        street:
          description: Ulica a číslo fakturačnej adresy dodávateľa uložené v snapshot-e.
          type: [string, 'null']
          example: Dodávateľská 1
        city:
          description: Mesto fakturačnej adresy dodávateľa uložené v snapshot-e.
          type: [string, 'null']
          example: Bratislava
        zip:
          description: PSČ fakturačnej adresy dodávateľa uložené v snapshot-e.
          type: [string, 'null']
          example: '81101'
        countryId:
          description: "ID krajiny z [referenčnej tabuľky krajín](/reference-tables#krajiny)."
          type: [integer, 'null']
          example: 703
        country:
          description: Fakturačná krajina dodávateľa uložená v snapshot-e ako vnorený objekt.
          anyOf:
            - $ref: '#/components/schemas/Country'
            - type: 'null'
    WarehouseReceiptItem:
      description: Jedna položka skladovej príjemky alebo výdajky.
      type: object
      properties:
        id:
          description: Interné ID položky skladového dokladu.
          type: integer
          example: 7001
        priceListItemId:
          description: ID skladovej alebo cenníkovej položky.
          type: integer
          example: 701
        priceListItemName:
          description: Názov skladovej alebo cenníkovej položky uložený na doklade.
          type: string
          example: Montážna sada
        priceListItemWarehouseCode:
          description: Skladový kód položky, ak je pri položke nastavený.
          type: [string, 'null']
          example: SKU-001
        unitName:
          description: Názov jednotky použitej na doklade.
          type: [string, 'null']
          example: ks
        quantity:
          description: Množstvo položky.
          type: number
          format: float
          example: 3
        unitPrice:
          description: Jednotková cena bez DPH.
          type: number
          format: float
          example: 15
        unitPriceWithVat:
          description: Jednotková cena s DPH.
          type: number
          format: float
          example: 18
        vatRate:
          description: Sadzba DPH na položke v percentách.
          type: number
          format: float
          example: 20
    WarehouseInboundReceipt:
      description: Skladová príjemka vrátane skladu, dodávateľského snapshotu a položiek.
      type: object
      properties:
        id:
          description: Interné ID skladovej príjemky.
          type: integer
          example: 901
        uuid:
          description: Verejné UUID skladovej príjemky použité aj vo webDoklad URL.
          type: string
          example: 5d6f8b1d-44c2-4ef6-a2c9-2d4d1c1a6e10
        number:
          description: Číslo skladovej príjemky.
          type: string
          example: PRI-2026-0001
        webDokladUrl:
          description: URL verejného web dokladu tejto príjemky.
          type: string
          example: https://app.fintoro.sk/web-doklad/company/warehouse-inbound-receipt/uuid
        pdfDownloadUrl:
          description: Priama URL na stiahnutie PDF exportu tejto príjemky.
          type: string
          example: https://app.fintoro.sk/api/public/v1/warehouse-inbound-receipts/901/pdf
        company:
          description: Historický snapshot dodávateľa uložený na doklade.
          $ref: '#/components/schemas/CompanySnapshot'
        warehouse:
          description: Sklad, do ktorého príjemka zapisuje tovar.
          $ref: '#/components/schemas/Warehouse'
        supplierId:
          description: Live ID dodávateľa, ak je príjemka stále naviazaná na existujúceho dodávateľa.
          type: [integer, 'null']
          example: 401
        supplier:
          description: Historický snapshot dodávateľa uložený na príjemke.
          anyOf:
            - $ref: '#/components/schemas/SupplierSnapshot'
            - type: 'null'
        currency:
          description: Mena príjemky.
          $ref: '#/components/schemas/Currency'
        language:
          description: Jazyk príjemky.
          $ref: '#/components/schemas/Language'
        issueDate:
          description: Dátum vystavenia príjemky.
          type: string
          format: date
          example: '2026-03-11'
        note:
          description: Voliteľná interná poznámka na príjemke.
          type: [string, 'null']
          example: Príjem z externého nákupu
        hasVat:
          description: Označuje, či príjemka obsahuje DPH.
          type: boolean
          example: true
        total:
          description: Celková suma bez DPH.
          type: number
          format: float
          example: 45
        totalWithVat:
          description: Celková suma s DPH.
          type: number
          format: float
          example: 54
        items:
          description: Položky skladovej príjemky.
          type: array
          items:
            $ref: '#/components/schemas/WarehouseReceiptItem'
    WarehouseInboundReceiptCreateInput:
      description: Payload pre vytvorenie skladovej príjemky.
      type: object
      required: [number, warehouseId, languageId, issueDate, items]
      properties:
        number:
          description: Číslo skladovej príjemky. Ak chcete použiť automatické ďalšie číslo skladu, pošlite ho explicitne podľa aktuálneho warehouse radu.
          type: string
          minLength: 1
          maxLength: 20
          example: PRI-2026-0001
        warehouseId:
          description: ID skladu.
          type: integer
          example: 301
        supplierId:
          description: Voliteľné ID existujúceho dodávateľa. Ak pošlete `supplierId`, objekt `supplier` sa použije len ako override snapshotu pre túto konkrétnu príjemku.
          type: [integer, 'null']
          example: 401
        supplier:
          description: Sparse dodávateľský payload. Ak pošlete `supplierId`, slúži ako override snapshotu na príjemke. Ak `supplierId` nepošlete, backend podľa týchto údajov dodávateľa dopáruje alebo vytvorí.
          anyOf:
            - $ref: '#/components/schemas/WarehouseInboundReceiptSupplierInput'
            - type: 'null'
        languageId:
          description: ID jazyka z lookup endpointu jazykov.
          type: integer
          example: 1
        issueDate:
          description: Dátum vystavenia príjemky.
          type: string
          format: date
          example: '2026-03-11'
        note:
          description: Voliteľná interná poznámka na príjemke.
          type: [string, 'null']
          maxLength: 3000
          example: Príjem z externého nákupu
        items:
          description: Položky príjemky. Každá položka musí smerovať na warehouse-enabled cenníkovú položku.
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/WarehouseReceiptLineInput'
    WarehouseInboundReceiptUpdateInput:
      description: Payload pre aktualizáciu skladovej príjemky. Fintoro API používa plný `PUT` kontrakt, preto sú required rovnaké business polia ako pri create.
      allOf:
        - $ref: '#/components/schemas/WarehouseInboundReceiptCreateInput'
    WarehouseOutboundReceipt:
      description: Skladová výdajka vrátane skladu, klientského snapshotu a položiek.
      type: object
      properties:
        id:
          description: Interné ID skladovej výdajky.
          type: integer
          example: 951
        uuid:
          description: Verejné UUID skladovej výdajky použité aj vo webDoklad URL.
          type: string
          example: 3f4c9fdd-6f9b-42c9-8c4b-a9d3a3435cf4
        number:
          description: Číslo skladovej výdajky.
          type: string
          example: VYD-2026-0001
        webDokladUrl:
          description: URL verejného web dokladu tejto výdajky.
          type: string
          example: https://app.fintoro.sk/web-doklad/company/warehouse-outbound-receipt/uuid
        pdfDownloadUrl:
          description: Priama URL na stiahnutie PDF exportu tejto výdajky.
          type: string
          example: https://app.fintoro.sk/api/public/v1/warehouse-outbound-receipts/951/pdf
        company:
          description: Historický snapshot dodávateľa uložený na doklade.
          $ref: '#/components/schemas/CompanySnapshot'
        warehouse:
          description: Sklad, z ktorého výdajka odpíše tovar.
          $ref: '#/components/schemas/Warehouse'
        clientId:
          description: Live ID klienta, ak je výdajka stále naviazaná na existujúceho klienta.
          type: [integer, 'null']
          example: 101
        client:
          description: Historický snapshot klienta uložený na výdajke.
          anyOf:
            - $ref: '#/components/schemas/ClientSnapshot'
            - type: 'null'
        currency:
          description: Mena výdajky.
          $ref: '#/components/schemas/Currency'
        language:
          description: Jazyk výdajky.
          $ref: '#/components/schemas/Language'
        issueDate:
          description: Dátum vystavenia výdajky.
          type: string
          format: date
          example: '2026-03-11'
        note:
          description: Voliteľná interná poznámka na výdajke.
          type: [string, 'null']
          example: Výdaj pre manuálny odber
        hasVat:
          description: Označuje, či výdajka obsahuje DPH.
          type: boolean
          example: true
        total:
          description: Celková suma bez DPH.
          type: number
          format: float
          example: 30
        totalWithVat:
          description: Celková suma s DPH.
          type: number
          format: float
          example: 36
        items:
          description: Položky skladovej výdajky.
          type: array
          items:
            $ref: '#/components/schemas/WarehouseReceiptItem'
    WarehouseOutboundReceiptCreateInput:
      description: Payload pre vytvorenie skladovej výdajky.
      type: object
      required: [number, warehouseId, languageId, issueDate, items]
      properties:
        number:
          description: Číslo skladovej výdajky. Ak chcete použiť automatické ďalšie číslo skladu, pošlite ho explicitne podľa aktuálneho warehouse radu.
          type: string
          minLength: 1
          maxLength: 20
          example: VYD-2026-0001
        warehouseId:
          description: ID skladu.
          type: integer
          example: 301
        clientId:
          description: Voliteľné ID existujúceho klienta. Ak pošlete `clientId`, objekt `client` sa použije len ako override snapshotu pre túto konkrétnu výdajku.
          type: [integer, 'null']
          example: 101
        client:
          description: Sparse klientský payload. Ak pošlete `clientId`, slúži ako override snapshotu na výdajke. Ak `clientId` nepošlete, backend podľa týchto údajov klienta dopáruje alebo vytvorí.
          anyOf:
            - $ref: '#/components/schemas/WarehouseOutboundReceiptClientInput'
            - type: 'null'
        languageId:
          description: ID jazyka z lookup endpointu jazykov.
          type: integer
          example: 1
        issueDate:
          description: Dátum vystavenia výdajky.
          type: string
          format: date
          example: '2026-03-11'
        note:
          description: Voliteľná interná poznámka na výdajke.
          type: [string, 'null']
          maxLength: 3000
          example: Výdaj pre manuálny odber
        items:
          description: Položky výdajky. Každá položka musí smerovať na warehouse-enabled cenníkovú položku a backend overuje dostupný stock.
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/WarehouseReceiptLineInput'
    WarehouseOutboundReceiptUpdateInput:
      description: Payload pre aktualizáciu skladovej výdajky. Fintoro API používa plný `PUT` kontrakt, preto sú required rovnaké business polia ako pri create.
      allOf:
        - $ref: '#/components/schemas/WarehouseOutboundReceiptCreateInput'
    WarehouseInboundReceiptSupplierInput:
      description: Dodávateľský payload pre resolve-or-create flow alebo snapshot override na skladovej príjemke.
      type: object
      required: [name]
      properties:
        name:
          description: Obchodné meno alebo meno dodávateľa.
          type: string
          maxLength: 255
          example: Supply s.r.o.
        type:
          description: Typ dodávateľa. Ak pole vynecháte, backend ho inferuje podľa identifikačných polí.
          type: string
          enum: [person, company]
          example: company
        subjectId:
          description: IČO dodávateľa, ak je dostupné.
          type: [string, 'null']
          maxLength: 40
          example: '12345678'
        taxId:
          description: DIČ dodávateľa, ak je dostupné.
          type: [string, 'null']
          maxLength: 40
          example: '2020123456'
        vatId:
          description: IČ DPH dodávateľa, ak je dostupné.
          type: [string, 'null']
          maxLength: 40
          example: SK2020123456
        isVatPayer:
          description: Informácia, či je dodávateľ platca DPH. Ak pole vynecháte, backend hodnotu inferuje z `vatId`.
          type: boolean
          example: true
        email:
          description: Kontaktný e-mail dodávateľa.
          type: [string, 'null']
          format: email
          maxLength: 255
          example: billing@supply.test
        street:
          description: Ulica a číslo fakturačnej adresy dodávateľa.
          type: [string, 'null']
          maxLength: 255
          example: Dodávateľská 1
        city:
          description: Mesto fakturačnej adresy dodávateľa.
          type: [string, 'null']
          maxLength: 255
          example: Bratislava
        zip:
          description: PSČ fakturačnej adresy dodávateľa.
          type: [string, 'null']
          maxLength: 10
          example: '81101'
        countryId:
          description: "ID fakturačnej krajiny z [referenčnej tabuľky krajín](/reference-tables#krajiny)."
          type: [integer, 'null']
          example: 703
    WarehouseOutboundReceiptClientInput:
      description: Klientský payload pre resolve-or-create flow alebo snapshot override na skladovej výdajke.
      type: object
      required: [name]
      properties:
        name:
          description: Obchodné meno alebo meno klienta.
          type: string
          maxLength: 255
          example: Client s.r.o.
        type:
          description: Typ klienta. Ak pole vynecháte, backend ho inferuje podľa identifikačných polí.
          type: string
          enum: [person, company]
          example: company
        subjectId:
          description: IČO klienta, ak je dostupné.
          type: [string, 'null']
          maxLength: 40
          example: '12345678'
        taxId:
          description: DIČ klienta, ak je dostupné.
          type: [string, 'null']
          maxLength: 40
          example: '2020123456'
        vatId:
          description: IČ DPH klienta, ak je dostupné.
          type: [string, 'null']
          maxLength: 40
          example: SK2020123456
        isVatPayer:
          description: Informácia, či je klient platca DPH. Ak pole vynecháte, backend hodnotu inferuje z `vatId`.
          type: boolean
          example: true
        email:
          description: Kontaktný e-mail klienta.
          type: [string, 'null']
          format: email
          maxLength: 255
          example: billing@client.test
        street:
          description: Ulica a číslo fakturačnej adresy klienta.
          type: [string, 'null']
          maxLength: 255
          example: Klientská 1
        city:
          description: Mesto fakturačnej adresy klienta.
          type: [string, 'null']
          maxLength: 255
          example: Bratislava
        zip:
          description: PSČ fakturačnej adresy klienta.
          type: [string, 'null']
          maxLength: 10
          example: '81101'
        countryId:
          description: "ID fakturačnej krajiny z [referenčnej tabuľky krajín](/reference-tables#krajiny)."
          type: [integer, 'null']
          example: 703
    WarehouseReceiptLineInput:
      description: Jedna položka create alebo update payloadu skladovej príjemky alebo výdajky.
      type: object
      required: [priceListItemId, quantity, unitPrice, vatRate]
      properties:
        priceListItemId:
          description: ID warehouse-enabled skladovej alebo cenníkovej položky.
          type: integer
          example: 701
        quantity:
          description: Množstvo položky. Minimálna hodnota je `0.00001`.
          type: number
          format: float
          minimum: 0.00001
          maximum: 10000000000000
          example: 3
        unitPrice:
          description: Jednotková cena bez DPH.
          type: number
          format: float
          minimum: -10000000000000
          maximum: 10000000000000
          example: 15
        vatRate:
          description: Sadzba DPH položky v percentách.
          type: number
          format: float
          minimum: 0
          maximum: 100
          example: 20
    PriceListItem:
      description: >-
        Skladová alebo cenníková položka. Objekt vracia business údaje použiteľné pri tvorbe dokladov aj
        skladové nastavenia, ak má položka zapnutú evidenciu skladu.
      type: object
      properties:
        id:
          description: Interné ID položky vo Fintoro.
          type: integer
          example: 701
        name:
          description: Názov položky.
          type: string
          example: Servisný balík
        description:
          description: Detailnejší popis položky, ak je na nej uložený.
          type: [string, 'null']
          example: Mesačný servis a podpora
        unitId:
          description: "ID jednotky z [referenčnej tabuľky jednotiek](/reference-tables#jednotky)."
          type: integer
          example: 1
        unit:
          description: Jednotka položky ako vnorený lookup objekt.
          $ref: '#/components/schemas/Unit'
        unitPrice:
          description: Predajná jednotková cena bez DPH.
          type: number
          format: float
          example: 129.9
        vatRate:
          description: Sadzba DPH použitá na predajnú cenu položky.
          type: number
          format: float
          example: 20
        unitPriceWithVat:
          description: Predajná jednotková cena s DPH dopočítaná backendom.
          type: number
          format: float
          example: 155.88
        stock:
          description: Aktuálny celkový skladový stav položky naprieč všetkými skladmi.
          type: number
          format: float
          example: 12
        stocks:
          description: Rozpis aktuálneho skladového stavu položky po jednotlivých skladoch firmy.
          type: array
          items:
            $ref: '#/components/schemas/PriceListItemStock'
        ean:
          description: EAN kód položky, ak je evidovaný.
          type: [string, 'null']
          maxLength: 255
          example: '8586012345678'
        useWarehouse:
          description: Označuje, či je na položke zapnutá skladová evidencia.
          type: boolean
          example: true
        warehouseCode:
          description: Interný kód skladovej karty. Pri zapnutej skladovej evidencii má byť unikátny v rámci firmy.
          type: [string, 'null']
          maxLength: 255
          example: SKU-PUBLIC-001
        enableNegativeStock:
          description: Označuje, či položka povoľuje záporný stav skladu.
          type: boolean
          example: false
        maxStock:
          description: Maximálny odporúčaný stav skladu, ak je na položke nastavený.
          type: [number, 'null']
          format: float
          example: 250
        purchasePrice:
          description: Nákupná cena bez DPH, ak je na položke evidovaná.
          type: [number, 'null']
          format: float
          example: 89.5
        purchaseVatRate:
          description: Nákupná sadzba DPH, ak je na položke evidovaná.
          type: [number, 'null']
          format: float
          example: 20
        purchasePriceWithVat:
          description: Nákupná cena s DPH dopočítaná backendom, ak je dostupná nákupná cena a sadzba DPH.
          type: [number, 'null']
          format: float
          example: 107.4
    PriceListItemStock:
      description: Aktuálny skladový stav konkrétnej cenníkovej položky na jednom sklade firmy.
      type: object
      properties:
        warehouseId:
          description: Interné ID skladu, ku ktorému sa stav viaže.
          type: integer
          example: 15
        warehouseName:
          description: Názov skladu.
          type: string
          example: Hlavný sklad
        warehouseCode:
          description: Interný kód skladu.
          type: string
          example: MAIN-WH
        stockQuantity:
          description: Aktuálne množstvo položky na danom sklade po započítaní príjemok a výdajok.
          type: number
          format: float
          example: 7
    PriceListItemCreateInput:
      description: >-
        Payload pre vytvorenie skladovej alebo cenníkovej položky. Required business polia sú vždy `name`, `unitPrice`, `unitId`
        a `vatRate`. Ak pošlete `useWarehouse: true`, `warehouseCode` sa stáva povinným poľom.
      type: object
      required: [name, unitPrice, unitId, vatRate]
      properties:
        name:
          description: Názov položky.
          type: string
          maxLength: 255
          example: Servisný balík
        description:
          description: Voliteľný detailnejší popis položky.
          type: [string, 'null']
          maxLength: 1000
          example: Mesačný servis a podpora
        unitPrice:
          description: Predajná jednotková cena bez DPH.
          type: number
          format: float
          minimum: -10000000000000
          maximum: 10000000000000
          example: 129.9
        unitId:
          description: "ID jednotky z [referenčnej tabuľky jednotiek](/reference-tables#jednotky)."
          type: integer
          example: 1
        vatRate:
          description: Predajná sadzba DPH položky.
          type: number
          format: float
          minimum: 0
          maximum: 100
          example: 20
        ean:
          description: >-
            Voliteľný EAN kód položky. Ak ho pošlete, musí byť unikátny.
          type: [string, 'null']
          maxLength: 255
          example: '8586012345678'
        useWarehouse:
          description: Ak pošlete `true`, položka bude vedená ako skladová.
          type: boolean
          default: false
          example: true
        warehouseCode:
          description: >-
            Voliteľný kód skladovej karty. Ak pošlete `useWarehouse: true`, toto pole je povinné a musí byť unikátne.
          type: [string, 'null']
          maxLength: 255
          example: SKU-PUBLIC-001
        enableNegativeStock:
          description: Označuje, či je povolený záporný skladový stav.
          type: boolean
          default: false
          example: false
        maxStock:
          description: Voliteľný maximálny odporúčaný stav skladu.
          type: [number, 'null']
          format: float
          minimum: 0
          maximum: 10000000000000
          example: 250
        purchasePrice:
          description: Voliteľná nákupná cena bez DPH.
          type: [number, 'null']
          format: float
          minimum: -10000000000000
          maximum: 10000000000000
          example: 89.5
        purchaseVatRate:
          description: Voliteľná nákupná sadzba DPH.
          type: [number, 'null']
          format: float
          minimum: 0
          maximum: 100
          example: 20
    PriceListItemUpdateInput:
      description: >-
        Payload pre aktualizáciu skladovej alebo cenníkovej položky. Fintoro API používa plný `PUT` kontrakt, preto sú required polia
        rovnaké ako pri create a vynechané polia nepredstavujú implicitné „zachovaj pôvodnú hodnotu“.
      allOf:
        - $ref: '#/components/schemas/PriceListItemCreateInput'
    InvoiceItem:
      description: Jedna položka faktúry.
      type: object
      properties:
        id:
          type: integer
          example: 1
        uuid:
          description: UUID riadku faktúry. Tento identifikátor dostanete v detaile faktúry a pri update ho môžete poslať späť, ak potrebujete zachovať väzby na skladové alokácie a výdajky na tom istom logickom riadku.
          type: string
          format: uuid
          example: 6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19
        name:
          type: string
          example: Konzultácia
        description:
          type: [string, 'null']
          example: Mesačný balík konzultácií
        unitPrice:
          type: number
          format: float
          example: 100.0
        unitId:
          type: integer
          description: "ID jednotky z [referenčnej tabuľky jednotiek](/reference-tables#jednotky)."
          example: 1
        quantity:
          type: number
          format: float
          example: 2.0
        vatRate:
          type: number
          format: float
          example: 20.0
        discountName:
          type: [string, 'null']
          example: Vernostná zľava
        discountType:
          type: [string, 'null']
          example: percentage
        discountValue:
          type: [number, 'null']
          format: float
          example: 10.0
        priceListItemId:
          type: [integer, 'null']
          example: 501
        total:
          type: number
          format: float
          example: 200.0
        totalWithVat:
          type: number
          format: float
          example: 240.0
    InvoiceWarehouseAllocation:
      type: object
      required: [warehouseId, quantity]
      properties:
        warehouseId:
          type: integer
          example: 1
        quantity:
          type: number
          format: float
          minimum: 0.00001
          maximum: 1000000
          example: 2.0
    InvoiceItemInput:
      description: >-
        Payload jednej položky faktúry. Podporované sú tri režimy: manuálna položka, `priceListItemId + quantity`, alebo `priceListItemId`
        s čiastočnými override poľami. Povinné je vždy `quantity`. Ak nepošlete `priceListItemId`, musíte poslať aj `name`, `unitPrice`
        a `vatRate`. `unitId` je voliteľné; ak ho pri manuálnej položke nepošlete, backend použije jednotku `1` (`ks` / `Unit::Piece`).
        Ak `priceListItemId` pošlete, backend si z cenníkovej položky vie dopočítať názov, jednotku, cenu a sadzbu DPH; payload potom
        slúži len ako sparse override.
      type: object
      required: [quantity]
      anyOf:
        - required: [priceListItemId]
        - required: [name, unitPrice, vatRate]
      properties:
        name:
          description: 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.
          type: [string, 'null']
          maxLength: 255
          example: Konzultácia
        description:
          description: Voliteľný popis položky. Pri `priceListItemId` môže prepísať alebo doplniť popis z cenníkovej položky.
          type: [string, 'null']
          maxLength: 1000
          example: Mesačný balík konzultácií
        unitPrice:
          description: Jednotková cena bez DPH. Pri manuálnej položke je povinná. Pri `priceListItemId` môže prepísať cenu načítanú z cenníka.
          type: [number, 'null']
          format: float
          minimum: -10000000000000
          maximum: 10000000000000
          example: 100.0
        unitId:
          description: "Voliteľné ID jednotky z [referenčnej tabuľky jednotiek](/reference-tables#jednotky). Pri manuálnej položke, kde ho nepošlete, backend použije jednotku `1` (`ks` / `Unit::Piece`). Pri `priceListItemId` môže prepísať jednotku z cenníkovej položky."
          type: [integer, 'null']
          example: 1
        quantity:
          description: 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.
          type: number
          format: float
          minimum: 0.00001
          maximum: 1000000
          example: 2.0
        vatRate:
          description: Sadzba DPH v percentách. Pri manuálnej položke je povinná. Pri `priceListItemId` môže prepísať sadzbu z cenníkovej položky.
          type: [number, 'null']
          format: float
          minimum: 0
          maximum: 100
          example: 20.0
        discountType:
          description: Typ zľavy na úrovni položky. Povolené hodnoty sú `percentage` a `fixed`.
          type: [string, 'null']
          enum: [percentage, fixed]
          example: percentage
        discountValue:
          description: Hodnota zľavy na úrovni položky. Ak pošlete `discountType`, musíte poslať aj toto pole.
          type: [number, 'null']
          format: float
          minimum: -10000000000000
          maximum: 10000000000000
          example: 10.0
        discountName:
          description: 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.
          type: [string, 'null']
          maxLength: 255
          example: Vernostná zľava
        priceListItemId:
          description: 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.
          type: [integer, 'null']
          example: 501
        warehouseAllocations:
          description: 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.
          type: array
          minItems: 1
          maxItems: 50
          items:
            $ref: '#/components/schemas/InvoiceWarehouseAllocation'
    CompanySnapshot:
      description: Snapshot dodávateľa uložený priamo na doklade. Tento objekt reprezentuje firemné údaje v čase vystavenia alebo posledného preuloženia dokladu, aby zostal na doklade zachovaný pôvodný názov, identifikačné údaje a adresa.
      type: object
      properties:
        name:
          description: Obchodné meno dodávateľa uložené na faktúre.
          type: string
          example: Fintoro s.r.o.
        subjectId:
          description: IČO dodávateľa uložené na faktúre.
          type: string
          example: '12345678'
        legalForm:
          description: Právna forma dodávateľa uložená na faktúre.
          type: string
          example: Spoločnosť s ručením obmedzeným
        taxId:
          description: DIČ dodávateľa uložené na faktúre, ak bolo k dispozícii.
          type: [string, 'null']
          example: '2020123456'
        vatId:
          description: IČ DPH dodávateľa uložené na faktúre, ak bolo k dispozícii.
          type: [string, 'null']
          example: SK2020123456
        vatPayerTypeId:
          description: Typ platcu DPH dodávateľa uložený na faktúre.
          type: integer
          example: 4
        country:
          description: Krajina dodávateľa uložená na faktúre ako textová hodnota.
          type: string
          example: Slovensko
        city:
          description: Mesto dodávateľa uložené na faktúre.
          type: string
          example: Bratislava
        street:
          description: Ulica a číslo dodávateľa uložené na faktúre.
          type: string
          example: Hlavná 1
        zip:
          description: PSČ dodávateľa uložené na faktúre.
          type: [string, 'null']
          example: '81101'
        registrationCourt:
          description: Registrový súd dodávateľa uložený na faktúre, ak bol k dispozícii.
          type: [string, 'null']
          example: Mestský súd Bratislava III
        registrationNumber:
          description: Registračné číslo dodávateľa uložené na faktúre, ak bolo k dispozícii.
          type: [string, 'null']
          example: 12345/B
        email:
          description: Kontaktný e-mail dodávateľa uložený na faktúre.
          type: [string, 'null']
          example: support@fintoro.sk
        phone:
          description: Kontaktný telefón dodávateľa uložený na faktúre.
          type: [string, 'null']
          example: '+421900000000'
        web:
          description: Web dodávateľa uložený na faktúre.
          type: [string, 'null']
          example: https://fintoro.sk
    ClientSnapshot:
      description: >-
        Historický snapshot klienta uložený priamo na doklade. Tento objekt reprezentuje stav klientskych údajov v čase vystavenia alebo posledného preuloženia dokladu. Ak si klient neskôr zmení názov alebo adresu, doklad si ponechá túto historickú hodnotu kvôli auditovateľnosti a perzistencii dát. Príklad: doklad vystavený na adresu `Hlavná 1, Bratislava` zostane historicky správny aj vtedy, keď má klient dnes v profile už inú adresu.
      type: object
      properties:
        name:
          description: Meno osoby alebo obchodné meno klienta uložené na faktúre v danom čase.
          type: string
          example: Acme s.r.o.
        type:
          description: Typ klienta uložený na faktúre.
          type: string
          example: company
        subjectId:
          type: [string, 'null']
          description: "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'
        taxId:
          description: DIČ klienta uložené na faktúre, ak bolo k dispozícii.
          type: [string, 'null']
          example: '2020123456'
        vatId:
          description: IČ DPH klienta uložené na faktúre, ak bolo k dispozícii.
          type: [string, 'null']
          example: SK2020123456
        isVatPayer:
          description: Informácia, či bol klient v čase uloženia snapshotu vedený ako platca DPH.
          type: boolean
          example: true
        email:
          description: Kontaktný e-mail klienta uložený na faktúre.
          type: [string, 'null']
          example: billing@acme.test
        street:
          description: Ulica a číslo fakturačnej adresy uložené na faktúre.
          type: [string, 'null']
          example: Hlavná 1
        city:
          description: Mesto fakturačnej adresy uložené na faktúre.
          type: [string, 'null']
          example: Bratislava
        zip:
          description: PSČ fakturačnej adresy uložené na faktúre.
          type: [string, 'null']
          example: '81101'
        countryId:
          type: [integer, 'null']
          description: "ID krajiny z [referenčnej tabuľky krajín](/reference-tables#krajiny)."
          example: 703
        country:
          description: Fakturačná krajina uložená na faktúre ako vnorený objekt.
          anyOf:
            - $ref: '#/components/schemas/Country'
            - type: 'null'
        hasDeliveryAddress:
          description: Informácia, či snapshot obsahuje samostatnú dodaciu adresu.
          type: boolean
          example: true
        deliveryStreet:
          description: Ulica a číslo dodacej adresy uložené na faktúre.
          type: [string, 'null']
          example: Skladová 9
        deliveryCity:
          description: Mesto dodacej adresy uložené na faktúre.
          type: [string, 'null']
          example: Košice
        deliveryZip:
          description: PSČ dodacej adresy uložené na faktúre.
          type: [string, 'null']
          example: '04001'
        deliveryCountryId:
          type: [integer, 'null']
          description: "ID krajiny z [referenčnej tabuľky krajín](/reference-tables#krajiny)."
          example: 703
        deliveryCountry:
          description: Dodacia krajina uložená na faktúre ako vnorený objekt.
          anyOf:
            - $ref: '#/components/schemas/Country'
            - type: 'null'
    InvoiceBankAccountReference:
      description: Bankový účet naviazaný na faktúru ako živá väzba. Faktúra tento účet načítava aj cez soft delete, takže detail zostane dostupný aj po jeho zmazaní z aktívneho zoznamu účtov.
      type: object
      properties:
        id:
          description: Interné ID bankového účtu vo Fintoro.
          type: integer
          example: 201
        bankId:
          description: "ID banky z [lookup endpointu bánk](#operation/listBanks), ak je účet naviazaný na známu banku."
          type: [integer, 'null']
          example: 1
        bank:
          description: Vnorený objekt banky priradenej k účtu, ak je známa.
          anyOf:
            - $ref: '#/components/schemas/Bank'
            - type: 'null'
        name:
          description: Názov bankového účtu v aktuálnom stave databázy.
          type: string
          example: Hlavný účet
        iban:
          description: IBAN naviazaného bankového účtu.
          type: string
          example: SK3111000000001234567890
        swift:
          description: SWIFT alebo BIC kód naviazaného bankového účtu.
          type: string
          example: TATRSKBX
        isPrimary:
          description: Informácia, či je účet aktuálne vedený ako primárny účet firmy.
          type: boolean
          example: true
        autoPaymentMatching:
          description: Informácia, či je účet aktuálne napojený na automatické párovanie platieb cez open banking.
          type: boolean
          example: true
    InvoicePreviewClient:
      description: Historický snapshot klienta uložený priamo v preview response dokladu. Live ID klienta je dostupné samostatne v poli `clientId`.
      allOf:
        - $ref: '#/components/schemas/ClientSnapshot'
    PaginatorLink:
      description: Jeden link v paginatori.
      type: object
      properties:
        url:
          description: URL cieľovej stránky alebo `null`, ak daný link nie je dostupný.
          type: [string, 'null']
          example: https://app.fintoro.sk/api/public/v1/invoices?page=2
        label:
          description: Textový label linku.
          type: string
          example: '2'
        active:
          description: Označuje, či ide o aktuálne aktívnu stránku.
          type: boolean
          example: false
    Paginator:
      description: Metadáta stránkovania vracané pri paginovaných list endpointoch.
      type: object
      properties:
        currentPage:
          description: Aktuálna stránka výsledku.
          type: integer
          example: 2
        perPage:
          description: Počet výsledkov na jednej stránke.
          type: integer
          example: 10
        totalPages:
          description: Celkový počet stránok.
          type: integer
          example: 5
        totalResults:
          description: Celkový počet záznamov naprieč všetkými stránkami.
          type: integer
          example: 42
        currentFrom:
          description: Poradové číslo prvého záznamu na aktuálnej stránke.
          type: integer
          example: 11
        currentTo:
          description: Poradové číslo posledného záznamu na aktuálnej stránke.
          type: integer
          example: 20
        firstPageUrl:
          description: URL prvej stránky.
          type: string
          example: https://app.fintoro.sk/api/public/v1/invoices?page=1
        lastPageUrl:
          description: URL poslednej stránky.
          type: string
          example: https://app.fintoro.sk/api/public/v1/invoices?page=5
        nextPageUrl:
          description: URL ďalšej stránky alebo `null`, ak ďalšia stránka neexistuje.
          type: [string, 'null']
          example: https://app.fintoro.sk/api/public/v1/invoices?page=3
        previousPageUrl:
          description: URL predchádzajúcej stránky alebo `null`, ak predchádzajúca stránka neexistuje.
          type: [string, 'null']
          example: https://app.fintoro.sk/api/public/v1/invoices?page=1
        links:
          description: Kompletný zoznam stránkovacích linkov v poradí, v akom ich vracia backend.
          type: array
          items:
            $ref: '#/components/schemas/PaginatorLink'
    NumericalSeries:
      description: Číselný rad použiteľný pri tvorbe public dokumentov.
      type: object
      properties:
        id:
          description: Jedinečné ID číselného radu v rámci firmy.
          type: integer
          example: 901
        documentType:
          description: Document typ, pre ktorý je tento rad určený.
          type: string
          enum: [invoice, proforma, credit-note, order, quotation]
          example: invoice
        name:
          description: Názov radu viditeľný vo Fintoro administrácii.
          type: string
          example: Faktúry 2026
        pattern:
          description: Formátovacia maska používaná na generovanie ďalšieho čísla dokladu.
          type: string
          example: INV-(RRRR)(CCC)
        nextNumber:
          description: Interná hodnota počítadla, ktorá sa použije pri ďalšom generovaní čísla z tohto radu.
          type: integer
          example: 11
        nextDocumentNumber:
          description: Finálne ďalšie číslo dokladu, ktoré by sa z tohto radu vygenerovalo pri najbližšom použití.
          type: string
          example: INV-2026011
        nextVariableSymbol:
          description: Variabilný symbol odvodený z `nextDocumentNumber` rovnakou logikou, akú backend používa pri tvorbe dokladov.
          type: integer
          example: 2026011
        isDefault:
          description: Označuje, či ide o predvolený rad pre daný typ dokladu.
          type: boolean
          example: false
    OrderPreview:
      description: Zjednodušený náhľadový objekt objednávky určený pre list endpoint. Neobsahuje položky, ale klient je dostupný ako plný historický snapshot v poli `client`; na detail použite detail endpoint objednávky.
      type: object
      properties:
        id:
          description: Interné ID objednávky vo Fintoro.
          type: integer
          example: 501
        uuid:
          description: Stabilný UUID identifikátor objednávky.
          type: string
          example: 6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19
        type:
          description: Typ dokladu.
          type: string
          example: order
        number:
          description: Číslo objednávky.
          type: string
          example: '20260001'
        clientId:
          description: Live ID klienta naviazaného na objednávku.
          type: integer
          example: 101
        client:
          description: Historický snapshot klienta uložený priamo na objednávke bez live ID. Live ID klienta je dostupné v poli `clientId`.
          $ref: '#/components/schemas/InvoicePreviewClient'
        issueDate:
          description: Dátum vystavenia objednávky.
          type: string
          format: date
          example: '2026-03-03'
        currency:
          description: Mena objednávky ako vnorený objekt.
          $ref: '#/components/schemas/Currency'
        total:
          description: Celková suma bez DPH po zľavách.
          type: number
          format: float
          example: 200.0
        totalWithVat:
          description: Celková suma s DPH po zľavách.
          type: number
          format: float
          example: 240.0
        hasVat:
          description: Informácia, či objednávka obsahuje položky s DPH.
          type: boolean
          example: true
    Order:
      description: Objednávka.
      type: object
      properties:
        id:
          type: integer
          example: 501
        uuid:
          type: string
          example: 6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19
        type:
          type: string
          example: order
        number:
          type: string
          example: '20260001'
        webDokladUrl:
          type: string
          format: uri
          description: Absolútna URL na verejný web doklad tejto objednávky.
          example: https://app.fintoro.sk/web-doklad/obj/4f3f8a95-5c4a-4c8b-9e6c-8a0c1a5df3a1
        pdfDownloadUrl:
          type: string
          format: uri
          description: Absolútna URL na Fintoro API endpoint, ktorý stiahne PDF tejto objednávky ako prílohu.
          example: https://app.fintoro.sk/api/public/v1/orders/501/pdf
        company:
          description: Snapshot dodávateľa uložený priamo na tomto doklade.
          $ref: '#/components/schemas/CompanySnapshot'
        clientId:
          description: Live ID klienta naviazaného na objednávku.
          type: integer
          example: 101
        client:
          description: Historický snapshot klienta uložený priamo na tomto doklade.
          $ref: '#/components/schemas/ClientSnapshot'
        issueDate:
          type: string
          format: date
          example: '2026-03-03'
        businessCaseId:
          type: [integer, 'null']
          description: Voliteľné ID obchodného prípadu. Ak ho pošlete, musí patriť zvolenému klientovi na doklade.
          example: 701
        discountType:
          type: [string, 'null']
          enum: [percentage, fixed]
          example: percentage
        discountValue:
          type: [number, 'null']
          format: float
          example: 10.0
        transferTaxLiability:
          type: boolean
          example: false
        numericalSeriesId:
          type: [integer, 'null']
          example: 12
        deliveryMethodId:
          type: integer
          description: "ID spôsobu dodania z [referenčnej tabuľky spôsobov dodania](/reference-tables#sposoby-dodania)."
          example: 1
        paymentMethodId:
          type: integer
          description: "ID spôsobu úhrady z [referenčnej tabuľky spôsobov úhrady](/reference-tables#sposoby-uhrady)."
          example: 1
        currencyId:
          type: integer
          description: "ID meny z [referenčnej tabuľky mien](/reference-tables#meny)."
          example: 1
        languageId:
          type: integer
          description: "ID jazyka z [referenčnej tabuľky jazykov](/reference-tables#jazyky)."
          example: 1
        note:
          type: [string, 'null']
          example: Ďakujeme za objednávku.
        textAboveItems:
          type: [string, 'null']
          example: Dakujeme za spoluprácu.
        itemsTotal:
          type: number
          format: float
          example: 200.0
        itemsTotalWithVat:
          type: number
          format: float
          example: 240.0
        total:
          type: number
          format: float
          example: 200.0
        totalWithVat:
          type: number
          format: float
          example: 240.0
        hasVat:
          type: boolean
          example: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
    OrderItem:
      description: Jedna položka objednávky.
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Konzultácia
        description:
          type: [string, 'null']
          example: Mesačný balík konzultácií
        unitPrice:
          type: number
          format: float
          example: 100.0
        unitId:
          type: integer
          description: "ID jednotky z [referenčnej tabuľky jednotiek](/reference-tables#jednotky)."
          example: 1
        quantity:
          type: number
          format: float
          example: 2.0
        vatRate:
          type: number
          format: float
          example: 20.0
        discountName:
          type: [string, 'null']
          example: Vernostná zľava
        discountType:
          type: [string, 'null']
          enum: [percentage, fixed]
          example: percentage
        discountValue:
          type: [number, 'null']
          format: float
          example: 10.0
        total:
          type: number
          format: float
          example: 200.0
        totalWithVat:
          type: number
          format: float
          example: 240.0
    QuotationPreview:
      description: Zjednodušený náhľadový objekt cenovej ponuky určený pre list endpoint. Neobsahuje položky, ale klient je dostupný ako plný historický snapshot v poli `client`; na detail použite detail endpoint cenovej ponuky.
      type: object
      properties:
        id:
          description: Interné ID cenovej ponuky vo Fintoro.
          type: integer
          example: 601
        uuid:
          description: Stabilný UUID identifikátor cenovej ponuky.
          type: string
          example: 6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19
        type:
          description: Typ dokladu.
          type: string
          example: quotation
        number:
          description: Číslo cenovej ponuky.
          type: string
          example: '20260001'
        clientId:
          description: Live ID klienta naviazaného na cenovú ponuku.
          type: integer
          example: 101
        client:
          description: Historický snapshot klienta uložený priamo na cenovej ponuke bez live ID. Live ID klienta je dostupné v poli `clientId`.
          $ref: '#/components/schemas/InvoicePreviewClient'
        issueDate:
          description: Dátum vystavenia cenovej ponuky.
          type: string
          format: date
          example: '2026-03-03'
        validityDate:
          description: Dátum platnosti cenovej ponuky.
          type: [string, 'null']
          format: date
          example: '2026-04-02'
        currency:
          description: Mena cenovej ponuky ako vnorený objekt.
          $ref: '#/components/schemas/Currency'
        total:
          description: Celková suma bez DPH po zľavách.
          type: number
          format: float
          example: 200.0
        totalWithVat:
          description: Celková suma s DPH po zľavách.
          type: number
          format: float
          example: 240.0
        status:
          description: Aktuálny stav cenovej ponuky.
          type: string
          enum: [waiting, accepted, rejected]
          example: waiting
        hasVat:
          description: Informácia, či cenová ponuka obsahuje položky s DPH.
          type: boolean
          example: true
    Quotation:
      description: Cenová ponuka.
      type: object
      properties:
        id:
          type: integer
          example: 601
        uuid:
          type: string
          example: 6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19
        type:
          type: string
          example: quotation
        number:
          type: string
          example: '20260001'
        webDokladUrl:
          type: string
          format: uri
          description: Absolútna URL na verejný web doklad tejto cenovej ponuky.
          example: https://app.fintoro.sk/web-doklad/cp/4f3f8a95-5c4a-4c8b-9e6c-8a0c1a5df3a1
        pdfDownloadUrl:
          type: string
          format: uri
          description: Absolútna URL na Fintoro API endpoint, ktorý stiahne PDF tejto cenovej ponuky ako prílohu.
          example: https://app.fintoro.sk/api/public/v1/quotations/601/pdf
        company:
          description: Snapshot dodávateľa uložený priamo na tomto doklade.
          $ref: '#/components/schemas/CompanySnapshot'
        clientId:
          description: Live ID klienta naviazaného na cenovú ponuku.
          type: integer
          example: 101
        client:
          description: Historický snapshot klienta uložený priamo na tomto doklade.
          $ref: '#/components/schemas/ClientSnapshot'
        issueDate:
          type: string
          format: date
          example: '2026-03-03'
        validityDate:
          type: [string, 'null']
          format: date
          example: '2026-04-02'
        businessCaseId:
          type: [integer, 'null']
          description: Voliteľné ID obchodného prípadu. Ak ho pošlete, musí patriť zvolenému klientovi na doklade.
          example: 701
        discountType:
          type: [string, 'null']
          enum: [percentage, fixed]
          example: percentage
        discountValue:
          type: [number, 'null']
          format: float
          example: 10.0
        transferTaxLiability:
          type: boolean
          example: false
        numericalSeriesId:
          type: [integer, 'null']
          example: 12
        currencyId:
          type: integer
          description: "ID meny z [referenčnej tabuľky mien](/reference-tables#meny)."
          example: 1
        languageId:
          type: integer
          description: "ID jazyka z [referenčnej tabuľky jazykov](/reference-tables#jazyky)."
          example: 1
        note:
          type: [string, 'null']
          example: Cenová ponuka platí 30 dní.
        textAboveItems:
          type: [string, 'null']
          example: Dakujeme za Váš záujem.
        itemsTotal:
          type: number
          format: float
          example: 200.0
        itemsTotalWithVat:
          type: number
          format: float
          example: 240.0
        total:
          type: number
          format: float
          example: 200.0
        totalWithVat:
          type: number
          format: float
          example: 240.0
        status:
          type: string
          enum: [waiting, accepted, rejected]
          example: waiting
        hasVat:
          type: boolean
          example: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/QuotationItem'
    QuotationItem:
      description: Jedna položka cenovej ponuky.
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Konzultácia
        description:
          type: [string, 'null']
          example: Mesačný balík konzultácií
        unitPrice:
          type: number
          format: float
          example: 100.0
        unitId:
          type: integer
          description: "ID jednotky z [referenčnej tabuľky jednotiek](/reference-tables#jednotky)."
          example: 1
        quantity:
          type: number
          format: float
          example: 2.0
        vatRate:
          type: number
          format: float
          example: 20.0
        discountName:
          type: [string, 'null']
          example: Vernostná zľava
        discountType:
          type: [string, 'null']
          enum: [percentage, fixed]
          example: percentage
        discountValue:
          type: [number, 'null']
          format: float
          example: 10.0
        total:
          type: number
          format: float
          example: 200.0
        totalWithVat:
          type: number
          format: float
          example: 240.0
    ProformaPreview:
      description: Zjednodušený náhľadový objekt zálohovej faktúry určený pre list endpoint. Neobsahuje položky ani snapshot bankového účtu, ale klient je dostupný ako plný historický snapshot v poli `client`; na detail použite detail endpoint zálohovej faktúry.
      type: object
      properties:
        id:
          description: Interné ID zálohovej faktúry vo Fintoro.
          type: integer
          example: 401
        uuid:
          description: Stabilný UUID identifikátor zálohovej faktúry.
          type: string
          example: 6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19
        type:
          description: Typ dokladu.
          type: string
          example: proforma
        number:
          description: Číslo zálohovej faktúry.
          type: string
          example: '20260001'
        clientId:
          description: Live ID klienta naviazaného na zálohovú faktúru.
          type: integer
          example: 101
        client:
          description: Historický snapshot klienta uložený priamo na zálohovej faktúre bez live ID. Live ID klienta je dostupné v poli `clientId`.
          $ref: '#/components/schemas/InvoicePreviewClient'
        issueDate:
          description: Dátum vystavenia zálohovej faktúry.
          type: string
          format: date
          example: '2026-03-03'
        dueDate:
          description: Dátum splatnosti zálohovej faktúry.
          type: string
          format: date
          example: '2026-03-17'
        currency:
          description: Mena zálohovej faktúry ako vnorený objekt.
          $ref: '#/components/schemas/Currency'
        total:
          description: Celková suma bez DPH.
          type: number
          format: float
          example: 200.0
        totalWithVat:
          description: Celková suma s DPH.
          type: number
          format: float
          example: 240.0
        toBePaid:
          description: Zostávajúca suma na úhradu.
          type: number
          format: float
          example: 240.0
        status:
          description: Aktuálny stav úhrady zálohovej faktúry.
          type: string
          enum: [paid, unpaid, partially_paid, overdue, will_not_be_paid]
          example: unpaid
        hasVat:
          description: Informácia, či zálohová faktúra obsahuje položky s DPH.
          type: boolean
          example: true
    Proforma:
      description: Zálohová faktúra.
      type: object
      properties:
        id:
          type: integer
          example: 401
        uuid:
          type: string
          example: 6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19
        type:
          type: string
          example: proforma
        number:
          type: string
          example: '20260001'
        webDokladUrl:
          type: string
          format: uri
          description: Absolútna URL na verejný web doklad tejto zálohovej faktúry.
          example: https://app.fintoro.sk/web-doklad/proforma/4f3f8a95-5c4a-4c8b-9e6c-8a0c1a5df3a1
        pdfDownloadUrl:
          type: string
          format: uri
          description: Absolútna URL na Fintoro API endpoint, ktorý stiahne PDF tejto zálohovej faktúry ako prílohu.
          example: https://app.fintoro.sk/api/public/v1/proformas/401/pdf
        company:
          description: Snapshot dodávateľa uložený priamo na tomto doklade.
          $ref: '#/components/schemas/CompanySnapshot'
        clientId:
          description: Live ID klienta naviazaného na zálohovú faktúru.
          type: integer
          example: 101
        client:
          description: Historický snapshot klienta uložený priamo na tomto doklade.
          $ref: '#/components/schemas/ClientSnapshot'
        bankAccount:
          description: Bankový účet naviazaný na zálohovú faktúru ako živá väzba načítaná aj cez soft delete.
          $ref: '#/components/schemas/InvoiceBankAccountReference'
        payments:
          description: Úhrady naviazané na túto zálohovú faktúru v poradí od najnovšej.
          type: array
          items:
            $ref: '#/components/schemas/DocumentPayment'
        variableSymbol:
          type: integer
          example: 20260001
        constantSymbol:
          type: [integer, 'null']
          example: 308
        specificSymbol:
          type: [integer, 'null']
          example: 55
        issueDate:
          type: string
          format: date
          example: '2026-03-03'
        dueDate:
          type: string
          format: date
          example: '2026-03-17'
        businessCaseId:
          type: [integer, 'null']
          description: Voliteľné ID obchodného prípadu. Ak ho pošlete, musí patriť zvolenému klientovi na doklade.
          example: 701
        discountType:
          type: [string, 'null']
          example: percentage
        discountValue:
          type: [number, 'null']
          format: float
          example: 10.0
        transferTaxLiability:
          type: boolean
          example: false
        numericalSeriesId:
          type: [integer, 'null']
          example: 12
        deliveryMethodId:
          type: integer
          description: "ID spôsobu dodania z [referenčnej tabuľky spôsobov dodania](/reference-tables#sposoby-dodania)."
          example: 1
        paymentMethodId:
          type: integer
          description: "ID spôsobu úhrady z [referenčnej tabuľky spôsobov úhrady](/reference-tables#sposoby-uhrady)."
          example: 1
        currencyId:
          type: integer
          description: "ID meny z [referenčnej tabuľky mien](/reference-tables#meny)."
          example: 1
        languageId:
          type: integer
          description: "ID jazyka z [referenčnej tabuľky jazykov](/reference-tables#jazyky)."
          example: 1
        qrTypeId:
          type: integer
          description: "ID QR typu z [referenčnej tabuľky QR typov](/reference-tables#qr-typy)."
          example: 1
        note:
          type: [string, 'null']
          example: Ďakujeme za objednávku.
        textAboveItems:
          type: [string, 'null']
          example: Dakujeme za spoluprácu.
        itemsTotal:
          type: number
          format: float
          example: 200.0
        itemsTotalWithVat:
          type: number
          format: float
          example: 240.0
        alreadyPaid:
          type: number
          format: float
          example: 0.0
        total:
          type: number
          format: float
          example: 200.0
        totalWithVat:
          type: number
          format: float
          example: 240.0
        toBePaid:
          type: number
          format: float
          example: 240.0
        willBePaid:
          type: boolean
          example: true
        status:
          type: string
          enum: [paid, unpaid, partially_paid, overdue, will_not_be_paid]
          example: unpaid
        hasVat:
          type: boolean
          example: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/ProformaItem'
    ProformaItem:
      description: Jedna položka zálohovej faktúry.
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Konzultácia
        description:
          type: [string, 'null']
          example: Mesačný balík konzultácií
        unitPrice:
          type: number
          format: float
          example: 100.0
        unitId:
          type: integer
          description: "ID jednotky z [referenčnej tabuľky jednotiek](/reference-tables#jednotky)."
          example: 1
        quantity:
          type: number
          format: float
          example: 2.0
        vatRate:
          type: number
          format: float
          example: 20.0
        discountName:
          type: [string, 'null']
          example: Vernostná zľava
        discountType:
          type: [string, 'null']
          example: percentage
        discountValue:
          type: [number, 'null']
          format: float
          example: 10.0
        total:
          type: number
          format: float
          example: 200.0
        totalWithVat:
          type: number
          format: float
          example: 240.0
    CreditNotePreview:
      description: Zjednodušený náhľadový objekt dobropisu určený pre list endpoint. Neobsahuje položky ani snapshot bankového účtu, ale klient je dostupný ako plný historický snapshot v poli `client`; na detail použite detail endpoint dobropisu.
      type: object
      properties:
        id:
          description: Interné ID dobropisu vo Fintoro.
          type: integer
          example: 351
        uuid:
          description: Stabilný UUID identifikátor dobropisu.
          type: string
          example: 6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19
        type:
          description: Typ dokladu.
          type: string
          example: credit-note
        number:
          description: Číslo dobropisu.
          type: string
          example: '20260051'
        clientId:
          description: Live ID klienta naviazaného na dobropis.
          type: integer
          example: 101
        client:
          description: Historický snapshot klienta uložený priamo na dobropise bez live ID. Live ID klienta je dostupné v poli `clientId`.
          $ref: '#/components/schemas/InvoicePreviewClient'
        issueDate:
          description: Dátum vystavenia dobropisu.
          type: string
          format: date
          example: '2026-03-03'
        dueDate:
          description: Dátum splatnosti dobropisu.
          type: string
          format: date
          example: '2026-03-17'
        deliveryDate:
          description: Dátum dodania dobropisu.
          type: [string, 'null']
          format: date
          example: '2026-03-03'
        currency:
          description: Mena dobropisu ako vnorený objekt.
          $ref: '#/components/schemas/Currency'
        total:
          description: Celková suma bez DPH.
          type: number
          format: float
          example: -20.0
        totalWithVat:
          description: Celková suma s DPH.
          type: number
          format: float
          example: -24.0
        toBePaid:
          description: Zostávajúca suma na vysporiadanie.
          type: number
          format: float
          example: -24.0
        status:
          description: Aktuálny stav dobropisu.
          type: string
          enum: [paid, unpaid, partially_paid, overdue, will_not_be_paid]
          example: unpaid
        hasVat:
          description: Informácia, či dobropis obsahuje položky s DPH.
          type: boolean
          example: true
    CreditNote:
      description: Dobropis.
      type: object
      properties:
        id:
          type: integer
          example: 351
        uuid:
          type: string
          example: 6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19
        type:
          type: string
          example: credit-note
        number:
          type: string
          example: '20260051'
        webDokladUrl:
          type: string
          format: uri
          description: Absolútna URL na verejný web doklad tohto dobropisu.
          example: https://app.fintoro.sk/web-doklad/credit-note/4f3f8a95-5c4a-4c8b-9e6c-8a0c1a5df3a1
        pdfDownloadUrl:
          type: string
          format: uri
          description: Absolútna URL na Fintoro API endpoint, ktorý stiahne PDF tohto dobropisu ako prílohu.
          example: https://app.fintoro.sk/api/public/v1/credit-notes/351/pdf
        company:
          description: Snapshot dodávateľa uložený priamo na tomto doklade.
          $ref: '#/components/schemas/CompanySnapshot'
        clientId:
          description: Live ID klienta naviazaného na dobropis.
          type: integer
          example: 101
        client:
          description: Historický snapshot klienta uložený priamo na tomto doklade.
          $ref: '#/components/schemas/ClientSnapshot'
        bankAccount:
          description: Bankový účet naviazaný na dobropis ako živá väzba načítaná aj cez soft delete.
          anyOf:
            - $ref: '#/components/schemas/InvoiceBankAccountReference'
            - type: 'null'
        payments:
          description: Úhrady naviazané na tento dobropis v poradí od najnovšej.
          type: array
          items:
            $ref: '#/components/schemas/DocumentPayment'
        invoiceId:
          description: ID pôvodnej faktúry, ku ktorej je dobropis naviazaný.
          type: [integer, 'null']
          example: 301
        variableSymbol:
          type: [integer, 'null']
          example: 20260051
        constantSymbol:
          type: [integer, 'null']
          example: 308
        specificSymbol:
          type: [integer, 'null']
          example: 55
        issueDate:
          type: string
          format: date
          example: '2026-03-03'
        dueDate:
          type: string
          format: date
          example: '2026-03-17'
        deliveryDate:
          type: [string, 'null']
          format: date
          example: '2026-03-03'
        businessCaseId:
          type: [integer, 'null']
          description: Voliteľné ID obchodného prípadu. Ak ho pošlete, musí patriť klientovi zdrojovej faktúry.
          example: 701
        discountType:
          type: [string, 'null']
          example: percentage
        discountValue:
          type: [number, 'null']
          format: float
          example: 10.0
        transferTaxLiability:
          type: boolean
          example: false
        numericalSeriesId:
          type: [integer, 'null']
          example: 12
        paymentMethodId:
          type: integer
          description: "ID spôsobu úhrady z [referenčnej tabuľky spôsobov úhrady](/reference-tables#sposoby-uhrady)."
          example: 1
        currencyId:
          type: integer
          description: "ID meny z [referenčnej tabuľky mien](/reference-tables#meny)."
          example: 1
        currencyRate:
          type: number
          format: float
          example: 1.0
        languageId:
          type: integer
          description: "ID jazyka z [referenčnej tabuľky jazykov](/reference-tables#jazyky)."
          example: 1
        note:
          type: [string, 'null']
          example: Dobropis k pôvodnej faktúre.
        textAboveItems:
          type: [string, 'null']
          example: Dobropisujeme pôvodné plnenie.
        itemsTotal:
          type: number
          format: float
          example: -20.0
        itemsTotalWithVat:
          type: number
          format: float
          example: -24.0
        alreadyPaid:
          type: number
          format: float
          example: 0.0
        total:
          type: number
          format: float
          example: -20.0
        totalWithVat:
          type: number
          format: float
          example: -24.0
        toBePaid:
          type: number
          format: float
          example: -24.0
        status:
          type: string
          enum: [paid, unpaid, partially_paid, overdue, will_not_be_paid]
          example: unpaid
        hasVat:
          type: boolean
          example: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/CreditNoteItem'
    CreditNoteItem:
      description: Jedna položka dobropisu.
      type: object
      properties:
        id:
          type: integer
          example: 1
        uuid:
          description: UUID riadku dobropisu. Pri update ho môžete poslať späť, ak potrebujete zachovať väzby na skladové príjemky a inbound sync.
          type: string
          format: uuid
          example: 6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19
        name:
          type: string
          example: Dobropisovaná konzultácia
        description:
          type: [string, 'null']
          example: Storno časti mesačného balíka
        unitPrice:
          type: number
          format: float
          example: -10.0
        unitId:
          type: integer
          description: "ID jednotky z [referenčnej tabuľky jednotiek](/reference-tables#jednotky)."
          example: 1
        quantity:
          type: number
          format: float
          example: 2.0
        vatRate:
          type: number
          format: float
          example: 20.0
        discountName:
          type: [string, 'null']
          example: Vernostná zľava
        discountType:
          type: [string, 'null']
          example: percentage
        discountValue:
          type: [number, 'null']
          format: float
          example: 10.0
        priceListItemId:
          type: [integer, 'null']
          example: 501
        total:
          type: number
          format: float
          example: -20.0
        totalWithVat:
          type: number
          format: float
          example: -24.0
    InvoicePreview:
      description: Zjednodušený náhľadový objekt faktúry určený pre list endpoint. Neobsahuje položky ani snapshot bankového účtu, ale klient je dostupný ako plný historický snapshot v poli `client`; na detail použite detail endpoint faktúry.
      type: object
      properties:
        id:
          description: Interné ID faktúry vo Fintoro.
          type: integer
          example: 301
        uuid:
          description: Stabilný UUID identifikátor faktúry.
          type: string
          example: 6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19
        type:
          description: Typ dokladu.
          type: string
          example: invoice
        number:
          description: Číslo faktúry.
          type: string
          example: '20260001'
        clientId:
          description: Live ID klienta naviazaného na faktúru.
          type: integer
          example: 101
        client:
          description: Historický snapshot klienta uložený priamo na faktúre bez live ID. Live ID klienta je dostupné v poli `clientId`.
          $ref: '#/components/schemas/InvoicePreviewClient'
        issueDate:
          description: Dátum vystavenia faktúry.
          type: string
          format: date
          example: '2026-03-03'
        dueDate:
          description: Dátum splatnosti faktúry.
          type: string
          format: date
          example: '2026-03-17'
        deliveryDate:
          description: Dátum dodania.
          type: string
          format: date
          example: '2026-03-03'
        currency:
          description: Mena faktúry ako vnorený objekt.
          $ref: '#/components/schemas/Currency'
        total:
          description: Celková suma bez DPH.
          type: number
          format: float
          example: 200.0
        totalWithVat:
          description: Celková suma s DPH.
          type: number
          format: float
          example: 240.0
        toBePaid:
          description: Zostávajúca suma na úhradu.
          type: number
          format: float
          example: 240.0
        status:
          description: Aktuálny stav úhrady faktúry.
          type: string
          enum: [paid, unpaid, partially_paid, overdue, will_not_be_paid]
          example: unpaid
        hasVat:
          description: Informácia, či faktúra obsahuje položky s DPH.
          type: boolean
          example: true
    Invoice:
      description: Faktúra.
      type: object
      properties:
        id:
          type: integer
          example: 301
        uuid:
          type: string
          example: 6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19
        type:
          type: string
          example: invoice
        number:
          type: string
          example: '20260001'
        webDokladUrl:
          type: string
          format: uri
          description: Absolútna URL na verejný web doklad tejto faktúry.
          example: https://app.fintoro.sk/web-doklad/fa/4f3f8a95-5c4a-4c8b-9e6c-8a0c1a5df3a1
        pdfDownloadUrl:
          type: string
          format: uri
          description: Absolútna URL na Fintoro API endpoint, ktorý stiahne PDF tejto faktúry ako prílohu.
          example: https://app.fintoro.sk/api/public/v1/invoices/123/pdf
        company:
          description: Snapshot dodávateľa uložený priamo na tomto doklade.
          $ref: '#/components/schemas/CompanySnapshot'
        clientId:
          description: Live ID klienta naviazaného na faktúru.
          type: integer
          example: 101
        client:
          description: Historický snapshot klienta uložený priamo na tomto doklade.
          $ref: '#/components/schemas/ClientSnapshot'
        bankAccount:
          description: Bankový účet naviazaný na faktúru ako živá väzba načítaná aj cez soft delete.
          $ref: '#/components/schemas/InvoiceBankAccountReference'
        payments:
          description: Úhrady naviazané na túto faktúru v poradí od najnovšej.
          type: array
          items:
            $ref: '#/components/schemas/DocumentPayment'
        variableSymbol:
          type: integer
          example: 20260001
        constantSymbol:
          type: [integer, 'null']
          example: 308
        specificSymbol:
          type: [integer, 'null']
          example: 55
        issueDate:
          type: string
          format: date
          example: '2026-03-03'
        dueDate:
          type: string
          format: date
          example: '2026-03-17'
        deliveryDate:
          type: string
          format: date
          example: '2026-03-03'
        businessCaseId:
          type: [integer, 'null']
          description: Voliteľné ID obchodného prípadu. Ak ho pošlete, musí patriť zvolenému klientovi na doklade.
          example: 701
        discountType:
          type: [string, 'null']
          example: percentage
        discountValue:
          type: [number, 'null']
          format: float
          example: 10.0
        transferTaxLiability:
          type: boolean
          example: false
        numericalSeriesId:
          type: [integer, 'null']
          example: 12
        deliveryMethodId:
          type: integer
          description: "ID spôsobu dodania z [referenčnej tabuľky spôsobov dodania](/reference-tables#sposoby-dodania)."
          example: 1
        paymentMethodId:
          type: integer
          description: "ID spôsobu úhrady z [referenčnej tabuľky spôsobov úhrady](/reference-tables#sposoby-uhrady)."
          example: 1
        currencyId:
          type: integer
          description: "ID meny z [referenčnej tabuľky mien](/reference-tables#meny)."
          example: 1
        currencyRate:
          type: number
          format: float
          example: 1.0
        languageId:
          type: integer
          description: "ID jazyka z [referenčnej tabuľky jazykov](/reference-tables#jazyky)."
          example: 1
        qrTypeId:
          type: integer
          description: "ID QR typu z [referenčnej tabuľky QR typov](/reference-tables#qr-typy)."
          example: 1
        note:
          type: [string, 'null']
          example: Ďakujeme za objednávku.
        textAboveItems:
          type: [string, 'null']
          example: Dakujeme za spoluprácu.
        itemsTotal:
          type: number
          format: float
          example: 200.0
        itemsTotalWithVat:
          type: number
          format: float
          example: 240.0
        total:
          type: number
          format: float
          example: 200.0
        totalWithVat:
          type: number
          format: float
          example: 240.0
        toBePaid:
          type: number
          format: float
          example: 240.0
        status:
          type: string
          example: unpaid
        hasVat:
          type: boolean
          example: true
        creditNotesSumTotalWithVat:
          type: number
          format: float
          example: 0.0
        items:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceItem'
    InvoiceClientInput:
      description: >-
        Sparse klientský payload používaný pri tvorbe alebo úprave faktúry. Ak pošlete `clientId`, tento objekt slúži ako voliteľný override snapshotu klienta iba pre konkrétny doklad. Ak `clientId` nepošlete, backend sa podľa tohto objektu pokúsi nájsť existujúceho klienta alebo vytvoriť nového.
      type: object
      properties:
        name:
          description: Názov firmy alebo meno osoby. Ak `clientId` neposielate, toto pole je povinné.
          type: string
          maxLength: 255
          example: Acme s.r.o.
        type:
          description: Typ klienta. Povolené hodnoty sú `person` a `company`. Ak ho nepošlete, backend ho dopočíta z identifikačných údajov.
          type: string
          enum: [person, company]
          example: company
        subjectId:
          description: IČO klienta alebo firmy.
          type: [string, 'null']
          maxLength: 40
          example: '12345678'
        taxId:
          description: DIČ klienta alebo firmy.
          type: [string, 'null']
          maxLength: 20
          example: '2020123456'
        vatId:
          description: IČ DPH klienta alebo firmy.
          type: [string, 'null']
          maxLength: 20
          example: SK2020123456
        isVatPayer:
          description: Voliteľná informácia, či je klient platca DPH. Ak ju nepošlete a vyplníte `vatId`, backend ju dopočíta automaticky.
          type: boolean
          example: true
        email:
          description: Kontaktný e-mail klienta.
          type: [string, 'null']
          format: email
          maxLength: 255
          example: billing@acme.test
        street:
          description: Fakturačná ulica klienta. Pri sparse override mení len snapshot na tomto doklade.
          type: [string, 'null']
          maxLength: 255
          example: Hlavná 1
        city:
          description: Fakturačné mesto klienta.
          type: [string, 'null']
          maxLength: 255
          example: Bratislava
        zip:
          description: Fakturačné PSČ klienta.
          type: [string, 'null']
          maxLength: 20
          example: '81101'
        countryId:
          type: [integer, 'null']
          description: "ID krajiny z [referenčnej tabuľky krajín](/reference-tables#krajiny)."
          example: 703
        hasDeliveryAddress:
          description: Voliteľný príznak dodacej adresy. Ak ho nepošlete, backend ho vie odvodiť z dodacích polí.
          type: boolean
          example: true
        deliveryStreet:
          description: Dodacia ulica klienta pre snapshot na tomto doklade.
          type: [string, 'null']
          maxLength: 255
          example: Skladová 5
        deliveryCity:
          description: Dodacie mesto klienta pre snapshot na tomto doklade.
          type: [string, 'null']
          maxLength: 255
          example: Trnava
        deliveryZip:
          description: Dodacie PSČ klienta pre snapshot na tomto doklade.
          type: [string, 'null']
          maxLength: 20
          example: '91701'
        deliveryCountryId:
          type: [integer, 'null']
          description: "ID krajiny dodacej adresy z [referenčnej tabuľky krajín](/reference-tables#krajiny)."
          example: 703
    InvoiceInput:
      description: >-
        Payload pre vytvorenie faktúry. V bežnom prípade stačí poslať `clientId` a `items`; ostatné polia môže backend dopočítať. Musíte poslať buď `clientId`, alebo objekt `client`.
      type: object
      required: [items]
      anyOf:
        - required: [clientId]
        - required: [client]
      properties:
        number:
          description: Manuálne číslo faktúry. Ak ho nepošlete, backend ho vygeneruje z číselného radu. Ak pošlete `number`, nepošlite zároveň `numericalSeriesId`.
          type: [string, 'null']
          minLength: 1
          maxLength: 20
          example: '20260001'
        proformaId:
          description: Voliteľné ID zálohovej faktúry, z ktorej sa faktúra vytvára.
          type: [integer, 'null']
          example: 401
        orderId:
          description: Voliteľné ID objednávky, z ktorej sa faktúra vytvára.
          type: [integer, 'null']
          example: 501
        quotationId:
          description: Voliteľné ID cenovej ponuky, z ktorej sa faktúra vytvára.
          type: [integer, 'null']
          example: 601
        clientId:
          description: 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.
          type: [integer, 'null']
          example: 101
        client:
          description: 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í.
          anyOf:
            - $ref: '#/components/schemas/InvoiceClientInput'
            - type: 'null'
        businessCaseId:
          description: Voliteľné ID obchodného prípadu. Ak ho pošlete, musí patriť klientovi určenému cez finálny `clientId`.
          type: [integer, 'null']
          example: 701
        numericalSeriesId:
          description: 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 `numericalSeriesId`, nepošlite zároveň manuálne `number`.
          type: [integer, 'null']
          example: 12
        bankAccountId:
          description: 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` validačnú chybu s chybou pri `bankAccountId`.
          type: integer
          example: 201
        issueDate:
          description: Dátum vystavenia vo formáte `Y-m-d`. Musí byť po `2009-01-01` a pred dátumom o jeden rok v budúcnosti. Ak ho nepošlete, použije sa dnešný dátum.
          type: string
          format: date
          example: '2026-03-03'
        dueDateDays:
          description: Počet dní splatnosti. Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy.
          type: integer
          minimum: 0
          maximum: 1000
          example: 14
        deliveryDate:
          description: Dátum dodania vo formáte `Y-m-d`. Ak ho pošlete, musí byť menší alebo rovný `issueDate`. Ak ho nepošlete, použije sa `issueDate`.
          type: string
          format: date
          example: '2026-03-03'
        variableSymbol:
          description: Variabilný symbol. Povolené sú hodnoty s dĺžkou 1 až 10 číslic. Ak ho nepošlete, backend ho odvodí z finálneho čísla faktúry.
          type: integer
          minimum: 0
          maximum: 9999999999
          example: 20260001
        constantSymbol:
          description: Konštantný symbol. Povolené sú hodnoty s dĺžkou 1 až 4 číslic. Priorita je payload → klientská predvolená hodnota → `null`.
          type: [integer, 'null']
          minimum: 0
          maximum: 9999
          example: 308
        specificSymbol:
          description: Špecifický symbol. Povolené sú hodnoty s dĺžkou 1 až 10 číslic. Priorita je payload → klientská predvolená hodnota → `null`.
          type: [integer, 'null']
          minimum: 0
          maximum: 9999999999
          example: 55
        discountType:
          description: Typ zľavy na úrovni celého dokladu.
          type: [string, 'null']
          enum: [percentage, fixed]
          example: percentage
        discountValue:
          description: Hodnota zľavy na úrovni celého dokladu.
          type: [number, 'null']
          format: float
          minimum: 0
          example: 10.0
        transferTaxLiability:
          description: Príznak prenesenej daňovej povinnosti. Ak ho nepošlete, použije sa `false`.
          type: boolean
          example: false
        deliveryMethodId:
          type: integer
          description: "ID spôsobu dodania z [referenčnej tabuľky spôsobov dodania](/reference-tables#sposoby-dodania). Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy."
          example: 1
        paymentMethodId:
          type: integer
          description: "ID spôsobu úhrady z [referenčnej tabuľky spôsobov úhrady](/reference-tables#sposoby-uhrady). Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy."
          example: 1
        currencyId:
          type: integer
          description: "ID meny z [referenčnej tabuľky mien](/reference-tables#meny). Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy."
          example: 1
        currencyRate:
          description: Kurz meny k EUR. Ak ho nepošlete, backend ho vyrieši server-side podľa `currencyId` a `deliveryDate`. Ak je finálna mena dokladu `EUR`, backend vždy uloží a vráti `1.0`.
          type: number
          format: float
          minimum: 0.00001
          maximum: 10000000
          example: 1.0
        languageId:
          type: integer
          description: "ID jazyka z [referenčnej tabuľky jazykov](/reference-tables#jazyky). Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy."
          example: 1
        qrTypeId:
          type: integer
          description: "ID QR typu z [referenčnej tabuľky QR typov](/reference-tables#qr-typy). Ak ho nepošlete, použije sa nastavenia dokladov firmy."
          example: 1
        note:
          description: Poznámka na doklade. Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy.
          type: [string, 'null']
          maxLength: 3000
          example: Ďakujeme za objednávku.
        textAboveItems:
          description: Text nad položkami. Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy.
          type: [string, 'null']
          maxLength: 3000
          example: Dakujeme za spoluprácu.
        items:
          description: Položky faktúry. Toto pole je povinné aj vtedy, keď väčšinu ostatných hodnôt necháte dopočítať backendom.
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/InvoiceItemInput'
    CreditNoteInput:
      description: >-
        Payload pre vytvorenie dobropisu. Ide o explicitný create flow bez inline client resolution. Musíte poslať kompletný business payload
        vrátane `invoiceId`, všetkých kľúčových dokladových polí a položiek. Klient sa automaticky odvodí zo zdrojovej faktúry a výsledná
        celková suma dobropisu musí zostať záporná.
      type: object
      required:
        - invoiceId
        - number
        - issueDate
        - dueDate
        - deliveryDate
        - bankAccountId
        - variableSymbol
        - transferTaxLiability
        - paymentMethodId
        - currencyId
        - currencyRate
        - languageId
        - items
      properties:
        invoiceId:
          description: ID pôvodnej faktúry, ku ktorej sa dobropis viaže.
          type: integer
          example: 301
        businessCaseId:
          description: Voliteľné ID obchodného prípadu. Ak ho pošlete, musí patriť klientovi zdrojovej faktúry.
          type: [integer, 'null']
          example: 701
        number:
          description: Explicitné číslo dobropisu. Musí byť unikátne v rámci dobropisov aj faktúr. Tento flow vyžaduje `number`, preto spolu s ním neposielajte `numericalSeriesId`.
          type: string
          minLength: 1
          maxLength: 20
          example: '20260051'
        numericalSeriesId:
          description: ID číselného radu pre dobropisy. V tomto explicitnom public create/update flowe ho neposielajte spolu s povinným poľom `number`.
          type: [integer, 'null']
          example: 12
        issueDate:
          description: Dátum vystavenia vo formáte `Y-m-d`.
          type: string
          format: date
          example: '2026-03-03'
        dueDate:
          description: Dátum splatnosti vo formáte `Y-m-d`. Musí byť väčší alebo rovný `issueDate`.
          type: string
          format: date
          example: '2026-03-17'
        deliveryDate:
          description: Dátum dodania vo formáte `Y-m-d`. Musí byť menší alebo rovný `issueDate`.
          type: string
          format: date
          example: '2026-03-03'
        bankAccountId:
          description: ID bankového účtu firmy použitého na dobropise.
          type: integer
          example: 201
        variableSymbol:
          description: Variabilný symbol s dĺžkou 1 až 10 číslic.
          type: integer
          minimum: 0
          maximum: 9999999999
          example: 20260051
        constantSymbol:
          description: Konštantný symbol s dĺžkou 1 až 4 číslic.
          type: [integer, 'null']
          minimum: 0
          maximum: 9999
          example: 308
        specificSymbol:
          description: Špecifický symbol s dĺžkou 1 až 10 číslic.
          type: [integer, 'null']
          minimum: 0
          maximum: 9999999999
          example: 55
        discountType:
          description: Typ zľavy na úrovni celého dokladu.
          type: [string, 'null']
          enum: [percentage, fixed]
          example: percentage
        discountValue:
          description: Hodnota zľavy na úrovni celého dokladu.
          type: [number, 'null']
          format: float
          example: 10.0
        transferTaxLiability:
          description: Príznak prenesenej daňovej povinnosti.
          type: boolean
          example: false
        paymentMethodId:
          type: integer
          description: "ID spôsobu úhrady z [referenčnej tabuľky spôsobov úhrady](/reference-tables#sposoby-uhrady)."
          example: 1
        currencyId:
          type: integer
          description: "ID meny z [referenčnej tabuľky mien](/reference-tables#meny)."
          example: 1
        currencyRate:
          description: Kurz meny k EUR. Ak je mena dokladu `EUR`, backend vždy uloží a vráti `1.0`.
          type: number
          format: float
          minimum: 0.00001
          maximum: 10000000
          example: 1.0
        languageId:
          type: integer
          description: "ID jazyka z [referenčnej tabuľky jazykov](/reference-tables#jazyky)."
          example: 1
        note:
          description: Poznámka na doklade.
          type: [string, 'null']
          maxLength: 3000
          example: Dobropis k pôvodnej faktúre.
        textAboveItems:
          description: Text nad položkami.
          type: [string, 'null']
          maxLength: 3000
          example: Dobropisujeme časť pôvodného plnenia.
        items:
          description: Položky dobropisu. Výsledný doklad musí mať zápornú celkovú sumu.
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/InvoiceItemInput'
    InvoiceCreditNoteInput:
      description: >-
        Voliteľný override payload pre shortcut endpoint `POST /invoices/{invoice}/credit-notes`. Všetky ostatné business polia dobropisu
        sa odvodia na serveri zo zdrojovej faktúry. Nepodporuje položky, klienta ani bankový účet v requeste.
      type: object
      properties:
        number:
          description: Manuálne číslo dobropisu. Ak ho nepošlete, backend použije číslo z primárneho číselného radu dobropisov, resp. z radu určeného cez `numericalSeriesId`. Ak pošlete `number`, nepošlite zároveň `numericalSeriesId`.
          type: string
          minLength: 1
          maxLength: 20
          example: '20260051'
        numericalSeriesId:
          description: ID číselného radu dobropisov. Ak ho pošlete bez `number`, backend z neho vygeneruje finálne číslo dobropisu. Ak pošlete `numericalSeriesId`, nepošlite zároveň manuálne `number`.
          type: [integer, 'null']
          example: 12
        issueDate:
          description: Voliteľný dátum vystavenia vo formáte `Y-m-d`. Ak ho nepošlete, použije sa dnešný dátum.
          type: string
          format: date
          example: '2026-03-05'
        dueDate:
          description: Voliteľný dátum splatnosti vo formáte `Y-m-d`. Ak ho nepošlete, použije sa finálny `issueDate`. Ak ho pošlete, musí byť väčší alebo rovný finálnemu `issueDate`.
          type: string
          format: date
          example: '2026-03-19'
        deliveryDate:
          description: Voliteľný dátum dodania vo formáte `Y-m-d`. Ak ho nepošlete, použije sa finálny `issueDate`. Ak ho pošlete, musí byť menší alebo rovný finálnemu `issueDate`.
          type: string
          format: date
          example: '2026-03-04'
        note:
          description: Voliteľný override poznámky. Ak pole nepošlete, použije sa `note` zo zdrojovej faktúry. Ak pošlete `null`, poznámka sa vynuluje.
          type: [string, 'null']
          maxLength: 3000
          example: Dobropis k čiastočnému storno plnenia.
        textAboveItems:
          description: Voliteľný override textu nad položkami. Ak pole nepošlete, použije sa `textAboveItems` zo zdrojovej faktúry. Ak pošlete `null`, text sa vynuluje.
          type: [string, 'null']
          maxLength: 3000
          example: Dobropisujeme pôvodné plnenie v plnom rozsahu.
    ProformaInput:
      description: >-
        Payload pre vytvorenie zálohovej faktúry. V bežnom prípade stačí poslať `clientId` a `items`; ostatné polia môže backend dopočítať. Musíte poslať buď `clientId`, alebo objekt `client`.
      type: object
      required: [items]
      anyOf:
        - required: [clientId]
        - required: [client]
      properties:
        number:
          description: Manuálne číslo zálohovej faktúry. Ak ho nepošlete, backend ho vygeneruje z číselného radu. Ak pošlete `number`, nepošlite zároveň `numericalSeriesId`.
          type: [string, 'null']
          minLength: 1
          maxLength: 20
          example: '20260001'
        orderId:
          description: Voliteľné ID objednávky, z ktorej sa zálohová faktúra vytvára.
          type: [integer, 'null']
          example: 501
        quotationId:
          description: Voliteľné ID cenovej ponuky, z ktorej sa zálohová faktúra vytvára.
          type: [integer, 'null']
          example: 601
        clientId:
          description: ID existujúceho klienta. Toto je odporúčaný spôsob tvorby zálohovej faktúry. Ak zároveň pošlete objekt `client`, použije sa ako sparse override snapshotu klienta pre tento konkrétny doklad.
          type: [integer, 'null']
          example: 101
        client:
          description: 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í.
          anyOf:
            - $ref: '#/components/schemas/InvoiceClientInput'
            - type: 'null'
        businessCaseId:
          description: Voliteľné ID obchodného prípadu. Ak ho pošlete, musí patriť klientovi určenému cez finálny `clientId`.
          type: [integer, 'null']
          example: 701
        numericalSeriesId:
          description: ID číselného radu. Ak ho nepošlete a nepošlete ani `number`, použije sa primárny číselný rad pre zálohové faktúry. Ak pošlete `numericalSeriesId`, nepošlite zároveň manuálne `number`.
          type: [integer, 'null']
          example: 12
        bankAccountId:
          description: ID bankového účtu, ktorý sa má použiť na doklade. 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` validačnú chybu s chybou pri `bankAccountId`.
          type: integer
          example: 201
        issueDate:
          description: Dátum vystavenia vo formáte `Y-m-d`. Musí byť po `2009-01-01` a pred dátumom o jeden rok v budúcnosti. Ak ho nepošlete, použije sa dnešný dátum.
          type: string
          format: date
          example: '2026-03-03'
        dueDateDays:
          description: Počet dní splatnosti. Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy.
          type: integer
          minimum: 0
          maximum: 1000
          example: 14
        variableSymbol:
          description: Variabilný symbol. Povolené sú hodnoty s dĺžkou 1 až 10 číslic. Ak ho nepošlete, backend ho odvodí z finálneho čísla dokladu.
          type: integer
          minimum: 0
          maximum: 9999999999
          example: 20260001
        constantSymbol:
          description: Konštantný symbol. Povolené sú hodnoty s dĺžkou 1 až 4 číslic. Priorita je payload → klientská predvolená hodnota → `null`.
          type: [integer, 'null']
          minimum: 0
          maximum: 9999
          example: 308
        specificSymbol:
          description: Špecifický symbol. Povolené sú hodnoty s dĺžkou 1 až 10 číslic. Priorita je payload → klientská predvolená hodnota → `null`.
          type: [integer, 'null']
          minimum: 0
          maximum: 9999999999
          example: 55
        discountType:
          description: Typ zľavy na úrovni celého dokladu.
          type: [string, 'null']
          enum: [percentage, fixed]
          example: percentage
        discountValue:
          description: Hodnota zľavy na úrovni celého dokladu.
          type: [number, 'null']
          format: float
          minimum: 0
          example: 10.0
        transferTaxLiability:
          description: Príznak prenesenej daňovej povinnosti. Ak ho nepošlete, použije sa `false`.
          type: boolean
          example: false
        deliveryMethodId:
          type: integer
          description: "ID spôsobu dodania z [referenčnej tabuľky spôsobov dodania](/reference-tables#sposoby-dodania). Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy."
          example: 1
        paymentMethodId:
          type: integer
          description: "ID spôsobu úhrady z [referenčnej tabuľky spôsobov úhrady](/reference-tables#sposoby-uhrady). Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy."
          example: 1
        currencyId:
          type: integer
          description: "ID meny z [referenčnej tabuľky mien](/reference-tables#meny). Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy."
          example: 1
        languageId:
          type: integer
          description: "ID jazyka z [referenčnej tabuľky jazykov](/reference-tables#jazyky). Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy."
          example: 1
        qrTypeId:
          type: integer
          description: "ID QR typu z [referenčnej tabuľky QR typov](/reference-tables#qr-typy). Ak ho nepošlete, použije sa nastavenia dokladov firmy."
          example: 1
        note:
          description: Poznámka na doklade. Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy.
          type: [string, 'null']
          maxLength: 3000
          example: Ďakujeme za objednávku.
        textAboveItems:
          description: Text nad položkami. Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy.
          type: [string, 'null']
          maxLength: 3000
          example: Dakujeme za spoluprácu.
        items:
          description: Položky zálohovej faktúry. Toto pole je povinné vždy.
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/ProformaItemInput'

    InvoiceUpdateItemInput:
      description: >-
        Payload jednej položky faktúry pri update. Pravidlá sú rovnaké ako pri create, ale navyše môžete poslať pôvodné `uuid` existujúceho riadku faktúry. Toto UUID máte k dispozícii v detaile faktúry. Backend ho používa pri synchronizácii skladových alokácií a výdajok, aby vedel spárovať upravovaný riadok s pôvodným riadkom dokladu. Pri create flowe `uuid` nie je súčasťou item request kontraktu; ak ho pošlete, backend ho ignoruje.
      allOf:
        - $ref: '#/components/schemas/InvoiceItemInput'
        - type: object
          properties:
            uuid:
              description: UUID pôvodného riadku faktúry, ktoré získate z detailu faktúry. Posielajte ho len pri update existujúcich položiek, keď chcete zachovať väzby na skladové pohyby a výdajky. UUID musí patriť položke aktuálne upravovanej faktúry.
              type: [string, 'null']
              format: uuid
              example: 6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19

    InvoiceUpdateInput:
      description: >-
        Payload pre aktualizáciu faktúry. Update používa rovnaké polia, rovnaké validačné pravidlá a rovnaké defaulty ako create flow. Musíte poslať buď `clientId`, alebo objekt `client`. Omitted polia sa nedoťahujú z aktuálnej faktúry; backend ich vyrieši rovnako ako pri create flowe. Jediný rozdiel oproti create je, že pri položkách môžete navyše posielať pôvodné `uuid` existujúcich riadkov faktúry; create flow ich ignoruje.
      allOf:
        - $ref: '#/components/schemas/InvoiceInput'
        - type: object
          properties:
            proformaId:
              description: Voliteľné ID zálohovej faktúry, z ktorej sa má vytvoriť finálny stav faktúry. Pri update môže byť toto ID buď ešte nepriradené, alebo už naviazané na aktuálne upravovanú faktúru.
              type: [integer, 'null']
              example: 401
            orderId:
              description: Voliteľné ID objednávky, z ktorej sa má vytvoriť finálny stav faktúry. Pri update môže byť toto ID buď ešte nepriradené, alebo už naviazané na aktuálne upravovanú faktúru.
              type: [integer, 'null']
              example: 501
            quotationId:
              description: Voliteľné ID cenovej ponuky, z ktorej sa má vytvoriť finálny stav faktúry. Pri update môže byť toto ID buď ešte nepriradené, alebo už naviazané na aktuálne upravovanú faktúru.
              type: [integer, 'null']
              example: 601
            items:
              description: Položky faktúry. Toto pole je pri update povinné vždy. Ak pri existujúcej položke pošlete jej pôvodné `uuid` z detailu faktúry, backend vie zachovať väzby na skladové výdajky a synchronizovať zmenené alokácie na tom istom riadku.
              type: array
              minItems: 1
              maxItems: 100
              items:
                $ref: '#/components/schemas/InvoiceUpdateItemInput'
    CreditNoteUpdateInput:
      description: >-
        Payload pre aktualizáciu dobropisu. Update používa rovnaké polia a rovnaké validačné pravidlá ako create flow. Musíte poslať celý
        business payload vrátane `invoiceId` a `items`; omitted polia sa nedoťahujú z aktuálneho dobropisu. Klient sa vždy preberá zo
        zvolenej zdrojovej faktúry.
      allOf:
        - $ref: '#/components/schemas/CreditNoteInput'
        - type: object
          properties:
            items:
              description: Položky dobropisu. Toto pole je pri update povinné vždy. Ak pri existujúcej položke pošlete jej pôvodné `uuid` z detailu dobropisu, backend vie zachovať väzby na skladové príjemky. Pri create flowe item `uuid` nie je súčasťou request kontraktu a backend ho ignoruje.
              type: array
              minItems: 1
              maxItems: 100
              items:
                $ref: '#/components/schemas/InvoiceUpdateItemInput'
    ProformaUpdateInput:
      description: >-
        Payload pre aktualizáciu zálohovej faktúry. Update používa rovnaké polia, rovnaké validačné pravidlá a rovnaké defaulty ako create flow. Musíte poslať buď `clientId`, alebo objekt `client`. Omitted polia sa nedoťahujú z aktuálnej zálohovej faktúry; backend ich vyrieši rovnako ako pri create flowe.
      allOf:
        - $ref: '#/components/schemas/ProformaInput'
        - type: object
          properties:
            orderId:
              description: Voliteľné ID objednávky, z ktorej sa má vytvoriť finálny stav zálohovej faktúry. Pri update môže byť toto ID buď ešte nepriradené, alebo už naviazané na aktuálne upravovanú zálohovú faktúru.
              type: [integer, 'null']
              example: 501
            quotationId:
              description: Voliteľné ID cenovej ponuky, z ktorej sa má vytvoriť finálny stav zálohovej faktúry. Pri update môže byť toto ID buď ešte nepriradené, alebo už naviazané na aktuálne upravovanú zálohovú faktúru.
              type: [integer, 'null']
              example: 601
            items:
              description: Položky zálohovej faktúry. Toto pole je pri update povinné vždy.
              type: array
              minItems: 1
              maxItems: 100
              items:
                $ref: '#/components/schemas/ProformaItemInput'
    ProformaItemInput:
      description: >-
        Payload jednej položky zálohovej faktúry. Podporované sú tri režimy: manuálna položka, `priceListItemId + quantity`, alebo
        `priceListItemId` s čiastočnými override poľami. Povinné je vždy `quantity`. Ak nepošlete `priceListItemId`, musíte poslať
        aj `name`, `unitPrice` a `vatRate`. `unitId` je voliteľné; ak ho pri manuálnej položke nepošlete, backend použije jednotku
        `1` (`ks` / `Unit::Piece`). Ak `priceListItemId` pošlete, backend si z cenníkovej položky vie dopočítať názov, jednotku,
        cenu a sadzbu DPH; payload potom slúži len ako sparse override. Per-item `uuid` nie je súčasťou request kontraktu; ak ho
        pošlete, backend ho ignoruje. `warehouseAllocations` pri zálohových faktúrach nie sú podporované.
      type: object
      required: [quantity]
      anyOf:
        - required: [priceListItemId]
        - required: [name, unitPrice, vatRate]
      properties:
        name:
          description: 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.
          type: [string, 'null']
          maxLength: 255
          example: Konzultácia
        description:
          description: Voliteľný popis položky. Pri `priceListItemId` môže prepísať alebo doplniť popis z cenníkovej položky.
          type: [string, 'null']
          maxLength: 1000
          example: Mesačný balík konzultácií
        unitPrice:
          description: Jednotková cena bez DPH. Pri manuálnej položke je povinná. Pri `priceListItemId` môže prepísať cenu načítanú z cenníka.
          type: [number, 'null']
          format: float
          minimum: -10000000000000
          maximum: 10000000000000
          example: 100.0
        unitId:
          description: "Voliteľné ID jednotky z [referenčnej tabuľky jednotiek](/reference-tables#jednotky). Pri manuálnej položke, kde ho nepošlete, backend použije jednotku `1` (`ks` / `Unit::Piece`). Pri `priceListItemId` môže prepísať jednotku z cenníkovej položky."
          type: [integer, 'null']
          example: 1
        quantity:
          description: 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.
          type: number
          format: float
          minimum: 0.00001
          maximum: 1000000
          example: 2.0
        vatRate:
          description: Sadzba DPH v percentách. Pri manuálnej položke je povinná. Pri `priceListItemId` môže prepísať sadzbu z cenníkovej položky.
          type: [number, 'null']
          format: float
          minimum: 0
          maximum: 100
          example: 20.0
        discountType:
          description: Typ zľavy na úrovni položky. Povolené hodnoty sú `percentage` a `fixed`.
          type: [string, 'null']
          enum: [percentage, fixed]
          example: percentage
        discountValue:
          description: Hodnota zľavy na úrovni položky. Ak pošlete `discountType`, musíte poslať aj toto pole.
          type: [number, 'null']
          format: float
          minimum: -10000000000000
          maximum: 10000000000000
          example: 10.0
        discountName:
          description: 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.
          type: [string, 'null']
          maxLength: 255
          example: Vernostná zľava
        priceListItemId:
          description: 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.
          type: [integer, 'null']
          example: 501
    OrderItemInput:
      description: >-
        Payload jednej položky objednávky. Podporované sú tri režimy: manuálna položka, `priceListItemId + quantity`, alebo
        `priceListItemId` s čiastočnými override poľami. Povinné je vždy `quantity`. Ak nepošlete `priceListItemId`, musíte poslať
        aj `name`, `unitPrice` a `vatRate`. `unitId` je voliteľné; ak ho pri manuálnej položke nepošlete, backend použije jednotku
        `1` (`ks` / `Unit::Piece`). Ak `priceListItemId` pošlete, backend si z cenníkovej položky vie dopočítať názov, jednotku,
        cenu a sadzbu DPH; payload potom slúži len ako sparse override.
      type: object
      required: [quantity]
      anyOf:
        - required: [priceListItemId]
        - required: [name, unitPrice, vatRate]
      properties:
        name:
          description: 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.
          type: [string, 'null']
          maxLength: 255
          example: Konzultácia
        description:
          description: Voliteľný popis položky. Pri `priceListItemId` môže prepísať alebo doplniť popis z cenníkovej položky.
          type: [string, 'null']
          maxLength: 1000
          example: Mesačný balík konzultácií
        unitPrice:
          description: Jednotková cena bez DPH. Pri manuálnej položke je povinná. Pri `priceListItemId` môže prepísať cenu načítanú z cenníka.
          type: [number, 'null']
          format: float
          minimum: -10000000000000
          maximum: 10000000000000
          example: 100.0
        unitId:
          description: "Voliteľné ID jednotky z [referenčnej tabuľky jednotiek](/reference-tables#jednotky). Pri manuálnej položke, kde ho nepošlete, backend použije jednotku `1` (`ks` / `Unit::Piece`). Pri `priceListItemId` môže prepísať jednotku z cenníkovej položky."
          type: [integer, 'null']
          example: 1
        quantity:
          description: 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.
          type: number
          format: float
          minimum: 0.00001
          maximum: 1000000
          example: 2.0
        vatRate:
          description: Sadzba DPH v percentách. Pri manuálnej položke je povinná. Pri `priceListItemId` môže prepísať sadzbu z cenníkovej položky.
          type: [number, 'null']
          format: float
          minimum: 0
          maximum: 100
          example: 20.0
        discountType:
          description: Typ zľavy na úrovni položky. Povolené hodnoty sú `percentage` a `fixed`.
          type: [string, 'null']
          enum: [percentage, fixed]
          example: percentage
        discountValue:
          description: Hodnota zľavy na úrovni položky. Ak pošlete `discountType`, musíte poslať aj toto pole.
          type: [number, 'null']
          format: float
          minimum: -10000000000000
          maximum: 10000000000000
          example: 10.0
        discountName:
          description: 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.
          type: [string, 'null']
          maxLength: 255
          example: Vernostná zľava
        priceListItemId:
          description: 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.
          type: [integer, 'null']
          example: 501
    OrderClientInput:
      description: >-
        Sparse klientský payload používaný pri tvorbe alebo úprave objednávky. Ak pošlete `clientId`, tento objekt slúži ako
        voliteľný override snapshotu klienta iba pre konkrétny doklad. Ak `clientId` nepošlete, backend sa podľa tohto objektu
        pokúsi nájsť existujúceho klienta alebo vytvoriť nového.
      allOf:
        - $ref: '#/components/schemas/InvoiceClientInput'
    OrderInput:
      description: >-
        Payload pre vytvorenie objednávky. V bežnom prípade stačí poslať `clientId` a `items`; ostatné polia môže backend dopočítať.
        Musíte poslať buď `clientId`, alebo objekt `client`.
      type: object
      required: [items]
      anyOf:
        - required: [clientId]
        - required: [client]
      properties:
        number:
          description: Manuálne číslo objednávky. Ak ho nepošlete, backend ho vygeneruje z číselného radu. Ak pošlete `number`, nepošlite zároveň `numericalSeriesId`.
          type: [string, 'null']
          minLength: 1
          maxLength: 20
          example: '20260001'
        quotationId:
          description: Voliteľné ID cenovej ponuky, z ktorej sa objednávka vytvára. Doklad nesmie byť naviazaný na inú objednávku.
          type: [integer, 'null']
          example: 601
        clientId:
          description: ID existujúceho klienta. Toto je odporúčaný spôsob tvorby objednávky. Ak zároveň pošlete objekt `client`, použije sa ako sparse override snapshotu klienta pre tento konkrétny doklad.
          type: [integer, 'null']
          example: 101
        client:
          description: 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í.
          anyOf:
            - $ref: '#/components/schemas/OrderClientInput'
            - type: 'null'
        businessCaseId:
          description: Voliteľné ID obchodného prípadu. Ak ho pošlete, musí patriť klientovi určenému cez finálny `clientId`.
          type: [integer, 'null']
          example: 701
        numericalSeriesId:
          description: ID číselného radu. Ak ho nepošlete a nepošlete ani `number`, použije sa primárny číselný rad pre objednávky. Ak pošlete `numericalSeriesId`, nepošlite zároveň manuálne `number`.
          type: [integer, 'null']
          example: 12
        issueDate:
          description: Dátum vystavenia vo formáte `Y-m-d`. Musí byť po `2009-01-01` a pred dátumom o jeden rok v budúcnosti. Ak ho nepošlete, použije sa dnešný dátum.
          type: string
          format: date
          example: '2026-03-03'
        discountType:
          description: Typ zľavy na úrovni celého dokladu.
          type: [string, 'null']
          enum: [percentage, fixed]
          example: percentage
        discountValue:
          description: Hodnota zľavy na úrovni celého dokladu.
          type: [number, 'null']
          format: float
          minimum: 0
          example: 10.0
        transferTaxLiability:
          description: Príznak prenesenej daňovej povinnosti. Ak ho nepošlete, použije sa `false`.
          type: boolean
          example: false
        deliveryMethodId:
          type: integer
          description: "ID spôsobu dodania z [referenčnej tabuľky spôsobov dodania](/reference-tables#sposoby-dodania). Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy."
          example: 1
        paymentMethodId:
          type: integer
          description: "ID spôsobu úhrady z [referenčnej tabuľky spôsobov úhrady](/reference-tables#sposoby-uhrady). Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy."
          example: 1
        currencyId:
          type: integer
          description: "ID meny z [referenčnej tabuľky mien](/reference-tables#meny). Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy."
          example: 1
        languageId:
          type: integer
          description: "ID jazyka z [referenčnej tabuľky jazykov](/reference-tables#jazyky). Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy."
          example: 1
        note:
          description: Poznámka na doklade. Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy.
          type: [string, 'null']
          maxLength: 3000
          example: Ďakujeme za objednávku.
        textAboveItems:
          description: Text nad položkami. Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy.
          type: [string, 'null']
          maxLength: 3000
          example: Dakujeme za spoluprácu.
        items:
          description: Položky objednávky. Toto pole je povinné vždy. Per-item `uuid` nie je súčasťou request kontraktu; ak ho pošlete, backend ho ignoruje. `warehouseAllocations` pri objednávkach nie sú podporované.
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/OrderItemInput'
    OrderUpdateInput:
      description: >-
        Payload pre aktualizáciu objednávky. Update používa rovnaké polia, rovnaké validačné pravidlá a rovnaké defaulty ako create
        flow. Musíte poslať buď `clientId`, alebo objekt `client`. Omitted polia sa nedoťahujú z aktuálnej objednávky; backend ich
        vyrieši rovnako ako pri create flowe. Ak pri update vynecháte `quotationId`, existujúca väzba na cenovú ponuku sa odstráni.
      allOf:
        - $ref: '#/components/schemas/OrderInput'
        - type: object
          properties:
            quotationId:
              description: Voliteľné ID cenovej ponuky, z ktorej sa má vytvoriť finálny stav objednávky. Pri update môže byť toto ID buď ešte nepriradené, alebo už naviazané na aktuálne upravovanú objednávku. Ak pole vynecháte alebo pošlete `null`, existujúca väzba sa odstráni.
              type: [integer, 'null']
              example: 601
            items:
              description: Položky objednávky. Toto pole je pri update povinné vždy. Per-item `uuid` nie je súčasťou request kontraktu; ak ho pošlete, backend ho ignoruje. `warehouseAllocations` pri objednávkach nie sú podporované.
              type: array
              minItems: 1
              maxItems: 100
              items:
                $ref: '#/components/schemas/OrderItemInput'
    QuotationItemInput:
      description: >-
        Payload jednej položky cenovej ponuky. Podporované sú tri režimy: manuálna položka, `priceListItemId + quantity`, alebo
        `priceListItemId` s čiastočnými override poľami. Povinné je vždy `quantity`. Ak nepošlete `priceListItemId`, musíte poslať
        aj `name`, `unitPrice` a `vatRate`. `unitId` je voliteľné; ak ho pri manuálnej položke nepošlete, backend použije jednotku
        `1` (`ks` / `Unit::Piece`). Ak `priceListItemId` pošlete, backend si z cenníkovej položky vie dopočítať názov, jednotku,
        cenu a sadzbu DPH; payload potom slúži len ako sparse override. `uuid` nie je súčasťou request kontraktu cenových ponúk; ak ho
        pošlete, backend ho ignoruje. `warehouseAllocations` pri cenových ponukách nie sú podporované.
      type: object
      required: [quantity]
      anyOf:
        - required: [priceListItemId]
        - required: [name, unitPrice, vatRate]
      properties:
        name:
          description: 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.
          type: [string, 'null']
          maxLength: 255
          example: Konzultácia
        description:
          description: Voliteľný popis položky. Pri `priceListItemId` môže prepísať alebo doplniť popis z cenníkovej položky.
          type: [string, 'null']
          maxLength: 1000
          example: Mesačný balík konzultácií
        unitPrice:
          description: Jednotková cena bez DPH. Pri manuálnej položke je povinná. Pri `priceListItemId` môže prepísať cenu načítanú z cenníka.
          type: [number, 'null']
          format: float
          minimum: -10000000000000
          maximum: 10000000000000
          example: 100.0
        unitId:
          description: "Voliteľné ID jednotky z [referenčnej tabuľky jednotiek](/reference-tables#jednotky). Pri manuálnej položke, kde ho nepošlete, backend použije jednotku `1` (`ks` / `Unit::Piece`). Pri `priceListItemId` môže prepísať jednotku z cenníkovej položky."
          type: [integer, 'null']
          example: 1
        quantity:
          description: 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.
          type: number
          format: float
          minimum: 0.00001
          maximum: 1000000
          example: 2.0
        vatRate:
          description: Sadzba DPH v percentách. Pri manuálnej položke je povinná. Pri `priceListItemId` môže prepísať sadzbu z cenníkovej položky.
          type: [number, 'null']
          format: float
          minimum: 0
          maximum: 100
          example: 20.0
        discountType:
          description: Typ zľavy na úrovni položky. Povolené hodnoty sú `percentage` a `fixed`.
          type: [string, 'null']
          enum: [percentage, fixed]
          example: percentage
        discountValue:
          description: Hodnota zľavy na úrovni položky. Ak pošlete `discountType`, musíte poslať aj toto pole.
          type: [number, 'null']
          format: float
          minimum: -10000000000000
          maximum: 10000000000000
          example: 10.0
        discountName:
          description: 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.
          type: [string, 'null']
          maxLength: 255
          example: Vernostná zľava
        priceListItemId:
          description: 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.
          type: [integer, 'null']
          example: 501
    QuotationClientInput:
      description: >-
        Sparse klientský payload používaný pri tvorbe alebo úprave cenovej ponuky. Ak pošlete `clientId`, tento objekt slúži ako
        voliteľný override snapshotu klienta iba pre konkrétny doklad. Ak `clientId` nepošlete, backend sa podľa tohto objektu
        pokúsi nájsť existujúceho klienta alebo vytvoriť nového.
      allOf:
        - $ref: '#/components/schemas/InvoiceClientInput'
    QuotationInput:
      description: >-
        Payload pre vytvorenie cenovej ponuky. V bežnom prípade stačí poslať `clientId` a `items`; ostatné polia môže backend
        dopočítať. Musíte poslať buď `clientId`, alebo objekt `client`.
      type: object
      required: [items]
      anyOf:
        - required: [clientId]
        - required: [client]
      properties:
        number:
          description: Manuálne číslo cenovej ponuky. Ak ho nepošlete, backend ho vygeneruje z číselného radu. Ak pošlete `number`, nepošlite zároveň `numericalSeriesId`.
          type: [string, 'null']
          minLength: 1
          maxLength: 20
          example: '20260001'
        clientId:
          description: ID existujúceho klienta. Toto je odporúčaný spôsob tvorby cenovej ponuky. Ak zároveň pošlete objekt `client`, použije sa ako sparse override snapshotu klienta pre tento konkrétny doklad.
          type: [integer, 'null']
          example: 101
        client:
          description: 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í.
          anyOf:
            - $ref: '#/components/schemas/QuotationClientInput'
            - type: 'null'
        businessCaseId:
          description: Voliteľné ID obchodného prípadu. Ak ho pošlete, musí patriť klientovi určenému cez finálny `clientId`.
          type: [integer, 'null']
          example: 701
        numericalSeriesId:
          description: ID číselného radu. Ak ho nepošlete a nepošlete ani `number`, použije sa primárny číselný rad pre cenové ponuky. Ak pošlete `numericalSeriesId`, nepošlite zároveň manuálne `number`.
          type: [integer, 'null']
          example: 12
        issueDate:
          description: Dátum vystavenia vo formáte `Y-m-d`. Musí byť po `2009-01-01` a pred dátumom o jeden rok v budúcnosti. Ak ho nepošlete, použije sa dnešný dátum.
          type: string
          format: date
          example: '2026-03-03'
        validityDate:
          description: Dátum platnosti vo formáte `Y-m-d`. Musí byť rovný alebo neskorší než finálny `issueDate`. Ak ho nepošlete, použije sa `issueDate + 30 dní`.
          type: [string, 'null']
          format: date
          example: '2026-04-02'
        discountType:
          description: Typ zľavy na úrovni celého dokladu.
          type: [string, 'null']
          enum: [percentage, fixed]
          example: percentage
        discountValue:
          description: Hodnota zľavy na úrovni celého dokladu.
          type: [number, 'null']
          format: float
          minimum: 0
          example: 10.0
        transferTaxLiability:
          description: Príznak prenesenej daňovej povinnosti. Ak ho nepošlete, použije sa `false`.
          type: boolean
          example: false
        currencyId:
          type: integer
          description: "ID meny z [referenčnej tabuľky mien](/reference-tables#meny). Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy."
          example: 1
        languageId:
          type: integer
          description: "ID jazyka z [referenčnej tabuľky jazykov](/reference-tables#jazyky). Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy."
          example: 1
        note:
          description: Poznámka na doklade. Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy.
          type: [string, 'null']
          maxLength: 3000
          example: Cenová ponuka platí 30 dní.
        textAboveItems:
          description: Text nad položkami. Priorita je payload → klientská predvolená hodnota → nastavenia dokladov firmy.
          type: [string, 'null']
          maxLength: 3000
          example: Dakujeme za Váš záujem.
        items:
          description: Položky cenovej ponuky. Toto pole je povinné vždy. Per-item `uuid` nie je súčasťou request kontraktu; ak ho pošlete, backend ho ignoruje. `warehouseAllocations` pri cenových ponukách nie sú podporované.
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/QuotationItemInput'
    QuotationUpdateInput:
      description: >-
        Payload pre aktualizáciu cenovej ponuky. Update používa rovnaké polia, rovnaké validačné pravidlá a rovnaké defaulty ako
        create flow. Musíte poslať buď `clientId`, alebo objekt `client`. Omitted polia sa nedoťahujú z aktuálnej cenovej ponuky;
        backend ich vyrieši rovnako ako pri create flowe.
      allOf:
        - $ref: '#/components/schemas/QuotationInput'
        - type: object
          properties:
            items:
              description: Položky cenovej ponuky. Toto pole je pri update povinné vždy.
              type: array
              minItems: 1
              maxItems: 100
              items:
                $ref: '#/components/schemas/QuotationItemInput'