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

Конвертация (sell)

Forward-конвертация: «у меня есть сумма в исходной валюте, сколько я получу в целевой валюте?». Используйте для точного расчёта получаемой суммы при переводе средств — не умножайте курс из «Курс валюты»/«Кросс-курс» на сумму вручную.

URL

GET https://api.pay.kvell.group/v1/currency/convert/sell

GET https://api.pay.stage.kvell.group/v1/currency/convert/sell

Запрос

Query-параметры

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

Заголовки

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

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

Пример

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

Ответ

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

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

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

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

amount = round(source_amount × source_to_base / base_to_target)

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

Метод не создаёт операцию перевода — только рассчитывает сумму на основе текущего курса.

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

Используйте amount как итоговую сумму получения в target_currency.

Пример ответа 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": "source_amount: 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 Описание технической ошибки.

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

Метод не создаёт финансовую операцию — техническая ошибка не может привести к неопределённому результату.

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

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