3.1.6. Formát objednávky Taler#

Formát objednávky Taler popisuje JSON, který musí být odeslán do backendu obchodníka pro vytvoření objednávky. Je to prototyp, ze kterého backend obchodníka vytvoří skutečné smluvní podmínky.

Existují různé verze formátu objednávky; jsou podrobně popsány v Referenční příručce.

Poznámka

Finanční částky se vždy zadávají jako řetězec ve formátu "CURRENCY:DECIMAL_VALUE".

Tato část obsahuje přehled nejčastějších polí:

částka: Určuje celkovou částku, kterou má zákazník zaplatit obchodníkovi.

max_fee: Jedná se o maximální celkovou částku poplatků za vklad, kterou je obchodník ochoten zaplatit. Pokud zálohové poplatky za mince přesáhnou tuto částku, musí je zákazník zahrnout do celkové platby. Poplatek se zadává ve stejném formátu jako částka.

max_wire_fee: Maximální poplatek za převod akceptovaný obchodníkem (podíl zákazníka se vydělí koeficientem wire_fee_amortization a dále se sníží, pokud jsou poplatky za vklad nižší než max_fee). Pokud chybí, je výchozí hodnota nula.

wire_fee_amortization: Za kolik zákaznických transakcí očekává obchodník průměrnou amortizaci poplatků za bankovní převod? Pokud je poplatek za převod na burze vyšší než max_wire_fee, rozdíl se vydělí tímto číslem a vypočítá se očekávaný příspěvek zákazníka na poplatek za převod. Příspěvek zákazníka může být dále snížen o rozdíl mezi max_fee a součtem skutečných poplatků za vklad. Nepovinné, výchozí hodnota, pokud chybí, je 1. Nulové a záporné hodnoty jsou neplatné a jsou rovněž interpretovány jako 1.

pay_url: Která adresa URL přijímá platby. Toto je adresa URL, na kterou bude peněženka posílat mince.

fulfillment_url: Na kterou adresu URL má peněženka přejít, aby získala plnění, například HTML nebo PDF zakoupeného článku, systém sledování objednávek pro zásilky nebo jednoduchou lidsky čitelnou webovou stránku s informací o stavu smlouvy.

order_id: Alfanumerický identifikátor, který může obchodník libovolně definovat. Používá jej obchodník k jednoznačné identifikaci transakce.

shrnutí: Krátké, lidsky čitelné shrnutí smlouvy. Používá se při zobrazení smlouvy pouze na jednom řádku, například v historii transakcí zákazníka.
časové razítko: Čas vygenerování nabídky.

pay_deadline: Časové razítko času, do kterého chce obchodník, aby směnárna definitivně převedla peníze splatné z této smlouvy. Po uplynutí této lhůty burza shromáždí všechny vklady, u nichž je termín refund_deadline překročen, a provede za ně jednu velkou bankovní platbu. Částky budou zaokrouhleny dolů na jednotku bankovního převodu; pokud je celková částka stále nižší než jednotka bankovního převodu, nebude vyplacena.

refund_deadline: Časové razítko, do kterého je obchodník ochoten (a schopen) vrátit peníze za smlouvu pomocí Taleru. Všimněte si, že burza Taler bude držet platbu v úschově nejméně do tohoto termínu. Do této doby bude moci obchodník podepsat zprávu, která vyvolá vrácení peněz zákazníkovi. Po uplynutí této doby již nebude možné zákazníkovi peníze vrátit. Musí být menší než pay_deadline.

produkty

Sortiment výrobků, které se prodávají zákazníkovi. Každá položka obsahuje tuple s následujícími hodnotami:

popis: Popis produktu.
množství: Množství odesílaných položek. Může být uvedena jednotka (např. 1 kg) nebo pouze počet.
cena: Cena za množství jednotek tohoto produktu odeslaných do daného dodacího_místa. Všimněte si, že obvykle by součet všech cen měl dát dohromady celkovou částku zakázky, ale může se lišit v důsledku slev nebo proto, že jednotlivé ceny nejsou k dispozici.
product_id: Jedinečné ID produktu v katalogu obchodníka. Obecně může být zvoleno libovolně, protože má význam pouze pro obchodníka, ale mělo by to být číslo v rozsahu $[0,2^{51})$ .
daně: Mapa platných daní, které musí obchodník zaplatit. Označení je název daně, tj. DPH, daň z obratu nebo daň z příjmu, a hodnota je výše příslušné daně. Všimněte si, že jsou povoleny libovolné štítky, pokud slouží k identifikaci platného daňového režimu. Podrobnosti může upřesnit regulátor. Slouží k oznámení zákazníkovi, které daně hodlá obchodník zaplatit, a zákazník je může použít jako účtenku. Tyto informace budou pravděpodobně použity také při daňových kontrolách obchodníka.
delivery_date: Čas, do kterého má být výrobek doručen na delivery_location.
delivery_location: Tím by se měl v mapě locations objevit popisek, který určuje, kam má být položka doručena.

Hodnoty lze vynechat, pokud nejsou použitelné. Například pokud se nákup týká balíčku produktů, které nemají žádné individuální ceny nebo ID produktu, nemusí být ve smlouvě uveden údaj product_id nebo price. Podobně u virtuálních produktů dodávaných přímo prostřednictvím URI plnění neexistuje delivery_location.

obchodník

adresa: To by mělo v mapě locations zobrazit popisek určující, kde se obchodník nachází.
název: Mělo by se jednat o lidsky čitelný název podniku obchodníka.
jurisdikce: To by mělo v mapě místa uvést označení, pod kterou jurisdikcí má být tato smlouva rozhodována.

lokality

Asociativní mapa míst použitých v zakázce. Označení míst v této mapě lze libovolně zvolit a použít, kdykoli je místo požadováno v jiných částech smlouvy. Tímto způsobem, pokud je stejné místo požadováno vícekrát (například adresa firmy zákazníka nebo obchodníka), stačí jej uvést (a předat) pouze jednou a jinak se na něj lze odkazovat prostřednictvím štítku. Neúplný seznam atributů umístění je následující:

název: Jméno příjemce pro doručení, buď jméno firmy, nebo jméno osoby.
země: Název země pro doručení, jak je uveden na poštovní zásilce, např. „Francie“.
stát: Název státu pro doručení, jak je uveden na poštovní zásilce, např. „NY“.
region: Název oblasti pro doručení, jak je uveden na poštovní zásilce.
provincie: Název provincie pro doručení, jak je uveden na poštovní zásilce.
město: Název města pro doručení, jak je uveden na poštovní zásilce.
zip_code: PSČ pro doručení, které je uvedeno na poštovní zásilce.
ulice: Název ulice pro doručení, jak je uveden na poštovní zásilce.
street_number: Číslo ulice (číslo domu) pro doručení, jak je uvedeno na poštovní zásilce.

Poznámka

Místa nemusí uvádět všechna tato pole a mohou mít i další pole. Vykreslovače smluv musí vykreslovat alespoň výše uvedená pole a pole, která nechápou jako seznam klíč-hodnota, by měly vykreslovat.