> ## Documentation Index > Fetch the complete documentation index at: https://docs.fintoro.sk/llms.txt > Use this file to discover all available pages before exploring further. # Vytvoriť objednávku > 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. ## OpenAPI ````yaml /openapi.yaml post /orders 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: [] 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: /orders: post: tags: - Objednávky summary: Vytvoriť objednávku 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. operationId: createOrder 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' components: parameters: 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 schemas: 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 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' 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: $ref: '#/components/schemas/CompanySnapshot' description: Snapshot dodávateľa uložený priamo na tomto doklade. clientId: description: Live ID klienta naviazaného na objednávku. type: integer example: 101 client: $ref: '#/components/schemas/ClientSnapshot' description: Historický snapshot klienta uložený priamo na tomto doklade. 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 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 itemsTotalWithVat: type: number format: float example: 240 total: type: number format: float example: 200 totalWithVat: type: number format: float example: 240 hasVat: type: boolean example: true items: type: array items: $ref: '#/components/schemas/OrderItem' 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' 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 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 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 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 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 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: description: >- ID krajiny z [referenčnej tabuľky krajín](/reference-tables#krajiny). type: - integer - 'null' 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: description: >- ID krajiny z [referenčnej tabuľky krajín](/reference-tables#krajiny). type: - integer - 'null' example: 703 deliveryCountry: description: Dodacia krajina uložená na faktúre ako vnorený objekt. anyOf: - $ref: '#/components/schemas/Country' - type: 'null' 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 unitId: description: >- ID jednotky z [referenčnej tabuľky jednotiek](/reference-tables#jednotky). type: integer example: 1 quantity: type: number format: float example: 2 vatRate: type: number format: float example: 20 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 total: type: number format: float example: 200 totalWithVat: type: number format: float example: 240 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: description: >- ID krajiny z [referenčnej tabuľky krajín](/reference-tables#krajiny). type: - integer - 'null' 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 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 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: 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 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Token description: Bearer token vytvorený pre konkrétnu firmu v Integrácie → API. ````