Формат экспортного файла курсов (XML)

Эта страница описывает единый формат экспортного XML‑файла курсов для мониторинга kassir.io. При добавлении обменного пункта необходимо предоставить публичную ссылку на этот файл на вашем сайте.

Ключевые принципы

• Протокол: XML или JSON.
• Частота опроса мониторингом: каждые 10 секунд.
• Актуальность данных: файл в любой момент должен отражать фактические курсы/резервы/комиссии на сайте обменника.
• Числовые значения: только числа с десятичной точкой (например, 1234.56), без суффиксов валют (RUB, USDT и т. п.). Валюта берётся из полей <from>/<to>.
• Кодировки валют/сетей: используются фиксированные коды (см. ниже список; при необходимости расширяем по согласованию).

Структура XML

• Корневой элемент: <rates>
• Каждое направление — элемент <item> с полями ниже.
• Рекомендуется начинать каждый <item> с новой строки (перенос \n).

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

1. <from> — код отдаваемой валюты/сети.
2. <to> — код получаемой валюты/сети.
3. <in> — сколько клиент отдаёт (в валюте from).
4. <out> — сколько клиент получает (в валюте to).
5. <amount> — текущий резерв по валюте to.
6. <minamount> — минимально возможная сумма к обмену (в валюте from), число без суффикса.
7. <maxamount> — максимально возможная сумма на одну заявку (в валюте from), число без суффикса.

Запрещено: элемент <minfee> (не поддерживается и не должен присутствовать).

Дополнительные поля <item>

• <fromfee> / <tofee> — дополнительные комиссии, не входящие в курс.
  • Могут повторяться в пределах одного <item> (до четырёх видов суммарно).
  • Значение с % — процент; значение без знака — фиксированная сумма.
  • Применяются все указанные комиссии.
• <floating> — признак плавающего курса (значение 1 или true).
• <delay> — возможная задержка обработки в минутах (число).
• <param> — список меток через запятую (см. полный справочник ниже).
• <city> — код(ы) города для направлений с наличными. Допускаются несколько кодов через запятую.
• <deliveryfee> — стоимость курьерской доставки (см. метку delivery ниже). Валюта — по умолчанию to. 0 означает «включена в курс».

Плавающий курс — требования витрины

Если курс в заявке фиксируется менее чем на 30 минут, обязательно:

• указать <floating>1</floating> и соответствующую метку (см. ниже),
• на сайте обменника явно описать:
  • условия, при которых курс может измениться;
  • условия, при которых средства считаются полученными обменным пунктом;
  • название биржи/индекса, на основании которых формируется курс;
  • максимальную величину изменения получаемой суммы.

Как обновлять экспорт

Cron раз в минуту недостаточно. Подходит один из вариантов:

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

Комиссии, которые должны быть учтены в курсах

1. Все затраты на отправку средств со стороны обменного пункта (включительно с комиссиями сети/банка выдачи).
2. Затраты на отправку со стороны клиента, за исключением внутриПС‑комиссий, если оплата идёт внутри той же ПС (их можно вынести в fromfee/tofee).

Ступенчатые курсы

Ступенчатые/брекетные курсы не поддерживаются. Передавайте курс с максимальным для клиента процентом (наихудшим для клиента вариантом) в пределах лимитов.

Список используемых меток в мониторинге kassir.io

Описание применяемых в мониторинге меток. На всех направлениях, имеющих особенности, соответствующие описанию меток, метки обязательны. Их можно передать через XML или выставить вручную.

• Плавающий курс обмена — «Курс обмена не фиксируется в заявке. Сумма обмена может измениться на момент отправки средств клиенту.»
  • Технически: <floating>1</floating> и метка попадёт в интерфейс автоматически.
  • Требования к содержимому сайта: см. раздел «Плавающий курс — требования витрины».
• Дополнительная комиссия — может включать до 4 типов, влияющих на итог:
  • доп. комиссия с отдаваемой валюты (в процентах);
  • доп. комиссия с получаемой валюты (в процентах);
  • доп. комиссия с отдаваемой валюты (фикс. значение);
  • доп. комиссия с получаемой валюты (фикс. значение).

  Технически задаются через повторяющиеся элементы <fromfee>/<tofee>.

• Ручной обмен (manual) — «Обменный пункт работает в ручном режиме.»
• Приём на стороннюю ПС (otherin) — «Реквизиты для перевода могут не соответствовать ПС, с которой пользователь платит.»
  Требование: все затраты клиента должны быть учтены в курсе или через fromfee.
• Выплата со сторонней ПС (otherout) — «ПС, соответствующая валюте выплаты, отличается от ПС, через которую обменник реально платит.»
• Отсутствует офис в городе (delivery) —
  • «Нет офиса в выбранном городе, средства доставляет курьер. Стоимость доставки включена в курс обмена.»
  • или «Нет офиса… Стоимость доставки: (число из поля deliveryfee).»
  • Если <deliveryfee>0</deliveryfee>, в интерфейсе будет «Стоимость доставки включена в курс».
• Верификация документов (verifying) — «При обмене может потребоваться верификация документов и личности.»
  Примечание: опечатка veryfying при импорте нормализуется к verifying.
• Верификация карты (cardverify) — «Для обмена требуется верификация карты.»
• Обязательная регистрация (reg) — «Для создания заявки требуется регистрация на сайте.»
• Кошелёк с функцией обмена (wallet) — «Онлайн‑кошелёк с функцией обмена.»
• Переводы от юрлица (juridical) — «Переводы осуществляются со счёта юрлица или ИП.»
• Задержка при приёме средств — задаётся числом минут в <delay>; при наведении в UI показываем время задержки.
• Анонимный обмен (anon) — «Не требуются личные данные, верификация карты и личности.»
  Примечание: anonim нормализуется к anon.
• Политика AML (aml) — «Блокируем средства с площадок, связанных с незаконной деятельностью, отмыванием денежных средств и финансированием терроризма.»

Справочники

Коды городов (наличные)

Коды электронных валют/сетей

Примеры

Пример 1 — плавающий курс, несколько комиссий, верификация и регистрация

<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <item>
    <from>USDTERC20</from>
    <to>BTC</to>
    <in>28990.0000</in>
    <out>1</out>
    <amount>8.30510473</amount>

    <fromfee>1.5%</fromfee>
    <fromfee>2.00</fromfee>
    <tofee>0.0002</tofee>

    <minamount>150.00</minamount>
    <maxamount>6000.00</maxamount>

    <floating>1</floating>
    <param>verifying,reg</param>
  </item>
</rates>

Пример 2 — наличные, доставка по городу, задержка

<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <item>
    <from>USDTTRC20</from>
    <to>CASHRUB</to>
    <in>1</in>
    <out>80.2005</out>
    <amount>154468024.3405</amount>

    <minamount>4000.00</minamount>
    <maxamount>1000000.00</maxamount>

    <city>MSK</city>
    <param>delivery</param>
    <deliveryfee>0</deliveryfee>
    <delay>30</delay>
  </item>
</rates>

Пример 3 — сторонние ПС на входе/выходе и ручной режим

<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <item>
    <from>USDTPOLYGON</from>
    <to>ETH</to>
    <in>3150.0000</in>
    <out>1</out>
    <amount>120.50000000</amount>

    <fromfee>0.8%</fromfee>
    <tofee>0.0035</tofee>

    <minamount>100.00</minamount>
    <maxamount>25000.00</maxamount>

    <param>manual,otherin,otherout</param>
  </item>
</rates>