3.1.6. Формат замовлення Taler#

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.

Примітка

Фінансові суми завжди вказуються у вигляді рядка у форматі "CURRENTY:DECIMAL_VALUE".

This section provides an overview of the most common fields:

кількість: Вказує загальну суму, яку покупець має сплатити продавцю.

max_fee: Це максимальна загальна сума комісійних, яку готовий сплатити продавець. Якщо комісія за зберігання монет перевищує цю суму, клієнт повинен включити її в загальну суму платежу. Комісія вказується в тому ж форматі, що і сума.

max_wire_fee: Максимальна комісія за переказ, яку приймає продавець (частка клієнта, яка ділиться на коефіцієнт wire_fee_amortization, і ще більше зменшується, якщо комісія за депозит нижча за max_fee). За замовчуванням, якщо відсутнє, дорівнює нулю.

амортизація_плати_за_передачу: За скільки клієнтських транзакцій продавець очікує в середньому амортизувати комісію за переказ? Якщо комісія за переказ перевищує max_wire_fee, різниця ділиться на це число, щоб обчислити очікуваний внесок клієнта в комісію за переказ. Внесок клієнта може бути додатково зменшений на різницю між max_fee і сумою фактичних комісій за депозит. Необов’язкове, значення за замовчуванням, якщо відсутнє - 1. Нульові та від’ємні значення є недійсними і також інтерпретуються як 1.

pay_url: На яку URL-адресу приймати платежі. Це адреса, на яку гаманець буде відправляти монети.

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

order_id: Буквено-цифровий ідентифікатор, який вільно визначається продавцем. Використовується продавцем для унікальної ідентифікації транзакції.

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

pay_deadline: Мітка часу, до якого продавець хоче, щоб біржа остаточно перевела гроші, належні за цим контрактом. Після закінчення цього терміну біржа об’єднає всі депозити, контракти за якими закінчилися після терміну_повернення_коштів, і виконає для них один великий банківський платіж. Суми будуть округлені до одиниці банківського переказу; якщо загальна сума все ще буде меншою за одиницю банківського переказу, вона не буде виплачена.

refund_deadline: Мітка часу, до якої продавець бажає (і може) відшкодувати кошти за контрактом з використанням Taler. Зверніть увагу, що біржа Taler буде утримувати платіж в ескроу принаймні до цього терміну. До цього часу продавець зможе підписати повідомлення, щоб ініціювати повернення коштів покупцеві. Після цього часу повернути кошти покупцеві буде вже неможливо. Має бути меншим за pay_deadline.

продукти

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

опис: Опис продукту.
кількість: Кількість товарів, що відправляються. Можна вказати одиницю виміру (наприклад, 1 кг) або просто кількість.
ціна: Ціна за кількість одиниць цього товару, що доставляється до вказаного місця_поставки. Зауважте, що зазвичай сума всіх цін повинна складати загальну суму контракту, але вона може відрізнятися через знижки або через те, що окремі ціни недоступні.
product_id: Унікальний ідентифікатор товару в каталозі продавця. Загалом може бути обраний довільно, оскільки має значення лише для продавця, але має бути числом у діапазоні $[0,2^{51})$ .
податки: Карта застосовних податків, які має сплатити продавець. Мітка - це назва податку, тобто ПДВ, податок з продажу або податок на прибуток, а значення - це сума податку, що підлягає сплаті. Зауважте, що дозволяється використовувати довільні позначки, якщо вони використовуються для ідентифікації застосовного податкового режиму. Деталі можуть бути визначені регулятором. Ця інформація використовується для того, щоб повідомити покупцеві, які податки продавець має намір сплатити, і може бути використана покупцем як квитанція. Ця інформація також може бути використана під час податкових перевірок продавця.
дата_поставки: Час, до якого товар має бути доставлений до місця_доставки.
місце_доставки: Це повинно призвести до появи мітки на мапі локації, яка вказує, куди буде доставлено товар.

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

купець

адреса: Це повинно призвести до появи мітки на карті місцезнаходження, яка вказує, де знаходиться продавець.
ім’я: Це повинно дати зрозумілу назву для бізнесу торговця.
юрисдикція: Це повинно призвести до появи позначки на карті «місцезнаходження» із зазначенням юрисдикції, відповідно до якої цей контракт має розглядатися в арбітражному суді.

локації

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

ім’я: Ім’я одержувача для доставки, або ім’я компанії, або ім’я фізичної особи.
країна: Назва країни доставки, вказана на поштовому пакеті, наприклад, «Франція».
стан: Назва штату для доставки, як зазначено на поштовому пакеті, наприклад, «NY».
регіон: Назва регіону доставки, вказана на поштовому пакеті.
провінції: Назва області для доставки, як зазначено на поштовому пакеті.
місто: Назва міста доставки, вказана на поштовому пакеті.
zip_code: Поштовий індекс для доставки, вказаний на поштовому пакеті.
вулиця: Назва вулиці для доставки, вказана на поштовому пакеті.
номер_вулиці: Номер вулиці (номер будинку) для доставки, вказаний на поштовому пакеті.

Примітка

Локації не зобов’язані вказувати всі ці поля, і вони також можуть мати додаткові поля. Рендери, що працюють за контрактом, повинні відображати принаймні перелічені вище поля, а поля, які вони не розуміють, повинні відображати у вигляді списку ключ-значення.