3.1.6. A Taler rendelési formátum#

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.

Megjegyzés

A pénzügyi összegeket mindig karakterláncként kell megadni a "CURRENCY:DECIMAL_VALUE" formátumban.

This section provides an overview of the most common fields:

összeg: Megadja a vásárló által a kereskedőnek fizetendő teljes összeget.

max_fee: Ez a kereskedő által fizetni hajlandó betéti díjak maximális összege. Ha az érmék letéti díjai meghaladják ezt az összeget, akkor azt a vásárlónak bele kell számolnia a fizetés végösszegébe. A díj megadása az összeg esetében használt formátumban történik.

max_wire_fee: A kereskedő által elfogadott maximális átutalási díj (az ügyfél részesedését el kell osztani a wire_fee_amortization tényezővel, és tovább kell csökkenteni, ha a befizetési díjak a max_fee alatt vannak). Ha hiányzik, az alapértelmezett érték nulla.

wire_fee_amortizáció: Hány ügyféltranzakció során várhatóan átlagosan mennyi átutalási díj amortizálódik a kereskedőnél? Ha a tőzsdei átutalási díj a max_wire_fee fölött van, a különbséget el kell osztani ezzel a számmal, hogy kiszámítsuk a várható ügyfél hozzájárulását az átutalási díjhoz. Az ügyfél hozzájárulása tovább csökkenthető a max_díj és a tényleges befizetési díjak összege közötti különbséggel. Opcionális, alapértelmezett érték, ha hiányzik, 1. A nulla és a negatív értékek érvénytelenek és szintén 1-nek értelmezhetők.

pay_url: Melyik URL fogadja el a fizetéseket. Ez az az URL, ahol a pénztárca POSTolja az érméket.

fulfillment_url: Melyik URL-címre menjen a pénztárca a teljesítés megszerzéséhez, például egy megvásárolt cikk HTML- vagy PDF-formátumához, vagy egy rendeléskövető rendszerhez a szállításokhoz, vagy egy egyszerű, ember által olvasható weboldalhoz, amely a szerződés állapotát jelzi.

order_id: A kereskedő által szabadon meghatározható alfanumerikus azonosító. A kereskedő által a tranzakció egyedi azonosítására használt azonosító.

összefoglaló: A szerződés rövid, ember által olvasható összefoglalója. Akkor használandó, ha a szerződést csak egy sorban jeleníti meg, például az ügyfél tranzakciótörténetében.
időbélyegző: Az ajánlat létrehozásának időpontja.

pay_deadline: Annak az időpontnak az időbélyege, ameddig a kereskedő azt szeretné, hogy a tőzsde véglegesen átutalja az ebből a szerződésből származó pénzt. Ha ez a határidő lejár, a tőzsde összesíti az összes olyan betétet, ahol a szerződések a „refund_deadline”-on túl vannak, és egyetlen nagy átutalást hajt végre. Az összegeket az átutalási egységre kerekítjük; ha a teljes összeg még mindig az átutalási egység alatt van, akkor nem kerül kifizetésre.

refund_deadline: Időbélyeg, ameddig a kereskedő hajlandó (és képes) visszatérítést adni a szerződésért a Taler segítségével. Ne feledje, hogy a Taler cseréje legalább addig a határidőig letétben tartja a fizetést. Addig az időpontig a kereskedő képes lesz aláírni egy üzenetet, hogy kiváltsa a visszatérítést az ügyfélnek. Ezt követően már nem lesz lehetőség a vásárlónak visszatérítésre. Kisebbnek kell lennie, mint a pay_deadline.

termékek

A vásárlónak eladott termékek sorozata. Minden egyes bejegyzés egy tuple-t tartalmaz a következő értékekkel:

leírás: A termék leírása.
mennyiség: A szállítandó tételek mennyisége. Megadhat egy egységet (pl. 1 kg) vagy csak a darabszámot.
ár: A termék adott quantity egységének ára, amelyet az adott delivery_location re szállítanak. Vegye figyelembe, hogy általában az összes ár összegének ki kell adnia a szerződés teljes összegét, de ez eltérhet a kedvezmények miatt vagy azért, mert az egyes árak nem állnak rendelkezésre.
product_id: A termék egyedi azonosítója a kereskedő katalógusában. Általában szabadon választható, mivel csak a kereskedő számára van jelentősége, de a $[0,2^{51})$ tartományba eső számnak kell lennie.
adók: A kereskedő által fizetendő adók térképe. A címke az adó neve, azaz HÉA, forgalmi adó vagy jövedelemadó, az érték pedig az alkalmazandó adó összege. Megjegyzendő, hogy tetszőleges címkék megengedettek, amennyiben az alkalmazandó adórendszer azonosítására szolgálnak. A részleteket a szabályozó hatóság határozhatja meg. Ez arra szolgál, hogy a vásárlónak nyilatkozzon arról, hogy a kereskedő mely adókat kívánja megfizetni, és a vásárló nyugtaként használhatja. Az információt valószínűleg a kereskedőnél végzett adóellenőrzések során is felhasználják.
delivery_date: Az az időpont, amikorra a terméket a delivery_location helyre kell szállítani.
delivery_location: Ennek meg kell adnia egy címkét a locations térképen, amely meghatározza, hogy hova kell szállítani az elemet.

Az értékek elhagyhatók, ha nem alkalmazhatóak. Például, ha egy vásárlás olyan termékcsomagról szól, amelynek nincsenek egyedi árai vagy termékazonosítói, a product_id vagy az ár nem adható meg a szerződésben. Hasonlóképpen, a közvetlenül a teljesítési URI-n keresztül szállított virtuális termékek esetében nincs szállítási_hely.

kereskedő

cím:: Ennek egy címkét kell adnia a locations térképen, amely megadja, hogy hol található a kereskedő.
név: Ennek egy ember által olvasható nevet kell adnia a kereskedő vállalkozásának.
joghatóság: Ennek meg kell adnia egy címkét a helyszínek térképen, amely meghatározza azt a joghatóságot, amely szerint ezt a szerződést választottbírósági eljárás alá kell vonni.

helyszínek

A szerződésben használt helyszínek asszociatív térképe. A térképen szereplő helyek címkéi szabadon választhatók és használhatók, amikor a szerződés más részeiben egy helyre van szükség. Így ha ugyanarra a helyszínre többször is szükség van (például az ügyfél vagy a kereskedő üzleti címére), akkor azt csak egyszer kell feltüntetni (és továbbítani), és egyébként a címkén keresztül lehet rá hivatkozni. A hely attribútumok nem teljes körű listája a következő:

név: A címzett neve a kézbesítéshez, akár cégnév, akár személynév.
ország: A kézbesítendő ország neve, ahogyan az a postai csomagon szerepel, pl. „Franciaország”.
állam: A kézbesítendő állam neve, ahogyan az a postai csomagon szerepel, pl. „NY”.
régió: A kézbesítendő régió neve, ahogyan az a postai csomagon található.
tartományok: A kézbesítendő tartomány neve, ahogyan az a postai csomagon található.
város: A kézbesítendő város neve, ahogyan az egy postai csomagon található.
irányítószám: Postai irányítószám a kézbesítéshez, ahogyan az egy postai csomagon található.
utca: A kézbesítéshez használt utcanév, ahogyan az egy postai csomagon található.
street_number: A házszám (házszám) a kézbesítéshez, ahogyan az a postai csomagon található.

Megjegyzés

A helyszíneknek nem kötelező az összes ilyen mezőt megadniuk, és további mezők is lehetnek. A szerződéses renderelőknek legalább a fent felsorolt mezőket kell megjeleníteniük, és azokat a mezőket, amelyeket nem kulcs-érték listaként értelmeznek, meg kell jeleníteniük.