Формат фида

Экспортный файл курсов (ЭФК)

Ваш сервис публикует по постоянному URL XML-файл с курсами по направлениям — мы забираем его по расписанию и раскладываем по рейтингу и калькулятору. Формат — XML ЭФК BestChange. Уже листитесь там и отдаёте ЭФК? Подключение бесшовное, отдельный файл под нас не нужен.

Скачать образец XML Полное ТЗ (для печати)

Как это работает

Вы отдаёте по постоянному URL актуальный XML с курсами.
TopChange периодически (интервал — минуты) запрашивает файл методом GET, асинхронно, без участия вашего бэкенда в момент сделки.
Курсы валидируются и раскладываются по направлениям; резервы обновляются автоматически.
Файл недоступен или невалиден — берём последнее валидное состояние (degraded), повтор на следующем цикле. Сбой одного запроса данные не ломает.
Направления (для наличных — пары «направление + город»), исчезнувшие из файла, скрываются до повторного появления.
После 3 неудач подряд ответственному приходит уведомление.

Требования к эндпоинту

Метод	`GET`
Протокол	HTTPS (рекомендуется), допустим HTTP
Тип ответа	`application/xml`, UTF-8
Код ответа	`200 OK` при успехе
Аутентификация	не требуется — URL публично доступен
Стабильность URL	постоянный; смена согласуется отдельно
Таймаут	ответ укладывается в ~10 секунд
Размер	без жёсткого лимита; типовой файл — десятки–сотни item

Формат приёма один — XML ЭФК. JSON и другие форматы отклоняются (invalid_feed), офферы при этом не трогаются.

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

Корень — <rates>. Каждое направление — отдельный <item>. Курс задаётся парой in/out: in единиц from меняются на out единиц to, то есть курс = out / in.

<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <item>
    <from>USDTTRC20</from><to>SBERRUB</to>
    <in>1</in><out>96.20</out>
    <amount>4500000</amount>
    <frommin>1000</frommin><frommax>500000</frommax>
  </item>
  <item>
    <from>BTC</from><to>CASHRUB</to>
    <in>1</in><out>9450000</out>
    <amount>5000000</amount>
    <city>SPB</city>
  </item>
</rates>

Поля `<item>`

Тег	Обяз.	Значение
`from`	да	Код отдаваемого актива (что отдаёт клиент)
`to`	да	Код получаемого актива (что получает клиент)
`in`	да	Сколько единиц from за out единиц to. > 0. Обычно 1
`out`	да	Сколько единиц to за in единиц from. Курс = out/in
`amount`	да	Резерв в единицах валюты to
`frommin`	нет	Мин. сумма сделки в единицах from
`frommax`	нет	Макс. сумма сделки в единицах from
`city`	нет*	Только для наличных (to=CASHRUB): код города BestChange
`param`	нет	manual / juridical / verifying… Принимается, пока не используется
`fromfee / tofee`	нет	Комиссия стороны. Принимается, пока не используется

* Для to=CASHRUB тег <city> фактически обязателен: без него наличное направление не привяжется к городу. Незнакомые теги внутри <item> (напр. delay, tomin) файл не ломают — мы их игнорируем, так что полный ЭФК BestChange подходит целиком.

Коды активов и городов

Коды — из справочника BestChange, у нас они совпадают 1:1. Полные списки с пометкой, что уже создаёт направления, — в отдельных разделах:

Коды валют Коды городов

Программно свериться с тем, что мы принимаем прямо сейчас, удобно по машиночитаемому справочнику /feed-directory.json — там актуальные активы, активные города и все принимаемые направления (генерится из базы). Направление из фида учитывается, только если пара from→to есть в этом списке.

Типы направлений: продажа (крипта → рублёвый рельс), покупка (рельс → крипта, тогда in — рубли), наличные (крипта → CASHRUB + city), крипто-кросс (крипта → крипта). Пара, которой у нас пока нет в каталоге, тихо пропускается и видна в счётчике «пропущено» — добавится направление, строка начнёт учитываться сама.

Правила валидности

Два уровня — и ведут себя по-разному, это важно:

Битая строка → тихо пропускается

<item> без обязательного поля (from, to, in, out, amount) или с in ≤ 0 отбрасывается, остальной файл принимается.

Нарушение правила курса → отклоняется весь файл

Строка формально полная, но out ≤ 0, frommin > frommax или отрицательные amount/frommin/frommax — файл не проходит валидацию (invalid_feed), остаёмся на последнем валидном состоянии. Держите каждую строку корректной.

Числа — точка как разделитель, без разрядов и кавычек (96.20).
Пара from→to (для наличных — с учётом города) в файле уникальна.
<rates> содержит хотя бы один валидный <item>.

Чек-лист перед сдачей

☐URL отдаёт 200 и валидный XML ЭФК, Content-Type: application/xml; charset=utf-8.
☐Все from/to — коды из справочника BestChange; для наличных to=CASHRUB есть <city>.
☐У каждого <item> заполнены from, to, in, out, amount.
☐Курс out/in строго положительный; где есть лимиты — frommin ≤ frommax; числа с точкой.
☐<rates> непустой; пары (с учётом города) уникальны.
☐Файл обновляется с нужной частотой; ответ ≤ 10 секунд; URL публично доступен.
☐Проверили на нашем образце XML.

Полная версия ТЗ (включая миграцию со старого JSON-формата и поведение импорта) — в печатной версии ТЗ. Вопросы по интеграции — раздел «Как подключиться».