3.1.6. Le format de commande Taler#

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.

Note

Les montants financiers sont toujours spécifiés sous la forme d’une chaîne de caractères au format « CURRENCY:DECIMAL_VALUE ».

This section provides an overview of the most common fields:

montant: Indique le montant total à payer au commerçant par le client.

max_fee: Il s’agit du montant total maximum des frais de dépôt que le commerçant est prêt à payer. Si les frais de dépôt pour les pièces dépassent ce montant, le client doit l’inclure dans le total du paiement. Les frais sont spécifiés en utilisant le même format que celui utilisé pour amount.

max_wire_fee: Frais de virement maximum acceptés par le commerçant (la part du client doit être divisée par le facteur wire_fee_amortization, et réduite si les frais de dépôt sont inférieurs à max_fee). La valeur par défaut en cas d’absence est zéro.

Amortissement de la taxe sur les fils: Sur combien de transactions le commerçant s’attend-il à amortir les frais de virement en moyenne ? Si les frais de virement de l’échange sont supérieurs au « max_wire_fee », la différence est divisée par ce nombre pour calculer la contribution attendue du client aux frais de virement. La contribution du client peut être réduite par la différence entre max_fee et la somme des frais de dépôt réels. Facultatif, la valeur par défaut si elle est manquante est 1. Les valeurs nulles et négatives ne sont pas valides et sont également interprétées comme 1.

pay_url: URL qui accepte les paiements. Il s’agit de l’URL où le portefeuille POST les pièces.

fulfillment_url: À quelle URL le portefeuille doit-il se rendre pour obtenir l’exécution, par exemple le code HTML ou le PDF d’un article acheté, ou un système de suivi des commandes pour les expéditions, ou une simple page web lisible par l’homme indiquant l’état d’avancement du contrat.

order_id: Identifiant alphanumérique, librement défini par le commerçant. Utilisé par le commerçant pour identifier la transaction de manière unique.

résumé: Résumé succinct du contrat, lisible par l’homme. À utiliser lorsque le contrat est affiché sur une seule ligne, par exemple dans l’historique des transactions du client.
horodatage: Heure à laquelle l’offre a été générée.

pay_deadline: Horodatage de l’heure à laquelle le commerçant souhaite que la bourse transfère définitivement l’argent dû au titre de ce contrat. Une fois ce délai expiré, la bourse regroupera tous les dépôts pour lesquels les contrats ont dépassé la date limite de remboursement et effectuera un seul virement important. Les montants seront arrondis à l’unité de virement ; si le montant total est encore inférieur à l’unité de virement, il ne sera pas déboursé.

délai_de_remboursement: Date limite jusqu’à laquelle le marchand souhaite (et peut) effectuer des remboursements pour le contrat en utilisant Taler. Notez que l’échange Taler conservera le paiement en dépôt fiduciaire au moins jusqu’à cette date limite. Jusqu’à cette date, le marchand pourra signer un message pour déclencher un remboursement au client. Passé ce délai, il ne sera plus possible de rembourser le client. Doit être plus petit que le pay_deadline.

produits

Tableau des produits vendus au client. Chaque entrée contient un tuple avec les valeurs suivantes :

description: Description du produit.
quantité: Quantité d’articles à expédier. Peut spécifier une unité (par exemple 1 kg) ou simplement le nombre.
prix: Prix pour une quantité d’unités de ce produit expédiées à la delivery_location donnée. Notez que la somme de tous les prix devrait normalement correspondre au montant total du contrat, mais elle peut être différente en raison de remises ou parce que les prix individuels ne sont pas disponibles.
produit_id: ID unique du produit dans le catalogue du marchand. Il peut généralement être choisi librement car il n’a de sens que pour le marchand, mais doit être un nombre compris dans l’intervalle $[0,2^{51})$ .
impôts: Carte des taxes applicables à payer par le commerçant. L’étiquette est le nom de la taxe, c’est-à-dire la TVA, la taxe sur les ventes ou l’impôt sur le revenu, et la valeur est le montant de la taxe applicable. Il convient de noter que les étiquettes arbitraires sont autorisées, à condition qu’elles soient utilisées pour identifier le régime fiscal applicable. Des détails peuvent être spécifiés par l’autorité de régulation. Cette information est utilisée pour déclarer au client les taxes que le commerçant a l’intention de payer, et peut être utilisée par le client comme un reçu. Ces informations sont également susceptibles d’être utilisées dans le cadre d’un contrôle fiscal du commerçant.
date_de_livraison: Heure à laquelle le produit doit être livré au lieu de livraison.
lieu de livraison: Cela devrait donner une étiquette dans la carte locations, spécifiant l’endroit où l’article doit être livré.

Les valeurs peuvent être omises si elles ne sont pas applicables. Par exemple, si un achat concerne un ensemble de produits qui n’ont pas de prix individuels ou d’identifiants de produits, le product_id ou le price peuvent ne pas être spécifiés dans le contrat. De même, pour les produits virtuels livrés directement via l’URI d’exécution, il n’y a pas de delivery_location.

merchant

adresse: Cela devrait donner une étiquette dans la carte locations, spécifiant où le marchand est situé.
nom: Il s’agit d’un nom lisible par l’homme pour l’entreprise du commerçant.
juridiction: Cela devrait donner une étiquette dans la carte locations, spécifiant la juridiction sous laquelle ce contrat doit être arbitré.

lieux

Carte associative des lieux utilisés dans le contrat. Les étiquettes des lieux figurant sur cette carte peuvent être choisies librement et utilisées chaque fois qu’un lieu est requis dans d’autres parties du contrat. Ainsi, si le même lieu est requis à plusieurs reprises (comme l’adresse professionnelle du client ou du commerçant), il ne doit être répertorié (et transmis) qu’une seule fois et peut être mentionné par l’intermédiaire de l’étiquette. Voici une liste non exhaustive d’attributs de localisation :

nom: Nom du destinataire de la livraison, qu’il s’agisse d’une entreprise ou d’une personne.
pays: Nom du pays de livraison, tel qu’il figure sur un colis postal, par exemple « France ».
État: Nom de l’État de livraison, tel qu’il figure sur un colis postal, par exemple « NY ».
région: Nom de la région de livraison, tel qu’il figure sur un colis postal.
provinces: Nom de la province de livraison, tel qu’il figure sur un colis postal.
ville: Nom de la ville de livraison, tel qu’il figure sur un colis postal.
code postal: Code postal pour la livraison, tel qu’il figure sur un colis postal.
rue: Nom de rue pour la livraison, tel qu’il figure sur un colis postal.
numéro de rue: Numéro de rue (numéro de la maison) pour la livraison, tel qu’il figure sur un colis postal.

Note

Les lieux ne sont pas obligés de spécifier tous ces champs, et ils sont également autorisés à en avoir d’autres. Les moteurs de rendu des contrats doivent rendre au moins les champs énumérés ci-dessus et doivent rendre les champs qu’ils ne comprennent pas sous la forme d’une liste clé-valeur.