POS Posting API για κατασκευαστές ταμειακών
Το STRYK POS Posting API χρεώνει τις πωλήσεις της ταμειακής σου στους λογαριασμούς δωματίων εγγεγραμμένων επισκεπτών. Η αναφορά δείχνει τη σύνδεση, τη χρέωση, την ακύρωση και τα webhooks.
Contents
Επισκόπηση
Το API είναι διεπαφή από διακομιστή σε διακομιστή για χρεώσεις σε εγγεγραμμένα επισκέπτες. Το ξενοδοχείο συνδέει την ταμειακή σου στις Ρυθμίσεις στο POS: Σύνδεση ταμειακής. Εκεί η ταμειακή λαμβάνει ένα κλειδί και τη Διεύθυνση για την ταμειακή.
| Στοιχείο | Τιμή |
|---|---|
| Βασική διεύθυνση | https://app.staystryk.com/api/v1/pos/public (βασική διεύθυνση) |
| Σύνδεση | Κλειδί Bearer του ξενοδοχείου στην κεφαλίδα Authorization |
| Προϋπόθεση | Το ξενοδοχείο έχει ενεργό το πρόσθετο STRYK POS |
| Χωρίς πρόσθετο | Κάθε κλήση απαντά με 403 και τον κωδικό module_disabled. Το STRYK δεν γράφει χρέωση. |
| Όριο κλήσεων | 100 αιτήματα ανά 60 δευτερόλεπτα και κλειδί. Μετά το STRYK απαντά με 429. |
| Έκδοση της περιγραφής | 1.3.0 |
Κλειδί και ασφάλεια
- Το κλειδί ξεκινά με
pos_live_. Το ξενοδοχείο το βλέπει μόνο μία φορά, όταν δημιουργείται. - Στείλε το αποκλειστικά από την πλευρά του διακομιστή μέσω HTTPS στην κεφαλίδα:
Authorization: Bearer <vollständiger Schlüssel>. Ποτέ ως παράμετρο στη διεύθυνση. - Ένα κλειδί ανήκει σε ακριβώς ένα ξενοδοχείο και προαιρετικά σε ένα outlet. Το ξενοδοχείο δημιουργεί ένα κλειδί για κάθε σύνδεση.
- Το 401 σημαίνει ότι το STRYK δεν μπόρεσε να ελέγξει το κλειδί. Έλεγξε τη ρύθμιση και την κατάσταση λειτουργίας. Μην αλλάζεις το κλειδί αυτόματα.
- Ένα νέο κλειδί είναι νέα περιοχή ιδεμποτέντ. Δεν βρίσκει και δεν ακυρώνει χρεώσεις του παλιού κλειδιού. Ολοκλήρωσε τις ανοιχτές εργασίες και αντιστοίχισέ τες, πριν το ξενοδοχείο ανακαλέσει το παλιό κλειδί.
- Αν ένα κλειδί χαθεί ή διαρρεύσει, το ξενοδοχείο το ανακαλεί με Ανάκληση κλειδιού και ελέγχει τις ύποπτες ενέργειες στο STRYK, πριν η ταμειακή σου στείλει αντικατάσταση.
Λογαριασμός δωματίου και ποσά
| Μέθοδος και διαδρομή | Σκοπός |
|---|---|
GET /ping (έλεγχος σύνδεσης) | Ελέγχει μόνο αν γίνεται δεκτό το κλειδί. |
GET /accounts (λογαριασμοί) | Εμφανίζει τους τρέχοντες λογαριασμούς δωματίων εγγεγραμμένων επισκεπτών, και τους κλειδωμένους. |
GET /room-lookup?room=105 (αναζήτηση δωματίου) | Αντιστοιχεί ένα δωμάτιο στην εγγεγραμμένη διαμονή. 404 χωρίς αντίστοιχο επισκέπτη, 409 αν το δωμάτιο είναι ασαφές. |
Ο λογαριασμός δωματίου περιέχει αυτά τα πεδία:
| Πεδίο | Σημασία |
|---|---|
bookingId, bookingNumber, guestName, roomNumber (πεδία) | Διαμονή και δωμάτιο |
allowPosting (πεδίο) | Το ξενοδοχείο έχει επιτρέψει χρεώσεις για τη διαμονή. Μόνο αυτό δεν αρκεί. |
allowCharge (πεδίο) | Συνολικός έλεγχος από την άδεια, το υπόλοιπο πίστωσης και τον κλειστό λογαριασμό. Έλεγξέ τον αμέσως πριν τη χρέωση. |
postingBlockReason (πεδίο) | no_post, credit_limit_reached, account_closed ή κενό |
openChargesCount, openChargesTotal, stayChargesTotal (πεδία) | Ανοιχτές χρεώσεις και άθροισμα των μη ακυρωμένων χρεώσεων |
creditLimit, remainingCredit, currency (πεδία) | Όριο, υπόλοιπο πίστωσης και νόμισμα του ξενοδοχείου |
Εμφάνισε επισκέπτη και δωμάτιο για επιβεβαίωση και στείλε το bookingId μαζί με το room. Μην κρατάς τη λίστα λογαριασμών ως μόνιμο κατάλογο επισκεπτών. Τα ποσά είναι αριθμοί JSON στο νόμισμα του ξενοδοχείου. Η στρογγυλοποίηση είναι HALF_UP: η ποσότητα στα τρία, τα ποσά στα δύο δεκαδικά ψηφία.
Χρέωση και επανάληψη
| Μέθοδος και διαδρομή | Σκοπός |
|---|---|
POST /charges (καταχώριση χρέωσης) | Χρεώνει μία χρέωση σε λογαριασμό δωματίου. Απάντηση 201 με τη χρέωση. |
POST /charges/batch (μαζική καταχώριση) | Χρεώνει 1 έως 50 χρεώσεις μαζί. Χρεώνονται είτε όλες οι νέες χρεώσεις είτε καμία. Η απάντηση ακολουθεί τη σειρά του αιτήματος. |
GET /charges/{externalRef} (λήψη χρέωσης) | Επιστρέφει τη μόνιμη κατάσταση μιας χρέωσης, και των cancelled και transferred. |
Πεδία μιας χρέωσης:
| Πεδίο | Υποχρεωτικό | Σημασία |
|---|---|---|
bookingId, room (πεδία) | τουλάχιστον ένα | Δωμάτιο ως κείμενο με γράμματα, όχι ως αριθμός. Αν δίνονται και τα δύο, πρέπει να ταιριάζουν. |
description (πεδίο) | ναι | 1 έως 500 χαρακτήρες |
unitPrice (πεδίο) | ναι | Μικτή τιμή ανά μονάδα, μεγαλύτερη από 0, το πολύ 99999.99 |
externalRef (πεδίο) | ναι | Μοναδικό κλειδί παραστατικού ή χρέωσης, 1 έως 255 χαρακτήρες, για παράδειγμα receipt-123-item-1 |
quantity (πεδίο) | όχι | 0,001 έως 9999, προεπιλογή 1 |
unit (πεδίο) | όχι | το πολύ 20 χαρακτήρες, προεπιλογή Stk. |
taxRate (πεδίο) | όχι | Ενεργός φορολογικός συντελεστής του ξενοδοχείου. Χωρίς τιμή ισχύει η προεπιλογή του outlet, και μετά η κεντρική. |
currency (πεδίο) | όχι | Πρέπει να είναι το νόμισμα του ξενοδοχείου |
outletId (πεδίο) | όχι | Σε κλειδί με outlet ισχύει αυτό το outlet. Άλλη τιμή δίνει 403. |
chargedAt (πεδίο) | όχι | Χρονική στιγμή της παροχής, προεπιλογή τώρα, το πολύ 5 λεπτά στο μέλλον |
notes, posRef (πεδία) | όχι | Σημείωση (1000 χαρακτήρες), αναφορά απόδειξης για τη ρεσεψιόν (100 χαρακτήρες) |
Το συνολικό ποσό από ποσότητα και τιμή μονάδας είναι μεγαλύτερο από 0 και το πολύ 99999999.99.
Το externalRef είναι το αμετάβλητο κλειδί ιδεμποτέντ του ξενοδοχείου και του κλειδιού. Μια ακριβής επανάληψη επιστρέφει την αρχική χρέωση με idempotentReplay=true. Αλλαγμένο περιεχόμενο ή ακυρωμένο κλειδί δίνει 409.
Μετά από timeout ή 5xx διαβάζεις πρώτα το GET /charges/{externalRef}. Μόνο όταν επιβεβαιωθεί 404, στέλνεις ξανά το ίδιο αίτημα αμετάβλητο, με το ίδιο κλειδί. Αποθήκευσε τα αιτήματα πριν την αποστολή και μην αλλάζεις ποτέ το chargedAt, την τιμή, τον φόρο ή την αναφορά. Αν η απάντηση δείχνει duplicateWarning, η χρέωση έχει ήδη καταχωριστεί. Αντιστοίχισέ την στο STRYK και μην στείλεις ξανά.
| Κατάσταση | Σημασία |
|---|---|
| 400 | Μη έγκυρα στοιχεία, διόρθωσέ τα. |
| 401 | Το κλειδί δεν μπορεί να ελεγχθεί |
| 403 | Περιοχή μη επιτρεπτή, για παράδειγμα λάθος outlet |
| 404 | Λογαριασμός ή χρέωση δεν υπάρχει |
| 409 | Σύγκρουση ως προς την επιχειρησιακή λογική. Έλεγξε τον κωδικό, μην επαναλαμβάνεις τυφλά. |
| 429 | Όριο κλήσεων, περίμενε τουλάχιστον 60 δευτερόλεπτα |
| 5xx | Πρώτα αντιστοίχισε, μετά επανάλαβε με περιορισμένη αναμονή |
Οι κωδικοί σφάλματος της απάντησης είναι μεταξύ άλλων pos_currency_mismatch, pos_external_ref_conflict, pos_external_ref_cancelled, pos_room_required, pos_guest_not_inhouse, pos_posting_blocked, pos_credit_limit_exceeded, pos_charge_already_invoiced και pos_account_closed. Μην διακλαδίζεις με βάση το γερμανικό κείμενο. Το requestId βοηθά την υποστήριξη.
Ακύρωση και τιμολόγιο
Το DELETE /charges/{externalRef} ακυρώνει μια ανοιχτή χρέωση του κλειδιού σου. Στο σώμα του αιτήματος μπορεί προαιρετικά να υπάρχει reason (έως 500 χαρακτήρες). Επανάληψη επιστρέφει ξανά την ακυρωμένη χρέωση.
- Η κατάσταση μιας χρέωσης είναι
open,cancelledήtransferred. - Μια χρέωση μένει
openμέχρι το check-out να δημιουργήσει το τιμολόγιο. Τότε το STRYK μεταφέρει τις ανοιχτές χρεώσεις σε γραμμές τιμολογίου και η κατάσταση γίνεταιtransferred. - Μεταφερμένη χρέωση δίνει 409 με
pos_charge_already_invoiced. Το ξενοδοχείο τη διορθώνει στη λογιστική: Διόρθωση τιμολογίου. - Η ακύρωση δεν διαγράφει τίποτα και δεν επιστρέφει χρήματα. Η ακυρωμένη χρέωση παραμένει ιχνηλάσιμη.
Το API χρεώνει θετικές χρεώσεις. Πληρωμές που ολοκληρώνονται στην ταμειακή δεν τις στέλνεις επιπλέον στο δωμάτιο. Σε μοιρασμένη πληρωμή στέλνεις μόνο το ανοιχτό μερίδιο του δωματίου, με σωστά κατανεμημένο φόρο. Εκπτώσεις τις αφαιρείς από τη μικτή τιμή πριν τη χρέωση.
Webhooks και αποδοχή
Το ξενοδοχείο δημιουργεί webhooks στις Ρυθμίσεις στο POS: Δημιουργία webhook.
| Στοιχείο | Τιμή |
|---|---|
| Συμβάντα | charge.posted, charge.cancelled, κατά τη δοκιμή ping |
Κεφαλίδα X-STRYK-Event | Όνομα συμβάντος |
Κεφαλίδα X-STRYK-Webhook-Id | ID του webhook, όχι της παράδοσης |
Κεφαλίδα X-STRYK-Signature | sha256= και HMAC-SHA-256 των αμετάβλητων bytes του αιτήματος. Μόνο με ρυθμισμένο μυστικό. |
| Σώμα | event, hotelId, timestamp, data με chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency και outlet |
| Απάντηση | 2xx μετά από μόνιμη αποδοχή μέσα σε 10 δευτερόλεπτα. Το STRYK δεν ακολουθεί ανακατευθύνσεις. |
| Επανάληψη | Μετά από 30 δευτερόλεπτα, 5 λεπτά, 30 λεπτά και 2 ώρες, μέχρι το αποθηκευμένο όριο |
Επαλήθευσε την υπογραφή στο αμετάβλητο σώμα, πριν το διαβάσεις ως JSON. Αποθήκευσε μόνιμα το event και το data.chargeId, για να αναγνωρίζεις επαναλήψεις. Οι παραδόσεις μπορεί να έρθουν διπλές ή με διαφορετική σειρά: ένα παλιό charge.posted δεν αντικαθιστά ένα charge.cancelled. Για check-in, check-out και μεταφορά τιμολογίου δεν υπάρχουν webhooks. Διάβασε εκεί ξανά την κατάσταση.
Λίστα αποδοχής με ένα δοκιμαστικό ξενοδοχείο και μια πραγματική δοκιμαστική διαμονή εγγεγραμμένου επισκέπτη:
- Έλεγξε
/pingκαι την αντιστοίχιση επισκέπτη και δωματίου, και σε κρατήσεις με πολλά δωμάτια. - Έλεγξε τον φόρο, το νόμισμα και τον περιορισμό outlet του κλειδιού.
- Ακριβής επανάληψη χωρίς διπλή χρέωση, αλλαγμένο περιεχόμενο με 409, χαμένη απάντηση με αντιστοίχιση.
- Batch ολόκληρο ή καθόλου, κλείδωμα και όριο, ακύρωση και επανάληψη ακύρωσης.
- Σύνολα τιμολογίου στο check-out και απόρριψη ακύρωσης μετά τη μεταφορά.
- Υπογεγραμμένο webhook, μη έγκυρη υπογραφή, διπλή και εναλλαγμένη παράδοση.
- Εμφάνιση σφαλμάτων, αλλαγή κλειδιού και αντιστοίχιση από το προσωπικό.
Τεχνική αναφορά
Η πλήρης περιγραφή υπάρχει ως αρχείο OpenAPI στα αγγλικά, ως YAML στο /developers/pos/openapi.yaml και ως JSON στο /developers/pos/openapi.json στον ιστότοπο του STRYK. Στο ξενοδοχείο, η Τεχνική τεκμηρίωση στην ενότητα Για τον τεχνικό της ταμειακής στις Ρυθμίσεις στο POS οδηγεί σε αυτή τη σελίδα.
| Μέθοδος | Διαδρομή | Σύντομη περιγραφή |
|---|---|---|
| GET (λήψη) | /ping (έλεγχος) | Έλεγχος σύνδεσης |
| GET (λήψη) | /accounts (λογαριασμοί) | Εμφάνιση εγγεγραμμένων λογαριασμών δωματίων |
| GET (λήψη) | /room-lookup (αναζήτηση δωματίου) | Εύρεση διαμονής για δωμάτιο |
| POST (αποστολή) | /charges (χρεώσεις) | Καταχώριση χρέωσης |
| POST (αποστολή) | /charges/batch (μαζική καταχώριση) | Μαζική χρέωση έως 50 χρεώσεων |
| GET (λήψη) | /charges/{externalRef} (λήψη χρέωσης) | Ανάγνωση κατάστασης μιας χρέωσης |
| DELETE (διαγραφή) | /charges/{externalRef} (διαγραφή χρέωσης) | Ακύρωση ανοιχτής χρέωσης |