Формат XML-файла конкурента

Для работы модуля «Курсы конкурентов» необходимо предоставить ссылку на XML-файл, содержащий курсы валют и криптовалют.

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

XML-файл должен соответствовать установленной структуре, иначе система не сможет корректно обработать данные.

---

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

XML-файл должен соответствовать следующим требованиям:

Параметр	Значение
Формат файла	XML
Кодировка	UTF-8
Максимальный размер файла	2 МБ
Тип ссылки	Публичная HTTP или HTTPS ссылка
Доступность	Без авторизации
Редиректы	Не поддерживаются

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

Базовая структура XML

Каждая валютная пара должна быть размещена внутри элемента <item>.

Минимальный пример:

<?xml version="1.0" encoding="UTF-8"?>

<rates>
    <item>
        <from>BTC</from>
        <to>USDT</to>
        <in>1</in>
        <out>65000</out>
    </item>
</rates>

После обработки система получит курс: BTC - USDT = 65000

Обязательные поля

Каждый элемент <item> должен содержать четыре обязательных поля.

Поле	Описание
<from>	Код валюты, которую отдаёт клиент
<to>	Код валюты, которую получает клиент
<in>	Количество валюты отдаю
<out>	Количество валюты получаю

Что означают поля

Рассмотрим пример:

<item>
    <from>BTC</from>
    <to>USDT</to>
    <in>1</in>
    <out>65000</out>
</item>

Здесь:

Поле	Значение
From	BTC
To	USDT
In	1
Out	65000

Это означает: 1 BTC = 65000 USDT

Как рассчитывается курс

Система рассчитывает курс по формуле: Курс = Out ÷ In

Пример:

<item>
    <from>USD</from>
    <to>RUB</to>
    <in>100</in>
    <out>9000</out>
</item>

Расчёт: 9000 ÷ 100 = 90

Результат: USD - RUB = 90

Полноценный пример XML-файла

<?xml version="1.0" encoding="UTF-8"?>

<rates>
    <item>
        <from>BTC</from>
        <to>USDT</to>
        <in>1</in>
        <out>65000</out>
    </item>
    <item>
        <from>ETH</from>
        <to>USDT</to>
        <in>1</in>
        <out>3500</out>
    </item>
    <item>
        <from>USD</from>
        <to>RUB</to>
        <in>100</in>
        <out>9000</out>
    </item>
</rates>

После обработки система получит:

Пара	Курс
BTC - USDT	65000
ETH - USDT	3500
USD - RUB	90

Поддерживаемые коды валют

В кодах валют допускаются:

Тип	Пример
Латинские буквы	BTC
Цифры	RUB1
Подчёркивание	USDT_TRC20
Дефис	USDT-TRC20

Примеры корректных кодов:

<from>BTC</from>
<from>USDT_TRC20</from>
<from>RUB1</from>

Рекомендации по кодам валют

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

BTC
ETH
USDT
USDC
TRX
LTC
XRP
BNB
RUB
USD
EUR

или общепринятые обозначения платёжных систем:

SBERRUB
TCSBRUB
TRC20
ERC20
BEP20
TON

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

Несколько примеров

1

Bitcoin → USDT

<item>
    <from>BTC</from>
    <to>USDT</to>
    <in>1</in>
    <out>65000</out>
</item>

Результат: BTC - USDT = 65000

2

USD → RUB

<item>
    <from>USD</from>
    <to>RUB</to>
    <in>100</in>
    <out>9000</out>
</item>

Результат: USD - RUB = 90

3

RUB → USD

<item>
    <from>RUB</from>
    <to>USD</to>
    <in>9000</in>
    <out>100</out>
</item>

Результат: RUB - USD = 0.01111111

Что поддерживается

Возможность	Поддерживается
XML-файлы	Да
UTF-8	Да
Любое количество валютных пар	Да
HTTP-ссылки	Да
HTTPS-ссылки	Да
Десятичные числа	Да
Большие значения курсов	Да
Автоматический расчёт курса через In / Out	Да

Что не поддерживается

Возможность	Поддерживается
JSON-файлы	Нет
CSV-файлы	Нет
TXT-файлы	Нет
Защищённые ссылки с авторизацией	Нет
Локальные адреса сервера	Нет
Редиректы	Нет
Файлы более 2 МБ	Нет
Некорректный XML	Нет

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

1

Отсутствует поле From

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

<item>
    <to>USDT</to>
    <in>1</in>
    <out>65000</out>
</item>

Правильно:

<item>
    <from>BTC</from>
    <to>USDT</to>
    <in>1</in>
    <out>65000</out>
</item>

2

Отсутствует поле To

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

<item>
    <from>BTC</from>
    <in>1</in>
    <out>65000</out>
</item>

3

Значение In равно нулю

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

<item>
    <from>BTC</from>
    <to>USDT</to>
    <in>0</in>
    <out>65000</out>
</item>

В данном случае система не сможет выполнить расчёт курса.

4

Неверная кодировка

Файл должен использовать кодировку: UTF-8

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

Проверка XML перед подключением

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

Проверка	Результат
Файл открывается в браузере	Да
XML корректно отображается	Да
Присутствуют элементы <item>	Да
Указаны поля From, To, In и Out	Да
Размер файла менее 2 МБ	Да
Используется UTF-8	Да

Рекомендации

Для стабильной работы рекомендуется:

• использовать только прямые ссылки на XML;
• не изменять структуру файла после подключения;
• использовать стандартные коды валют;
• регулярно проверять доступность XML-файла;
• не превышать размер 2 МБ;
• использовать кодировку UTF-8;
• обновлять XML автоматически на стороне источника.