3.1.6. Формат заказа Талера#

The Taler order format describes the JSON that must be POSTed to the merchant backend to create an order. It is the prototype from which the merchant backend will create the actual contract terms.

There are different versions for order format; they are described in detail in the Reference manual.

Примечание

Финансовые суммы всегда указываются в виде строки в формате CURRENCY:DECIMAL_VALUE.

This section provides an overview of the most common fields:

сумма: Указывает общую сумму, которую клиент должен заплатить продавцу.

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

max_wire_fee: Максимальная комиссия за перевод средств, принимаемая торговцем (доля клиента, которая делится на коэффициент wire_fee_amortization, и далее уменьшается, если комиссия по депозиту ниже max_fee). По умолчанию, если отсутствует, равна нулю.

амортизация_комиссии: За какое количество транзакций клиента торговец рассчитывает в среднем амортизировать комиссию за перевод? Если комиссия биржи за перевод средств превышает max_wire_fee, разница делится на это число, чтобы вычислить ожидаемый вклад клиента в комиссию за перевод средств. В дальнейшем вклад клиента может быть уменьшен на разницу между max_fee и суммой фактических комиссий по вкладам. Необязательно, значение по умолчанию, если отсутствует, равно 1. Нулевые и отрицательные значения недействительны и также интерпретируются как 1.

pay_url: URL, принимающий платежи. Это URL, на котором кошелек будет размещать монеты.

fulfillment_url: На какой URL-адрес должен перейти кошелек, чтобы получить исполнение, например, HTML или PDF-файл купленной статьи, или систему отслеживания заказов на поставку, или простую человекочитаемую веб-страницу, указывающую на статус контракта.

идентификатор заказа: Буквенно-цифровой идентификатор, свободно определяемый торговцем. Используется продавцом для уникальной идентификации транзакции.

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

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

срок_возврата: Временная метка, до которой торговец готов (и может) произвести возврат средств по контракту с помощью Taler. Обратите внимание, что биржа Taler будет держать платеж в условном депонировании как минимум до этого срока. До этого времени торговец сможет подписать сообщение, чтобы инициировать возврат средств клиенту. По истечении этого времени возврат средств покупателю будет невозможен. Должно быть меньше, чем pay_deadline.

продукция

Массив товаров, которые продаются покупателю. Каждая запись содержит кортеж со следующими значениями:

описание: Описание товара.
количество: Количество отправляемых предметов. Можно указать единицу измерения (например, 1 кг) или просто количество.
цена: Цена за количество единиц данного товара, поставляемого в указанное место_доставки. Обратите внимание, что обычно сумма всех цен должна равняться общей сумме контракта, но она может отличаться из-за скидок или недоступности отдельных цен.
идентификатор товара: Уникальный идентификатор продукта в каталоге продавца. Может быть выбран произвольно, так как имеет значение только для продавца, но должен быть числом в диапазоне $[0,2^{51})$ .
налоги: Карта применимых налогов, которые должен уплатить продавец. Метка - это название налога, например НДС, налог с продаж или подоходный налог, а значение - сумма применимого налога. Обратите внимание, что допускаются произвольные обозначения, если они используются для идентификации применимого налогового режима. Детали могут быть указаны регулирующим органом. Эта информация используется для того, чтобы сообщить клиенту, какие налоги торговец намерен заплатить, и может быть использована клиентом в качестве квитанции. Эта информация также может быть использована при проведении налоговых проверок продавца.
дата доставки: Время, к которому товар должен быть доставлен в место_доставки.
место_доставки: Это должно дать метку в карте локаций, указывающую, куда будет доставлен предмет.

Значения могут быть опущены, если они неприменимы. Например, если покупка касается пакета продуктов, у которых нет индивидуальных цен или идентификаторов продуктов, product_id или price могут не указываться в контракте. Аналогично, для виртуальных продуктов, доставляемых напрямую через URI выполнения, не указывается место_доставки.

торговец

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

места

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

имя: Имя получателя для доставки, либо имя компании, либо имя человека.
страна: Название страны доставки, указанное на почтовом пакете, например, «Франция».
государство: Название штата, в который осуществляется доставка, как указано на почтовом пакете, например, «NY».
регион: Название региона доставки, указанное на почтовом отправлении.
Провинции: Название провинции, в которую осуществляется доставка, как указано на почтовом пакете.
город: Название города для доставки, как указано на почтовом пакете.
почтовый индекс: Почтовый индекс доставки, указанный на почтовой посылке.
улица: Название улицы для доставки, как на почтовом пакете.
номер_улицы: Номер улицы (номер дома) для доставки, указанный на почтовом пакете.

Примечание

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