Παραγγελίες καταστήματος

Όταν μια παραγγελία καταχωρηθεί ή πληρωθεί, στείλτε την με το POST /store_orders: τον έμπορο (mer_…) και την παραγγελία όπως την έχει η πλατφόρμα (γραμμές, φόροι, αποστολή, χρεώσεις, κουπόνια, πύλη πληρωμής, αγοραστής). Το Tallio αντιστοιχίζει μια πληρωμένη παραγγελία σε απόδειξη ή τιμολόγιο και το εκδίδει μέσω της σύνδεσης του εμπόρου στη λειτουργία του κλειδιού· ένα δοκιμαστικό κλειδί χωρίς δοκιμαστική σύνδεση εκδίδει μέσω του sandbox του Tallio. Μια απλήρωτη παραγγελία κρατιέται και παραλείπεται ως order_not_paid: επαναλάβετέ την μόλις πληρωθεί.

• Μία παραγγελία καταστήματος ανά παραγγελία. Το Tallio κρατά μία ανά έμπορο, λειτουργία, πλατφόρμα και id παραγγελίας. Αν στείλετε μια παραγγελία που ήδη έχει, απαντά με εκείνη την παραγγελία καταστήματος και 200 χωρίς να αντιστοιχίσει τίποτα ξανά, οπότε μια επαναποστολή μετά από χαμένη απάντηση είναι ασφαλής. Χρησιμοποιήστε επίσης ένα κλειδί idempotency ανά παραγγελία.
• Αντιστοιχίζει το Tallio, ποτέ το κατάστημα. Οι φόροι, οι στρογγυλοποιήσεις, οι τρόποι πληρωμής και ο αγοραστής διαβάζονται από την παραγγελία με τις ρυθμίσεις καταστήματος του εμπόρου. Μια παραγγελία που το Tallio δεν μπορεί να αντιστοιχίσει με ακρίβεια παραλείπεται με λόγο, και δεν εκδίδεται ποτέ στα τυφλά.
• Διαβάστε την ξανά. Το GET /store_orders/{id} επιστρέφει την κατάσταση, τον λόγο και το παραστατικό της, με τον αριθμό και, στην Ελλάδα, το MARK μόλις εκδοθεί. Το GET /store_orders επιστρέφει τις παραγγελίες καταστήματος της λειτουργίας του κλειδιού, τις νεότερες πρώτες.

• pending: παραλήφθηκε, δεν έχει αντιστοιχιστεί ακόμη ή περιμένει να σταλεί.
• skipped: δεν αντιστοιχεί σε κανένα παραστατικό· το reason λέει γιατί.
• sent: το παραστατικό της δημιουργήθηκε και είναι καθ’ οδόν προς τον πάροχο.
• issued: το παραστατικό εκδόθηκε.
• failed: το παραστατικό απορρίφθηκε, απέτυχε ή ακυρώθηκε, ή το Tallio δεν μπόρεσε να το δημιουργήσει· το reason λέει γιατί.

Κάθε παραγγελία καταστήματος που παραλείφθηκε ή απέτυχε έχει έναν μηχαναγνώσιμο λόγο στο reason και μια πρόταση στο detail για τον έμπορο (ο πίνακας παρακάτω). Το warnings περιέχει ό,τι αξίζει να ξέρετε για ένα εκδομένο παραστατικό: ένα λεπτό στρογγυλοποίησης, μια δωρεάν γραμμή που παραλείφθηκε, τον προεπιλεγμένο τρόπο πληρωμής του καταστήματος που χρησιμοποιήθηκε.

Μια παραγγελία καταστήματος που παραλείφθηκε ή απέτυχε και περιμένει τον έμπορο έχει action_needed: true, και το GET /store_orders?status=action_needed τις επιστρέφει, μαζί με τις παραγγελίες των οποίων η επιστροφή χρημάτων περιμένει. Οι παραλείψεις που δεν χρειάζονται τίποτα (μια δοκιμαστική παραγγελία, τίποτα για τιμολόγηση, μια γαλλική πώληση για δήλωση) μένουν εκτός λίστας.

• Επανάληψη. Όταν το retryable είναι true, η αιτία ήταν έξω από την παραγγελία (κανένας συνδεδεμένος πάροχος, ένας τρόπος πληρωμής προς επιλογή, το όριο του πακέτου) και έχει πλέον διορθωθεί: καλέστε το POST /store_orders/{id}/retry με την παραγγελία όπως την έχει τώρα η πλατφόρμα. Ένα παραστατικό που απέτυχε στέλνεται ξανά όπως ήταν. Μια επανάληψη δεν δημιουργεί ποτέ δεύτερο παραστατικό.
• Σήμανση ως διεκπεραιωμένη. Όταν ο έμπορος εξέδωσε το παραστατικό χειροκίνητα, το POST /store_orders/{id}/mark_handled βγάζει την παραγγελία από τη λίστα· ο λόγος της παραμένει. Στείλτε τον λόγο που είδε ο έμπορος: αν έχει αλλάξει στο μεταξύ, η απάντηση είναι 409 invalid_state, ώστε ένα νεότερο αποτέλεσμα να μην κρύβεται ποτέ αδιάβαστο.

Στείλτε κάθε επιστροφή χρημάτων με το POST /store_orders/{id}/refunds. Το Tallio πιστώνει ακριβώς ό,τι επιστράφηκε με πιστωτικό συνδεδεμένο με το παραστατικό της παραγγελίας: ολόκληρη την πώληση, τις γραμμές της ή ένα ποσό σε πώληση με έναν συντελεστή. Μια επιστροφή που στέλνεται πριν εκδοθεί το παραστατικό της παραγγελίας το περιμένει. Μια επιστροφή που το Tallio δεν μπορεί να αντιστοιχίσει παραλείπεται με λόγο και περιμένει τον έμπορο, που εκδίδει το πιστωτικό χειροκίνητα και τη σημειώνει ως διεκπεραιωμένη με το POST /store_orders/{id}/refunds/{refundId}/mark_handled. Το refunds της παραγγελίας τις περιέχει, την καθεμία με το πιστωτικό της.

Ένας αγοραστής που θέλει τιμολόγιο δίνει τον αριθμό ΦΠΑ του (στη Γαλλία, το SIREN, το SIRET ή τον αριθμό ΦΠΑ του) και την επωνυμία της εταιρείας. Αν συμπληρωθούν στο ταμείο, περιλαμβάνονται στο invoice_request της παραγγελίας. Αν ζητηθούν μετά το ταμείο, στη σελίδα επιβεβαίωσης της παραγγελίας ή στον λογαριασμό του αγοραστή, αποθηκεύονται με το PUT /store_orders/{id}/invoice_request. Η παραγγελία μπορεί να δηλωθεί ως platform:external_id πριν τη στείλει το κατάστημα, και τότε διαβάζει το αίτημα όταν φτάσει. Αφού δημιουργηθεί το παραστατικό της παραγγελίας, ένα αίτημα δεν αλλάζει τίποτα (409 already_issued): ο έμπορος επανεκδίδει το παραστατικό (η κλήση διόρθωσης παρακάτω).

Πριν εκδοθεί ένα ελληνικό τιμολόγιο, το Tallio αναζητά τον ΑΦΜ του αγοραστή στο μητρώο. Ένας ΑΦΜ που δεν είναι καταχωρημένος παραλείπει την παραγγελία ως buyer_vat_not_registered. Όταν η καταχωρημένη επωνυμία διαφέρει από αυτή της παραγγελίας, ή το μητρώο δεν τη δίνει, ή οι ρυθμίσεις του καταστήματος ζητούν επιβεβαίωση κάθε τιμολογίου, η παραγγελία περιμένει ως invoice_awaiting_confirmation:

• Το POST /store_orders/{id}/invoice_review επιστρέφει τον αγοραστή όπως τον αναγράφει το τιμολόγιο δίπλα στην απάντηση του μητρώου. Δεν αλλάζει τίποτα· δείξτε και τα δύο στον έμπορο.
• Όταν το registry.confirmable είναι true, το POST /store_orders/{id}/confirm_invoice με την παραγγελία όπως είναι τώρα και το registry_hash εκδίδει το τιμολόγιο με την καταχωρημένη επωνυμία και διεύθυνση. Αν το μητρώο άλλαξε στο μεταξύ, η παραγγελία περιμένει ξανά νέο έλεγχο.

Όταν ο έμπορος αλλάξει μια εκδομένη παραγγελία, ή αλλάξουν τα στοιχεία του αγοραστή, το POST /store_orders/{id}/correct αντικαθιστά το παραστατικό με ένα που αντιστοιχίζεται από την παραγγελία όπως είναι τώρα. Στην Ελλάδα το αρχικό ακυρώνεται στο myDATA, ή πιστώνεται ολόκληρο όπου δεν μπορεί να ακυρωθεί· στη Γαλλία πιστώνεται ολόκληρο και εκδίδεται νέο τιμολόγιο. Το POST /store_orders/{id}/cancel ακυρώνει ένα ελληνικό παραστατικό για πώληση που δεν έγινε· ένα γαλλικό τιμολόγιο δεν ακυρώνεται ποτέ, μόνο διορθώνεται. Τα correctable και cancellable της παραγγελίας καταστήματος λένε τι επιτρέπει το Tallio τώρα· προσφέρετε μόνο αυτές τις ενέργειες.

Η εφαρμογή Shopify και το πρόσθετο WooCommerce του Tallio ονομάζουν αυτή την ενέργεια «Επανέκδοση»: το παραστατικό δεν τροποποιείται, εκδίδεται νέο με δικό του αριθμό και σημερινή ημερομηνία, και το παλιό μένει καταχωρημένο, ακυρωμένο ή πιστωμένο. Ονομάστε την έτσι στους εμπόρους και ζητήστε τους να αλλάξουν πρώτα την παραγγελία στο κατάστημα.

Τα γαλλικά τιμολόγια και πιστωτικά των παραγγελιών καταστήματος αριθμούνται από το Tallio, σε μία αδιάσπαστη σειρά για τα τιμολόγια και μία για τα πιστωτικά, ανά λειτουργία και έτος, με τα προθέματα των ρυθμίσεων καταστήματος του εμπόρου (PATCH /merchants/{id}/store_settings). Ένας αριθμός που δόθηκε σε εγγραφή που τελικά δεν έγινε παραστατικό κρατιέται ως κενό και καταγράφεται στο voided_numbers, ώστε η σειρά να μπορεί να εξηγηθεί.

Το Tallio στέλνει store_order.updated όταν αλλάζει η κατάσταση, ο λόγος, η σήμανση διεκπεραίωσης, το παραστατικό ή οι επιστροφές χρημάτων μιας παραγγελίας καταστήματος. Η σύνδεση ενός καταστήματος δημιουργεί τα endpoints webhook του, ένα ανά κλειδί, περιορισμένα στον έμπορό του. Αντιμετωπίστε το συμβάν ως ένδειξη: ελέγξτε την υπογραφή του και μετά διαβάστε ξανά την παραγγελία καταστήματος. Ένα κατάστημα του οποίου ο host μπλοκάρει τα εισερχόμενα αιτήματα ζητά αντί γι’ αυτό τις πρόσφατες παραγγελίες καταστήματος σε τακτά διαστήματα.

Μια ομάδα καταστήματος εκδίδει πραγματικά παραστατικά χωρίς κάρτα με το πακέτο Free, έως 50 παραστατικά τον μήνα, ή με ένα επί πληρωμή πακέτο καταστήματος που επιλέγει ένας ιδιοκτήτης στον πίνακα ελέγχου. Το GET /store_usage επιστρέφει το πακέτο, τα πραγματικά παραστατικά που μετρήθηκαν σε αυτή την περίοδο και το όριο, ώστε το κατάστημα να προειδοποιεί τον έμπορο από το 80% του ορίου. Πέρα από το όριο, το Tallio εκδίδει ακόμη 10% επιπλέον· σε εκείνο το σημείο οι νέες παραγγελίες παραλείπονται ως plan_cap_reached, και ο έμπορος τις επαναλαμβάνει μόλις αλλάξει το πακέτο ή αρχίσει η επόμενη περίοδος. Τα πιστωτικά, οι διορθώσεις και τα παραστατικά δοκιμαστικής λειτουργίας δεν μετρώνται ποτέ.

Όταν ένας αγοραστής ζητήσει τη διαγραφή του, το POST /erasures με store_orders (τα ids ord_… του) αφαιρεί τα προσωπικά δεδομένα του αγοραστή που κρατά το Tallio για κάθε παραγγελία: στα παραστατικά της, στα πιστωτικά και στις διορθώσεις των επιστροφών της, στο αίτημα τιμολογίου του αγοραστή και στα αιτήματα που καταγράφηκαν γι’ αυτήν. Ο πάροχος παραμένει το αρχείο των εκδομένων παραστατικών.