Валюты

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

  1. {
  2.   "currencies": {...}
  3. }

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


Псевдонимы сигнатур валют

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

Эта секция была введена исходя из следующих соображений:

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

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

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

В примере ниже, указано псевдонимы для двух сигнатур: WMZ и BTCE и одно направление обмена:

  1. {
  2.   "currencies":
  3.   {
  4.     "aliases":
  5.     {
  6.       "WMZ": "WMUSD",
  7.       "BTCE": "BTCEUSD"
  8.     }
  9.   },
  10.   "from":
  11.   {
  12.     "WMZ":
  13.     {
  14.       "to":
  15.       {
  16.         "BTCE": {...}
  17.       }
  18.     }
  19.   }
  20. }

Как видно из примера выше, для указания направления обмена, в качестве сигнатур валют использовались ключи псевдонимов, это: WMZ и BTCE.

Когда обработчик будет обрабатывать файл, чтобы определить валюты ему, вместо ключей псевдонимов, необходимо будет использовать соответствующие им сигнатуры псевдонимов тоесть, вместо WMZ использовать сигнатуру WMUSD, а вместо BTCE сигнатуру BTCEUSD.


Резервы валют

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

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

В примере ниже, указано резервы для валют с такими сигнатурами: PMUSD и YAMRUB:

  1. {
  2.   "amounts":
  3.   {
  4.     "PMUSD": 413.45,
  5.     "YAMRUB": 17138.98
  6.   }
  7. }

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

Например:

  1. {
  2.   "currencies":
  3.   {
  4.     "amounts":
  5.     {
  6.       "PMUSD": 413.45,
  7.       "YAMRUB": 17138.98
  8.     }
  9.   },
  10.   "from":
  11.   {
  12.     "YAMRUB":
  13.     {
  14.       "to":
  15.       {
  16.         "PMUSD": {...}
  17.       }
  18.     },
  19.     "PMUSD":
  20.     {
  21.       "to":
  22.       {
  23.         "YAMRUB": {...}
  24.       }
  25.     },
  26.     "P24UAH":
  27.     {
  28.       "to":
  29.       {
  30.         "PMUSD":
  31.         {
  32.           "amount": 2500.00
  33.         }
  34.       }
  35.     }
  36.   }
  37. }

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


Комиссии

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

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

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

В примере ниже, указано комиссии для валют с такими сигнатурами: P24UAH и QWRUB:

  1. {
  2.   "fees":
  3.   {
  4.     "P24UAH": "2%",
  5.     "QWRUB": "3.1%"
  6.   }
  7. }

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

Например:

  1. {
  2.   "currencies":
  3.   {
  4.     "fees":
  5.     {
  6.       "P24UAH": "2%"
  7.     }
  8.   },
  9.   "from":
  10.   {
  11.     "P24UAH":
  12.     {
  13.       "to":
  14.       {
  15.         "QWRUB": {...}
  16.       }
  17.     },
  18.     "QWRUB":
  19.     {
  20.       "to":
  21.       {
  22.         "P24UAH":
  23.         {
  24.           "out_fee": 0.5
  25.         }
  26.       }
  27.     }
  28.   }
  29. }

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


Зависимость комиссии от направления обмена

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

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

in
полностью соответствует ключу in_fee в секции с информацией о направлении обмена;
out
полностью соответствует ключу out_fee в секции с информацией о направлении обмена.

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

Например:

  1. {
  2.   "currencies":
  3.   {
  4.     "fees":
  5.     {
  6.       "P24UAH":
  7.       {
  8.         "in": "2%",
  9.         "out": 0.5
  10.       }
  11.     }
  12.   },
  13.   "from":
  14.   {
  15.     "P24UAH":
  16.     {
  17.       "to":
  18.       {
  19.         "QWRUB": {...}
  20.       }
  21.     },
  22.     "QWRUB":
  23.     {
  24.       "to":
  25.       {
  26.         "P24UAH": {...}
  27.       }
  28.     }
  29.   }
  30. }

Как видно из примера выше, в файле указано два направления обмена между валютами P24UAH и QWRUB в обоих направлениях, а также указана комиссия P24UAH в секции комиссий, в обоих направлениях. Так, во время перевода P24UAH пользователю нужно будет заплатить 2% комиссии, а во время перевода сайтом P24UAH пользователю, из суммы получения, перед ее переводом будут вычтены 50 копеек.