> For the complete documentation index, see [llms.txt](https://docs.iexexchanger.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iexexchanger.com/guide/kursy/istochniki/kursy-iz-faila/formaty-failov-i-pravila-podgotovki-dannykh.md).

# Форматы файлов и правила подготовки данных

Для работы с разделом **«Парсер курсов» — «Курсы из файла»** подготовьте файл в формате TXT, CSV, JSON или XML и разместите его по прямой ссылке.

iEXExchanger читает содержимое файла, определяет пары, вычисляет выражения и получает значения для курсов, которые вы создали в панели управления.

В этой статье описаны структуры файлов, допустимые поля, правила вычислений, обратные пары, города и ошибки подготовки данных.

{% content-ref url="/pages/DoE3UmZHRVvH7K1sLZmA" %}
[Курсы из файла](https://docs.iexexchanger.com/guide/kursy/istochniki/kursy-iz-faila.md)
{% endcontent-ref %}

{% hint style="info" %}
Все значения в примерах учебные.

Используйте готовые примеры файлов по отдельности. Если объединяете несколько примеров, проверяйте повторяющиеся пары: разные определения одной пары могут создать конфликт.
{% endhint %}

## Общие требования

### Поддерживаемые форматы

<table><thead><tr><th width="163.03125">Формат</th><th>Как задаются пары и значения</th><th>Особенности</th></tr></thead><tbody><tr><td>TXT</td><td>Текстовые строки</td><td>Поддерживает алиасы и несколько пар с одним выражением в строке</td></tr><tr><td>CSV</td><td>Колонки с парой и курсом либо с отдельными полями</td><td>Поддерживает заголовки, <code>from/to</code>, <code>in/out</code> и города</td></tr><tr><td>JSON</td><td>Объект с ключами-парами или массив записей</td><td>Поддерживает готовые значения и структурированные записи</td></tr><tr><td>XML</td><td>Элементы и атрибуты</td><td>Поддерживает <code>from/to</code>, <code>base/quote</code>, <code>in/out</code>, выражения и города</td></tr></tbody></table>

Во всех четырёх форматах можно использовать готовые числа и поддерживаемые математические выражения.

Ссылки на другие пары этого же файла также доступны во всех четырёх форматах. Для XML отдельно учитываются правила наличия запрошенной пары.

При добавлении источника в поле **«Тип файла»** выберите нужный формат или оставьте **«Авто»**.

### Требования к файлу и ссылке

<table><thead><tr><th width="228.8984375">Параметр</th><th>Требование</th></tr></thead><tbody><tr><td>Кодировка</td><td>UTF-8</td></tr><tr><td>Размер файла</td><td>В стандартной конфигурации — до 64 МБ; на сервере ограничение может быть изменено</td></tr><tr><td>Адрес</td><td>Прямая публичная HTTP- или HTTPS-ссылка</td></tr><tr><td>Доступ</td><td>Файл должен открываться с сервера обменного пункта</td></tr><tr><td>Перенаправления</td><td>Используйте конечный адрес без перенаправления</td></tr><tr><td>Содержимое</td><td>Корректный файл с хотя бы одним допустимым положительным курсом</td></tr></tbody></table>

Пример адреса:

```
https://example.com/rates.txt
```

При настройке замените его действующей ссылкой вашего источника.

Страница просмотра файла в облачном хранилище не всегда является прямой ссылкой на содержимое. По указанному адресу должен возвращаться сам файл, без формы входа, HTML-страницы или дополнительных действий в браузере.

Локальные и внутренние адреса сети не подходят. Авторизация через логин и пароль внутри URL не поддерживается.

XLSX, XLS и ZIP не являются форматами этого раздела. Переименование такого файла в `.csv` или `.txt` не преобразует его содержимое.

### Автоматическое определение формата

В режиме **«Авто»** система учитывает содержимое файла и адрес источника.

JSON и XML распознаются по структуре содержимого. Для TXT и CSV также учитываются расширение адреса и первые содержательные строки.

Поэтому ссылка может не иметь расширения, например:

```
https://example.com/rates
```

Если структура TXT или CSV неоднозначна, укажите формат явно.

При явном выборе формата система обрабатывает содержимое именно в нём. Выбор **«CSV»** не означает, что файл с разделителем `;` будет автоматически преобразован в поддерживаемый CSV.

### Названия валютных пар

Обычная пара состоит из двух частей:

```
USD - RUB
```

Пара с городом — из трёх:

```
CASHRUB - USDTTRC20 - MSK
```

Для каждого кода действуют правила:

* первый символ — латинская буква;
* далее допускаются латинские буквы, цифры и подчёркивание `_`;
* длина — от 1 до 32 символов;
* пробелы внутри одного кода не допускаются.

Правильные примеры:

```
BTC - USDT
USD - RUB
USDT_TRC20 - RUB_CARD
CASHRUB - USDTTRC20 - MSK
```

Система приводит регистр и оформление к нормализованному виду:

<table><thead><tr><th width="264.046875">Исходная запись</th><th>Нормализованное название</th></tr></thead><tbody><tr><td><code>usd-rub</code></td><td><code>USD - RUB</code></td></tr><tr><td><code>BTC:USDT</code></td><td><code>BTC - USDT</code></td></tr><tr><td><code>cashrub-usdttrc20-msk</code></td><td><code>CASHRUB - USDTTRC20 - MSK</code></td></tr></tbody></table>

Для обычных названий используйте дефис или двоеточие как разделитель. В значении пары внутри XML также распознаются `/` и `|`. Для единого оформления во всех форматах удобнее использовать `-`.

Неправильные примеры:

<table><thead><tr><th width="270.50390625">Запись</th><th>Причина</th></tr></thead><tbody><tr><td><code>123BTC - USD</code></td><td>Первый код начинается с цифры</td></tr><tr><td><code>USD - РУБ</code></td><td>В коде используется кириллица</td></tr><tr><td><code>BTC - RUB CLIENT</code></td><td>Внутри второго кода есть пробел</td></tr><tr><td><code>USD - RUB - MSK - CASH</code></td><td>Указано больше трёх частей</td></tr><tr><td><code>USD</code></td><td>Не указана вторая часть пары</td></tr></tbody></table>

{% hint style="info" %}
`USDT`, `USDTTRC20` и `USDT_TRC20` — разные коды.

Система не заменяет их друг другом автоматически. Используйте обозначения поставщика и выбирайте соответствующую пару при настройке направления.
{% endhint %}

### Числовые значения

Курс должен быть положительным числом или выражением, которое даёт положительный результат.

Для десятичной части используйте точку:

```
90
90.5
60000
0.000025
```

Не добавляйте разделители тысяч, обозначения валют или пояснения внутрь значения:

```
60 000
90 RUB
$100
около 90
```

Такие записи не являются готовыми числовыми курсами.

Десятичная запятая поддерживается в отдельных значениях, но может конфликтовать с разделителем CSV или аргументами функции. Поэтому во всех готовых примерах используется точка.

Научную запись вида `1e-8` не используйте в текстовых значениях и выражениях. Записывайте число полностью:

```
0.00000001
```

Нулевой и отрицательный итоговые курсы не публикуются как рабочие значения.

## Формат TXT

### Структура строки

Основная запись:

```
USD - RUB : 90
```

Слева находится название пары, справа — число или выражение.

Последнее двоеточие в строке отделяет значение от названия. Поэтому допустима и такая запись:

```
USD:RUB : 90
```

Для читаемости используйте единое оформление:

```
USD - RUB : 90
BTC - USDT : 60000
ETH - USDT : 2500
```

Пустые строки можно использовать для разделения блоков.

### Несколько пар с одним значением

В TXT можно перечислить несколько пар через запятую перед двоеточием:

```
USD - RUB, USDT - RUB : 90
```

Обе пары получат значение 90.

Справа также может находиться выражение:

```
USD - RUB, USDT - RUB : 90 * 1.02
```

Обе пары получат значение 91.8.

Используйте такую запись только тогда, когда одинаковое значение действительно предназначено для всех перечисленных пар.

Не добавляйте ниже другое определение одной из этих пар: это может создать конфликт.

### Комментарии

В TXT поддерживаются комментарии на отдельных строках:

```
# Основные курсы
USD - RUB : 90

; Криптовалютные пары
BTC - USDT : 60000

// Дополнительные пары
ETH - USDT : 2500
```

Строки, начинающиеся с `#`, `;` или `//`, пропускаются.

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

Неправильно:

```
USD - RUB : 90 # основной курс
```

Правильно:

```
# Основной курс
USD - RUB : 90
```

### Алиасы

Алиас — короткое имя для числа, выражения, валютного кода или пары.

Объявление записывается через знак `=`:

```
MARKUP = 1.02
```

Имя алиаса должно начинаться с латинской буквы, содержать только латинские буквы, цифры и подчёркивание и иметь длину от 1 до 32 символов.

Объявляйте алиасы до использования и не задавайте одному имени несколько разных значений.

#### Алиас числа или выражения

```
BASE = 90
MARKUP = 1.02

USD - RUB : (BASE) * (MARKUP)
```

Результат:

```
USD - RUB = 91.8
```

Для использования значения алиаса в выражении заключите его имя в круглые скобки.

#### Алиас пары

```
BASE = USD - RUB

USD - RUB : 90
EUR - RUB : (BASE) * 1.1
```

Результат:

```
USD - RUB = 90
EUR - RUB = 99
```

Алиас пары можно использовать и вместо полного названия слева:

```
BASE = USD - RUB

BASE : 90
EUR - RUB : (BASE) * 1.1
```

В результате создаются определения `USD - RUB` и `EUR - RUB`. Сам `BASE` не становится отдельной валютной парой.

{% hint style="warning" %}
Не используйте один общий алиас пары одновременно для обычных и обратных расчётов: в текущей обработке это может дать значение неправильного направления.

В определении обратного курса указывайте полное имя исходной пары, например `RUB - USD : (USD - RUB)`.
{% endhint %}

#### Алиас валютного кода

```
TETHER = USDT_TRC20

TETHER - RUB : 90
```

Нормализованная пара:

```
USDT_TRC20 - RUB
```

При добавлении пары в панели ориентируйтесь на итоговое название. Каталог **«Выбрать из доступных пар»** помогает выбрать его без ручного преобразования.

### Полный пример TXT

```
# Коэффициент для отдельной пары
MARKUP = 1.02

# Основные курсы
USD - RUB : 90
USDT - USD : 1
BTC - USDT : 60000
EUR - USD : 1.1

# Обратный курс
RUB - USD : (USD - RUB)

# Производные курсы
BTC - RUB : (BTC - USDT) * (USDT - USD) * (USD - RUB)
EUR - RUB : (EUR - USD) * (USD - RUB)

# Отдельная пара с коэффициентом
USD - RUB_CARD : (USD - RUB) * (MARKUP)
```

Ожидаемые значения при стандартной точности:

<table><thead><tr><th width="244.5390625">Пара</th><th>Результат</th></tr></thead><tbody><tr><td><code>USD - RUB</code></td><td><code>90</code></td></tr><tr><td><code>USDT - USD</code></td><td><code>1</code></td></tr><tr><td><code>BTC - USDT</code></td><td><code>60000</code></td></tr><tr><td><code>EUR - USD</code></td><td><code>1.1</code></td></tr><tr><td><code>RUB - USD</code></td><td><code>0.011111111111111111</code></td></tr><tr><td><code>BTC - RUB</code></td><td><code>5400000</code></td></tr><tr><td><code>EUR - RUB</code></td><td><code>99</code></td></tr><tr><td><code>USD - RUB_CARD</code></td><td><code>91.8</code></td></tr></tbody></table>

`RUB_CARD` в примере — отдельный условный код. Парсер не создаёт по нему платёжную систему или направление обмена автоматически.

## Формат CSV

### Разделители и кодировка

Используйте CSV в кодировке UTF-8 с запятой в качестве разделителя колонок.

Поддерживаемый вариант:

```csv
USD - RUB,90
BTC - USDT,60000
```

Вариант с точкой с запятой не подходит:

```
USD - RUB;90
BTC - USDT;60000
```

Если файл создаётся из электронной таблицы, проверьте фактический разделитель после экспорта.

### CSV без заголовков

Без заголовков используются первые две колонки:

1. Название пары.
2. Значение или выражение.

Пример:

```csv
USD - RUB,90
USDT - USD,1
BTC - USDT,60000
BTC - RUB,(BTC - USDT) * (USDT - USD) * (USD - RUB)
```

Дополнительные колонки в таком варианте не заменяют именованные поля. Для `from`, `to`, `in`, `out` и города используйте строку заголовков.

### CSV с заголовками

Пример с полями `pair` и `rate`:

```csv
pair,rate
USD - RUB,90
EUR - USD,1.1
EUR - RUB,(EUR - USD) * (USD - RUB)
```

Пример с отдельными кодами валют:

```csv
from,to,rate
USD,RUB,90
EUR,USD,1.1
BTC,USDT,60000
```

Заголовки должны соответствовать поддерживаемым именам полей. Система распознаёт строку заголовков по известным названиям; используйте как минимум два подходящих поля.

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

### Кавычки и запятые внутри значений

Если значение содержит запятую, заключите всю ячейку в двойные кавычки.

Например, функция с несколькими аргументами:

```csv
pair,rate
USD - RUB,"MAX(90, 95)"
```

Результат — 95.

Число с десятичной запятой:

```csv
USD - RUB,"90,5"
```

Результат — 90.5.

Без кавычек получится другое содержимое колонок:

```csv
USD - RUB,90,5
```

В таком случае во второй колонке находится `90`, а `5` — уже третья колонка. Это не запись курса 90.5.

{% hint style="warning" %}
В CSV действуют два разных правила:

* запятые внутри ячейки требуют кавычек вокруг всей ячейки;
* между числовыми аргументами функции нужен пробел после запятой.

Поэтому используйте `"MAX(90, 95)"`.
{% endhint %}

### Курсы через `in` и `out`

Вместо готового курса можно передать две суммы:

```csv
from,to,in,out
USD,RUB,100,9000
BTC,USDT,1,60000
```

Расчёт выполняется по правилу:

```
курс = out / in
```

Для первой строки:

```
9000 / 100 = 90
```

Для второй:

```
60000 / 1 = 60000
```

Оба значения должны быть положительными числами. Выражения в полях `in` и `out` не используются вместо сумм. Для вычисляемого курса задавайте выражение в поле `rate`.

### Города в CSV

Добавьте колонку `city`:

```csv
from,to,in,out,city
CASHRUB,USDTTRC20,9000,100,MSK
CASHRUB,USDTTRC20,9100,100,SPB
```

Будут определены две разные пары:

```
CASHRUB - USDTTRC20 - MSK
CASHRUB - USDTTRC20 - SPB
```

При добавлении в панели выбирайте полное название с нужным городом.

### Приоритет поля курса

Если в записи задано поле курса, например `rate`, оно имеет приоритет перед расчётом `out / in`.

```csv
from,to,rate,in,out
USD,RUB,92,100,9000
```

Результат — 92.

{% hint style="warning" %}
Если рассчитываете CSV через `in` и `out`, не оставляйте пустую колонку `rate`:

```csv
from,to,rate,in,out
USD,RUB,,100,9000
```

Пустая строка в поле курса мешает перейти к расчёту отношения. Уберите колонку `rate` либо заполните её корректным значением.
{% endhint %}

### Комментарии в CSV

Пропускаются строки, у которых первая ячейка начинается с `#` или `//`.

```csv
# Основные курсы
pair,rate
USD - RUB,90
BTC - USDT,60000
```

Точка с запятой не является маркером комментария CSV.

Для обмена файлами между разными программами удобнее использовать обычный CSV без комментариев.

## Поля CSV и JSON

### Допустимые названия полей

Структурированные CSV- и JSON-записи используют следующие поля.

<table><thead><tr><th width="283.09375">Назначение</th><th>Допустимые названия</th></tr></thead><tbody><tr><td>Полное название пары</td><td><code>pair</code>, <code>name</code>, <code>currency_pair</code>, <code>currencypair</code>, <code>symbol</code>, <code>market</code></td></tr><tr><td>Первая валюта</td><td><code>from</code>, <code>currency_from</code>, <code>from_currency</code>, <code>exchange_in</code>, <code>give</code>, <code>base</code></td></tr><tr><td>Вторая валюта</td><td><code>to</code>, <code>currency_to</code>, <code>to_currency</code>, <code>exchange_out</code>, <code>get</code>, <code>quote</code>, <code>currency</code></td></tr><tr><td>Готовый курс или выражение</td><td><code>rate</code>, <code>value</code>, <code>price</code>, <code>course</code>, <code>summa</code>, <code>result</code>, <code>exchange_rate</code></td></tr><tr><td>Исходная сумма</td><td><code>in</code>, <code>amount_in</code>, <code>input</code>, <code>from_amount</code>, <code>give_amount</code>, <code>source_amount</code></td></tr><tr><td>Выходная сумма</td><td><code>out</code>, <code>amount_out</code>, <code>output</code>, <code>to_amount</code>, <code>get_amount</code>, <code>target_amount</code></td></tr><tr><td>Город</td><td><code>city</code>, <code>city_code</code>, <code>citycode</code>, <code>location</code></td></tr></tbody></table>

Для собственного файла удобнее использовать короткие имена `pair`, `from`, `to`, `rate`, `in`, `out`, `city`.

Не передавайте несколько полей одного назначения с разными значениями. Система выбирает поле по своему порядку обработки, а не объединяет их.

### Как определяется пара

Можно использовать один из способов:

* полное имя в `pair`;
* отдельные коды в `from` и `to`;
* отдельные коды в `base` и `quote`.

Если есть полное имя пары, не рассчитывайте, что дополнительные `from` и `to` исправят его.

Если указан отдельный `city`, он добавляется к паре без города. Если город уже включён в полное имя, второй город к нему не добавляется.

Чтобы избежать неоднозначности, задавайте город одним способом.

### Дополнительные поля

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

Например, наличие `reserve`, `minamount`, `maxamount` или комментария в записи не означает автоматического изменения резервов, лимитов и комиссий направления.

Для получения курса используются поддерживаемые поля пары, значения и города.

## Формат JSON

### Объект с парами в ключах

Простой вариант:

```json
{
  "USD - RUB": "90",
  "BTC - USDT": "60000",
  "ETH - USDT": "2500"
}
```

Ключ — название пары. Значение — число или выражение.

Для десятичных значений, особенно длинных, используйте строки в двойных кавычках.

### Выражения в JSON

```json
{
  "USD - RUB": "90",
  "EUR - USD": "1.1",
  "EUR - RUB": "(EUR - USD) * (USD - RUB)",
  "RUB - USD": "(USD - RUB)"
}
```

Ожидаемые значения:

<table><thead><tr><th width="216.3359375">Пара</th><th>Результат</th></tr></thead><tbody><tr><td><code>USD - RUB</code></td><td><code>90</code></td></tr><tr><td><code>EUR - USD</code></td><td><code>1.1</code></td></tr><tr><td><code>EUR - RUB</code></td><td><code>99</code></td></tr><tr><td><code>RUB - USD</code></td><td><code>0.011111111111111111</code></td></tr></tbody></table>

Выражение обязательно должно быть строкой JSON.

### Массив записей

Вместо пар в ключах можно использовать массив объектов:

```json
[
  {
    "pair": "USD - RUB",
    "rate": "90"
  },
  {
    "from": "EUR",
    "to": "USD",
    "rate": "1.1"
  },
  {
    "from": "EUR",
    "to": "RUB",
    "rate": "(EUR - USD) * (USD - RUB)"
  }
]
```

У каждого объекта должна быть информация, достаточная для определения пары и её значения.

Одна запись также оформляется массивом:

```json
[
  {
    "pair": "USD - RUB",
    "rate": "90"
  }
]
```

### Объект с подробными записями

Название пары можно оставить в ключе, а параметры разместить внутри объекта:

```json
{
  "USD - RUB": {
    "rate": "90"
  },
  "BTC - USDT": {
    "in": "1",
    "out": "60000"
  },
  "CASHRUB - USDTTRC20": {
    "in": "9000",
    "out": "100",
    "city": "MSK"
  }
}
```

Последняя запись определяет пару:

```
CASHRUB - USDTTRC20 - MSK
```

Если используете такой вариант, ключи должны быть названиями пар. Для служебных идентификаторов записей удобнее использовать массив объектов с явным полем `pair`.

### Курсы через `in` и `out`

```json
[
  {
    "from": "USD",
    "to": "RUB",
    "in": "100",
    "out": "9000"
  },
  {
    "base": "BTC",
    "quote": "USDT",
    "in": "1",
    "out": "60000"
  }
]
```

Результаты — 90 и 60000 соответственно.

Как и в CSV, явно заданный курс имеет приоритет перед отношением сумм.

При расчёте через `in` и `out` не добавляйте пустое строковое поле `"rate": ""`. Уберите его из записи.

### Города в JSON

```json
[
  {
    "from": "CASHRUB",
    "to": "USDTTRC20",
    "in": "9000",
    "out": "100",
    "city": "MSK"
  },
  {
    "from": "CASHRUB",
    "to": "USDTTRC20",
    "in": "9100",
    "out": "100",
    "city": "SPB"
  }
]
```

Город можно включить и непосредственно в ключ:

```json
{
  "CASHRUB - USDTTRC20 - MSK": "0.011",
  "CASHRUB - USDTTRC20 - SPB": "0.0109"
}
```

Это два самостоятельных примера. Не объединяйте их в один источник без проверки значений и дубликатов.

### Какие структуры JSON не подходят

Произвольная вложенность не раскрывается автоматически.

Например, такая обёртка не является поддерживаемым массивом записей на верхнем уровне:

```json
{
  "rates": [
    {
      "pair": "USD - RUB",
      "rate": "90"
    }
  ]
}
```

Для обработки используйте сам массив:

```json
[
  {
    "pair": "USD - RUB",
    "rate": "90"
  }
]
```

Одиночный объект записи на верхнем уровне также не заменяет массив:

```json
{
  "pair": "USD - RUB",
  "rate": "90"
}
```

Другой неподходящий вариант — массивы из двух значений вместо объектов:

```json
[
  ["USD - RUB", "90"]
]
```

Используйте объект с ключами-парами или массив объектов с поддерживаемыми полями.

### Правила корректного JSON

Соблюдайте синтаксис JSON:

* строки и названия полей заключаются в двойные кавычки;
* между элементами ставится запятая;
* после последнего элемента запятая не ставится;
* комментарии `#`, `//` и `/* ... */` не допускаются;
* значения `true`, `false`, `null`, объекты и массивы не заменяют числовой курс;
* повторяющиеся ключи не следует использовать для хранения нескольких курсов.

Если нужен комментарий, его можно передать отдельным строковым полем структурированной записи. Это будет дополнительная информация, а не часть выражения курса.

## Формат XML

### Основная структура

XML должен иметь корректную структуру с одним корневым элементом.

Пример:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <item>
    <from>USD</from>
    <to>RUB</to>
    <in>100</in>
    <out>9000</out>
  </item>
  <item>
    <from>BTC</from>
    <to>USDT</to>
    <in>1</in>
    <out>60000</out>
  </item>
</rates>
```

Результат:

```
USD - RUB = 90
BTC - USDT = 60000
```

Название контейнера записи не обязано быть `item`. Значение определяется по поддерживаемым полям и структуре записи.

### Готовый курс в поле

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <item>
    <pair>USD - RUB</pair>
    <rate>90</rate>
  </item>
  <item>
    <pair>BTC - USDT</pair>
    <rate>60000</rate>
  </item>
</rates>
```

Вместо полного имени можно указать отдельные валюты:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <item>
    <from>USD</from>
    <to>RUB</to>
    <rate>90</rate>
  </item>
</rates>
```

### Значения в атрибутах

Поддерживаемые поля можно передавать атрибутами:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <item pair="USD - RUB" rate="90"/>
  <item from="BTC" to="USDT" in="1" out="60000"/>
</rates>
```

В одной записи можно сочетать атрибуты и дочерние поля, если они не дублируют друг друга.

Не указывайте одно и то же поле одновременно атрибутом и дочерним элементом:

```xml
<rates>
  <item pair="USD - RUB" rate="90">
    <rate>90</rate>
  </item>
</rates>
```

Такая запись содержит повторное поле `rate` и не используется как корректное определение курса, даже если значения совпадают.

### Значение в тексте элемента

Если пара задана атрибутами, сам курс может находиться в тексте элемента:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <rate from="USD" to="RUB">90</rate>
  <rate from="BTC" to="USDT">60000</rate>
</rates>
```

Поддерживается и листовой элемент, имя которого является парой:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <USD-RUB>90</USD-RUB>
  <BTC-USDT>60000</BTC-USDT>
</rates>
```

Такой элемент не должен содержать вложенные элементы вместо готового значения.

### Общая базовая валюта

Базовую валюту можно задать у родительского элемента:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rates base="USD">
  <item currency="RUB" value="90"/>
  <item currency="EUR" value="0.9"/>
</rates>
```

Получатся пары:

```
USD - RUB = 90
USD - EUR = 0.9
```

Базовую валюту можно передать отдельным полем:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <base>USD</base>
  <item currency="RUB" value="90"/>
  <item currency="EUR" value="0.9"/>
</rates>
```

{% hint style="warning" %}
Если базовая валюта задаётся дочерним полем, разместите его до записей, которые от него зависят.

XML читается последовательно. Поле `<base>`, расположенное после зависимых записей, не задаёт базовую валюту для уже прочитанных элементов.
{% endhint %}

### Допустимые поля XML

Набор XML-полей шире набора CSV и JSON.

<table><thead><tr><th width="331.21484375">Назначение</th><th>Допустимые названия</th></tr></thead><tbody><tr><td>Полное название пары</td><td><code>pair</code>, <code>name</code>, <code>currency_pair</code>, <code>currencypair</code>, <code>symbol</code>, <code>market</code>, <code>ticker</code></td></tr><tr><td>Первая валюта</td><td><code>from</code>, <code>currency_from</code>, <code>from_currency</code>, <code>exchange_in</code>, <code>currency1</code>, <code>give</code>, <code>base_currency</code></td></tr><tr><td>Вторая валюта</td><td><code>to</code>, <code>currency_to</code>, <code>to_currency</code>, <code>exchange_out</code>, <code>currency2</code>, <code>get</code>, <code>quote_currency</code></td></tr><tr><td>Базовая валюта</td><td><code>base</code>, <code>base_currency</code>, <code>from_currency</code></td></tr><tr><td>Валюта относительно базовой</td><td><code>quote</code>, <code>quote_currency</code>, <code>currency</code>, <code>code</code>, <code>target_currency</code></td></tr><tr><td>Готовый курс или выражение</td><td><code>rate</code>, <code>value</code>, <code>price</code>, <code>course</code>, <code>summa</code>, <code>result</code>, <code>exchange_rate</code></td></tr><tr><td>Исходная сумма</td><td><code>in</code>, <code>amount_in</code>, <code>input</code>, <code>from_amount</code>, <code>give_amount</code>, <code>source_amount</code></td></tr><tr><td>Выходная сумма</td><td><code>out</code>, <code>amount_out</code>, <code>output</code>, <code>to_amount</code>, <code>get_amount</code>, <code>target_amount</code></td></tr><tr><td>Город</td><td><code>city</code>, <code>city_code</code>, <code>citycode</code>, <code>location</code></td></tr></tbody></table>

Используйте один понятный способ определения пары и одно поле каждого назначения.

Поля должны быть атрибутами записи или её непосредственными дочерними элементами со скалярным значением.

Например, поле:

```xml
<from>USD</from>
```

подходит, а произвольная вложенная структура:

```xml
<from>
  <code>USD</code>
</from>
```

не равнозначна ему.

### Приоритет значений XML

Курс определяется в следующем порядке:

1. Явно заданный курс или выражение в поле `rate` либо его синониме.
2. Отношение положительных чисел `out / in`.
3. Текст листового элемента, если он подходит для определения значения.

Пример:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <item
    from="USD"
    to="RUB"
    rate="92"
    in="100"
    out="9000"
  />
</rates>
```

Будет использовано значение 92 из `rate`.

Если явно заданное выражение ошибочно, не рассчитывайте, что система автоматически заменит его отношением `out / in`.

### Выражения в XML

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <item pair="USD - RUB" rate="90"/>
  <item pair="EUR - USD" rate="1.1"/>
  <item pair="EUR - RUB" rate="(EUR - USD) * (USD - RUB)"/>
</rates>
```

Результат для `EUR - RUB` — 99.

Выражение можно передать и дочерним полем:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <item>
    <pair>USD - RUB</pair>
    <rate>MAX(90, 95)</rate>
  </item>
</rates>
```

Результат — 95.

### Города в XML

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <item>
    <from>CASHRUB</from>
    <to>USDTTRC20</to>
    <in>9000</in>
    <out>100</out>
    <city>MSK</city>
  </item>
  <item>
    <from>CASHRUB</from>
    <to>USDTTRC20</to>
    <in>9100</in>
    <out>100</out>
    <city>SPB</city>
  </item>
</rates>
```

Получатся две самостоятельные пары:

```
CASHRUB - USDTTRC20 - MSK
CASHRUB - USDTTRC20 - SPB
```

В предварительной проверке система может показать **«Доступные варианты»**. Выберите нужный город либо укажите полное имя вручную.

Наличие кода города не создаёт город в настройках обменного пункта и не привязывает курс к городскому направлению автоматически.

### Обратные пары в XML

В XML наличие прямой пары не означает наличие обратной.

Если файл содержит только:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <item pair="USD - RUB" rate="90"/>
</rates>
```

запрос пары `RUB - USD` не получит курс только за счёт этой записи.

Чтобы предоставить обратную пару, добавьте её явно:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <item pair="USD - RUB" rate="90"/>
  <item pair="RUB - USD" rate="(USD - RUB)"/>
</rates>
```

Запись `RUB - USD` теперь присутствует в XML, а её значение вычисляется как обратное исходному курсу.

### Комментарии и ограничения XML

Используйте стандартные XML-комментарии:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <!-- Основной курс -->
  <item pair="USD - RUB" rate="90"/>
</rates>
```

Соблюдайте ограничения:

* XML должен быть синтаксически корректным;
* все открытые элементы должны быть закрыты;
* значения атрибутов должны быть заключены в кавычки;
* DTD и объявления `DOCTYPE` не поддерживаются;
* внешние сущности не используются для получения данных;
* одинаковые известные поля внутри записи не должны повторяться;
* произвольные вложенные объекты не заменяют скалярные поля курса.

Повреждение структуры XML может сделать недоступным весь файл, включая корректные записи до места ошибки.

## Выражения и вычисления

### Где можно использовать выражение

Выражение задаётся:

* справа от двоеточия в TXT;
* в колонке значения или `rate` в CSV;
* строковым значением пары или полем `rate` в JSON;
* полем курса или подходящим текстовым значением в XML.

Во всех случаях используется общий набор поддерживаемых операций.

Это не произвольный программный код и не полный язык выражений раздела **«Курсы по формуле»**.

### Арифметические операции

| Операция  | Пример значения   | Результат |
| --------- | ----------------- | --------- |
| Сложение  | `90 + 2`          | `92`      |
| Вычитание | `90 - 2`          | `88`      |
| Умножение | `90 * 1.02`       | `91.8`    |
| Деление   | `90 / 2`          | `45`      |
| Скобки    | `(90 + 2) * 1.01` | `92.92`   |

Умножение и деление выполняются раньше сложения и вычитания. Скобки меняют порядок вычисления.

Промежуточные действия могут содержать вычитание, но итоговый рабочий курс должен оставаться положительным.

### Проценты

Знак `%` обозначает процент. Он не является оператором остатка от деления.

| Выражение    | Как рассчитывается                  | Результат |
| ------------ | ----------------------------------- | --------- |
| `90 + 2%`    | Увеличение 90 на 2%                 | `91.8`    |
| `90 - 2%`    | Уменьшение 90 на 2%                 | `88.2`    |
| `90 * 98.5%` | Умножение 90 на 0.985               | `88.65`   |
| `90 / 50%`   | Деление 90 на 0.5                   | `180`     |
| `98.5%`      | Самостоятельное процентное значение | `0.985`   |

При сложении или вычитании процент справа применяется к значению слева.

При умножении и делении процент используется как доля от единицы.

Если нужен коэффициент, можно записать его непосредственно:

```
USD - RUB : 90 * 1.02
```

### Функции

Поддерживаются `MIN`, `MAX`, `AVG` и `IF`.

| Функция | Пример значения    | Результат |
| ------- | ------------------ | --------- |
| `MIN`   | `MIN(90, 95, 100)` | `90`      |
| `MAX`   | `MAX(90, 95, 100)` | `100`     |
| `AVG`   | `AVG(90, 95, 100)` | `95`      |
| `IF`    | `IF(1, 91, 90)`    | `91`      |
| `IF`    | `IF(0, 91, 90)`    | `90`      |

`MIN`, `MAX` и `AVG` принимают одно или несколько числовых выражений.

`IF` принимает ровно три аргумента. Если первый аргумент не равен нулю, возвращается второй; если равен нулю — третий.

#### Разделение аргументов

Между аргументами используйте запятую с пробелом:

```
MAX(90, 95)
```

Без пробела запись:

```
MAX(90,95)
```

читается как функция с одним числом `90.95`. Результатом будет 90.95, а не 95.

Это правило действует независимо от формата файла.

#### Ограничения `IF`

Операторы сравнения `>`, `<`, `>=`, `<=`, `==` и `!=` в файловых выражениях не поддерживаются.

Такая запись не подходит:

```
IF(90 > 80, 90, 80)
```

Также вычисляются все аргументы функции. Нельзя использовать `IF` для сокрытия ошибки в невыбранной ветви:

```
IF(1, 90, 1 / 0)
```

Несмотря на первый аргумент `1`, выражение содержит деление на ноль и не даст корректный курс.

Функции, которых нет в списке поддерживаемых, например `ROUND`, нельзя переносить сюда из других редакторов формул.

## Ссылки на пары и обратные курсы

### Ссылка на значение другой пары

Заключите полное название пары в круглые скобки:

```
USD - RUB : 90
EUR - USD : 1.1
EUR - RUB : (EUR - USD) * (USD - RUB)
```

Расчёт:

```
1.1 × 90 = 99
```

Ссылка обращается к данным этого же файла. Она не ищет курс в других файловых источниках или во всех разделах iEXExchanger.

Все необходимые зависимости должны присутствовать или разрешаться по поддерживаемым правилам внутри текущего файла.

### Порядок записей

Пара, на которую ссылается выражение, может находиться ниже:

```
EUR - RUB : (EUR - USD) * (USD - RUB)

USD - RUB : 90
EUR - USD : 1.1
```

Результат останется равным 99.

Это не отменяет отдельных правил объявления алиасов и общей базовой валюты XML. Алиасы размещайте до использования, а XML-поле базовой валюты — до зависимых записей.

### Расчёт через несколько пар

```
BTC - USDT : 60000
USDT - USD : 1
USD - RUB : 90

BTC - RUB : (BTC - USDT) * (USDT - USD) * (USD - RUB)
```

Результат:

```
60000 × 1 × 90 = 5400000
```

Если промежуточные валюты различаются, добавляйте необходимую конверсию явно. Наличие похожих названий не означает автоматического равенства USD и USDT.

### Явное определение обратного курса

```
USD - RUB : 90
RUB - USD : (USD - RUB)
```

Для обратной пары система учитывает противоположное направление и рассчитывает:

```
1 / 90 = 0.011111111111111111…
```

При стандартной точности результат:

```
0.011111111111111111
```

#### Почему не нужно повторно делить на исходную пару

Не используйте такое определение для той же обратной пары:

```
USD - RUB : 90
RUB - USD : 1 / (USD - RUB)
```

Ссылка `(USD - RUB)` в контексте `RUB - USD` уже пересчитывается как обратное значение. Дополнительное `1 /` переворачивает его повторно.

В этом примере получится 90, что не соответствует требуемому обратному курсу.

Используйте:

```
RUB - USD : (USD - RUB)
```

### Получение отсутствующей обратной пары

Для TXT, CSV и JSON запрошенная пара может быть вычислена через существующую обратную запись.

Например, в TXT есть только:

```
USD - RUB : 90
```

Если в панели запрошена пара `RUB - USD`, система может получить её как `1 / 90`.

Это не создаёт автоматически отдельную запись пары в панели. Нужную пару всё равно необходимо добавить и проверить.

Для XML такое получение отсутствующей записи не применяется: запрошенная пара должна присутствовать в файле.

### Собственные значения для обоих направлений

Прямую и обратную пары можно задать независимо:

```
USD - RUB : 90
RUB - USD : 0.0108
```

В этом случае используются указанные значения. Они не обязаны быть точными математическими обратными друг другу.

Если поставщик передаёт отдельные курсы покупки и продажи, сохраняйте смысл этих значений и не заменяйте один из них автоматическим пересчётом без необходимости.

### Города и обратное направление

Город является частью полного имени пары.

Например:

```
CASHRUB - USDTTRC20 - MSK
```

и:

```
CASHRUB - USDTTRC20 - SPB
```

— разные пары.

При обращении к обратной городской паре код города сохраняется:

```
USDTTRC20 - CASHRUB - MSK
```

Пара без города не заменяет городской вариант, а курс для одного города не подставляется автоматически вместо другого.

### Циклические зависимости

Нельзя определять пары друг через друга без исходного значения:

```
USD - RUB : (EUR - RUB)
EUR - RUB : (USD - RUB)
```

В таком файле нет значения, с которого можно начать расчёт.

Правильный вариант:

```
USD - RUB : 90
EUR - RUB : (USD - RUB) * 1.1
```

Циклы могут возникать и через алиасы. Проверяйте всю цепочку зависимостей.

## Дубликаты и конфликтующие записи

### Что считается одной парой

В пределах одного файла идентичность записи определяется:

* первой валютой;
* второй валютой;
* городом, если он указан.

Регистр и допустимые различия в оформлении нормализуются.

Поэтому записи:

```
USD - RUB : 90
usd-rub : 90
```

относятся к одной паре.

Пары с разными городами не считаются дубликатами.

### Одинаковые повторы

Полностью одинаковые определения могут быть объединены.

```
USD - RUB : 90
USD - RUB : 90
```

Однако для собственного файла лучше оставлять одно определение каждой пары. Это упрощает проверку и изменение данных.

### Разные определения

Если у одной пары разные определения, возникает конфликт:

```
USD - RUB : 90
USD - RUB : 91
```

Система не выбирает автоматически первую или последнюю строку как правильную.

Совпадение математического результата тоже не делает определения одинаковыми:

```
USD - RUB : 90
USD - RUB : 45 * 2
```

Различия в записи числа также могут создать конфликт:

```
USD - RUB : 90
USD - RUB : 90.0
```

При сравнении учитываются исходное выражение и значения `in/out`. Например, записи `in = 1, out = 90` и `in = 100, out = 9000` не следует дублировать для одной пары только потому, что их отношение одинаково.

{% hint style="warning" %}
Оставляйте одно однозначное определение пары.

Конфликтные определения исключаются из набора прямых значений. В TXT, CSV и JSON при наличии отдельной корректной обратной пары может сработать обратный пересчёт. Поэтому получение какого-либо результата не заменяет проверку и устранение дубликатов.
{% endhint %}

### Дубликаты в JSON

Не используйте повторяющиеся ключи для разных курсов:

```json
{
  "USD - RUB": "90",
  "USD - RUB": "91"
}
```

Для нескольких самостоятельных записей используйте разные пары или массив объектов с различающимися валютами либо городами.

Даже в массиве два разных определения одной нормализованной пары остаются конфликтом.

## Точность и округление

### Готовое число и выражение

Готовое десятичное значение и математическое выражение проходят разные пути обработки.

Например:

```
A - B : 0.123456789012345678
```

передаёт готовую десятичную строку.

А запись:

```
A - B : 1 / 3
```

требует арифметического вычисления. При стандартных настройках её результат:

```
0.333333333333
```

Для арифметических выражений применяется округление не более чем до 12 знаков после запятой, с учётом общей настройки точности системы.

Отношение `out / in` и обратный пересчёт могут использовать точность до 18 знаков после запятой.

Поэтому нельзя считать, что любой способ задания курса гарантирует одинаковую точность.

### Очень маленькие значения

Готовое число может пройти обработку, а равнозначное арифметическое выражение — округлиться до нуля.

Например:

```
A - B : 0.0000000000001
```

содержит готовое положительное значение.

Но вычисление:

```
A - B : 1 / 10000000000000
```

при округлении выражения до 12 знаков может дать ноль. Такой результат не используется как рабочий курс.

Проверка положительного курса выполняется с точностью до 18 знаков после запятой. Значения меньше `0.000000000000000001` не следует использовать как рабочие курсы.

Для очень маленьких или высокоточных значений передавайте заранее рассчитанную десятичную строку и проверяйте фактический результат.

### Точность JSON

Для длинных дробных значений используйте строки:

```json
{
  "A - B": "0.123456789012345678"
}
```

JSON-число без кавычек может потерять часть точности при декодировании:

```json
{
  "A - B": 0.123456789012345678
}
```

Строковая запись помогает сохранить исходное десятичное значение до дальнейшей обработки.

Если затем использовать это значение в арифметическом выражении, ограничения вычисления выражений всё равно действуют.

### Поле «Количество знаков после запятой»

В форме файловой пары есть поле **«Количество знаков после запятой»**.

В текущей обработке файлов оно не округляет загружаемый рабочий курс и не ограничивает значение, используемое направлением или формулой.

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

Если нужен определённый округлённый курс, подготовьте его в файле либо настройте соответствующий расчёт в разделе **«Курсы по формуле»**.

## Проверка и подключение подготовленного файла

### Порядок действий

{% stepper %}
{% step %}

#### Подготовьте содержимое

Выберите один формат и создайте файл по соответствующему примеру.

Проверьте названия пар, значения, зависимости и отсутствие конфликтующих определений.
{% endstep %}

{% step %}

#### Проверьте файл перед размещением

Убедитесь, что файл сохранён в UTF-8 и содержит текст выбранного формата.

Для CSV проверьте разделители и кавычки. Для JSON и XML — корректность всей структуры.

Заранее рассчитайте ожидаемые значения хотя бы для основных, обратных и производных пар.
{% endstep %}

{% step %}

#### Разместите файл

Опубликуйте его по прямой ссылке, доступной серверу обменного пункта.

Проверьте, что по адресу возвращается содержимое файла без перенаправления, страницы входа или HTML-ошибки.
{% endstep %}

{% step %}

#### Добавьте источник

Откройте **«Парсер курсов» — «Курсы из файла»**.

Нажмите **«Источники»**, затем **«Добавить источник»**. Укажите название, прямую ссылку и тип файла.

Нажмите **«Сохранить»** и убедитесь, что проверка источника завершилась успешно.
{% endstep %}

{% step %}

#### Добавьте необходимые пары

Нажмите **«Добавить пару»**, выберите источник и используйте **«Выбрать из доступных пар»** либо введите полное название.

Для городской пары укажите город. Для XML проверьте наличие именно запрошенного направления.
{% endstep %}

{% step %}

#### Сравните результат проверки

Дождитесь блока **«Проверка пары по файловому источнику»**.

Сравните найденную пару, исходные суммы или выражение и **«Сформированный курс»** с ожидаемым результатом.

Если показаны **«Доступные варианты»**, выберите нужную запись и дождитесь повторной проверки.
{% endstep %}

{% step %}

#### Сохраните и дождитесь рабочего обновления

Сохраните пару, установите нужный статус и дождитесь загрузки значения при автоматическом обновлении.

Предварительная проверка не записывает найденное значение в рабочий курс пары.

Проверьте сохранённое число в таблице.
{% endstep %}

{% step %}

#### Подключите курс к расчёту

Привяжите пару к направлению через поле **«Курс обмена из файла»** либо используйте её тег в формуле.

Проверьте фактически используемый источник в окне **«Формирование курса»** и расчёт направления на сайте.

Полный порядок привязки приведён в статье [«Курсы из файла»](https://docs.iexexchanger.com/guide/kursy/istochniki/kursy-iz-faila).
{% endstep %}
{% endstepper %}

### Что проверять при изменении файла

После изменения содержимого проверьте:

* пары, значения которых изменились;
* все выражения, зависящие от этих пар;
* прямые и обратные направления;
* записи с городами;
* формулы с процентами и функциями;
* отсутствие новых дубликатов;
* сохранение ожидаемой точности.

Смена названия пары во внешнем файле не переименовывает автоматически соответствующую запись в панели. Настройки нужно согласовать.

### Загрузка и скорость обработки

В штатном цикле обновления файл источника загружается для совместной обработки настроенных пар. Отдельная ссылка для каждой пары не требуется.

Предварительная проверка и открытие каталога являются отдельными обращениями за актуальными данными. Не считайте их частью одной гарантированно общей загрузки с фоновым обновлением.

Время обработки зависит от размера файла, количества записей и зависимостей, скорости источника и работы фоновых задач.

Фиксированного времени обработки для определённого количества строк нет.

## Ошибки подготовки данных

### Частые ошибки

| Ошибка                                                | Что происходит                                | Как исправить                                     |
| ----------------------------------------------------- | --------------------------------------------- | ------------------------------------------------- |
| Неправильный код пары                                 | Запись не распознаётся                        | Используйте допустимые коды длиной до 32 символов |
| Пропущено двоеточие в TXT                             | Не удаётся отделить пару от значения          | Запишите `USD - RUB : 90`                         |
| CSV разделён через `;`                                | Колонки не читаются в нужной структуре        | Используйте запятую                               |
| Запятая внутри CSV-значения без кавычек               | Значение разбивается на колонки               | Заключите ячейку в двойные кавычки                |
| `MAX(90,95)`                                          | Получается число 90.95 вместо двух аргументов | Запишите `MAX(90, 95)`                            |
| Пустое `rate` при расчёте CSV или JSON через `in/out` | Отношение сумм не используется как ожидается  | Уберите пустое поле курса                         |
| Произвольная обёртка JSON                             | Вложенные записи не извлекаются автоматически | Вынесите массив записей на верхний уровень        |
| Отсутствует обратная запись XML                       | Запрошенная пара не находится                 | Добавьте её явно                                  |
| Не указан город                                       | Не удаётся однозначно выбрать городской курс  | Используйте полное имя с городом                  |
| Разные определения одной пары                         | Возникает конфликт                            | Оставьте одно определение                         |
| Ссылка на отсутствующую пару                          | Зависимость не вычисляется                    | Добавьте исходную пару или исправьте имя          |
| Циклическая зависимость                               | Нет исходного значения для расчёта            | Разорвите цикл                                    |
| Деление на ноль                                       | Выражение не даёт допустимый курс             | Исправьте выражение                               |
| Неизвестная функция                                   | Выражение не поддерживается                   | Используйте доступные функции                     |
| Повреждён JSON или XML                                | Весь файл может быть отклонён                 | Исправьте структуру                               |
| В XML используется DTD                                | Файл отклоняется                              | Уберите DTD и передавайте готовые значения        |

### Ошибка отдельной пары и ошибка файла

Если проблема относится к одной записи или её выражению, остальные независимые корректные пары могут быть обработаны.

Если повреждена структура всего JSON или XML либо файл невозможно загрузить, проблема может затронуть весь источник.

Не рассчитывайте, что любая ошибочная строка будет незаметно пропущена без влияния на настроенные курсы.

### Почему в таблице остаётся старое число

При неудачном обновлении последнее сохранённое значение может остаться в записи пары. Одновременно система может считать источник ошибочным и не использовать его для расчёта.

Поэтому старое положительное число не подтверждает успешную обработку нового файла.

После исправления:

1. Повторите предварительную проверку нужной пары.
2. Убедитесь, что получено ожидаемое значение.
3. Дождитесь успешного фонового обновления.
4. Проверьте рабочее значение пары.
5. Проверьте связанные формулы и направления.
