لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/currencies.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Currencies

Currency directory of your Bitrix24 account, with exchange rates. The currency ID is a string code (USD, EUR, …).

Bitrix24 API: crm.currency.* Scope: crm

Create currency

POST /v1/currencies

Creates a new currency in CRM. The currency code is set in the id field (three-letter ISO 4217 code).

Request body parameters

Parameter Type Required Description
Parameterid Typestring Requiredyes DescriptionCurrency code (USD, EUR, …)
Parameteramount Typenumber Requiredyes DescriptionExchange rate relative to the base currency
ParameteramountCnt Typenumber Requiredyes DescriptionDenomination — 1 for most currencies, 100 for JPY
Parametersort Typenumber Required DescriptionSort order
ParameterfullName Typestring Required DescriptionCurrency name. When omitted, the currency code is used as the name
ParameterformatString Typestring Requiredyes DescriptionDisplay template, e.g. # $. The # character is the placeholder for the amount
Parameterdecimals Typenumber Required DescriptionNumber of decimal places
ParameterdecPoint Typestring Required DescriptionDecimal separator
ParameterthousandsSep Typestring Required DescriptionThousands separator

Localizable fields can be sent flat. fullName, formatString, decimals, decPoint, thousandsSep are stored per-language in Bitrix24. The API packs them into your language's localization (the API key's language), so a flat write now persists and reads back. A raw LANG object in the body is not accepted — the field is read-only and the request returns 400 READONLY_FIELD. Setting different values for several languages at once via the API is not yet supported.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/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": "Chinese yuan", "formatString": "# ¥"}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/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": "Chinese yuan", "formatString": "# ¥"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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: 'Chinese yuan', formatString: '# ¥' }),
})
const { success, data } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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: 'Chinese yuan', formatString: '# ¥' }),
})
const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe created currency with all fields
Fielddata.id Typestring DescriptionCurrency code (USD, EUR, …)
Fielddata.amountCnt Typenumber DescriptionNumber of units for the rate
Fielddata.amount Typenumber DescriptionExchange rate
Fielddata.sort Typenumber DescriptionSort order
Fielddata.base Typeboolean DescriptionBase currency
Fielddata.fullName Typestring DescriptionName (e.g. $, €)
Fielddata.lid Typestring DescriptionID of the site the currency is bound to
Fielddata.formatString Typestring DescriptionDisplay format
Fielddata.decPoint Typestring DescriptionDecimal separator
Fielddata.thousandsSep Typestring DescriptionThousands separator
Fielddata.decimals Typenumber DescriptionDecimal places
Fielddata.dateUpdate Typedatetime DescriptionDate of the last update
Fielddata.lang Typeobject DescriptionPer-language display settings — format, name, separators, keyed by language ID. Filled from the flat request fields for your API key's language

Response example

A successful request returns the full created currency object with status 201.

JSON 
{
  "success": true,
  "data": {
    "id": "CNY",
    "fullName": "Chinese yuan",
    "amount": 12.7,
    "amountCnt": 1,
    "base": false,
    "sort": 300,
    "lid": "en",
    "formatString": "# ¥",
    "decimals": 2,
    "decPoint": ".",
    "thousandsSep": " ",
    "dateUpdate": "2024-11-12T07:20:08.000Z",
    "lang": {
      "en": {
        "FORMAT_STRING": "# ¥",
        "FULL_NAME": "Chinese yuan",
        "DEC_POINT": ".",
        "THOUSANDS_SEP": " ",
        "DECIMALS": "2",
        "THOUSANDS_VARIANT": "S",
        "HIDE_ZERO": "N"
      }
    }
  }
}

Error response example

422 — a currency with this id already exists. The message below is an English rendering of the text the API returns:

JSON 
{
  "success": false,
  "error": { "code": "BITRIX_ERROR", "message": "A currency with this identifier already exists" }
}

Errors

HTTP Code Description
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains a read-only field, such as LANG or dateUpdate. The field name is given in message
HTTP422 CodeBITRIX_ERROR DescriptionformatString is missing — the message states that the format field is not filled in for your language
HTTP422 CodeBITRIX_ERROR DescriptionA currency with this id already exists
HTTP422 CodeBITRIX_ERROR Descriptionid is not three Latin letters — the message states that the currency identifier must be 3 Latin characters
HTTP422 CodeBITRIX_ERROR Descriptionamount is zero — the message reports an invalid default rate
HTTP422 CodeBITRIX_ERROR DescriptionAny other Bitrix24 validation failure — the exact reason is in message
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the crm scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing

Full list of errors — Errors.

See also