> ## 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. # Create invoice > Creates a new invoice. ### Recommended flow The recommended happy path is to send `clientId` and `items`. This is the simplest flow when the client already exists in Fintoro. If the client does not exist yet or you do not want to perform a separate client create step, send the `client` object without `clientId`. The backend attempts to match an existing client and creates a new one only when no match is found. If you send both `clientId` and `client`, the `client` object acts as a sparse snapshot override for this specific document. This lets you adjust, for example, the delivery address or contact details only for this invoice without changing the stored client record. ### How defaults are resolved Most document fields are optional. The backend resolves them in this order: 1. explicit value from the payload, 2. client default values, 3. company document settings, 4. system resolver. In practice, this means for example: - `deliveryMethodId`, `paymentMethodId`, `currencyId`, and `languageId` may be resolved from the client or company settings, - `number` and `numericalSeriesId` are resolved from the primary numbering series when omitted, - `variableSymbol` is derived from the final document number when omitted, - `bankAccountId` falls back to the primary company bank account when omitted, - `currencyRate` is resolved from the currency and delivery date, - if the final document currency is `EUR`, the backend always stores and returns `currencyRate = 1.0`, even when you send a different value, - `issueDate` and `deliveryDate` default to today. ### How client resolution works Client resolution is strictly deterministic: - when you send `clientId`, the backend loads that client by ID within the token scope, - when `clientId` is omitted, the `client` object is used to match or create the client, - when you send both `clientId` and `client`, `client` is applied only as a snapshot override for this document. Matching is deterministic and follows this order: - for companies: `vatId`, then `countryId + subjectId`, then `name + email`, then `name + street`, - for people: `name + email`, then `name + street`. If no match is found, a new client is created. If more than one client matches, the backend uses the first record in a stable order. If you send an explicit `clientId` that does not exist or is outside the token scope, the endpoint returns a `422` validation error on `clientId`. If you send an explicit `bankAccountId` and that record does not exist or is outside the token scope, the endpoint returns a `422` validation error on `bankAccountId`. If you omit `bankAccountId` and the company has no primary bank account configured, the endpoint returns `422`. ### How line items work A line item can be created in three ways: 1. as a manual item with its own name, unit, price, and VAT rate, 2. through `priceListItemId` and `quantity`, 3. through `priceListItemId` and sparse overrides for selected fields such as the price or name. If you send a discount without `discountName`, the backend fills in a localized default discount label based on the document language. ### Request examples Existing client with a manual item: ```json { "clientId": 101, "issueDate": "2026-03-04", "items": [ { "name": "Monthly retainer", "quantity": 1, "unitId": 1, "unitPrice": 120.0, "vatRate": 23 } ] } ``` Inline client without `clientId`: ```json { "client": { "type": "company", "name": "Acme s.r.o.", "email": "billing@acme.test", "countryId": 703, "subjectId": "12345678", "street": "Hlavna 1", "city": "Bratislava", "zip": "81101" }, "items": [ { "name": "API implementation", "quantity": 10, "unitId": 7, "unitPrice": 80.0, "vatRate": 23 } ] } ``` Price list item with the minimum payload: ```json { "clientId": 101, "items": [ { "priceListItemId": 501, "quantity": 2 } ] } ``` If you send an `Idempotency-Key`, the same key with the same payload returns the original response without creating the invoice again. ## OpenAPI ````yaml /en/openapi.yaml post /invoices openapi: 3.1.0 info: title: Fintoro API v1 version: 1.0.0 description: > Fintoro API v1 is a REST API for integrating Fintoro invoicing, CRM, and warehouse workflows into third-party systems. Production and sandbox companies use the same base URL `https://app.fintoro.sk/api/public/v1`. The bearer token decides which company you work with. The optional `Accept-Language` request header localizes system-owned labels in lookups, in related response objects, and in validation errors. The `Content-Language` response header returns the language used in the response. For onboarding and operational guidance, also see: - [Getting started](/en/getting-started) - [Authentication](/en/authentication) - [Webhooks](/en/webhooks) - [Sandbox testing](/en/sandbox-testing) - [API conventions](/en/conventions) - [Errors and idempotency](/en/errors-and-idempotency) servers: - url: https://app.fintoro.sk/api/public/v1 description: Production Fintoro API. security: - bearerAuth: [] tags: - name: Token identity description: >- Technical read-only endpoint that confirms which company the current bearer token belongs to. - name: Lookups description: >- Read-only lookup endpoints for integration data. These endpoints return lookup datasets with stable IDs that are safe to cache on your side. When new lookup values are added, existing IDs do not change or get reassigned. - name: Numerical Series description: >- Read-only endpoints for numerical series. They return the live configuration used when creating documents, including the next generated document number and variable symbol. - name: Subjects description: Look up and verify subject details before creating a client. - name: Clients description: >- Manage clients, including billing address, delivery address, and client-scoped default values that can be reused when building payloads for new documents. Create, update, and delete operations can emit `clients.created`, `clients.updated`, and `clients.deleted` webhook events. - name: Suppliers description: >- Manage suppliers, including billing address and identifier data used by the warehouse inbound resolve-or-create flow. Create, update, and delete operations can emit `suppliers.created`, `suppliers.updated`, and `suppliers.deleted` webhook events. - name: Business Case Statuses description: >- Manage business-case statuses. Statuses represent pipeline columns. In this API version, a reorder endpoint is not available; when a status is deleted, linked business cases are detached to `null`. Create, update, and delete operations can emit `business-case-statuses.created`, `business-case-statuses.updated`, and `business-case-statuses.deleted` webhook events. - name: Business Cases description: >- Manage business cases, including the nested client or supplier and an optional status. Reorder flows and changing the linked contact through update are not available in this API version. Create, update, and delete operations can emit `business-cases.created`, `business-cases.updated`, and `business-cases.deleted` webhook events. - name: CRM Events description: >- Manage CRM events for `note`, `email`, `phone_call`, and `document_linked`. Attachments use a separate two-step upload endpoint. Create, update, and delete operations can emit `contact-activity-logs.created`, `contact-activity-logs.updated`, and `contact-activity-logs.deleted` webhook events. - name: Bank Accounts description: >- Manage bank accounts, including bank details, primary account state, and open banking metadata. Create, update, and delete operations can emit `bank-accounts.created`, `bank-accounts.updated`, and `bank-accounts.deleted` webhook events. - name: Webhooks description: >- Manage outbound webhook subscriptions for Fintoro API. This section covers subscription CRUD, manual secret rotation, and the delivery payload contract for event-driven integrations. The delivery contract, signature verification, retry behavior, and full event catalog are documented in the [Webhooks guide](/en/webhooks). - name: Warehouses description: >- CRUD operations for warehouses, including inbound and outbound numbering series. Create, update, and delete operations can emit `warehouses.created`, `warehouses.updated`, and `warehouses.deleted` webhook events. - name: Warehouse Inbound Receipts description: >- CRUD operations for warehouse inbound receipts, including warehouse detail, supplier snapshot, receipt items, and `pdfDownloadUrl`. Create, update, and delete operations can emit `warehouse-inbound-receipts.created`, `warehouse-inbound-receipts.updated`, and `warehouse-inbound-receipts.deleted` webhook events. - name: Warehouse Outbound Receipts description: >- CRUD operations for warehouse outbound receipts, including warehouse detail, client snapshot, receipt items, and `pdfDownloadUrl`. Create and update use the same stock-availability validation as the web. Create, update, and delete operations can emit `warehouse-outbound-receipts.created`, `warehouse-outbound-receipts.updated`, and `warehouse-outbound-receipts.deleted` webhook events. - name: Price List Items description: >- CRUD operations for price list and warehouse items. These endpoints return the unit as a nested object, support filtering by name, EAN, warehouse code, price, and stock, and expose the same business contract that Fintoro uses for warehouse tracking, EANs, and purchase prices. Create, update, and delete operations can emit `price-list-items.created`, `price-list-items.updated`, and `price-list-items.deleted` webhook events. Stock changes caused by warehouse inbound and outbound receipts can emit the `price-list-items.stock-updated` webhook event. - name: Document Payments description: >- Payment records for public documents. This section covers listing payments of one document, creating a new payment, showing one payment, and deleting it. Supported document types are `invoice`, `proforma`, `credit-note`, `received-invoice`, and `received-receipt`. Create and delete operations can emit `document-payments.created` and `document-payments.deleted` webhook events. When a newly recorded payment makes a supported document fully paid, Fintoro can also emit the matching `*.paid` event for that document resource. - name: Document Emails description: >- Send supported public documents by email. The endpoint uses a single contract around `documentType` + `documentId`, validates document ownership, and supports `invoice`, `proforma`, `order`, `credit-note`, and `quotation`. - name: Invoices description: >- CRUD operations for invoices. Create, update, and delete operations can emit `invoices.created`, `invoices.updated`, and `invoices.deleted` webhook events. When a recorded payment makes the invoice fully paid, Fintoro can also emit `invoices.paid`. - name: Credit Notes description: >- CRUD operations for credit notes. The contract uses camelCase payloads, a full `PUT` update flow, and an explicit link to the original invoice through `invoiceId`. The credit-note client is always derived from the selected source invoice; `clientId` is not part of the request contract, and inline client resolution or create behavior is not supported here. Create, update, and delete operations can emit `credit-notes.created`, `credit-notes.updated`, and `credit-notes.deleted` webhook events. When a recorded payment makes the credit note fully paid, Fintoro can also emit `credit-notes.paid`. - name: Proformas description: >- CRUD operations for proformas. The contract follows the same philosophy as the public invoice API: camelCase payloads, deterministic client resolve/create behavior, create-like defaults, and a full `PUT` update flow with no patch fallback to the previous persisted document state. Create, update, and delete operations can emit `proformas.created`, `proformas.updated`, `proformas.deleted`, and, when a recorded payment makes the document fully paid, `proformas.paid`. - name: Orders description: >- CRUD operations for orders. The contract uses camelCase payloads, deterministic client resolve/create behavior, create-like defaults, and a full `PUT` update flow with no patch fallback to the previous persisted document state. Create, update, and delete operations can emit `orders.created`, `orders.updated`, and `orders.deleted` webhook events. - name: Quotations description: >- CRUD operations for quotations. The contract uses camelCase payloads, deterministic client resolve/create behavior, create-like defaults, and a full `PUT` update flow with no patch fallback to the previous persisted document state. Create, update, and delete operations can emit `quotations.created`, `quotations.updated`, and `quotations.deleted` webhook events. paths: /invoices: post: tags: - Invoices summary: Create invoice description: > Creates a new invoice. ### Recommended flow The recommended happy path is to send `clientId` and `items`. This is the simplest flow when the client already exists in Fintoro. If the client does not exist yet or you do not want to perform a separate client create step, send the `client` object without `clientId`. The backend attempts to match an existing client and creates a new one only when no match is found. If you send both `clientId` and `client`, the `client` object acts as a sparse snapshot override for this specific document. This lets you adjust, for example, the delivery address or contact details only for this invoice without changing the stored client record. ### How defaults are resolved Most document fields are optional. The backend resolves them in this order: 1. explicit value from the payload, 2. client default values, 3. company document settings, 4. system resolver. In practice, this means for example: - `deliveryMethodId`, `paymentMethodId`, `currencyId`, and `languageId` may be resolved from the client or company settings, - `number` and `numericalSeriesId` are resolved from the primary numbering series when omitted, - `variableSymbol` is derived from the final document number when omitted, - `bankAccountId` falls back to the primary company bank account when omitted, - `currencyRate` is resolved from the currency and delivery date, - if the final document currency is `EUR`, the backend always stores and returns `currencyRate = 1.0`, even when you send a different value, - `issueDate` and `deliveryDate` default to today. ### How client resolution works Client resolution is strictly deterministic: - when you send `clientId`, the backend loads that client by ID within the token scope, - when `clientId` is omitted, the `client` object is used to match or create the client, - when you send both `clientId` and `client`, `client` is applied only as a snapshot override for this document. Matching is deterministic and follows this order: - for companies: `vatId`, then `countryId + subjectId`, then `name + email`, then `name + street`, - for people: `name + email`, then `name + street`. If no match is found, a new client is created. If more than one client matches, the backend uses the first record in a stable order. If you send an explicit `clientId` that does not exist or is outside the token scope, the endpoint returns a `422` validation error on `clientId`. If you send an explicit `bankAccountId` and that record does not exist or is outside the token scope, the endpoint returns a `422` validation error on `bankAccountId`. If you omit `bankAccountId` and the company has no primary bank account configured, the endpoint returns `422`. ### How line items work A line item can be created in three ways: 1. as a manual item with its own name, unit, price, and VAT rate, 2. through `priceListItemId` and `quantity`, 3. through `priceListItemId` and sparse overrides for selected fields such as the price or name. If you send a discount without `discountName`, the backend fills in a localized default discount label based on the document language. ### Request examples Existing client with a manual item: ```json { "clientId": 101, "issueDate": "2026-03-04", "items": [ { "name": "Monthly retainer", "quantity": 1, "unitId": 1, "unitPrice": 120.0, "vatRate": 23 } ] } ``` Inline client without `clientId`: ```json { "client": { "type": "company", "name": "Acme s.r.o.", "email": "billing@acme.test", "countryId": 703, "subjectId": "12345678", "street": "Hlavna 1", "city": "Bratislava", "zip": "81101" }, "items": [ { "name": "API implementation", "quantity": 10, "unitId": 7, "unitPrice": 80.0, "vatRate": 23 } ] } ``` Price list item with the minimum payload: ```json { "clientId": 101, "items": [ { "priceListItemId": 501, "quantity": 2 } ] } ``` If you send an `Idempotency-Key`, the same key with the same payload returns the original response without creating the invoice again. operationId: createInvoice parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InvoiceInput' responses: '201': description: Invoice created. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' Idempotency-Key: description: >- The original idempotency key when it was provided in the request. schema: type: string Idempotency-Status: description: >- `Original` for the first processed request or `Repeated` when the original response is replayed. schema: type: string enum: - Original - Repeated content: application/json: schema: $ref: '#/components/schemas/Invoice' '404': $ref: '#/components/responses/NotFound' '422': description: >- The request is syntactically valid but cannot be processed because of a business rule failure or an idempotency conflict. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: examples: missingPrimaryBankAccount: summary: Missing primary company bank account value: message: The given data was invalid. errors: bankAccountId: - Company has no primary bank account configured. idempotencyConflict: summary: Idempotency key reused with a different payload 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: >- Optional request identifier for safe retries. Use a unique value for each create request you want to retry safely. schema: type: string example: invoice-create-2026-03-03-001 schemas: InvoiceInput: description: >- Payload used to create an invoice. The usual happy path is `clientId` plus `items`; the backend can resolve many other values automatically. You must send either `clientId` or `client`. type: object required: - items anyOf: - required: - clientId - required: - client properties: number: description: >- Manual invoice number. If omitted, the backend generates it from the numbering series. If you send `number`, do not send `numericalSeriesId` in the same payload. type: - string - 'null' minLength: 1 maxLength: 20 example: '20260001' proformaId: description: Optional ID of the proforma invoice the invoice is created from. type: - integer - 'null' example: 401 orderId: description: Optional ID of the order the invoice is created from. type: - integer - 'null' example: 501 quotationId: description: Optional ID of the quotation the invoice is created from. type: - integer - 'null' example: 601 clientId: description: >- Existing client ID. This is the recommended way to create an invoice. If you also send the `client` object, it is applied as a sparse snapshot override for this specific document. type: - integer - 'null' example: 101 client: description: >- Sparse client payload. When `clientId` is sent, it overrides the client snapshot for this document only. When `clientId` is omitted, the backend uses it to match or create the client. anyOf: - $ref: '#/components/schemas/InvoiceClientInput' - type: 'null' businessCaseId: description: >- Optional business case ID. When sent, it must be available in the token scope and to the client resolved as the final `clientId`. type: - integer - 'null' example: 701 numericalSeriesId: description: >- Numbering series ID. If omitted together with `number`, the primary invoice series is used. If you send `numericalSeriesId`, do not send manual `number` in the same payload. type: - integer - 'null' example: 12 bankAccountId: description: >- Bank account ID to use on the invoice. It must be available in the token scope. If omitted, the primary company bank account is used. If the company has no primary bank account configured, the endpoint returns a `422` validation error on `bankAccountId`. type: integer example: 201 issueDate: description: >- Issue date in `Y-m-d` format. It must be after `2009-01-01` and before a date one year in the future. If omitted, today's date is used. type: string format: date example: '2026-03-03' dueDateDays: description: >- Number of due days. Precedence is payload → client default → company document settings. type: integer minimum: 0 maximum: 1000 example: 14 deliveryDate: description: >- Delivery date in `Y-m-d` format. If sent, it must be less than or equal to `issueDate`. If omitted, `issueDate` is used. type: string format: date example: '2026-03-03' variableSymbol: description: >- Variable symbol. Allowed values have 1 to 10 digits. If omitted, the backend derives it from the final invoice number. type: integer minimum: 0 maximum: 9999999999 example: 20260001 constantSymbol: description: >- Constant symbol. Allowed values have 1 to 4 digits. Precedence is payload → client default → `null`. type: - integer - 'null' minimum: 0 maximum: 9999 example: 308 specificSymbol: description: >- Specific symbol. Allowed values have 1 to 10 digits. Precedence is payload → client default → `null`. type: - integer - 'null' minimum: 0 maximum: 9999999999 example: 55 discountType: description: Document-level discount type. type: - string - 'null' enum: - percentage - fixed example: percentage discountValue: description: Document-level discount value. type: - number - 'null' format: float minimum: 0 example: 10 transferTaxLiability: description: Reverse-charge tax liability flag. If omitted, `false` is used. type: boolean example: false deliveryMethodId: type: integer description: >- Delivery method ID from the [delivery method reference table](/en/reference-tables#delivery-methods). Precedence is payload → client default → company document settings. example: 1 paymentMethodId: type: integer description: >- Payment method ID from the [payment method reference table](/en/reference-tables#payment-methods). Precedence is payload → client default → company document settings. example: 1 currencyId: type: integer description: >- Currency ID from the [currency reference table](/en/reference-tables#currencies). Precedence is payload → client default → company document settings. example: 1 currencyRate: description: >- Currency exchange rate against EUR. If omitted, the backend resolves it server-side from `currencyId` and `deliveryDate`. If the final document currency is `EUR`, the backend always stores and returns `1.0`. type: number format: float minimum: 0.00001 maximum: 10000000 example: 1 languageId: type: integer description: >- Language ID from the [language reference table](/en/reference-tables#languages). Precedence is payload → client default → company document settings. example: 1 qrTypeId: type: integer description: >- QR type ID from the [QR type reference table](/en/reference-tables#qr-types). If omitted, the company document settings value is used. example: 1 note: description: >- Note shown on the document. Precedence is payload → client default → company document settings. type: - string - 'null' maxLength: 3000 example: Thank you for your order. textAboveItems: description: >- Text shown above the line items. Precedence is payload → client default → company document settings. type: - string - 'null' maxLength: 3000 example: Thank you for working with us. items: description: >- Invoice line items. This field stays required even when the backend resolves most other values automatically. type: array minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/InvoiceItemInput' Invoice: description: Invoice. 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: Absolute URL of the public web document for this invoice. example: >- https://app.fintoro.sk/web-doklad/fa/4f3f8a95-5c4a-4c8b-9e6c-8a0c1a5df3a1 pdfDownloadUrl: type: string format: uri description: >- Absolute URL of the Fintoro API endpoint that downloads this invoice PDF as an attachment. example: https://app.fintoro.sk/api/public/v1/invoices/123/pdf company: $ref: '#/components/schemas/CompanySnapshot' description: Supplier snapshot stored directly on this document. clientId: description: Live ID of the client linked to the invoice. type: integer example: 101 client: $ref: '#/components/schemas/ClientSnapshot' description: Historical client snapshot stored directly on this document. bankAccount: $ref: '#/components/schemas/InvoiceBankAccountReference' description: >- Bank account linked to the invoice as a live relation loaded through soft delete. payments: description: Payments linked to this invoice ordered from newest to oldest. 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: >- Optional business case ID. When sent, it must belong to the client selected on the document. example: 701 discountType: type: - string - 'null' 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: >- Delivery method ID from the [delivery method reference table](/en/reference-tables#delivery-methods). example: 1 paymentMethodId: type: integer description: >- Payment method ID from the [payment method reference table](/en/reference-tables#payment-methods). example: 1 currencyId: type: integer description: >- Currency ID from the [currency reference table](/en/reference-tables#currencies). example: 1 currencyRate: type: number format: float example: 1 languageId: type: integer description: >- Language ID from the [language reference table](/en/reference-tables#languages). example: 1 qrTypeId: type: integer description: >- QR type ID from the [QR type reference table](/en/reference-tables#qr-types). example: 1 note: type: - string - 'null' example: Thank you for your order. textAboveItems: type: - string - 'null' example: Thank you for working with us. 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 toBePaid: type: number format: float example: 240 status: type: string example: unpaid hasVat: type: boolean example: true creditNotesSumTotalWithVat: type: number format: float example: 0 items: type: array items: $ref: '#/components/schemas/InvoiceItem' InvoiceClientInput: description: >- Sparse client payload used during invoice create or update. When you send `clientId`, this object acts as an optional snapshot override only for the specific document. When `clientId` is omitted, the backend tries to match an existing client or create a new one from this payload. type: object properties: name: description: >- Company name or person name. This field is required when `clientId` is not provided. type: string maxLength: 255 example: Acme s.r.o. type: description: >- Client type. Allowed values are `person` and `company`. If omitted, the backend infers it from the identification fields. type: string enum: - person - company example: company subjectId: description: Business ID of the client or company. type: - string - 'null' maxLength: 40 example: '12345678' taxId: description: Tax ID of the client or company. type: - string - 'null' maxLength: 20 example: '2020123456' vatId: description: VAT ID of the client or company. type: - string - 'null' maxLength: 20 example: SK2020123456 isVatPayer: description: >- Optional VAT payer flag. If omitted and `vatId` is provided, the backend derives it automatically. type: boolean example: true email: description: Client contact email. type: - string - 'null' format: email maxLength: 255 example: billing@acme.test street: description: >- Billing street of the client. With sparse overrides it changes only the snapshot stored on this document. type: - string - 'null' maxLength: 255 example: Main Street 1 city: description: Billing city of the client. type: - string - 'null' maxLength: 255 example: Bratislava zip: description: Billing ZIP or postal code of the client. type: - string - 'null' maxLength: 20 example: '81101' countryId: description: >- Country ID from the [country reference table](/en/reference-tables#countries). type: - integer - 'null' example: 703 hasDeliveryAddress: description: >- Optional delivery address flag. If omitted, the backend can infer it from the delivery address fields. type: boolean example: true deliveryStreet: description: Delivery street stored in the snapshot for this document. type: - string - 'null' maxLength: 255 example: Warehouse Street 5 deliveryCity: description: Delivery city stored in the snapshot for this document. type: - string - 'null' maxLength: 255 example: Trnava deliveryZip: description: >- Delivery ZIP or postal code stored in the snapshot for this document. type: - string - 'null' maxLength: 20 example: '91701' deliveryCountryId: type: - integer - 'null' description: >- Country ID of the delivery address from the [country reference table](/en/reference-tables#countries). example: 703 InvoiceItemInput: description: >- Payload for a single invoice line item. Three modes are supported: a manual item, `priceListItemId + quantity`, or `priceListItemId` with sparse override fields. `quantity` is always required. If you omit `priceListItemId`, you must also send `name`, `unitPrice`, and `vatRate`. `unitId` is optional; when you omit it for a manual item, the backend defaults to unit `1` (`piece` / `Unit::Piece`). If you send `priceListItemId`, the backend can hydrate the name, unit, unit price, and VAT rate from the price list item, and the payload acts only as a sparse override. type: object required: - quantity anyOf: - required: - priceListItemId - required: - name - unitPrice - vatRate properties: name: description: >- Item name. Required for manual items. When `priceListItemId` is used, it may override the name hydrated from the price list item. type: - string - 'null' maxLength: 255 example: Consulting description: description: >- Optional item description. With `priceListItemId`, it may override or supplement the description coming from the price list item. type: - string - 'null' maxLength: 1000 example: Monthly consulting package unitPrice: description: >- Unit price without VAT. Required for manual items. When `priceListItemId` is used, it may override the price hydrated from the price list item. type: - number - 'null' format: float minimum: -10000000000000 maximum: 10000000000000 example: 100 unitId: description: >- Optional unit ID from the [unit reference table](/en/reference-tables#units). For a manual item, if you omit it, the backend uses unit `1` (`piece` / `Unit::Piece`). When `priceListItemId` is used, it may override the unit from the price list item. type: - integer - 'null' example: 1 quantity: description: >- Item quantity. This field is always required, regardless of whether the item is manual or hydrated from the price list. type: number format: float minimum: 0.00001 maximum: 1000000 example: 2 vatRate: description: >- VAT rate in percent. Required for manual items. When `priceListItemId` is used, it may override the VAT rate from the price list item. type: - number - 'null' format: float minimum: 0 maximum: 100 example: 20 discountType: description: >- Item-level discount type. Allowed values are `percentage` and `fixed`. type: - string - 'null' enum: - percentage - fixed example: percentage discountValue: description: >- Item-level discount value. If you send `discountType`, you must also send this field. type: - number - 'null' format: float minimum: -10000000000000 maximum: 10000000000000 example: 10 discountName: description: >- Item-level discount label. If omitted while `discountType` and `discountValue` are provided, the backend fills in a localized `Discount` based on the document language. type: - string - 'null' maxLength: 255 example: Loyalty discount priceListItemId: description: >- Price list item ID. When provided, the backend can hydrate the item name, unit, unit price, and VAT rate from the linked price list item, and the payload can stay sparse. type: - integer - 'null' example: 501 warehouseAllocations: description: >- Optional per-warehouse quantity allocations. Use them only for items that are linked to stock cards and require explicit warehouse movement allocation. type: array minItems: 1 maxItems: 50 items: $ref: '#/components/schemas/InvoiceWarehouseAllocation' CompanySnapshot: description: >- Supplier snapshot stored directly on the document. This object represents the company details exactly as they existed when the document was issued or last re-saved, so the original supplier name, identifiers, and address remain preserved on the document. type: object properties: name: description: Supplier company name stored on the invoice. type: string example: Fintoro s.r.o. subjectId: description: Supplier business ID stored on the invoice. type: string example: '12345678' legalForm: description: Supplier legal form stored on the invoice. type: string example: Limited liability company taxId: description: Supplier tax ID stored on the invoice when it was available. type: - string - 'null' example: '2020123456' vatId: description: Supplier VAT ID stored on the invoice when it was available. type: - string - 'null' example: SK2020123456 vatPayerTypeId: description: Supplier VAT payer type stored on the invoice. type: integer example: 4 country: description: Supplier country stored on the invoice as a plain text value. type: string example: Slovakia city: description: Supplier city stored on the invoice. type: string example: Bratislava street: description: Supplier street and house number stored on the invoice. type: string example: Main Street 1 zip: description: Supplier ZIP or postal code stored on the invoice. type: - string - 'null' example: '81101' registrationCourt: description: >- Supplier registration court stored on the invoice, when it was available. type: - string - 'null' example: City Court Bratislava III registrationNumber: description: >- Supplier registration number stored on the invoice, when it was available. type: - string - 'null' example: 12345/B email: description: Supplier contact email stored on the invoice. type: - string - 'null' example: support@fintoro.sk phone: description: Supplier contact phone stored on the invoice. type: - string - 'null' example: '+421900000000' web: description: Supplier website stored on the invoice. type: - string - 'null' example: https://fintoro.sk ClientSnapshot: description: >- Historical client snapshot stored directly on the document. This object represents the client data exactly as it existed when the document was issued or last re-saved. If the client changes later, for example the name or billing address, the document keeps this historical value for auditability and long-term data persistence. Example: a document issued to `Main Street 1, Bratislava` remains historically correct even if the client profile now contains a different billing address. type: object properties: name: description: >- Person name or company name stored on the invoice at that moment in time. type: string example: Acme s.r.o. type: description: Client type stored on the invoice. type: string example: company subjectId: type: - string - 'null' description: >- Business ID of the client or company. For Slovak entities, you can typically also find this value through the [subject registry lookup](#operation/searchSubjects). example: '12345678' taxId: description: Tax ID stored on the invoice when it was available. type: - string - 'null' example: '2020123456' vatId: description: VAT ID stored on the invoice when it was available. type: - string - 'null' example: SK2020123456 isVatPayer: description: >- Indicates whether the client was marked as a VAT payer when this snapshot was stored. type: boolean example: true email: description: Client contact email stored on the invoice. type: - string - 'null' example: billing@acme.test street: description: Billing street and house number stored on the invoice. type: - string - 'null' example: Main Street 1 city: description: Billing city stored on the invoice. type: - string - 'null' example: Bratislava zip: description: Billing ZIP or postal code stored on the invoice. type: - string - 'null' example: '81101' countryId: description: >- Country ID from the [country reference table](/en/reference-tables#countries). type: - integer - 'null' example: 703 country: description: Billing country stored on the invoice as a nested object. anyOf: - $ref: '#/components/schemas/Country' - type: 'null' hasDeliveryAddress: description: >- Indicates whether this snapshot contains a separate delivery address. type: boolean example: true deliveryStreet: description: Delivery street and house number stored on the invoice. type: - string - 'null' example: Warehouse 9 deliveryCity: description: Delivery city stored on the invoice. type: - string - 'null' example: Kosice deliveryZip: description: Delivery ZIP or postal code stored on the invoice. type: - string - 'null' example: '04001' deliveryCountryId: description: >- Country ID from the [country reference table](/en/reference-tables#countries). type: - integer - 'null' example: 703 deliveryCountry: description: Delivery country stored on the invoice as a nested object. anyOf: - $ref: '#/components/schemas/Country' - type: 'null' InvoiceBankAccountReference: description: >- Bank account linked to the invoice as a live relation. The invoice still loads this account through soft delete, so the detail remains available even after the account is removed from the active bank account list. type: object properties: id: description: Internal bank account ID in Fintoro. type: integer example: 201 bankId: description: Bank ID from the [banks lookup endpoint](#operation/listBanks). type: - integer - 'null' example: 1 bank: description: Nested bank object linked to the bank account, when it is known. anyOf: - $ref: '#/components/schemas/Bank' - type: 'null' name: description: Bank account name in the current database state. type: string example: Main account iban: description: IBAN of the linked bank account. type: string example: SK3111000000001234567890 swift: description: SWIFT or BIC code of the linked bank account. type: string example: TATRSKBX isPrimary: description: >- Indicates whether the account is currently marked as the company's primary bank account. type: boolean example: true autoPaymentMatching: description: >- Indicates whether the account is currently connected to automatic payment matching through open banking. type: boolean example: true DocumentPayment: description: One payment of a public document. type: object properties: id: description: Internal payment ID. type: integer example: 801 documentType: description: Type of the document this payment belongs to. type: string enum: - invoice - proforma - credit-note example: invoice documentId: description: ID of the document this payment belongs to. type: integer example: 301 paymentMethod: $ref: '#/components/schemas/PaymentMethod' description: Used payment method as a nested lookup object. currency: $ref: '#/components/schemas/Currency' description: Payment currency as a nested lookup object. paymentDate: description: Payment date in `Y-m-d` format. type: string format: date example: '2026-03-07' amount: description: Payment amount in the payment currency. type: number format: float example: 15.5 currencyRate: description: >- Exchange rate of the payment currency against EUR. If the payment currency is `EUR`, the backend always returns `1.0`. type: number format: float example: 1 receiptInvoice: description: Preview of the linked payment receipt invoice, when it exists. anyOf: - $ref: '#/components/schemas/InvoicePreview' - type: 'null' InvoiceItem: description: Single invoice line item. type: object properties: id: type: integer example: 1 uuid: description: >- UUID of the invoice row. You receive this identifier in the invoice detail response and may send it back during update if you need warehouse allocations and outbound receipt links to stay attached to the same logical row. type: string format: uuid example: 6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19 name: type: string example: Consulting description: type: - string - 'null' example: Monthly consulting package unitPrice: type: number format: float example: 100 unitId: description: Unit ID from the [unit reference table](/en/reference-tables#units). type: integer example: 1 quantity: type: number format: float example: 2 vatRate: type: number format: float example: 20 discountName: type: - string - 'null' example: Loyalty discount discountType: type: - string - 'null' example: percentage discountValue: type: - number - 'null' format: float example: 10 priceListItemId: type: - integer - 'null' example: 501 total: type: number format: float example: 200 totalWithVat: type: number format: float example: 240 InvoiceWarehouseAllocation: type: object required: - warehouseId - quantity properties: warehouseId: type: integer example: 1 quantity: type: number format: float minimum: 0.00001 maximum: 1000000 example: 2 Country: description: >- Country available in Fintoro API lookup endpoints and in nested objects where the country is returned directly in the response. type: object properties: id: description: Stable country ID used across the API. type: integer example: 703 name: description: >- Localized country label. When you send `Accept-Language`, the backend translates this system-owned label accordingly. type: string example: Slovakia code: description: Two-letter ISO country code. type: string example: SK eu: description: Indicates whether the country is part of the European Union. type: boolean example: true Bank: description: >- Bank available through Fintoro API lookup endpoints. This is a stable lookup dataset whose existing bank IDs do not change or get reassigned. type: object properties: id: description: >- Stable bank ID used in Fintoro. Existing IDs do not change or get reassigned when new banks are added. type: integer example: 23 name: description: Bank name. type: string example: Tatra Banka swift: description: Bank SWIFT code if available. type: string example: TATRSKBX PaymentMethod: description: Payment method available in Fintoro API lookup endpoints. type: object properties: id: description: Stable payment method ID used across the API. type: integer example: 1 name: description: >- Localized payment-method label. When you send `Accept-Language`, the backend translates this system-owned label accordingly. type: string example: Bank transfer Currency: description: Currency available in Fintoro API lookup endpoints. type: object properties: id: description: Stable currency ID used across the API. type: integer example: 1 symbol: description: ISO or internal currency symbol. type: string example: EUR name: description: >- Localized currency label. When you send `Accept-Language`, the backend translates this system-owned label accordingly. type: string example: Euro mark: description: Short currency mark displayed in Fintoro. type: string example: € InvoicePreview: description: >- Simplified invoice preview object returned by the list endpoint. It does not include line items or the bank account snapshot, but it does include the full historical client snapshot in `client`; use the invoice detail endpoint for the complete document. type: object properties: id: description: Internal invoice ID in Fintoro. type: integer example: 301 uuid: description: Stable UUID of the invoice. type: string example: 6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19 type: description: Document type. type: string example: invoice number: description: Invoice number. type: string example: '20260001' clientId: description: Live ID of the client linked to the invoice. type: integer example: 101 client: $ref: '#/components/schemas/InvoicePreviewClient' description: >- Historical client snapshot stored directly on the invoice without the live client ID. The live ID is available separately in `clientId`. issueDate: description: Invoice issue date. type: string format: date example: '2026-03-03' dueDate: description: Invoice due date. type: string format: date example: '2026-03-17' deliveryDate: description: Delivery date. type: string format: date example: '2026-03-03' currency: $ref: '#/components/schemas/Currency' description: Invoice currency as a nested object. total: description: Total amount without VAT. type: number format: float example: 200 totalWithVat: description: Total amount with VAT. type: number format: float example: 240 toBePaid: description: Remaining amount to be paid. type: number format: float example: 240 status: description: Current payment status of the invoice. type: string enum: - paid - unpaid - partially_paid - overdue - will_not_be_paid example: unpaid hasVat: description: Indicates whether the invoice contains any VAT-bearing items. type: boolean example: true InvoicePreviewClient: description: >- Historical client snapshot embedded directly in a document preview response. The live client ID is exposed separately through `clientId`. allOf: - $ref: '#/components/schemas/ClientSnapshot' headers: XRequestId: description: >- Unique request identifier used for tracing, audit logs, and support diagnostics. schema: type: string example: req_public_api_01 ContentLanguage: description: Language selected for the request based on `Accept-Language`. schema: type: string example: en responses: NotFound: description: The requested resource was not found. 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. TooManyRequests: description: >- The company exceeded the Fintoro API rate limit. This 429 response includes the same `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers as other throttled responses and additionally adds `Retry-After` and `X-RateLimit-Reset`. If you need a higher limit, contact info@fintoro.sk for custom enterprise terms. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-RateLimit-Limit: description: >- Maximum number of requests allowed for the company in the current 60-second window. This header is returned on all throttled responses, not only on 429. schema: type: integer example: 120 X-RateLimit-Remaining: description: >- Number of requests remaining for the company in the current 60-second window. This header is returned on all throttled responses, not only on 429. schema: type: integer example: 0 Retry-After: description: >- Number of seconds after which you can safely retry the request. This header is sent only on 429 responses. schema: type: integer example: 60 X-RateLimit-Reset: description: >- Unix timestamp when the current rate-limit window resets. This header is sent only on 429 responses. schema: type: integer example: 1774810800 content: application/json: schema: type: object properties: message: type: string example: Too Many Attempts. InternalServerError: description: >- An unexpected internal error occurred. This should not happen in normal operation and is automatically reported to us. 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: >- The API is temporarily unavailable during scheduled maintenance. We announce planned downtime at least 24 hours in advance. 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 created for a specific company in Integrations → API. ````