3.1.6. Η μορφή παραγγελίας Taler#

Η μορφή παραγγελίας του Taler περιγράφει το JSON που πρέπει να POSTed στο backend του εμπόρου για τη δημιουργία μιας παραγγελίας. Είναι το πρωτότυπο από το οποίο το backend του εμπόρου θα δημιουργήσει τους πραγματικούς «όρους της σύμβασης <https://docs.taler.net/core/api-merchant.html#the-contract-terms>»__.

Υπάρχουν διαφορετικές εκδόσεις για τη μορφή παραγγελίας- περιγράφονται λεπτομερώς στο Εγχειρίδιο αναφοράς.

Σημείωση

Τα οικονομικά ποσά καθορίζονται πάντα ως συμβολοσειρά με τη μορφή "CURRENCY:DECIMAL_VALUE".

Αυτή η ενότητα παρέχει μια επισκόπηση των πιο συνηθισμένων πεδίων:

ποσό: Καθορίζει το συνολικό ποσό που πρέπει να καταβληθεί στον έμπορο από τον πελάτη.

max_fee: Πρόκειται για το μέγιστο συνολικό ποσό των τελών κατάθεσης που είναι διατεθειμένος να πληρώσει ο έμπορος. Εάν τα τέλη κατάθεσης για τα κέρματα υπερβαίνουν αυτό το ποσό, ο πελάτης πρέπει να το συμπεριλάβει στο συνολικό ποσό πληρωμής. Το τέλος καθορίζεται με την ίδια μορφή που χρησιμοποιείται για το amount.

max_wire_fee: Μέγιστη αμοιβή εμβάσματος που γίνεται δεκτή από τον έμπορο (το μερίδιο του πελάτη διαιρείται με τον παράγοντα «απόσβεση αμοιβής εμβάσματος» και μειώνεται περαιτέρω εάν οι αμοιβές κατάθεσης είναι χαμηλότερες από τη «μέγιστη αμοιβή»). Η προεπιλογή αν λείπει είναι μηδέν.

wire_fee_amortization: Σε πόσες συναλλαγές πελατών ο έμπορος αναμένει να αποσβέσει κατά μέσο όρο τα έξοδα μεταφοράς; Εάν η αμοιβή του ανταλλακτηρίου είναι πάνω από το max_wire_fee, η διαφορά διαιρείται με αυτόν τον αριθμό για να υπολογιστεί η αναμενόμενη συνεισφορά του πελάτη στην αμοιβή. Η συνεισφορά του πελάτη μπορεί να μειωθεί περαιτέρω κατά τη διαφορά μεταξύ του max_fee και του αθροίσματος των πραγματικών τελών κατάθεσης. Προαιρετικό, η προεπιλεγμένη τιμή αν λείπει είναι 1. Οι μηδενικές και αρνητικές τιμές είναι άκυρες και ερμηνεύονται επίσης ως 1.

pay_url: Ποια διεύθυνση URL δέχεται πληρωμές. Αυτή είναι η διεύθυνση URL στην οποία το πορτοφόλι θα ΠΟΣΤΑΡΙΣΕΙ τα νομίσματα.

fulfillment_url: Σε ποια διεύθυνση URL θα πρέπει να μεταβεί το πορτοφόλι για να λάβει την εκπλήρωση, για παράδειγμα την HTML ή το PDF ενός άρθρου που αγοράστηκε, ή ένα σύστημα παρακολούθησης παραγγελιών για αποστολές, ή μια απλή ιστοσελίδα με δυνατότητα ανάγνωσης από τον άνθρωπο που υποδεικνύει την κατάσταση της σύμβασης.

order_id: Αλφαριθμητικό αναγνωριστικό, ελεύθερα καθοριζόμενο από τον έμπορο. Χρησιμοποιείται από τον έμπορο για τη μοναδική αναγνώριση της συναλλαγής.

περίληψη: Σύντομη, ευανάγνωστη από τον άνθρωπο περίληψη της σύμβασης. Χρησιμοποιείται όταν η σύμβαση εμφανίζεται σε μία μόνο γραμμή, για παράδειγμα στο ιστορικό συναλλαγών του πελάτη.
timestamp: Ώρα κατά την οποία δημιουργήθηκε η προσφορά.

pay_deadline: Χρονοσφραγίδα της ώρας μέχρι την οποία ο έμπορος θέλει το ανταλλακτήριο να εμβάσει οριστικά τα χρήματα που οφείλονται από τη σύμβαση αυτή. Μόλις λήξει αυτή η προθεσμία, το ανταλλακτήριο θα συγκεντρώσει όλες τις καταθέσεις στις οποίες τα συμβόλαια έχουν περάσει την refund_deadline και θα εκτελέσει μία μεγάλη πληρωμή με έμβασμα για αυτές. Τα ποσά θα στρογγυλοποιούνται προς τα κάτω στη μονάδα εμβάσματος- εάν το συνολικό ποσό εξακολουθεί να είναι κάτω από τη μονάδα εμβάσματος, δεν θα εκταμιεύεται.

προθεσμία επιστροφής χρημάτων: Χρονοσφραγίδα μέχρι την οποία ο έμπορος είναι πρόθυμος (και ικανός) να δώσει επιστροφές χρημάτων για το συμβόλαιο που χρησιμοποιεί το Taler. Σημειώστε ότι το ανταλλακτήριο Taler θα κρατήσει την πληρωμή σε μεσεγγύηση τουλάχιστον μέχρι αυτή την προθεσμία. Μέχρι αυτή τη στιγμή, ο έμπορος θα είναι σε θέση να υπογράψει ένα μήνυμα για να προκαλέσει επιστροφή χρημάτων στον πελάτη. Μετά από αυτό το χρονικό διάστημα, δεν θα είναι πλέον δυνατή η επιστροφή χρημάτων στον πελάτη. Πρέπει να είναι μικρότερη από την προθεσμία pay_deadline.

προϊόντα

Σειρά προϊόντων που πωλούνται στον πελάτη. Κάθε εγγραφή περιέχει μια πλειάδα με τις ακόλουθες τιμές:

περιγραφή: Περιγραφή του προϊόντος.
ποσότητα: Ποσότητα των προς αποστολή αντικειμένων. Μπορεί να καθορίσει μια μονάδα (π.χ. 1 kg) ή απλώς την ποσότητα.
τιμή: Τιμή για ποσότητα μονάδων αυτού του προϊόντος που αποστέλλεται στη δεδομένη θέση παράδοσης. Σημειώστε ότι συνήθως το άθροισμα όλων των τιμών θα πρέπει να ανέρχεται στο συνολικό ποσό της σύμβασης, αλλά μπορεί να είναι διαφορετικό λόγω εκπτώσεων ή επειδή οι μεμονωμένες τιμές δεν είναι διαθέσιμες.
product_id: Μοναδικό αναγνωριστικό του προϊόντος στον κατάλογο του εμπόρου. Μπορεί γενικά να επιλεγεί ελεύθερα, καθώς έχει σημασία μόνο για τον έμπορο, αλλά θα πρέπει να είναι ένας αριθμός στο εύρος $[0,2^{51})$ .
φόροι: Χάρτης των φόρων που πρέπει να καταβληθούν από τον έμπορο. Η ετικέτα είναι η ονομασία του φόρου, π.χ. ΦΠΑ, φόρος επί των πωλήσεων ή φόρος εισοδήματος, και η τιμή είναι το εφαρμοστέο ποσό φόρου. Σημειώστε ότι επιτρέπονται αυθαίρετες ετικέτες, αρκεί να χρησιμοποιούνται για τον προσδιορισμό του ισχύοντος φορολογικού καθεστώτος. Οι λεπτομέρειες μπορούν να καθοριστούν από τη ρυθμιστική αρχή. Αυτό χρησιμοποιείται για να δηλωθεί στον πελάτη ποιοι φόροι προτίθεται να καταβληθούν από τον έμπορο και μπορεί να χρησιμοποιηθεί από τον πελάτη ως απόδειξη. Οι πληροφορίες είναι επίσης πιθανό να χρησιμοποιηθούν από φορολογικούς ελέγχους του εμπόρου.
delivery_date: Ώρα κατά την οποία το προϊόν πρέπει να παραδοθεί στην τοποθεσία «delivery_location».
τοποθεσία_παράδοσης: Αυτό θα πρέπει να δώσει μια ετικέτα στο χάρτη locations, καθορίζοντας πού θα παραδοθεί το αντικείμενο.

Οι τιμές μπορούν να παραλειφθούν εάν δεν ισχύουν. Για παράδειγμα, εάν μια αγορά αφορά μια δέσμη προϊόντων που δεν έχουν μεμονωμένες τιμές ή αναγνωριστικά προϊόντος, το product_id ή η τιμή μπορεί να μην καθορίζονται στη σύμβαση. Ομοίως, για εικονικά προϊόντα που παραδίδονται απευθείας μέσω του URI εκτέλεσης, δεν υπάρχει delivery_location.

έμπορος

διεύθυνση: Αυτό θα πρέπει να δώσει μια ετικέτα στο χάρτη locations, καθορίζοντας πού βρίσκεται ο έμπορος.
όνομα: Αυτό θα πρέπει να δίνει ένα ευανάγνωστο από τον άνθρωπο όνομα για την επιχείρηση του εμπόρου.
δικαιοδοσία: Αυτό θα πρέπει να δώσει μια ετικέτα στο χάρτη «τοποθεσίες», καθορίζοντας τη δικαιοδοσία υπό την οποία θα γίνει η διαιτησία αυτής της σύμβασης.

τοποθεσίες

Συνδετικός χάρτης των τοποθεσιών που χρησιμοποιούνται στη σύμβαση. Οι ετικέτες για τις τοποθεσίες σε αυτόν τον χάρτη μπορούν να επιλέγονται ελεύθερα και να χρησιμοποιούνται όποτε απαιτείται μια τοποθεσία σε άλλα μέρη της σύμβασης. Με αυτόν τον τρόπο, εάν η ίδια τοποθεσία απαιτείται πολλές φορές (όπως η επαγγελματική διεύθυνση του πελάτη ή του εμπόρου), χρειάζεται να καταχωρηθεί (και να διαβιβαστεί) μόνο μία φορά, ενώ διαφορετικά μπορεί να αναφέρεται μέσω της ετικέτας. Ένας μη εξαντλητικός κατάλογος χαρακτηριστικών τοποθεσίας είναι ο ακόλουθος:

όνομα: Όνομα παραλήπτη για την παράδοση, είτε πρόκειται για επιχείρηση είτε για πρόσωπο.
χώρα: Όνομα της χώρας παράδοσης, όπως αναγράφεται σε ένα ταχυδρομικό πακέτο, π.χ. «Γαλλία».
κράτος: Όνομα της πολιτείας παράδοσης, όπως αναγράφεται σε ένα ταχυδρομικό πακέτο, π.χ. «NY».
περιοχή: Όνομα της περιοχής παράδοσης, όπως αναγράφεται σε ένα ταχυδρομικό δέμα.
επαρχίες: Όνομα της επαρχίας παράδοσης, όπως αναγράφεται σε ένα ταχυδρομικό δέμα.
πόλη: Όνομα της πόλης παράδοσης, όπως αναγράφεται σε ένα ταχυδρομικό δέμα.
zip_code: ZIP code για την παράδοση, όπως βρίσκεται σε ένα ταχυδρομικό πακέτο.
δρόμος: Όνομα οδού για την παράδοση, όπως αναγράφεται σε ένα ταχυδρομικό πακέτο.
street_number: Αριθμός οδού (αριθμός σπιτιού) για την παράδοση, όπως αναγράφεται σε ένα ταχυδρομικό πακέτο.

Σημείωση

Οι τοποθεσίες δεν είναι υποχρεωμένες να καθορίζουν όλα αυτά τα πεδία και επιτρέπεται να έχουν και πρόσθετα πεδία. Οι φορείς απόδοσης συμβολαίων πρέπει να αποδίδουν τουλάχιστον τα πεδία που αναφέρονται παραπάνω και πρέπει να αποδίδουν τα πεδία που δεν κατανοούν ως λίστα κλειδιών-τιμών.