> ## 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ť odber webhookov > 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. ## OpenAPI ````yaml /openapi.yaml post /webhook-subscriptions 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: /webhook-subscriptions: post: tags: - Webhooky summary: Vytvoriť odber webhookov 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. operationId: createWebhookSubscription 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' 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: 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 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 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' 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: 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. 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. ````