> ## 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. # Zoznam klientov > 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. ## OpenAPI ````yaml /openapi.yaml get /clients 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: /clients: get: tags: - Klienti summary: Zoznam klientov 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. operationId: listClients 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' components: 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 schemas: 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. 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 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. ````