Формат XML-файла курсов обменника

1 Общие сведения

1.1. Мониторинг сам запрашивает XML-файл на сайте обменника и показывает направления из него. Формат совместим с форматом BestChange: подойдёт файл, который обменник уже отдаёт другим мониторингам, если коды в нём совпадают с нашими кодами.

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

1.3. Если файл в другом формате — напишите нам через форму обратной связи, обсудим.

2 Структура файла

Корневой элемент — <rates>. Каждое направление обмена описывается отдельным элементом <item>. Элементы, которых нет в этом описании, мониторинг пропускает.

<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <item>
    <from>BTC</from>
    <to>SBERRUB</to>
    <in>1</in>
    <out>6150000</out>
    <amount>5000000</amount>
    <minamount>0.001</minamount>
    <maxamount>1</maxamount>
  </item>
  <item>
    <from>USDTTRC20</from>
    <to>CASHUSD</to>
    <in>1.01</in>
    <out>1</out>
    <amount>50000</amount>
    <minamount>100</minamount>
    <maxamount>20000</maxamount>
    <city>MSK, SPB</city>
  </item>
</rates>

3 Обязательные элементы

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

Элемент	Что указывать
`from`	Код валюты, которую обменник принимает от клиента.
`to`	Код валюты, которую обменник отправляет клиенту.
`in`	Сколько валюты `from` отдаёт клиент.
`out`	Сколько валюты `to` получает клиент за эту сумму.
`amount`	Резерв валюты `to` — максимум, который может получить клиент.
`minamount`	Минимальная сумма обмена в валюте `from`. Если минимумов несколько — например, отдельно на приём и на выплату, — указывается наибольший.
`maxamount`	Максимальная сумма одного обмена в валюте `from`. Если ограничений несколько, указывается наименьшее.

4 Дополнительные элементы

Элемент	Что указывать
`fromfee`	Дополнительная комиссия, которая не входит в курс и берётся с суммы, переводимой клиентом обменнику. Число в валюте `from` или процент: `2.15`, `1%`.
`tofee`	Дополнительная комиссия с суммы, которую обменник переводит клиенту. Число в валюте `to` или процент.
`city`	Код города для направлений с наличными. Если условия в нескольких городах одинаковые, коды перечисляются через запятую.
`param`	Метки условий обмена через запятую. Список меток — на странице кодов. Неизвестную метку мониторинг пропускает, курс при этом показывается.
`floating`	Плавающий курс: на сколько минут фиксируется курс в заявке.
`delay`	Задержка проведения обмена в минутах.

5 Числа и форматы

5.1. Дробная часть отделяется точкой: 0.001. Число с запятой не принимается.

5.2. В in и out — только число: без пробелов между разрядами, обозначений валют и других символов.

5.3. Значения не могут быть отрицательными, курс (out / in) — больше нуля.

5.4. maxamount больше minamount.

5.5. Резерва хватает на минимальную заявку: minamount, пересчитанный по курсу в валюту to, не больше amount.

5.6. Комиссии fromfee и tofee — число или число со знаком %. Комиссия, которая съедает всю сумму обмена, делает курс недействительным.

5.7. Значение delay пишется вплотную к тегам: <delay>15</delay>. Пробел или перенос строки перед числом — частое следствие автоматического форматирования XML — делает курс недействительным.

6 Наличные и города

6.1. Направление с наличными — когда в паре есть код из раздела «Наличные» — обязательно содержит city. Без города курс не показывается.

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

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

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

7 Обновление и доступность

7.1. Мониторинг запрашивает файл раз в 30 секунд. Файл отражает изменения сразу: как только на сайте изменились курс, резерв, лимиты или условия обмена, файл отдаёт новые данные. Пересоздание по расписанию, например раз в минуту, не подходит. Подходит файл, который формируется при каждом запросе или пересоздаётся при каждом изменении данных.

7.2. Файл доступен постоянно — не меньше 99% времени. Сервер отвечает кодом 200. Защита от DDoS и проверки на роботов не должны блокировать запросы мониторинга к файлу: адреса для белого списка сообщаем при подключении.

7.3. Размер файла — не больше 15 МБ. Объявления DTD и XML-сущностей (<!DOCTYPE>, <!ENTITY>) в файле не допускаются.

7.4. Если файл не отвечает, отвечает не кодом 200, не разбирается как XML или превышает размер, обменник автоматически получает статус «Недоступен». Статус снимается сам, когда файл снова в порядке.

8 Перерыв в работе

8.1. Чтобы снять с показа все курсы, отдайте файл без элементов <item> или добавьте в <rates> элемент <error>. Обменник получает статус «Перерыв»: карточка остаётся на сайте, курсов в списках нет. Элемент <error> снимает с показа весь файл, даже если в нём есть направления.

8.2. Чтобы снять одно направление, уберите его <item> из файла. Если обменник работает по графику, направления на нерабочее время убираются из файла.

9 Почему курс не показан

Курс не попадает на сайт, если:

направление встречается в файле несколько раз — отбрасываются все его записи;
кода валюты нет в списке кодов мониторинга или валюта отключена для вашего обменника;
нарушено одно из требований к числам и форматам (раздел 5);
нарушено одно из требований к наличным и городам (раздел 6);
направление отключено для вашего обменника администрацией мониторинга;
курс заметно выбивается из курсов других обменников по направлению — такие значения отсекаются автоматически.

Если файл целиком не разбирается (раздел 7), не показывается ни один курс.

Если причина неясна, напишите нам через форму обратной связи: укажите домен обменника и направление.

10 Частые вопросы

Курс зависит от суммы обмена. Как передать ступенчатые курсы?

Ступенчатые курсы мониторинг не поддерживает. Передавайте курс, по которому обменник проведёт обмен на любой сумме от minamount до maxamount, — наименее выгодный для клиента.

У направления дневной лимит. Как его указать?

Уменьшайте резерв направления (amount) до остатка лимита на сегодня. Когда лимит исчерпан, уберите направление из файла.

Условия в разных городах отличаются. Что делать?

Опишите направление отдельным <item> для каждого города со своими курсом, резервом и лимитами. Список городов в одном <city> подходит, только когда условия совпадают.