3.1.6. Formát objednávky Taler#

Formát objednávky Taler opisuje JSON, ktorý sa musí odoslať do backendu obchodníka, aby sa vytvorila objednávka. Je to prototyp, z ktorého backend obchodníka vytvorí skutočné zmluvné podmienky.

Existujú rôzne verzie formátu objednávky; sú podrobne opísané v Referenčnej príručke.

Poznámka

Finančné sumy sa vždy zadávajú ako reťazec vo formáte "CURRENCY:DECIMAL_VALUE".

Táto časť obsahuje prehľad najbežnejších polí:

suma: Určuje celkovú sumu, ktorú má zákazník zaplatiť obchodníkovi.

max_fee: Ide o maximálnu celkovú sumu poplatkov za vklad, ktorú je obchodník ochotný zaplatiť. Ak zálohové poplatky za mince presiahnu túto sumu, zákazník ju musí zahrnúť do celkovej sumy platby. Poplatok sa uvádza v rovnakom formáte, aký sa používa pre sum.

max_wire_fee: Maximálny poplatok za prevod akceptovaný obchodníkom (podiel zákazníka sa vydelí koeficientom wire_fee_amortization a ďalej sa zníži, ak sú poplatky za vklad nižšie ako max_fee). Ak chýba, predvolená hodnota je nula.

wire_fee_amortization: V priebehu koľkých zákazníckych transakcií očakáva obchodník priemernú amortizáciu poplatkov za prevod? Ak je poplatok za prevod na burze vyšší ako max_wire_fee, rozdiel sa vydelí týmto číslom, aby sa vypočítal očakávaný príspevok zákazníka na poplatok za prevod. Príspevok zákazníka sa môže ďalej znížiť o rozdiel medzi číslom max_prevodného poplatku a súčtom skutočných poplatkov za vklad. Nepovinné, predvolená hodnota, ak chýba, je 1. Nulové a záporné hodnoty sú neplatné a tiež sa interpretujú ako 1.

pay_url: Ktorá adresa URL prijíma platby. Toto je adresa URL, na ktorú bude peňaženka posielať mince.

fulfillment_url: Na ktorú adresu URL má peňaženka prejsť, aby získala plnenie, napríklad HTML alebo PDF zakúpeného článku, systém sledovania objednávok pre zásielky alebo jednoduchú ľudsky čitateľnú webovú stránku s informáciou o stave zmluvy.

order_id: Alfanumerický identifikátor, ktorý môže obchodník voľne definovať. Používa ho obchodník na jednoznačnú identifikáciu transakcie.

zhrnutie: Krátke, ľudsky čitateľné zhrnutie zmluvy. Používa sa pri zobrazovaní zmluvy len v jednom riadku, napríklad v histórii transakcií zákazníka.
časová pečiatka: Čas, kedy bola ponuka vygenerovaná.

pay_deadline: Časová pečiatka času, do ktorého chce obchodník, aby burza definitívne previedla peniaze splatné z tejto zmluvy. Po uplynutí tohto termínu burza spojí všetky vklady, pri ktorých už uplynula lehota refund_deadline, a vykoná za ne jednu veľkú bankovú platbu. Sumy sa zaokrúhlia nadol na jednotku bankového prevodu; ak je celková suma stále nižšia ako jednotka bankového prevodu, nebude vyplatená.

refund_deadline: Časová pečiatka, do ktorej je obchodník ochotný (a schopný) vrátiť peniaze za zmluvu pomocou Taleru. Upozorňujeme, že burza Taler bude držať platbu v úschove minimálne do tohto termínu. Do tohto času bude môcť obchodník podpísať správu, ktorá vyvolá vrátenie peňazí zákazníkovi. Po tomto čase už nebude možné zákazníkovi vrátiť peniaze. Musí byť menšia ako pay_deadline.

produkty

Sortiment výrobkov, ktoré sa predávajú zákazníkovi. Každá položka obsahuje tuple s nasledujúcimi hodnotami:

popis: Popis výrobku.
množstvo: Množstvo položiek, ktoré sa majú odoslať. Môže uvádzať jednotku (napr. 1 kg) alebo len počet.
cena: Cena za množstvo jednotiek tohto produktu dodaných na dané dodacie_miesto. Všimnite si, že zvyčajne by sa súčet všetkých cien mal rovnať celkovej sume zákazky, ale môže sa líšiť v dôsledku zliav alebo preto, že jednotlivé ceny nie sú k dispozícii.
product_id: Jedinečné ID výrobku v katalógu obchodníka. Vo všeobecnosti môže byť zvolené ľubovoľne, pretože má význam len pre obchodníka, ale malo by to byť číslo v rozsahu $[0,2^{51})$ .
dane: Mapa platných daní, ktoré má zaplatiť obchodník. Označenie je názov dane, t. j. DPH, daň z obratu alebo daň z príjmu, a hodnota je výška uplatniteľnej dane. Upozorňujeme, že ľubovoľné označenia sú povolené, pokiaľ sa používajú na identifikáciu platného daňového režimu. Podrobnosti môže špecifikovať regulačný orgán. Slúži na vyhlásenie zákazníkovi, ktoré dane má obchodník v úmysle zaplatiť, a zákazník ho môže použiť ako potvrdenie. Tieto informácie sa pravdepodobne použijú aj pri daňových kontrolách obchodníka.
delivery_date: Čas, do ktorého má byť výrobok doručený na delivery_location.
delivery_location: Tým by sa mal v mape locations vytvoriť štítok, ktorý určí, kam sa má položka doručiť.

Hodnoty sa môžu vynechať, ak nie sú použiteľné. Ak sa napríklad nákup týka balíka produktov, ktoré nemajú individuálne ceny alebo ID produktu, v zmluve sa nemusí uvádzať product_id ani price. Podobne v prípade virtuálnych produktov dodávaných priamo prostredníctvom URI plnenia neexistuje delivery_location.

obchodník

adresa: Týmto by sa mal v mape locations objaviť štítok, ktorý špecifikuje, kde sa obchodník nachádza.
názov: Malo by ísť o ľudsky čitateľný názov podniku obchodníka.
jurisdikcia: Týmto by sa v mape miesta malo uviesť označenie jurisdikcie, pod ktorou sa má táto zmluva rozhodovať.

lokality

Asociatívna mapa miest použitých v zmluve. Označenia pre miesta v tejto mape možno ľubovoľne vyberať a používať vždy, keď sa miesto vyžaduje v iných častiach zmluvy. Takto, ak sa to isté miesto vyžaduje viackrát (napríklad adresa podniku zákazníka alebo obchodníka), stačí ho uviesť (a preniesť) len raz a inak sa naň možno odvolať prostredníctvom štítku. Neúplný zoznam atribútov umiestnenia je nasledovný:

názov: Názov príjemcu pre doručenie, buď obchodné meno, alebo meno osoby.
krajina: Názov krajiny doručenia, ako je uvedený na poštovom balíku, napr. „Francúzsko“.
štát: Názov štátu doručenia, ako je uvedený na poštovom balíku, napr. „NY“.
región: Názov regiónu pre doručenie, ako sa nachádza na poštovom balíku.
provincie: Názov provincie, do ktorej sa má zásielka doručiť, ako sa uvádza na poštovom balíku.
mesto: Názov mesta na doručenie, ako sa nachádza na poštovom balíku.
poštové_predčíslie: PSČ pre doručenie, ako je uvedené na poštovom balíku.
ulica: Názov ulice na doručenie, ako sa nachádza na poštovom balíku.
street_number: číslo ulice (číslo domu) na doručenie, ako je uvedené na poštovej zásielke.

Poznámka

Lokality nemusia uvádzať všetky tieto polia a môžu mať aj ďalšie polia. Vykresľovače zmlúv musia vykresľovať aspoň uvedené polia a polia, ktorým nerozumejú, by mali vykresľovať ako zoznam kľúč-hodnota.