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

`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 — личный ключ

```bash
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-приложение

```bash
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()
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | string | Код валюты (RUB, USD, EUR) |
| `amountCnt` | number | Количество единиц для курса |
| `amount` | number | Курс обмена |
| `sort` | number | Сортировка |
| `base` | boolean | Базовая валюта |
| `fullName` | string | Название (руб., $) |
| `lid` | string | Идентификатор сайта, к которому привязана валюта |
| `formatString` | string | Формат отображения |
| `decPoint` | string | Разделитель дробной части |
| `thousandsSep` | string | Разделитель тысяч |
| `decimals` | number | Знаков после запятой |
| `dateUpdate` | datetime | Дата последнего изменения |
| `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 | Код | Описание |
|------|-----|---------|
| 400 | `READONLY_FIELD` | В теле передано поле только для чтения, например `LANG` или `dateUpdate`. Имя поля указано в `message` |
| 422 | `BITRIX_ERROR` | Не передан `formatString` — сообщение `Не заполнено поле "Формат" для языка ru` |
| 422 | `BITRIX_ERROR` | Валюта с таким `id` уже существует |
| 422 | `BITRIX_ERROR` | `id` не из трёх латинских букв — сообщение `Идентификатор валюты должен состоять из 3-х символов латинского алфавита` |
| 422 | `BITRIX_ERROR` | `amount` равен нулю — сообщение `Неверный курс по умолчанию` |
| 422 | `BITRIX_ERROR` | Прочие отказы валидации Битрикс24 — конкретная причина в `message` |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `crm` |
| 401 | `TOKEN_MISSING` | Не передан API-ключ |

Полный список ошибок — [Ошибки](/docs/errors).

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

- [Список валют](/docs/entities/currencies/list)
- [Описание полей](/docs/entities/currencies/fields)
- [Валюты](/docs/entities/currencies)