Μετάβαση στο περιεχόμενο
Reference, STRYK POS

POS Posting API για κατασκευαστές ταμειακών

Το STRYK POS Posting API χρεώνει τις πωλήσεις της ταμειακής σου στους λογαριασμούς δωματίων εγγεγραμμένων επισκεπτών. Η αναφορά δείχνει τη σύνδεση, τη χρέωση, την ακύρωση και τα webhooks.

Last updated: Developers
Contents
  1. Επισκόπηση
  2. Κλειδί και ασφάλεια
  3. Λογαριασμός δωματίου και ποσά
  4. Χρέωση και επανάληψη
  5. Ακύρωση και τιμολόγιο
  6. Webhooks και αποδοχή
  7. Τεχνική αναφορά

Επισκόπηση

Το 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-IdID του webhook, όχι της παράδοσης
Κεφαλίδα X-STRYK-Signaturesha256= και 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. Διάβασε εκεί ξανά την κατάσταση.

Λίστα αποδοχής με ένα δοκιμαστικό ξενοδοχείο και μια πραγματική δοκιμαστική διαμονή εγγεγραμμένου επισκέπτη:

  1. Έλεγξε /ping και την αντιστοίχιση επισκέπτη και δωματίου, και σε κρατήσεις με πολλά δωμάτια.
  2. Έλεγξε τον φόρο, το νόμισμα και τον περιορισμό outlet του κλειδιού.
  3. Ακριβής επανάληψη χωρίς διπλή χρέωση, αλλαγμένο περιεχόμενο με 409, χαμένη απάντηση με αντιστοίχιση.
  4. Batch ολόκληρο ή καθόλου, κλείδωμα και όριο, ακύρωση και επανάληψη ακύρωσης.
  5. Σύνολα τιμολογίου στο check-out και απόρριψη ακύρωσης μετά τη μεταφορά.
  6. Υπογεγραμμένο webhook, μη έγκυρη υπογραφή, διπλή και εναλλαγμένη παράδοση.
  7. Εμφάνιση σφαλμάτων, αλλαγή κλειδιού και αντιστοίχιση από το προσωπικό.

Τεχνική αναφορά

Η πλήρης περιγραφή υπάρχει ως αρχείο 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} (διαγραφή χρέωσης)Ακύρωση ανοιχτής χρέωσης
Επικοινωνία