Перейти к содержанию

Обзор

Currency API даёт доступ к курсам валют из двух источников:

  • Коммерческий курс банка-партнёра (/rates, /cross-rate, /convert/*) — реальные курсы обмена со спредом (sell/buy), для фактической конвертации сумм.

  • Официальные курсы ЦБ Республики Узбекистан - референсные курсы Центрального банка Республики Узбекистан (источник cbu.uz). Одна котировка в сутки, без спреда — для отображения официального курса, бухгалтерии и справки.

Интеграция подключается заранее

Курсы валют доступны магазину только после подключения интеграции с провайдером курсов. Обратитесь в поддержку KVELL, чтобы включить её для нужного X-Api-Key. Пока интеграция не подключена, любой метод раздела возвращает 404 с кодом 20044.

Методы

Метод Путь Назначение
Курс валюты GET /v1/currency/rates Коммерческий курс банка к UZS (sell/buy) — для отображения в интерфейсе.
Кросс-курс GET /v1/currency/cross-rate Коммерческий курс между двумя произвольными валютами.
Конвертация (sell) GET /v1/currency/convert/sell Расчёт суммы получения по исходной сумме перевода.
Конвертация (buy) GET /v1/currency/convert/buy Расчёт суммы платежа для получения нужной суммы в другой валюте.
Курсы ЦБ РУз (список) GET /v1/currency/cbu/rates Все официальные курсы ЦБ РУз на текущий день (~75 валют).
Курс ЦБ РУз (одна валюта) GET /v1/currency/cbu/rate Официальный курс ЦБ РУз для одной валюты.

Какой метод выбрать

Sell и Buy: в чём разница

«Конвертация (sell)» и «Конвертация (buy)» считают одну и ту же конвертацию в разных направлениях:

  • Sell (forward) — известна сумма в исходной валюте: «у меня есть source_amount в source_ccy, сколько я получу в target_ccy?».
  • Buy (reverse) — известна сумма в целевой валюте: «я хочу получить target_amount в target_ccy, сколько нужно заплатить в source_ccy?».

Выбирайте метод по тому, какая сумма известна заранее — сумма списания или сумма зачисления.

Как считается курс

«Кросс-курс» и оба метода конвертации считают результат через базовую валюту UZS, а не напрямую между source_ccy и target_ccy:

rate = source_to_base / base_to_target

где source_to_base — курс исходной валюты к UZS, base_to_target — курс UZS к целевой валюте. Оба значения возвращаются в ответе вместе с результатом — при необходимости пересчитайте сумму самостоятельно, не выполняя повторный запрос.

Заголовки запроса

Название Тип Обязательно Описание
X-Api-Key string Да Идентификатор магазина.

Подпись X-Signature для методов раздела не требуется.

Коды валют

Валюты передаются числовым кодом ISO 4217 в виде строки, например "840" для USD, а не буквенным кодом ("USD"). Базовая валюта расчётов — "860" (UZS).

На момент публикации доступны следующие валюты:

Валюта Код ISO Статус
UZS 860 базовая
USD 840 доступна
EUR 978 доступна
RUB 643 доступна
GBP 826 недоступна

Список может меняться

Набор доступных валют зависит от провайдера курсов и может измениться без предупреждения. Если запрошенная валюта временно недоступна, метод вернёт 404 с кодом 20099.

Правила:

Минорные единицы

В методах «Конвертация (sell)» и «Конвертация (buy)» суммы передаются и возвращаются в минорных единицах валюты — аналогично копейкам для рубля.

Валюта Минорная единица Пример
USD цент 100.00 USD = 10000
EUR цент 50.00 EUR = 5000
RUB копейка 10 000.00 RUB = 1000000
UZS тийин 1 000 000 UZS = 100000000

Коды ошибок

Ошибки возвращаются в общем формате KVELL: {"errors": [{"code", "message"}]}.

Код Описание
20044 Интеграция с провайдером курсов не настроена для магазина.
20098 Ошибка валидации полей запроса.
20099 Ошибка провайдера курсов, message передаётся без изменений. HTTP-код ответа соответствует ответу провайдера (400, 404, 502 или 503).
20000 Внутренняя ошибка KVELL.