Фрагмент курсов обмена

Этот фрагмент, может иметь любое название (определяется автором формата), и должен состоять из четырех различных фрагментов, последовательно вложенных друг в друга, образовывая в конечном итоге, такую иерархическую структуру:

Ниже, приведен пример такой иерархической структуры.

Ознакомиться со структурой этого фрагмента также можно и на конкретном примере.

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

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


Фрагмент с информацией о курсе обмена

Этот фрагмент содержит в себе всю информацию о конкретном курсе обмена. Он может содержать такие элементы:

in
(число) элемент курса;
out
(число) элемент курса;
amount
(число) элемент резерва;
in_fee
(комиссия) элемент комиссии;
out_fee
(комиссия) элемент комиссии;
in_min_amount
(число) элемент минимальной суммы обмена;
options
(массив) элемент признаков;
domains
(массив) элемент доменов.

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

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

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

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


Значения элементов по умолчанию

Значение по умолчанию используется тогда, когда оно явно не задано с помощью соответствующего элемента.

Значением по умолчанию для элементов in и out является 1, для options и domains это пустой массив, а для всех остальных элементов это 0.

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


Элементы курса

К таким элементам относятся in и out.

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

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

Эти элементы могут содержать значения только в двух форматах: числовом или формате зависимого курса.

Если элемент in или out содержит значение по умолчанию то, его необходимо удалить.


Формат числового курса

Курс в этом формате указывается в виде числа, которое должно быть больше или равно 1.

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

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

Если, в элементах курса необходимо указать значение меньше 1 то, это можно сделать, следуя такой инструкции:

  1. в элементе курса, который должен был содержать значение меньше 1, указываем 1;
  2. в другом элементе курса, указываем значение, которое является результатом деления 1 на значение курса меньше 1;
  3. выполняем округление в меньшую сторону до 6 знаков после точки (если это необходимо).

Например, нам необходимо указать такой курс: 0.0218 = 1 но, так указывать нельзя:

Применив инструкцию выше, мы решили поставленную задачу:

Что было сделано? Было выполнено деление 1 / 0.0218, а потом полученное число было округлено до 6 знаков после точки.


Формат зависимого курса

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

Сумма обмена, это такая сумма, которую отдает меняющий во время обмена.

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

Суммы обменов должны быть числами, больше или равными 0. Точность чисел, должна быть такая же, как и у значения элемента резерва.

Значения курса, должны соответствовать формату числового курса.

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

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


Элемент резерва

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

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

Например, резервы криптовалют 0.98761 и 0.98769 должны быть округлены до 0.9876.

Элементы комиссии

К таким элементам относятся in_fee и out_fee. Значения этих элементов должны быть указаны в соответствии с форматом комиссий.

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

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


Элемент минимальной суммы обмена

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

Точность значения у этого элемента такая же, как и у значения элемента резерва.


Элемент признаков

Признак, сообщает о какой-то особенности, присущей указанному обмену и отличающей его, от всех остальных обменов.

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

Названия признаков и их назначение перечислены в этом списке:

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

Элемент доменов

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

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

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


Фрагмент дополнительного режима обмена

Этот фрагмент содержит в себе всю информацию о дополнительном режиме обмена.

Основной режим обмена определяется на основании элемента признаков в фрагменте с информацией о курсе обмена. Если в нем указан признак manual то, основной режим обмена будет ручной либо полуавтоматический, а если не указан то автоматический.

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

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

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


Группировка элементов и фрагментов

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

Группировка элементов и фрагментов применяется только с целью оптимизации файла (уменьшения его объема).

Группировать можно только такие элементы из фрагмента с информацией о курсе обмена:

options
элементы признаков;
in_min_amount
элементы минимальной суммы обмена.

Оба этих элемента можно выносить на 3 уровень этого фрагмента (рядом с to), а вот элемент options, можно выносить еще и на 1 уровень (рядом с from).

После того, как элементы были сгруппированы и вынесены на верхние уровни, их необходимо удалить там, где они были до группировки.

Пример группировки можно увидеть в разделе группировки значений (оптимизация).


Пример

В примере указано 4 курса обмена:

  1. Курс обмена PMUSD на PMEUR в соотношении 1.0886 = 1. Обменять можно максимум 16.27 PMEUR. Обмен будет произведен в автоматическом режиме.
  2. Курс обмена PMUSD на YAMRUB в соотношении 1 = 58.1201. Обменять можно от 10 PMUSD до 23013.36 YAMRUB причем, из суммы получения (в YAMRUB) будет еще вычтено 0.5%. Обмен будет произведен в автоматическом режиме.
  3. Курс обмена SBERRUB на BTC в соотношении 100475.7578 = 1. Обменять можно от 3000 SBERRUB до 1.28 BTC причем, для совершения обмена необходимо будет пройти идентификацию (верификацию). Обмен будет произведен в ручном режиме.
  4. Курс обмена P24UAH на PMUSD в соотношении 26.3703 = 1. Обменять можно от 270 P24UAH до 3524.3 PMUSD в двух различных режимах, в автоматическом, с оплатой дополнительной комиссии 2% (P24UAH) или ручном, без дополнительной комиссии.