Σύνδεση καταστήματος

Η «Σύνδεση με το Tallio» είναι εξουσιοδότηση OAuth 2.0 με κωδικό εξουσιοδότησης (authorization code) και PKCE (S256). Ο κωδικός ταξιδεύει μέσω του browser· ο verifier δεν φεύγει ποτέ από τον διακομιστή του καταστήματος, οπότε ένας κωδικός μόνος του είναι άχρηστος.

• Αίτηση. Το κατάστημα κρατά ένα τυχαίο state και ένα code_verifier (43 έως 128 χαρακτήρες) και στέλνει τον browser του διαχειριστή του στη φιλοξενούμενη σελίδα του Tallio με το challenge. Το redirect_uri πρέπει να είναι ακριβώς το callback του καταστήματος κάτω από το URL του, τίποτε άλλο.
• Συναίνεση. Ο διαχειριστής συνδέεται στο Tallio ή εγγράφεται, και ένας ιδιοκτήτης της ομάδας εγκρίνει το κατάστημα, επιβεβαιώνοντας με δεύτερο παράγοντα ή με νέα σύνδεση. Στην πρώτη σύνδεση πληκτρολογεί επίσης τα φορολογικά στοιχεία της επιχείρησης, και το Tallio δημιουργεί τον έμπορό της.
• Επιστροφή. Ο browser επιστρέφει στο redirect_uri με το code και το ίδιο state, ή με error=access_denied όταν ο διαχειριστής ακυρώσει. Ο κωδικός ισχύει 10 λεπτά.
• Ανταλλαγή. Ο διακομιστής του καταστήματος καλεί το POST /store_grants/token με τον κωδικό, τον verifier και το ίδιο redirect_uri, δηλώνοντας τον εαυτό του στο Tallio-Store-Url. Η απάντηση, που δίνεται μία φορά, περιέχει τον έμπορο, την ομάδα, τα δύο κλειδιά και τα μυστικά των endpoints webhook του καταστήματος.

Κάθε ανταλλαγή που απορρίπτεται παίρνει το ίδιο 400 invalid_grant, όποια κι αν είναι η αιτία. Μην επαναλαμβάνετε ποτέ μια επιτυχημένη ανταλλαγή: αν ανταλλάξετε ξανά έναν χρησιμοποιημένο κωδικό με τον verifier του, ανακαλούνται τα κλειδιά που έδωσε, αφού μια επανάληψη σημαίνει ότι ο κωδικός διέρρευσε. Αν χαθεί η απάντηση, συνδέστε ξανά το κατάστημα.

Περάστε τη γλώσσα του διαχειριστή στο locale (el, fr_FR, en_US): η σελίδα εισόδου και η σελίδα συναίνεσης την ακολουθούν όταν το Tallio την υποστηρίζει, μόνο για εκείνη τη συνεδρία. Μια άγνωστη τιμή ή μια τιμή που λείπει δεν απορρίπτει ποτέ το αίτημα.

Η ανταλλαγή δίνει πάντα δοκιμαστικό κλειδί, και πραγματικό κλειδί μόνο για κατάστημα σε παραγωγή. Στείλτε το store_environment (production, staging, development, local): οτιδήποτε εκτός από production παίρνει μόνο δοκιμαστικό κλειδί, όπως και ένας host ανάπτυξης (localhost, .test, μια ιδιωτική διεύθυνση, ένα δημόσιο tunnel). Ένα δοκιμαστικό κλειδί εκδίδει μέσω της δοκιμαστικής σύνδεσης του εμπόρου ή, αν δεν υπάρχει, μέσω του sandbox του Tallio.

Τα κλειδιά ενός καταστήματος είναι δεσμευμένα στο URL του. Στείλτε το στο Tallio-Store-Url σε κάθε κλήση: άλλη τιμή, ή καμία, δίνει 409 store_url_mismatch. Η δέσμευση αυτή εμποδίζει ένα αντίγραφο staging του καταστήματος να εκδίδει πραγματικά παραστατικά με αντιγραμμένες ρυθμίσεις· το URL δεν είναι μυστικό. Όταν το κατάστημα πράγματι μεταφερθεί, ο διαχειριστής του επιβεβαιώνει τη μεταφορά και το κατάστημα στέλνει το νέο του URL στο PUT /store_binding· όσο το κατάστημα έχει πραγματικό κλειδί, μόνο αυτό το κλειδί μπορεί να το μεταφέρει.

Ένα κλειδί καταστήματος φτάνει μόνο στις λειτουργίες του παρακάτω πίνακα, και μόνο για τον δικό του έμπορο: τα ids άλλου εμπόρου απαντούν 404, σαν να μην υπήρχαν. Κάθε άλλη λειτουργία δίνει 403 restricted_key: ένα κλειδί καταστήματος δεν μπορεί να δημιουργήσει εμπόρους, να δει τη λίστα συμβάντων, να διαχειριστεί endpoints webhook ή κλειδιά, ούτε να φτάσει στον διακομιστή MCP.

Όταν το κατάστημα αποσυνδέεται ή το πρόσθετο αφαιρείται, το κατάστημα παραιτείται από κάθε κλειδί με το DELETE /api_keys/current. Ένας ιδιοκτήτης της ομάδας μπορεί επίσης να ανακαλέσει τα κλειδιά του καταστήματος από τον πίνακα ελέγχου· μια νέα σύνδεση αντικαθιστά τα παλιά κλειδιά.