Skip to main content
POST
/
proformas
Create proforma
curl --request POST \
  --url https://app.fintoro.sk/api/public/v1/proformas \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "clientId": 101,
  "items": [
    {
      "quantity": 2,
      "priceListItemId": 501,
      "name": "Consulting",
      "description": "Monthly consulting package",
      "unitPrice": 100,
      "unitId": 1,
      "vatRate": 20,
      "discountType": "percentage",
      "discountValue": 10,
      "discountName": "Loyalty discount"
    }
  ],
  "number": "20260001",
  "orderId": 501,
  "quotationId": 601,
  "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,
    "hasDeliveryAddress": true,
    "deliveryStreet": "Warehouse Street 5",
    "deliveryCity": "Trnava",
    "deliveryZip": "91701",
    "deliveryCountryId": 703
  },
  "businessCaseId": 701,
  "numericalSeriesId": 12,
  "bankAccountId": 201,
  "issueDate": "2026-03-03",
  "dueDateDays": 14,
  "variableSymbol": 20260001,
  "constantSymbol": 308,
  "specificSymbol": 55,
  "discountType": "percentage",
  "discountValue": 10,
  "transferTaxLiability": false,
  "deliveryMethodId": 1,
  "paymentMethodId": 1,
  "currencyId": 1,
  "languageId": 1,
  "qrTypeId": 1,
  "note": "Thank you for your order.",
  "textAboveItems": "Thank you for working with us."
}
'
{ "id": 401, "uuid": "6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19", "type": "proforma", "number": "20260001", "webDokladUrl": "https://app.fintoro.sk/web-doklad/proforma/4f3f8a95-5c4a-4c8b-9e6c-8a0c1a5df3a1", "pdfDownloadUrl": "https://app.fintoro.sk/api/public/v1/proformas/401/pdf", "company": { "name": "Fintoro s.r.o.", "subjectId": "12345678", "legalForm": "Limited liability company", "taxId": "2020123456", "vatId": "SK2020123456", "vatPayerTypeId": 4, "country": "Slovakia", "city": "Bratislava", "street": "Main Street 1", "zip": "81101", "logo": "https://cdn.fintoro.sk/company/logo.svg", "signature": "https://cdn.fintoro.sk/company/signature.png", "registrationCourt": "City Court Bratislava III", "registrationNumber": "12345/B", "email": "support@fintoro.sk", "phone": "+421900000000", "web": "https://fintoro.sk" }, "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 } }, "bankAccount": { "id": 201, "bankId": 1, "bank": { "id": 23, "name": "Tatra Banka", "swift": "TATRSKBX" }, "name": "Main account", "iban": "SK3111000000001234567890", "swift": "TATRSKBX", "isPrimary": true, "autoPaymentMatching": true }, "payments": [ { "id": 801, "documentType": "invoice", "documentId": 301, "paymentMethod": { "id": 1, "name": "Bank transfer" }, "currency": { "id": 1, "symbol": "EUR", "name": "Euro", "mark": "€" }, "paymentDate": "2026-03-07", "amount": 15.5, "currencyRate": 1, "receiptInvoice": { "id": 301, "uuid": "6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19", "type": "invoice", "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", "deliveryDate": "2026-03-03", "currency": { "id": 1, "symbol": "EUR", "name": "Euro", "mark": "€" }, "total": 200, "totalWithVat": 240, "toBePaid": 240, "status": "unpaid", "hasVat": true } } ], "variableSymbol": 20260001, "constantSymbol": 308, "specificSymbol": 55, "issueDate": "2026-03-03", "dueDate": "2026-03-17", "businessCaseId": 701, "discountType": "percentage", "discountValue": 10, "transferTaxLiability": false, "numericalSeriesId": 12, "deliveryMethodId": 1, "paymentMethodId": 1, "currencyId": 1, "languageId": 1, "qrTypeId": 1, "note": "Thank you for your order.", "textAboveItems": "Thank you for working with us.", "itemsTotal": 200, "itemsTotalWithVat": 240, "alreadyPaid": 0, "total": 200, "totalWithVat": 240, "toBePaid": 240, "willBePaid": true, "status": "unpaid", "hasVat": true, "items": [ { "id": 1, "name": "Consulting", "description": "Monthly consulting package", "unitPrice": 100, "unitId": 1, "quantity": 2, "vatRate": 20, "discountName": "Loyalty discount", "discountType": "percentage", "discountValue": 10, "total": 200, "totalWithVat": 240 } ] }

Authorizations

​
Authorization
string
header
required

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

Headers

​
Idempotency-Key
string

Optional request identifier for safe retries. Use a unique value for each create request you want to retry safely.

Example:

"invoice-create-2026-03-03-001"

Body

application/json

Payload used to create a proforma. The usual happy path is clientId plus items; the backend can resolve many other values automatically. You must send either clientId or client.

​
clientId
integer | null
required

Existing client ID. This is the recommended way to create a proforma. If you also send the client object, it is applied as a sparse snapshot override for this specific document.

Example:

101

​
items
object[]
required

Proforma line items. This field stays required at all times.

Required array length: 1 - 100 elements

Payload for a single proforma 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 then acts only as a sparse override. Per-item uuid is not part of the request contract; if you send it, the backend ignores it. warehouseAllocations are not supported for proformas.

​
number
string | null

Manual proforma number. If omitted, the backend generates it from the numbering series. If you send number, do not send numericalSeriesId in the same payload.

Required string length: 1 - 20
Example:

"20260001"

​
orderId
integer | null

Optional ID of the order the proforma is created from.

Example:

501

​
quotationId
integer | null

Optional ID of the quotation the proforma is created from.

Example:

601

​
client
object

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.

​
businessCaseId
integer | null

Optional business case ID. When sent, it must be available in the token scope and to the client resolved as the final clientId.

Example:

701

​
numericalSeriesId
integer | null

Numbering series ID. If omitted together with number, the primary proforma series is used. If you send numericalSeriesId, do not send manual number in the same payload.

Example:

12

​
bankAccountId
integer

Bank account ID to use on the document. 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.

Example:

201

​
issueDate
string<date>

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.

Example:

"2026-03-03"

​
dueDateDays
integer

Number of due days. Precedence is payload → client default → company document settings.

Required range: 0 <= x <= 1000
Example:

14

​
variableSymbol
integer

Variable symbol. Allowed values have 1 to 10 digits. If omitted, the backend derives it from the final document number.

Required range: 0 <= x <= 9999999999
Example:

20260001

​
constantSymbol
integer | null

Constant symbol. Allowed values have 1 to 4 digits. Precedence is payload → client default → null.

Required range: 0 <= x <= 9999
Example:

308

​
specificSymbol
integer | null

Specific symbol. Allowed values have 1 to 10 digits. Precedence is payload → client default → null.

Required range: 0 <= x <= 9999999999
Example:

55

​
discountType
enum<string> | null

Document-level discount type.

Available options:
percentage,
fixed
Example:

"percentage"

​
discountValue
number<float> | null

Document-level discount value.

Required range: x >= 0
Example:

10

​
transferTaxLiability
boolean

Reverse-charge tax liability flag. If omitted, false is used.

Example:

false

​
deliveryMethodId
integer

Delivery method ID from the delivery method reference table. Precedence is payload → client default → company document settings.

Example:

1

​
paymentMethodId
integer

Payment method ID from the payment method reference table. Precedence is payload → client default → company document settings.

Example:

1

​
currencyId
integer

Currency ID from the currency reference table. Precedence is payload → client default → company document settings.

Example:

1

​
languageId
integer

Language ID from the language reference table. Precedence is payload → client default → company document settings.

Example:

1

​
qrTypeId
integer

QR type ID from the QR type reference table. If omitted, the company document settings value is used.

Example:

1

​
note
string | null

Note shown on the document. Precedence is payload → client default → company document settings.

Maximum string length: 3000
Example:

"Thank you for your order."

​
textAboveItems
string | null

Text shown above the line items. Precedence is payload → client default → company document settings.

Maximum string length: 3000
Example:

"Thank you for working with us."

Response

Proforma created.

Proforma.

​
id
integer
Example:

401

​
uuid
string
Example:

"6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19"

​
type
string
Example:

"proforma"

​
number
string
Example:

"20260001"

​
webDokladUrl
string<uri>

Absolute URL of the public web document for this proforma.

Example:

"https://app.fintoro.sk/web-doklad/proforma/4f3f8a95-5c4a-4c8b-9e6c-8a0c1a5df3a1"

​
pdfDownloadUrl
string<uri>

Absolute URL of the Fintoro API endpoint that downloads this proforma PDF as an attachment.

Example:

"https://app.fintoro.sk/api/public/v1/proformas/401/pdf"

​
company
object

Supplier snapshot stored directly on this document.

​
clientId
integer

Live ID of the client linked to the proforma.

Example:

101

​
client
object

Historical client snapshot stored directly on this document.

​
bankAccount
object

Bank account linked to the proforma as a live relation loaded through soft delete.

​
payments
object[]

Payments linked to this proforma ordered from newest to oldest.

​
variableSymbol
integer
Example:

20260001

​
constantSymbol
integer | null
Example:

308

​
specificSymbol
integer | null
Example:

55

​
issueDate
string<date>
Example:

"2026-03-03"

​
dueDate
string<date>
Example:

"2026-03-17"

​
businessCaseId
integer | null

Optional business case ID. When sent, it must belong to the client selected on the document.

Example:

701

​
discountType
string | null
Example:

"percentage"

​
discountValue
number<float> | null
Example:

10

​
transferTaxLiability
boolean
Example:

false

​
numericalSeriesId
integer | null
Example:

12

​
deliveryMethodId
integer

Delivery method ID from the delivery method reference table.

Example:

1

​
paymentMethodId
integer

Payment method ID from the payment method reference table.

Example:

1

​
currencyId
integer

Currency ID from the currency reference table.

Example:

1

​
languageId
integer

Language ID from the language reference table.

Example:

1

​
qrTypeId
integer

QR type ID from the QR type reference table.

Example:

1

​
note
string | null
Example:

"Thank you for your order."

​
textAboveItems
string | null
Example:

"Thank you for working with us."

​
itemsTotal
number<float>
Example:

200

​
itemsTotalWithVat
number<float>
Example:

240

​
alreadyPaid
number<float>
Example:

0

​
total
number<float>
Example:

200

​
totalWithVat
number<float>
Example:

240

​
toBePaid
number<float>
Example:

240

​
willBePaid
boolean
Example:

true

​
status
enum<string>
Available options:
paid,
unpaid,
partially_paid,
overdue,
will_not_be_paid
Example:

"unpaid"

​
hasVat
boolean
Example:

true

​
items
object[]