Úhrady dokladov

Vytvoriť úhradu dokladu

Vytvorí novú úhradu pre public doklad.

Podporované typy dokladov

Endpoint podporuje len invoice, proforma a credit-note.

Business správanie

Úhrada sa vždy viaže na konkrétny doklad cez kombináciu documentType + documentId.
Minimálny create payload je len documentType + documentId; ostatné polia môžete vynechať a server ich dopočíta.
Ak paymentDate nepošlete, použije sa dnešný dátum.
Ak paymentMethodId nepošlete, použije sa spôsob úhrady zo zdrojového dokladu.
Ak currencyId nepošlete, použije sa mena zo zdrojového dokladu.
Ak amount nepošlete, použije sa aktuálna zostávajúca suma toBePaid zo zdrojového dokladu. Tento shortcut funguje len pri doklade s nenulovým toBePaid; inak endpoint vráti 422.
Ak amount pošlete explicitne, môže mať najviac 2 desatinné miesta.
Ak amount pošlete explicitne, nesmie svojou veľkosťou presiahnuť aktuálne toBePaid a musí rešpektovať jeho znamienko, aby nevznikla preplatková úhrada alebo opačný smer platby.
Ak currencyRate nepošlete, systém ho odvodí z finálneho paymentDate kurzom z predchádzajúceho dňa.
Ak pošlete currencyRate pre inú menu než EUR, použije sa presne táto override hodnota.
Ak je finálna mena úhrady EUR, backend vždy uloží a vráti currencyRate = 1.0, aj keď pošlete inú hodnotu.
Pri vytvorení sa prepočíta stav úhrady dokladu rovnako ako vo web a mobile flowe.
Ak pošlete úhradu pre proformu a neskôr k nej vytvoríte daňový doklad k prijatej platbe, response úhrady vie obsahovať aj receiptInvoice.

Ak pošlete Idempotency-Key, rovnaký key s rovnakým payloadom vráti pôvodnú odpoveď bez druhého vytvorenia úhrady.

POST

document-payments

Vytvoriť úhradu dokladu

curl --request POST \
  --url https://app.fintoro.sk/api/public/v1/document-payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentType": "invoice",
  "documentId": 301,
  "currencyId": 1,
  "currencyRate": 1,
  "paymentDate": "2026-03-07",
  "paymentMethodId": 1,
  "amount": 15.5
}
'

{
  "id": 801,
  "documentType": "invoice",
  "documentId": 301,
  "paymentMethod": {
    "id": 1,
    "name": "Platba prevodom"
  },
  "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": "Hlavná 1",
      "city": "Bratislava",
      "zip": "81101",
      "countryId": 703,
      "country": {
        "id": 703,
        "name": "Slovensko",
        "code": "SK",
        "eu": true
      },
      "hasDeliveryAddress": true,
      "deliveryStreet": "Skladová 9",
      "deliveryCity": "Košice",
      "deliveryZip": "04001",
      "deliveryCountryId": 703,
      "deliveryCountry": {
        "id": 703,
        "name": "Slovensko",
        "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
  }
}

Autorizace

Authorization

string

header

povinné

Bearer token vytvorený pre konkrétnu firmu v Integrácie → API.

Hlavičky

Idempotency-Key

string

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ť.

Příklad:

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

Tělo

application/json

Payload pre vytvorenie úhrady dokladu. Podporované sú len dokumenty invoice, proforma a credit-note, pričom cieľový doklad musí byť dostupný pre token.

documentType

enum<string>

povinné

Typ dokladu, ku ktorému úhradu vytvárate.

Dostupné možnosti:

invoice,

proforma,

credit-note

Příklad:

"invoice"

documentId

integer

povinné

ID dokladu, ku ktorému úhradu vytvárate.

Příklad:

301

currencyId

integer

Voliteľné ID meny z referenčnej tabuľky mien. Ak ho nepošlete, použije sa mena zo zdrojového dokladu.

Příklad:

1

currencyRate

number<float>

Kurz meny úhrady voči EUR. Ak ho nepošlete, systém ho dopočíta z finálneho paymentDate kurzom z predchádzajúceho dňa. Ak ho pošlete pre inú menu než EUR, použije sa presne táto override hodnota. Ak je finálna mena úhrady EUR, backend vždy uloží 1.0.

Příklad:

1

paymentDate

string<date>

Dátum úhrady vo formáte Y-m-d. Ak ho nepošlete, použije sa dnešný dátum.

Příklad:

"2026-03-07"

paymentMethodId

integer

Voliteľné ID spôsobu úhrady z referenčnej tabuľky spôsobov úhrady. Ak ho nepošlete, použije sa spôsob úhrady zo zdrojového dokladu.

Příklad:

1

amount

number<float>

Suma úhrady v mene úhrady. Ak ju nepošlete, použije sa aktuálna zostávajúca suma toBePaid zo zdrojového dokladu. Toto odvodenie funguje len pri doklade s nenulovým toBePaid; inak endpoint vráti 422. Ak ju pošlete explicitne, môže mať najviac 2 desatinné miesta, nesmie svojou veľkosťou presiahnuť aktuálne toBePaid a musí rešpektovať jeho znamienko. Backend akceptuje aj záporné sumy, napríklad pri vysporiadaní dobropisu.

Musí být násobkem 0.01

Příklad:

15.5

Odpověď

Úhrada bola vytvorená.

Jedna úhrada public dokladu.

integer

Interné ID úhrady.

Příklad:

801

documentType

enum<string>

Typ dokladu, ku ktorému úhrada patrí.

Dostupné možnosti:

invoice,

proforma,

credit-note

Příklad:

"invoice"

documentId

integer

ID dokladu, ku ktorému úhrada patrí.

Příklad:

301

paymentMethod

object

Použitý spôsob úhrady ako vnorený lookup objekt.

Show child attributes

currency

object

Mena úhrady ako vnorený lookup objekt.

Show child attributes

paymentDate

string<date>

Dátum úhrady vo formáte Y-m-d.

Příklad:

"2026-03-07"

amount

number<float>

Suma úhrady v mene úhrady.

Příklad:

15.5

currencyRate

number<float>

Kurz meny úhrady voči EUR. Ak je mena úhrady EUR, backend vždy vráti 1.0.

Příklad:

1

receiptInvoice

object

Preview daňového dokladu k prijatej platbe, ak existuje.

Show child attributes

Předchozí

Detail úhrady dokladuVráti detail jednej úhrady. Response obsahuje typ a ID zdrojového dokladu, použitú menu, spôsob úhrady a prípadne aj preview daňového dokladu k prijatej platbe.

Další

Vytvoriť úhradu dokladu

curl --request POST \
  --url https://app.fintoro.sk/api/public/v1/document-payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentType": "invoice",
  "documentId": 301,
  "currencyId": 1,
  "currencyRate": 1,
  "paymentDate": "2026-03-07",
  "paymentMethodId": 1,
  "amount": 15.5
}
'

{
  "id": 801,
  "documentType": "invoice",
  "documentId": 301,
  "paymentMethod": {
    "id": 1,
    "name": "Platba prevodom"
  },
  "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": "Hlavná 1",
      "city": "Bratislava",
      "zip": "81101",
      "countryId": 703,
      "country": {
        "id": 703,
        "name": "Slovensko",
        "code": "SK",
        "eu": true
      },
      "hasDeliveryAddress": true,
      "deliveryStreet": "Skladová 9",
      "deliveryCity": "Košice",
      "deliveryZip": "04001",
      "deliveryCountryId": 703,
      "deliveryCountry": {
        "id": 703,
        "name": "Slovensko",
        "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
  }
}