Для AI-агентов: markdown этой страницы — /docs-content/entities/currencies.md индекс документации — /llms.txt

Валюты

Справочник валют портала с курсами обмена. ID валюты — строковый код (RUB, USD, EUR).

Bitrix24 API: crm.currency.* Скоуп: crm

Создать валюту

POST /v1/currencies

Создаёт новую валюту в CRM. Код валюты задаётся в поле id (трёхбуквенный код ISO 4217).

Параметры тела запроса

Параметр Тип Обязат. Описание
Параметрid Типstring Обязат.да ОписаниеКод валюты (RUB, USD, EUR)
Параметрamount Типnumber Обязат.да ОписаниеКурс обмена относительно базовой валюты
ПараметрamountCnt Типnumber Обязат.да ОписаниеНоминал — для большинства валют равен 1, для JPY 100
Параметрsort Типnumber Обязат. ОписаниеПорядок сортировки
ПараметрfullName Типstring Обязат. ОписаниеНазвание валюты. Если не передать, в названии остаётся код валюты
ПараметрformatString Типstring Обязат.да ОписаниеШаблон отображения, например # ₽. Символ # — место для суммы
Параметрdecimals Типnumber Обязат. ОписаниеЧисло знаков после запятой
ПараметрdecPoint Типstring Обязат. ОписаниеДесятичный разделитель
ПараметрthousandsSep Типstring Обязат. ОписаниеРазделитель тысяч

Локализуемые поля можно передавать плоско. fullName, formatString, decimals, decPoint, thousandsSep в Битрикс24 хранятся в структуре локализации по языкам. API сам упаковывает их в локализацию вашего языка (языка API-ключа), так что плоская запись теперь сохраняется и читается обратно. Сырой объект LANG в теле передавать нельзя — поле только для чтения, запрос вернётся 400 READONLY_FIELD. Задание разных значений сразу для нескольких языков через API пока не поддерживается.

Примеры

curl — личный ключ

Terminal
curl -X POST "https://vibecode.bitrix24.tech/v1/currencies" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "CNY", "amount": 12.7, "amountCnt": 1, "sort": 300, "fullName": "Китайский юань", "formatString": "# ¥"}'

curl — OAuth-приложение

Terminal
curl -X POST "https://vibecode.bitrix24.tech/v1/currencies" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "CNY", "amount": 12.7, "amountCnt": 1, "sort": 300, "fullName": "Китайский юань", "formatString": "# ¥"}'

JavaScript — личный ключ

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/currencies', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ id: 'CNY', amount: 12.7, amountCnt: 1, sort: 300, fullName: 'Китайский юань', formatString: '# ¥' }),
})
const { success, data } = await res.json()

JavaScript — OAuth-приложение

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/currencies', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ id: 'CNY', amount: 12.7, amountCnt: 1, sort: 300, fullName: 'Китайский юань', formatString: '# ¥' }),
})
const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata Типobject ОписаниеСозданная валюта со всеми полями
Полеdata.id Типstring ОписаниеКод валюты (RUB, USD, EUR)
Полеdata.amountCnt Типnumber ОписаниеКоличество единиц для курса
Полеdata.amount Типnumber ОписаниеКурс обмена
Полеdata.sort Типnumber ОписаниеСортировка
Полеdata.base Типboolean ОписаниеБазовая валюта
Полеdata.fullName Типstring ОписаниеНазвание (руб., $)
Полеdata.lid Типstring ОписаниеИдентификатор сайта, к которому привязана валюта
Полеdata.formatString Типstring ОписаниеФормат отображения
Полеdata.decPoint Типstring ОписаниеРазделитель дробной части
Полеdata.thousandsSep Типstring ОписаниеРазделитель тысяч
Полеdata.decimals Типnumber ОписаниеЗнаков после запятой
Полеdata.dateUpdate Типdatetime ОписаниеДата последнего изменения
Полеdata.lang Типobject ОписаниеНастройки отображения по языкам — формат, название, разделители, с ключом-идентификатором языка. Заполняется из плоских полей запроса для языка вашего API-ключа

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

Успешный запрос возвращает полный объект созданной валюты со статусом 201.

JSON
{
  "success": true,
  "data": {
    "id": "CNY",
    "fullName": "Китайский юань",
    "amount": 12.7,
    "amountCnt": 1,
    "base": false,
    "sort": 300,
    "lid": "ru",
    "formatString": "# ¥",
    "decimals": 2,
    "decPoint": ".",
    "thousandsSep": " ",
    "dateUpdate": "2024-11-12T07:20:08.000Z",
    "lang": {
      "ru": {
        "FORMAT_STRING": "# ¥",
        "FULL_NAME": "Китайский юань",
        "DEC_POINT": ".",
        "THOUSANDS_SEP": " ",
        "DECIMALS": "2",
        "THOUSANDS_VARIANT": "S",
        "HIDE_ZERO": "N"
      }
    }
  }
}

Пример ответа при ошибке

422 — валюта с таким id уже заведена:

JSON
{
  "success": false,
  "error": { "code": "BITRIX_ERROR", "message": "Валюта с таким идентификатором уже существует<br>" }
}

Ошибки

HTTP Код Описание
HTTP400 КодREADONLY_FIELD ОписаниеВ теле передано поле только для чтения, например LANG или dateUpdate. Имя поля указано в message
HTTP422 КодBITRIX_ERROR ОписаниеНе передан formatString — сообщение Не заполнено поле "Формат" для языка ru
HTTP422 КодBITRIX_ERROR ОписаниеВалюта с таким id уже существует
HTTP422 КодBITRIX_ERROR Описаниеid не из трёх латинских букв — сообщение Идентификатор валюты должен состоять из 3-х символов латинского алфавита
HTTP422 КодBITRIX_ERROR Описаниеamount равен нулю — сообщение Неверный курс по умолчанию
HTTP422 КодBITRIX_ERROR ОписаниеПрочие отказы валидации Битрикс24 — конкретная причина в message
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа crm
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key

Полный список ошибок — Ошибки.

Смотрите также