Перейти до основного вмісту

Валюти та курси валют через API

API валют потрібен для інтеграцій, які працюють з мультивалютними документами, платежами, цінами, банківськими рахунками або звітами. Валюти читаються з довідника, а курси валют можна створювати й оновлювати через API.

попередження

Курс валюти впливає на документи, платежі, взаєморозрахунки й звіти. Не оновлюйте курси автоматично без узгодженої бізнес-логіки, особливо якщо компанія вже використовує мультивалютний облік у роботі.

Endpoint-и валют​

МетодEndpointПризначення
GET/v1/currenciesотримати список валют
GET/v1/currencies/:idотримати одну валюту

Створення, оновлення й видалення валют через API V1 не описані.

Поля валюти​

ПолеЩо означає
idID валюти.
codeКод валюти.
titleНазва валюти.
short_titleКоротка назва валюти.
signСимвол валюти.
coinНазва розмінної одиниці.
created_atДата створення.
updated_atДата оновлення.

Endpoint-и курсів валют​

МетодEndpointПризначення
GET/v1/currency_ratesотримати список курсів валют
GET/v1/currency_rates/:idотримати один курс
POST/v1/currency_ratesстворити курс
PUT/v1/currency_rates/:idоновити курс за ID
PUT/v1/currency_rates/update_by_currencyоновити курс за валютою і датою

Отримання списку курсів​

GET /v1/currency_rates повертає список курсів валют.

Параметри:

ПараметрПризначення
currency_idФільтр за валютою.
rate_dateФільтр за датою курсу.

Поля курсу валют​

ПолеЩо означає
idID курсу валюти.
currency_idID валюти.
rateКурс.
rate_dateДата курсу.
currency_codeКод валюти.
currency_titleНазва валюти.
created_atДата створення.
updated_atДата оновлення.

Створення курсу​

Для створення курсу передається обʼєкт currency_rate.

{
  "currency_rate": {
    "currency_id": "currency-id",
    "rate": 42.5,
    "rate_date": "2026-05-17"
  }
}

Поля для створення:

ПолеПризначення
currency_idВалюта, для якої встановлюється курс.
rateКурс валюти.
rate_dateДата курсу.

Для однієї валюти на одну дату має бути один курс. Якщо курс на цю дату вже існує, створення поверне помилку.

Оновлення курсу за ID​

PUT /v1/currency_rates/:id оновлює значення курсу.

{
  "currency_rate": {
    "rate": 42.8
  }
}

Поля для оновлення:

ПолеПризначення
rateНове значення курсу.

Оновлення курсу за валютою і датою​

PUT /v1/currency_rates/update_by_currency зручно використовувати, коли інтеграція знає валюту й дату, але не зберігає ID конкретного запису курсу.

Потрібно передати currency_id, rate_date і новий rate.

{
  "currency_rate": {
    "currency_id": "currency-id",
    "rate_date": "2026-05-17",
    "rate": 42.8
  }
}

Поля:

ПолеПризначення
currency_idВалюта, курс якої потрібно оновити.
rate_dateДата курсу.
rateНове значення курсу.

Якщо курс для валюти й дати не знайдено, API поверне помилку.

Як використовувати з документами й платежами​

У документах і платежах використовуються:

ПолеДе використовується
currency_idВалюта документа або платежу.
currency_rateКурс валюти на момент операції.
converted_currency_idВалюта конвертації в платежах.
converted_amountСума після конвертації в платежах.
Порада

Якщо інтеграція створює документи або платежі в іноземній валюті, спочатку отримайте ID валюти, перевірте актуальний курс на дату операції, а вже потім створюйте обліковий документ.

Чеклист​

Перед автоматизацією курсів валют перевірте:

  • яка валюта є базовою в компанії;
  • які валюти реально використовуються в документах, платежах і рахунках;
  • хто відповідає за актуальність курсу;
  • чи можна інтеграції створювати новий курс на нову дату;
  • чи дозволено інтеграції оновлювати вже створений курс;
  • як обробляти ситуацію, коли курс на дату вже існує або не знайдений.

Повʼязані матеріали​

Підсумок​

API валют дає довідник валют, а API курсів дозволяє підтримувати актуальні курси для мультивалютного обліку. Для запису документів і платежів використовуйте реальні currency_id і курс, погоджений із правилами обліку компанії.

Останнє оновлення