Курсы обмена

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

Направления обмена указываются в секции from (она обычно называется секцией направлений обмена). Перед этим, они должны быть сгруппированы по сигнатуре валюты, которую принимает сайт от пользователя. Сигнатура этой валюты будет использована в качестве названия для секции, которая в свою очередь будет находиться в секции from. Эта секция имеет название секции группы направлений обмена.

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

Ниже, приведен пример того, как в файле будут выглядеть два направления обмена:

  1. {
  2.   "from":
  3.   {
  4.     "PMUSD":
  5.     {
  6.       "to":
  7.       {
  8.         "YAMRUB": {...},
  9.         "PMEUR": {...}
  10.       }
  11.     }
  12.   }
  13. }

В примере выше, указано два направления обмена с использованием сигнатур валют вместо их названий. Указано такие направления:

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


Секция с информацией о направлении обмена

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

in
(число) сумма, которую должен отдать пользователь;
out
(число) сумма, которую получит пользователь;
amount
(число) резерв, максимальная сумма, которую сможет получить пользователь.

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

  1. {
  2.   "from":
  3.   {
  4.     "PMUSD":
  5.     {
  6.       "to":
  7.       {
  8.         "YAMRUB":
  9.         {
  10.           "in": 1,
  11.           "out": 47.5,
  12.           "amount": 52.58
  13.         },
  14.         "PMEUR":
  15.         {
  16.           "in": 1.27,
  17.           "out": 1,
  18.           "amount": 1710.97
  19.         }
  20.       }
  21.     }
  22.   }
  23. }

В примере выше, указано такие направления обмена:

Для первого направления указан такой курс: 1 (PMUSD) = 47.5 (YAMRUB) и резерв 52.58 YAMRUB. Для второго же направления соответственно указано такой курс: 1.27 (PMUSD) = 1 (PMEUR) и такой резерв 1710.97 PMEUR.

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

В этой секции может также содержаться и другая дополнительная информация, касающаяся направления обмена, а именно:

Не один из ключей этой секции, не является обязательным. Это означает, что, если какой-либо из ключей не указан то, считается, что он содержит значение по умолчанию. Ниже перечислен список ключей и их соответствующие значения по умолчанию, которые они принимают:


Резервы

Число, отвечающее за резерв, должно быть больше или равно 0.

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

Поскольку, значение резерва по умолчанию равняется 0 то, ключ с указанием резерва можно опустить.

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

В примере ниже, указано резервы для разных режимов, 10000 единиц валюты для скоростного режима и 25000 для экономного:

  1. {
  2.   "amount":
  3.   {
  4.     "fast": 10000.00,
  5.     "best": 25000.00
  6.   }
  7. }

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


Комиссии

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

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

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

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

В примере ниже указано оба вида комиссий:

  1. {
  2.   "in": 45.8715,
  3.   "out": 1,
  4.   "amount": 945.21,
  5.   "in_fee": 5,
  6.   "out_fee": "0.8%"
  7. }

Как видно из примера выше, пользователю нужно будет дополнительно заплатить 5 единиц валюты, вдобавок к основной сумме перевода. А из суммы получения, перед отправкой, будет вычтено 0.8%.

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

В примере ниже указано, что в скоростном режиме обмена, пользователю дополнительно необходимо будет перевести 2% от суммы обмена:

  1. {
  2.   "in_fee":
  3.   {
  4.     "fast": "2%"
  5.   }
  6. }

Минимальная сумма для совершения обмена

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

Для указания этого ограничения предусмотрен ключ in_min_amount, в качестве значения которого, указывается число, соответствующе минимально-допустимой для совершения обмена сумме.

В примере ниже указано, что обмен возможен только в том случае, если менять 10 и более единиц валюты:

  1. {
  2.   "in": 1,
  3.   "out": 45.8715,
  4.   "amount": 435098.03,
  5.   "in_min_amount": 10
  6. }

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


Свойства

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

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

На сегодняшний день распознаются такие константы:

manual
сообщает о том, что обмен в данном направлении осуществляется в ручном или полуавтоматическом режиме;
auth
сообщает о том, что для совершения обмена в данном направлении, необходимо предварительно авторизоваться или зарегистрироваться на сайте.

В примере ниже, указывается, что обмен будет доступен после авторизации на сайте и осуществлен вручную, оператором этого сайта:

  1. {
  2.   "options":
  3.   [
  4.     "manual", "auth"
  5.   ]
  6. }

Точность курса

Что бы курс обмена, указанный на сайте, точно совпадал с курсом, полученным после разбора файла необходимо, что бы значения ключей in и out были больше или равны 1.

Если, значение одного из ключей меньше 1 то, оно должно быть заменено на 1, а значение второго ключа, должно быть заменено на соответствующий ему эквивалент, согласно указанного курса для одной единицы валюты.

Например, такое указание курса недопустимо:

  1. {
  2.   "in": 0.0218,
  3.   "out": 1
  4. }

Правильно будет так:

  1. {
  2.   "in": 1,
  3.   "out": 45.8715
  4. }

С учетом того, что значение в in соответствует значению по умолчанию то, этот ключ можно опустить, тогда получим следующее:

  1. {
  2.   "out": 45.8715
  3. }

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

Точность чисел, отвечающих за курс, должна составлять 6 знаков после запятой, а округление должно выполняться в меньшую сторону.

Например, числа 1.2343671 и 1.23436799 должны быть округлены до 1.234367.

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


Указание нескольких курсов для одного направления обмена

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

Этот формат предусматривает изменение значений ключей in или out, они вместо чисел будут содержать секции. Содержимое этих секций зависит от того, какова причина указания различных курсов. На сегодняшний день секции могут содержать данные о таких курсах:

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


Указание курсов зависящих от суммы обмена

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

В примере ниже, отдельно указан курс для сумм меньше 100 и отдельно для 100 и более единиц валюты:

  1. {
  2.   "in": 1,
  3.   "out":
  4.   {
  5.     "0": 45.2361,
  6.     "100": 45.8715
  7.   }
  8. }

Как видно из примера выше, если сумма обмена будет менее 100 единиц валюты то, курс обмена будет составлять 1 = 45.2361, а если сумма обмена будет 100 и более единиц валюты то, курс соответственно будет составлять 1 = 45.8715.


Указание курсов зависящих от режима обмена

В данном случае, секция должна содержать всего два ключа, которые сообщают о режиме обмена, а именно:

fast
максимальная скорость обмена, но менее выгодный курс;
best
более выгодный курс но, большая длительность обмена.

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

В примере ниже, указано курсы для разных режимов обмена, в одном из которых, также еще указан курс для сумм меньше 100 и отдельно для 100 и более единиц валюты:

  1. {
  2.   "in": 1,
  3.   "out":
  4.   {
  5.     "fast": 45.133,
  6.     "best":
  7.     {
  8.       "0": 45.2361,
  9.       "100": 45.8715
  10.     }
  11.   }
  12. }

Как видно из примера выше, обмен может быть осуществлен или по более выгодному курсу или с большей скорость. Обмен в скоростном режиме осуществляется по курс 1 = 45.133, в другом же режиме, курс будет зависеть от суммы обмена. Так, если сумма обмена будет менее 100 единиц валюты то, курс обмена будет составлять 1 = 45.2361, а если сумма обмена будет 100 и более единиц валюты то, курс соответственно будет составлять 1 = 45.8715.

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