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

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

Формат замовлення Taler описує JSON, який необхідно відправити до бекенду продавця для створення замовлення. Це прототип, з якого бекенд продавця створить фактичні умови контракту.

Існують різні версії формату замовлення; вони детально описані в Довіднику.

Примітка

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

Цей розділ містить огляд найпоширеніших полів:

сума

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

max_fee

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

max_wire_fee

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

wire_fee_amortization

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

pay_url

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

fulfillment_url

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

order_id

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

підсумок

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

мітка часу

Час, в який було згенеровано пропозицію.

pay_deadline

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

refund_deadline

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

товари

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

опис

Опис продукту.

кількість

Кількість товарів, що відправляються. Можна вказати одиницю виміру (наприклад, 1 kg) або просто кількість.

ціна

Ціна за quantity одиниць цього товару, що доставляється до вказаного delivery_location. Зауважте, що зазвичай сума всіх цін повинна складати загальну суму контракту, але вона може відрізнятися через знижки або через те, що окремі ціни недоступні.

product_id

Унікальний ідентифікатор товару в каталозі продавця. Загалом може бути обраний довільно, оскільки має значення лише для продавця, але має бути числом у діапазоні

.

податки

Карта застосовних податків, які має сплатити продавець. Мітка - це назва податку, тобто ПДВ, податок з продажу або податок на прибуток, а значення - це сума податку, що підлягає сплаті. Зауважте, що дозволяється використовувати довільні позначки, якщо вони використовуються для ідентифікації застосовного податкового режиму. Деталі можуть бути визначені регулятором. Ця інформація використовується для того, щоб повідомити покупцеві, які податки продавець має намір сплатити, і може бути використана покупцем як квитанція. Ця інформація також може бути використана під час податкових перевірок продавця.

delivery_date

Час, до якого товар має бути доставлений до delivery_location.

delivery_location

Це повинно призвести до появи мітки на мапі locations, яка вказує, куди буде доставлено товар.

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

продавець
адреса

Це повинно призвести до появи мітки на карті locations, яка вказує, де знаходиться продавець.

назва

Це повинно дати зрозумілу назву для бізнесу торговця.

юрисдикція

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

локації

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

назва

Ім’я одержувача для доставки, або ім’я компанії, або ім’я фізичної особи.

країна

Назва країни доставки, вказана на поштовому пакеті, наприклад, «Франція».

штат

Назва штату для доставки, як зазначено на поштовому пакеті, наприклад, «NY».

регіон

Назва регіону доставки, вказана на поштовому пакеті.

провінція

Назва області для доставки, як зазначено на поштовому пакеті.

місто

Назва міста доставки, вказана на поштовому пакеті.

zip_code

Поштовий індекс для доставки, вказаний на поштовому пакеті.

вулиця

Назва вулиці для доставки, вказана на поштовому пакеті.

street_number

Номер вулиці (номер будинку) для доставки, вказаний на поштовому пакеті.

Примітка

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