3.1.6. Format zamówienia Taler#

Format zamówienia Taler opisuje JSON, który musi zostać przesłany POST do backendu sprzedawcy w celu utworzenia zamówienia. Jest to prototyp, z którego backend sprzedawcy utworzy rzeczywiste warunki umowy <https://docs.taler.net/core/api-merchant.html#the-contract-terms>`__.

Istnieją różne wersje formatu zamówienia; są one szczegółowo opisane w Podręczniku.

Informacja

Kwoty finansowe są zawsze określane jako ciąg znaków w formacie "CURRENCY:DECIMAL_VALUE".

Ta sekcja zawiera przegląd najczęściej używanych pól:

kwota: Określa całkowitą kwotę do zapłaty sprzedawcy przez klienta.

max_fee: Jest to maksymalna łączna kwota opłat depozytowych, które sprzedawca jest skłonny zapłacić. Jeśli opłaty depozytowe za monety przekroczą tę kwotę, klient musi uwzględnić ją w sumie płatności. Opłata jest określana przy użyciu tego samego formatu, co amount.

max_wire_fee: Maksymalna opłata za przelew akceptowana przez sprzedawcę (udział klienta podzielony przez współczynnik wire_fee_amortization i dodatkowo zmniejszony, jeśli opłaty za depozyt są niższe niż max_fee). Wartość domyślna w przypadku braku wynosi zero.

wire_fee_amortization: Przez ile transakcji klienta sprzedawca spodziewa się średnio zamortyzować opłaty za przelewy? Jeśli opłata za przelew giełdowy jest wyższa niż max_wire_fee, różnica jest dzielona przez tę liczbę, aby obliczyć oczekiwany wkład klienta w opłatę za przelew. Wkład klienta może zostać dodatkowo zmniejszony o różnicę między max_fee a sumą rzeczywistych opłat depozytowych. Opcjonalne, wartość domyślna w przypadku braku to 1. Wartości zerowe i ujemne są nieprawidłowe i również interpretowane jako 1.

pay_url: Który adres URL akceptuje płatności. Jest to adres URL, pod którym portfel będzie POST monet.

fulfillment_url: Na jaki adres URL powinien przejść portfel, aby uzyskać spełnienie, na przykład HTML lub PDF zakupionego artykułu, system śledzenia zamówień dla przesyłek lub prostą, czytelną dla człowieka stronę internetową wskazującą status umowy.

order_id: Alfanumeryczny identyfikator, dowolnie definiowany przez sprzedawcę. Używany przez sprzedawcę do jednoznacznej identyfikacji transakcji.

podsumowanie: Krótkie, czytelne dla człowieka podsumowanie umowy. Używane podczas wyświetlania umowy w jednym wierszu, na przykład w historii transakcji klienta.
znacznik czasu: Czas, w którym oferta została wygenerowana.

pay_deadline: Znacznik czasu, do którego sprzedawca chce, aby giełda ostatecznie przelała pieniądze należne z tego kontraktu. Po upływie tego terminu giełda połączy wszystkie depozyty, w przypadku których kontrakty przekroczyły refund_deadline i wykona dla nich jedną dużą płatność przelewem. Kwoty zostaną zaokrąglone w dół do jednostki przelewu; jeśli całkowita kwota jest nadal poniżej jednostki przelewu, nie zostanie wypłacona.

refund_deadline: Znacznik czasu, do którego sprzedawca chce (i może) dokonać zwrotu pieniędzy za umowę za pomocą Taler. Należy pamiętać, że giełda Taler zatrzyma płatność w depozycie co najmniej do tego terminu. Do tego czasu sprzedawca będzie mógł podpisać wiadomość, aby uruchomić zwrot pieniędzy klientowi. Po tym czasie zwrot pieniędzy klientowi nie będzie już możliwy. Musi być mniejszy niż pay_deadline.

produkty

Tablica produktów sprzedawanych klientowi. Każdy wpis zawiera krotkę z następującymi wartościami:

opis: Opis produktu.
ilość: Ilość przedmiotów do wysłania. Może określać jednostkę (np. 1 kg) lub tylko liczbę.
cena: Cena za ilość jednostek tego produktu wysłanych do danej lokalizacji dostawy. Należy pamiętać, że zazwyczaj suma wszystkich cen powinna sumować się do całkowitej kwoty kontraktu, ale może być inna ze względu na rabaty lub niedostępność poszczególnych cen.
product_id: Unikalny identyfikator produktu w katalogu sprzedawcy. Może być wybrany dowolnie, ponieważ ma znaczenie tylko dla sprzedawcy, ale powinien być liczbą z zakresu $[0,2^{51})$ .
podatki: Mapa obowiązujących podatków do zapłacenia przez sprzedawcę. Etykieta to nazwa podatku, tj. VAT, podatek od sprzedaży lub podatek dochodowy, a wartość to obowiązująca kwota podatku. Należy pamiętać, że arbitralne etykiety są dozwolone, o ile są używane do identyfikacji obowiązującego systemu podatkowego. Szczegóły mogą być określone przez organ regulacyjny. Służy to do zadeklarowania klientowi, jakie podatki sprzedawca zamierza zapłacić, i może być wykorzystane przez klienta jako pokwitowanie. Informacje te mogą być również wykorzystywane przez kontrole podatkowe sprzedawcy.
delivery_date: Czas, w którym produkt ma zostać dostarczony do delivery_location.
delivery_location: Powinno to dać etykietę na mapie locations, określającą gdzie przedmiot ma zostać dostarczony.

Wartości mogą zostać pominięte, jeśli nie mają zastosowania. Na przykład, jeśli zakup dotyczy pakietu produktów, które nie mają indywidualnych cen lub identyfikatorów produktów, product_id lub price mogą nie być określone w umowie. Podobnie, w przypadku produktów wirtualnych dostarczanych bezpośrednio przez URI realizacji, nie ma delivery_location.

kupiec

adres: Powinno to dać etykietę na mapie locations, określającą gdzie znajduje się sprzedawca.
nazwa: Powinna to być czytelna dla człowieka nazwa firmy sprzedawcy.
jurysdykcja: Powinno to dać etykietę na mapie locations, określającą jurysdykcję, zgodnie z którą ten kontrakt ma być arbitrażowany.

lokalizacje

Mapa asocjacyjna lokalizacji używanych w umowie. Etykiety dla lokalizacji na tej mapie mogą być dowolnie wybierane i używane za każdym razem, gdy lokalizacja jest wymagana w innych częściach umowy. W ten sposób, jeśli ta sama lokalizacja jest wymagana wiele razy (np. adres biznesowy klienta lub sprzedawcy), musi być wymieniona (i przesłana) tylko raz, a w przeciwnym razie można się do niej odwoływać za pomocą etykiety. Niewyczerpująca lista atrybutów lokalizacji jest następująca:

nazwa: Nazwa odbiorcy dostawy, nazwa firmy lub osoby.
kraj: Nazwa kraju dostawy, znajdująca się na paczce pocztowej, np. „Francja”.
stan: Nazwa stanu dostawy, taka jak na paczce pocztowej, np. „NY”.
region: Nazwa regionu dostawy, taka jak na paczce pocztowej.
prowincje: Nazwa prowincji dostawy, znajdująca się na paczce pocztowej.
miasto: Nazwa miasta dostawy, znajdująca się na paczce pocztowej.
zip_code: Kod pocztowy dostawy, znajdujący się na paczce pocztowej.
ul.: Nazwa ulicy dla dostawy, jak na paczce pocztowej.
street_number: Numer ulicy (numer domu) dla dostawy, znajdujący się na paczce pocztowej.

Informacja

Lokalizacje nie muszą określać wszystkich tych pól, a także mogą mieć dodatkowe pola. Programy renderujące umowy muszą renderować co najmniej pola wymienione powyżej i powinny renderować pola, których nie rozumieją jako listę klucz-wartość.