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

Кросс-курс

Возвращает коммерческий кросс-курс между двумя произвольными валютами, рассчитанный через базовую валюту (UZS). Используйте для отображения кросс-курса; для точного расчёта суммы конвертации применяйте «Конвертация (sell)» или «Конвертация (buy)».

URL

GET https://api.pay.kvell.group/v1/currency/cross-rate

GET https://api.pay.stage.kvell.group/v1/currency/cross-rate

Запрос

Query-параметры

Параметр Тип Обязательно Описание
source_ccy string Да Числовой код исходной валюты. См. «Коды валют».
target_ccy string Да Числовой код целевой валюты. Должен отличаться от source_ccy.

Заголовки

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

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

Пример

curl --request GET \
  --url 'https://api.pay.stage.kvell.group/v1/currency/cross-rate?source_ccy=840&target_ccy=643' \
  --header 'X-Api-Key: 00000000-0000-4000-8000-000000000000'

Ответ

Пример ответа 200 (OK)
{
  "source_currency": "840",
  "target_currency": "643",
  "rate": 85.3846,
  "source_to_base": 12210,
  "base_to_target": 143,
  "base_currency": "UZS"
}

Параметры ответа

Параметр Тип Описание
source_currency string Числовой код исходной валюты.
target_currency string Числовой код целевой валюты.
rate number Единиц target_currency за 1 единицу source_currency. Равно source_to_base / base_to_target.
source_to_base number Курс исходной валюты к базовой (UZS).
base_to_target number Курс базовой валюты (UZS) к целевой.
base_currency string Базовая валюта расчёта — всегда "UZS".

Формула расчёта

rate = source_to_base / base_to_target

Что означает ответ

Курс актуален на момент ответа и может измениться при следующем запросе.

Что делать дальше

Используйте rate для отображения кросс-курса. Для точного расчёта суммы перевода применяйте «Конвертация (sell)» или «Конвертация (buy)».

Пример ответа 400 (Bad Request)
{
  "errors": [
    {
      "code": 20099,
      "message": "source_ccy and target_ccy must differ"
    }
  ]
}

Параметры ответа

Параметр Тип Описание
errors array Список ошибок. Коды и рекомендации по обработке приведены в разделе «Ошибки HTTP-ответов».
errors[].code integer Код ошибки.
errors[].message string Описание причины отклонения запроса.

Что означает ответ

source_ccy и target_ccy совпадают — кросс-курс валюты к самой себе не имеет смысла.

Что делать дальше

Передайте два разных кода валют и повторите запрос.

Пример ответа 404 (Not Found)
{
  "errors": [
    {
      "code": 20044,
      "message": "Интеграция с Montra не настроена для магазина"
    }
  ]
}

Параметры ответа

Параметр Тип Описание
errors array Список ошибок. Коды и рекомендации по обработке приведены в разделе «Ошибки HTTP-ответов».
errors[].code integer 20044 — интеграция не подключена; 20099 — курс для одной из валют недоступен у провайдера.
errors[].message string Описание причины.

Что означает ответ

Для кода 20044 обратитесь в поддержку KVELL, чтобы подключить интеграцию с провайдером курсов. Для кода 20099 проверьте коды валют в source_ccy/target_ccy.

Что делать дальше

Устраните причину ошибки и повторите запрос.

Пример ответа 422 (Unprocessable Entity)
{
  "errors": [
    {
      "code": 20098,
      "message": "target_ccy: Field required"
    }
  ]
}

Параметры ответа

Параметр Тип Описание
errors array Список ошибок валидации.
errors[].code integer Код ошибки.
errors[].message string Поле и причина ошибки валидации.

Что означает ответ

Не передан обязательный параметр или он не соответствует формату.

Что делать дальше

Исправьте поле из errors[].message и повторите запрос.

Пример ответа 5XX (Internal Server Error)
{
  "errors": [
    {
      "code": 20000,
      "message": "Неизвестная ошибка"
    }
  ]
}

Параметры ответа

Параметр Тип Описание
errors array Список ошибок. Коды и рекомендации по обработке приведены в разделе «Ошибки HTTP-ответов».
errors[].code integer Код ошибки.
errors[].message string Описание технической ошибки.

Что означает ответ

Метод read-only и ничего не меняет — техническая ошибка не может привести к неопределённому результату.

Что делать дальше

Безопасно повторите тот же запрос. Если ошибка повторяется, обратитесь в поддержку KVELL и передайте URL, время запроса, HTTP-код, code и message.