3.1.6. A Taler rendelési formátum#

A Taler megrendelési formátum leírja azt a JSON-t, amelyet a kereskedői háttértárra kell POST-olni a megrendelés létrehozásához. Ez az a prototípus, amelyből a kereskedő backend létrehozza a tényleges „szerződési feltételeket <https://docs.taler.net/core/api-merchant.html#the-contract-terms>”.

A rendelésformátumnak különböző változatai vannak; ezeket részletesen a <https://docs.taler.net/core/api-merchant.html#tsref-type-Order>`__ referencia kézikönyvben ismertetjük.

Megjegyzés

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

Ez a szakasz áttekintést nyújt a leggyakoribb mezőkről:

ö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.