3.1.6. Das Taler-Format für Aufträge#

Das Taler-Bestellformat beschreibt das JSON, das an das Händler-Backend gepostet werden muss, um eine Bestellung zu erstellen. Es ist der Prototyp, aus dem das Händler-Backend die eigentlichen „Vertragsbedingungen <https://docs.taler.net/core/api-merchant.html#the-contract-terms>“ erstellen wird.

Es gibt verschiedene Versionen für das Auftragsformat; sie sind im Referenzhandbuch ausführlich beschrieben.

Bemerkung

Finanzbeträge werden immer als String im Format "WÄHRUNG:DEZIMAL_WERT" angegeben.

Dieser Abschnitt gibt einen Überblick über die gängigsten Felder:

Betrag: Gibt den Gesamtbetrag an, den der Kunde an den Händler zu zahlen hat.

max_fee: Dies ist der maximale Gesamtbetrag der Einzahlungsgebühren, den der Händler zu zahlen bereit ist. Wenn die Einzahlungsgebühren für die Münzen diesen Betrag übersteigen, muss der Kunde sie in die Gesamtsumme der Zahlung einrechnen. Die Gebühr wird in demselben Format angegeben wie Betrag.

max_wire_fee: Maximale vom Händler akzeptierte Überweisungsgebühr (der Kundenanteil wird durch den Faktor wire_fee_amortization geteilt und weiter reduziert, wenn die Einzahlungsgebühren unter max_fee liegen). Der Standardwert ist Null, wenn er fehlt.

draht_gebühren_amortisation: Über wie viele Kundentransaktionen rechnet der Händler damit, die Überweisungsgebühren im Durchschnitt zu amortisieren? Liegt die Überweisungsgebühr der Börse über der max_wire_fee, wird die Differenz durch diese Zahl geteilt, um den erwarteten Beitrag des Kunden zur Überweisungsgebühr zu berechnen. Der Beitrag des Kunden kann weiter um die Differenz zwischen max_fee und der Summe der tatsächlichen Einzahlungsgebühren reduziert werden. Optional, Standardwert bei Fehlen ist 1. Nullen und negative Werte sind ungültig und werden ebenfalls als 1 interpretiert.

pay_url: Welche URL Zahlungen annimmt. Dies ist die URL, unter der die Wallet Münzen POSTEN wird.

fulfillment_url: Zu welcher URL soll die Wallet gehen, um die Erfüllung zu erhalten, z. B. die HTML- oder PDF-Datei eines gekauften Artikels oder ein System zur Auftragsverfolgung für Sendungen oder eine einfache, von Menschen lesbare Webseite, die den Status des Vertrags angibt.

order_id: Alphanumerische Kennung, die vom Händler frei definiert werden kann. Wird vom Händler zur eindeutigen Identifizierung der Transaktion verwendet.

Zusammenfassung: Kurze, für den Menschen lesbare Zusammenfassung des Vertrags. Zu verwenden, wenn der Vertrag in nur einer Zeile angezeigt werden soll, z. B. in der Transaktionshistorie des Kunden.
Zeitstempel: Zeitpunkt, zu dem das Angebot erstellt wurde.

pay_deadline: Zeitstempel des Zeitpunkts, bis zu dem der Händler möchte, dass die Börse das aus diesem Vertrag fällige Geld endgültig überweist. Nach Ablauf dieser Frist fasst die Börse alle Einzahlungen zusammen, bei denen die Verträge die refund_deadline überschritten haben, und führt eine große Überweisung für sie aus. Die Betraege werden auf die Ueberweisungseinheit abgerundet; wenn der Gesamtbetrag noch unter der Ueberweisungseinheit liegt, wird er nicht ausgezahlt.

rückerstattung_frist: Zeitstempel, bis zu dem der Händler bereit (und in der Lage) ist, Erstattungen für den Vertrag mit Taler zu geben. Beachten Sie, dass die Taler-Börse die Zahlung mindestens bis zu dieser Frist auf einem Treuhandkonto hält. Bis zu diesem Zeitpunkt wird der Händler in der Lage sein, eine Nachricht zu unterschreiben, um eine Rückerstattung an den Kunden auszulösen. Nach diesem Zeitpunkt ist eine Rückerstattung an den Kunden nicht mehr möglich. Muss kleiner sein als die pay_deadline.

Produkte

Array der Produkte, die an den Kunden verkauft werden. Jeder Eintrag enthält ein Tupel mit den folgenden Werten:

Beschreibung: Beschreibung des Produkts.
Menge: Menge der zu versendenden Artikel. Kann eine Einheit (z.B. 1 kg) oder nur die Anzahl angeben.
Preis: Preis für Menge Einheiten dieses Produkts, die an den angegebenen Lieferort geliefert werden. Beachten Sie, dass die Summe aller Preise in der Regel den Gesamtbetrag des Vertrages ergeben sollte, sie kann aber aufgrund von Rabatten oder weil einzelne Preise nicht verfügbar sind, abweichen.
produkt_id: Eindeutige ID des Produkts im Katalog des Händlers. Kann im Allgemeinen frei gewählt werden, da sie nur für den Händler von Bedeutung ist, sollte aber eine Zahl im Bereich $[0,2^{51})$ sein.
Steuern: Karte der anwendbaren Steuern, die vom Händler zu zahlen sind. Die Bezeichnung ist der Name der Steuer, d. h. Mehrwertsteuer, Umsatzsteuer oder Einkommensteuer, und der Wert ist der anwendbare Steuerbetrag. Beliebige Bezeichnungen sind zulässig, solange sie zur Identifizierung der geltenden Steuerregelung verwendet werden. Die Einzelheiten können von der Aufsichtsbehörde festgelegt werden. Dies dient dazu, dem Kunden zu erklären, welche Steuern der Händler zu zahlen beabsichtigt, und kann vom Kunden als Quittung verwendet werden. Die Informationen werden wahrscheinlich auch bei Steuerprüfungen des Händlers verwendet.
Lieferdatum: Zeitpunkt, zu dem das Produkt an den Lieferort geliefert werden soll.
lieferung_ort: Dies sollte eine Bezeichnung in der Karte Orte ergeben, die angibt, wohin der Gegenstand geliefert werden soll.

Werte können weggelassen werden, wenn sie nicht zutreffend sind. Wenn es sich bei einem Kauf beispielsweise um ein Bündel von Produkten handelt, die keine individuellen Preise oder Produkt-IDs haben, kann die product_id oder der price im Vertrag nicht angegeben werden. Ebenso gibt es für virtuelle Produkte, die direkt über den Fulfillment-URI geliefert werden, keinen Lieferort.

merchant

Adresse: Dies sollte eine Bezeichnung in der Karte Orte ergeben, die angibt, wo sich der Händler befindet.
Name: Dies sollte ein für Menschen lesbarer Name für das Geschäft des Händlers sein.
Gerichtsbarkeit: Dies sollte eine Bezeichnung in der Karte Orte ergeben, welche die Gerichtsbarkeit angibt, unter der dieser Vertrag geschlichtet werden soll.

Standorte

Assoziative Karte der im Vertrag verwendeten Orte. Die Bezeichnungen für die Orte in dieser Karte können frei gewählt und immer dann verwendet werden, wenn ein Ort in anderen Teilen des Vertrages benötigt wird. Auf diese Weise muss derselbe Ort, wenn er mehrfach benötigt wird (z. B. die Geschäftsadresse des Kunden oder des Händlers), nur einmal aufgeführt (und übermittelt) werden und kann ansonsten über die Bezeichnung referenziert werden. Eine nicht erschöpfende Liste von Ortsattributen ist die folgende:

Name: Name des Empfängers für die Zustellung, entweder Firmen- oder Personenname.
Land: Name des Zustellungslandes, wie er auf einem Postpaket steht, z. B. „Frankreich“.
Staat: Name des Zustellungsstaats, wie er auf einem Postpaket steht, z. B. „NY“.
Region: Name der Zustellregion, wie er auf einem Postpaket steht.
Provinzen: Name der zustellenden Provinz, wie er auf einem Postpaket steht.
Stadt: Name des Zustellungsortes, wie er auf einem Postpaket steht.
Postleitzahl: Postleitzahl für die Zustellung, wie sie auf einem Postpaket steht.
Straße: Straßenname für die Zustellung, wie er auf einem Postpaket steht.
Straße_Nummer: Straßennummer (Hausnummer) für die Zustellung, wie sie auf einem Postpaket steht.

Bemerkung

Standorte müssen nicht alle diese Felder angeben und können auch zusätzliche Felder haben. Vertragsrenderer müssen mindestens die oben aufgeführten Felder rendern und sollten Felder, die sie nicht verstehen, als Schlüsselwertliste rendern.