Δημιουργία παραγγελιών

3.1.3. Δημιουργία παραγγελιών#

Αυτή η σελίδα περιέχει όλη την τεκμηρίωση για το εκπαιδευτικό βίντεο που εξηγεί μια απλή δημιουργία παραγγελίας μέσω του API και τον έλεγχο της κατάστασής της.

3.1.3.1. Βίντεο#

3.1.3.2. Απαιτήσεις#

Απαιτείται για αυτή τη σειρά σεμιναρίων:

  • Ένα εμπορικό backend Taler
    Αν χρειάζεστε βοήθεια για να χρησιμοποιήσετε το backend του εμπόρου για πρώτη φορά, μπορείτε να παρακολουθήσετε το σεμινάριο Taler merchant introduction.
  • Μια περίπτωση πορτοφολιού Taler
    Οι οδηγίες εγκατάστασης είναι διαθέσιμες στη διεύθυνση https://wallet.taler.net.
  • Λογισμικό διαχείρισης REST API ή σχετικές δεξιότητες προγραμματισμού
    Σε αυτή τη σειρά βίντεο, θα χρησιμοποιήσουμε το δωρεάν λογισμικό Insomnia, το οποίο είναι διαθέσιμο για λήψη από τη διεύθυνση https://insomnia.rest.

3.1.3.3. Demo backend ειδοποίηση#

Μπορείτε να χρησιμοποιήσετε τη δική σας εμπορική υπηρεσία backend ή την online υπηρεσία επίδειξης στη διεύθυνση https://backend.demo.taler.net/instances/sandbox/ για αυτό το σεμινάριο.

3.1.3.4. Περισσότερες σημειώσεις σχετικά με την εμπορική επεξεργασία πληρωμών#

  1. Δημιουργία εντολής πληρωμής

Οι πληρωμές στο Taler περιστρέφονται γύρω από μια εντολή, η οποία είναι μια μηχανικά αναγνώσιμη περιγραφή της επιχειρηματικής συναλλαγής για την οποία πρόκειται να γίνει η πληρωμή. Πριν αποδεχτείτε μια πληρωμή Taler ως έμπορος, πρέπει να δημιουργήσετε μια τέτοια εντολή.

Αυτό επιτυγχάνεται με την αποστολή ενός αντικειμένου JSON στο τελικό σημείο API /private/orders του backend. Τουλάχιστον τα ακόλουθα πεδία πρέπει να δίνονται μέσα στο πεδίο order:

  • Ποσό: Το ποσό προς πληρωμή, ως συμβολοσειρά στη μορφή CURRENCY:DECIMAL_VALUE, για παράδειγμα EUR:10 για 10 ευρώ ή KUDOS:1.5 για 1.5 KUDOS.

  • «Περίληψη»: Μια ευανάγνωστη από τον άνθρωπο περίληψη για το τι αφορά η πληρωμή. Η περίληψη θα πρέπει να είναι αρκετά σύντομη ώστε να χωράει σε τίτλους, αν και δεν υπάρχει αυστηρό όριο.

  • fulfillment_url: Μια διεύθυνση URL που θα εμφανιστεί μόλις ολοκληρωθεί η πληρωμή. Για τα ψηφιακά αγαθά, αυτή θα πρέπει να είναι μια σελίδα που εμφανίζει το προϊόν που αγοράστηκε. Κατά την επιτυχή πληρωμή, το πορτοφόλι προσθέτει αυτόματα το order_id ως παράμετρο ερώτησης, καθώς και το session_sig για πληρωμές που συνδέονται με τη σύνοδο (που αναλύονται παρακάτω).

Οι παραγγελίες μπορούν να έχουν πολλά περισσότερα πεδία, δείτε The Taler Order Format. Κατά την POSTing μιας παραγγελίας, μπορείτε επίσης να καθορίσετε πρόσθετες λεπτομέρειες, όπως μια παράκαμψη για τη διάρκεια επιστροφής χρημάτων και οδηγίες για τη διαχείριση των αποθεμάτων. Αυτά χρειάζονται σπάνια και δεν καλύπτονται σε αυτό το σεμινάριο- ανατρέξτε στο Εγχειρίδιο αναφοράς για λεπτομέρειες.

Ένα ελάχιστο απόσπασμα Python για τη δημιουργία μιας παραγγελίας θα έμοιαζε ως εξής:

>>> import requests
>>> body = dict(order=dict(amount="KUDOS:10",
...                        summary="Donation",
...                        fulfillment_url="https://example.com/thanks.html"),
...             create_token=False)
>>> response = requests.post("https://backend.demo.taler.net/instances/sandbox/private/orders",
...               json=body,
...               headers={"Authorization": "Bearer secret-token:sandbox"})
<Response [200]>

Το backend θα συμπληρώσει ορισμένες λεπτομέρειες που λείπουν από την παραγγελία, όπως η διεύθυνση της εμπορικής μονάδας. Οι πλήρεις λεπτομέρειες ονομάζονται όροι σύμβασης.

Σημείωση

Η παραπάνω αίτηση απενεργοποιεί τη χρήση των claim tokens θέτοντας την επιλογή create_token σε false. Εάν χρειάζεστε claim tokens, πρέπει να προσαρμόσετε τον κώδικα για την κατασκευή του URI taler://pay/ που δίνεται παρακάτω ώστε να περιλαμβάνει το claim token.

Μετά την επιτυχή POST στο /private/orders, θα επιστραφεί ένα JSON με μόνο ένα πεδίο order_id με μια συμβολοσειρά που αντιπροσωπεύει το αναγνωριστικό της παραγγελίας. Εάν λάβετε επίσης ένα claim token, ελέγξτε ξανά ότι χρησιμοποιήσατε την αίτηση όπως περιγράφεται παραπάνω.

Μαζί με την εμπορική instance, το αναγνωριστικό παραγγελίας ταυτοποιεί μοναδικά την παραγγελία σε ένα εμπορικό backend. Χρησιμοποιώντας το αναγνωριστικό της παραγγελίας, μπορείτε να κατασκευάσετε το αντίστοιχο URI taler://pay/ που πρέπει να παρέχεται στο πορτοφόλι. Έστω example.com είναι το όνομα τομέα όπου είναι προσβάσιμα τα δημόσια τελικά σημεία της περίπτωσης. Το URI πληρωμής του Taler είναι τότε απλά taler://pay/example.com/$ORDER_ID/ όπου το $ORDER_ID πρέπει να αντικατασταθεί με το αναγνωριστικό της παραγγελίας που επιστράφηκε.

Μπορείτε να βάλετε το URI taler:// ως στόχο ενός συνδέσμου για να ανοίξετε το πορτοφόλι Taler μέσω του σχήματος taler:// ή να το βάλετε σε έναν κώδικα QR. Ωστόσο, για ένα διαδικτυακό κατάστημα, ο ευκολότερος τρόπος είναι απλά να ανακατευθύνετε το πρόγραμμα περιήγησης στο https://example.com/orders/$ORDER_ID. Αυτή η σελίδα θα ενεργοποιήσει στη συνέχεια το πορτοφόλι Taler. Εδώ το backend παράγει τη σωστή λογική για την ενεργοποίηση του πορτοφολιού, υποστηρίζοντας τους διάφορους τύπους πορτοφολιών Taler που υπάρχουν. Αντί να κατασκευάσετε το παραπάνω URL με το χέρι, είναι επίσης δυνατό να το λάβετε ελέγχοντας την κατάσταση πληρωμής, όπως περιγράφεται στην επόμενη ενότητα.

Όταν κατασκευάζετε χειροκίνητα αυτή τη διεύθυνση URL, βεβαιωθείτε ότι παρέχετε το claim token (εκτός αν έχει απενεργοποιηθεί) και εάν το backend εκτελείται χωρίς TLS να χρησιμοποιήσετε το taler+http:// (σημειώστε ότι το τελευταίο υποστηρίζεται μόνο από πορτοφόλια που εκτελούνται σε debug mode).

Σημείωση

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

  1. Έλεγχος κατάστασης πληρωμής και προτροπή για πληρωμή

Με δεδομένο το αναγνωριστικό παραγγελίας, η κατάσταση μιας πληρωμής μπορεί να ελεγχθεί με το τελικό σημείο /private/orders/$ORDER_ID. Εάν η πληρωμή δεν έχει ακόμη ολοκληρωθεί από τον πελάτη, το /private/orders/$ORDER_ID θα δώσει στο frontend μια διεύθυνση URL (με το όνομα payment_redirect_url) που θα ενεργοποιήσει το πορτοφόλι του πελάτη να εκτελέσει την πληρωμή. Αυτό είναι ουσιαστικά το URL https://example.com/orders/$ORDER_ID που συζητήσαμε παραπάνω.

>>> import requests
>>> r = requests.get("https://backend.demo.taler.net/instances/sandbox/private/orders/" + order_id,
...                  headers={"Authorization": "Bearer secret-token:sandbox"})
>>> print(r.json())

Εάν το πεδίο κατάσταση παραγγελίας στην απόκριση είναι πληρωμένο, δεν θα λάβετε ένα payment_redirect_url και αντ” αυτού πληροφορίες σχετικά με την κατάσταση πληρωμής, όπως:

  • contract_terms: Οι πλήρεις όροι της σύμβασης της παραγγελίας.

  • refunded: true εάν χορηγήθηκε (ενδεχομένως μερική) επιστροφή χρημάτων για αυτή την αγορά.

  • refunded_amount: Ποσό που επιστράφηκε

Μόλις το frontend επιβεβαιώσει ότι η πληρωμή ήταν επιτυχής, συνήθως πρέπει να ενεργοποιήσει την επιχειρησιακή λογική για τον έμπορο ώστε να εκπληρώσει τις υποχρεώσεις του εμπόρου βάσει της σύμβασης.

Σημείωση

Δεν χρειάζεται να συνεχίσετε να ρωτάτε για να παρατηρήσετε τις αλλαγές στην κατάσταση συναλλαγής της παραγγελίας. Τα τελικά σημεία υποστηρίζουν μακροχρόνια δημοσκόπηση, απλά καθορίστε μια παράμετρο ερώτησης timeout_ms με το πόσο καιρό θέλετε να περιμένετε το πολύ μέχρι η κατάσταση της παραγγελίας να αλλάξει σε πληρωμένη.

3.1.3.5. Περισσότερα σεμινάρια#

Για να δείτε πρόσθετα σεμινάρια, μπορείτε να περιηγηθείτε σε αυτόν τον ιστότοπο ή να επισκεφθείτε τη διεύθυνση https://docs.taler.net για να λάβετε την πιο πρόσφατη τεκμηρίωση σχετικά με τις υπηρεσίες Taler.