List proformas - Fintoro API

GET

proformas

List proformas

curl --request GET \
  --url https://app.fintoro.sk/api/public/v1/proformas \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "id": 401,
      "uuid": "6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19",
      "type": "proforma",
      "number": "20260001",
      "clientId": 101,
      "client": {
        "name": "Acme s.r.o.",
        "type": "company",
        "subjectId": "12345678",
        "taxId": "2020123456",
        "vatId": "SK2020123456",
        "isVatPayer": true,
        "email": "billing@acme.test",
        "street": "Main Street 1",
        "city": "Bratislava",
        "zip": "81101",
        "countryId": 703,
        "country": {
          "id": 703,
          "name": "Slovakia",
          "code": "SK",
          "eu": true
        },
        "hasDeliveryAddress": true,
        "deliveryStreet": "Warehouse 9",
        "deliveryCity": "Kosice",
        "deliveryZip": "04001",
        "deliveryCountryId": 703,
        "deliveryCountry": {
          "id": 703,
          "name": "Slovakia",
          "code": "SK",
          "eu": true
        }
      },
      "issueDate": "2026-03-03",
      "dueDate": "2026-03-17",
      "currency": {
        "id": 1,
        "symbol": "EUR",
        "name": "Euro",
        "mark": "€"
      },
      "total": 200,
      "totalWithVat": 240,
      "toBePaid": 240,
      "status": "unpaid",
      "hasVat": true
    }
  ],
  "paginator": {
    "currentPage": 2,
    "perPage": 10,
    "totalPages": 5,
    "totalResults": 42,
    "currentFrom": 11,
    "currentTo": 20,
    "firstPageUrl": "https://app.fintoro.sk/api/public/v1/invoices?page=1",
    "lastPageUrl": "https://app.fintoro.sk/api/public/v1/invoices?page=5",
    "nextPageUrl": "https://app.fintoro.sk/api/public/v1/invoices?page=3",
    "previousPageUrl": "https://app.fintoro.sk/api/public/v1/invoices?page=1",
    "links": [
      {
        "url": "https://app.fintoro.sk/api/public/v1/invoices?page=2",
        "label": "2",
        "active": false
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Bearer token created for a specific company in Integrations → API.

Query Parameters

number

string

Filter by document number.

clientId

integer

Filter by client.

paymentStatus

enum<string>

Filter by payment status.

Available options:

paid,

unpaid,

partially_paid,

overdue,

will_not_be_paid

issueDateFrom

string<date>

Issue date from.

issueDateTo

string<date>

Issue date to.

dueDateFrom

string<date>

Due date from.

dueDateTo

string<date>

Due date to.

totalFrom

number<float>

Minimum total amount without VAT.

totalTo

number<float>

Maximum total amount without VAT.

withoutInvoice

boolean

When true, only proformas that do not yet have a linked final invoice are returned.

sortBy

enum<string>

default:issueDate

Field used for sorting.

Available options:

number,

issueDate,

dueDate,

total,

totalWithVat

sortDirection

enum<string>

default:desc

Sorting direction.

Available options:

asc,

desc

perPage

integer

default:10

Number of results per page.

Required range: 1 <= x <= 500

page

integer

default:1

Page number.

Required range: x >= 1

Response

Paginated proforma list in preview shape.

data

object[]

List of proforma preview objects for the current page.

Show child attributes

paginator

object

Pagination information for the current result set.

Show child attributes

Create proformaCreates a new proforma. ### Recommended flow The recommended happy path is to send `clientId` and `items`. If the client does not exist yet or you do not want 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 proforma. ### 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: - `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, - `dueDateDays` may be resolved from client preferences or company document settings, - `deliveryMethodId`, `paymentMethodId`, `currencyId`, `languageId`, `qrTypeId`, `note`, and `textAboveItems` may be resolved from the client or company settings, - `issueDate` defaults 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`. ### 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. If you send an `Idempotency-Key`, the same key with the same payload returns the original response without creating the proforma again.

List proformas

curl --request GET \
  --url https://app.fintoro.sk/api/public/v1/proformas \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "id": 401,
      "uuid": "6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19",
      "type": "proforma",
      "number": "20260001",
      "clientId": 101,
      "client": {
        "name": "Acme s.r.o.",
        "type": "company",
        "subjectId": "12345678",
        "taxId": "2020123456",
        "vatId": "SK2020123456",
        "isVatPayer": true,
        "email": "billing@acme.test",
        "street": "Main Street 1",
        "city": "Bratislava",
        "zip": "81101",
        "countryId": 703,
        "country": {
          "id": 703,
          "name": "Slovakia",
          "code": "SK",
          "eu": true
        },
        "hasDeliveryAddress": true,
        "deliveryStreet": "Warehouse 9",
        "deliveryCity": "Kosice",
        "deliveryZip": "04001",
        "deliveryCountryId": 703,
        "deliveryCountry": {
          "id": 703,
          "name": "Slovakia",
          "code": "SK",
          "eu": true
        }
      },
      "issueDate": "2026-03-03",
      "dueDate": "2026-03-17",
      "currency": {
        "id": 1,
        "symbol": "EUR",
        "name": "Euro",
        "mark": "€"
      },
      "total": 200,
      "totalWithVat": 240,
      "toBePaid": 240,
      "status": "unpaid",
      "hasVat": true
    }
  ],
  "paginator": {
    "currentPage": 2,
    "perPage": 10,
    "totalPages": 5,
    "totalResults": 42,
    "currentFrom": 11,
    "currentTo": 20,
    "firstPageUrl": "https://app.fintoro.sk/api/public/v1/invoices?page=1",
    "lastPageUrl": "https://app.fintoro.sk/api/public/v1/invoices?page=5",
    "nextPageUrl": "https://app.fintoro.sk/api/public/v1/invoices?page=3",
    "previousPageUrl": "https://app.fintoro.sk/api/public/v1/invoices?page=1",
    "links": [
      {
        "url": "https://app.fintoro.sk/api/public/v1/invoices?page=2",
        "label": "2",
        "active": false
      }
    ]
  }
}