POS Posting API kasų gamintojams
STRYK POS Posting API įrašo kasos įrašus į apgyvendintų svečių kambarių sąskaitas. Nuorodoje rasi registraciją, įrašymą, storno ir webhook'us.
Contents
Apžvalga
API yra serverio su serveriu sąsaja įrašams į įregistruotus apgyvendinimus. Viešbutis sujungia tavo kasą skiltyje Nustatymai ir POS: Prijungti kasą. Ten kasa gauna raktą ir Adresas kasai.
| Nurodymas | Reikšmė |
|---|---|
| Bazinis adresas | https://app.staystryk.com/api/v1/pos/public |
| Registracija | Viešbučio Bearer raktas antraštėje Authorization |
| Sąlyga | Viešbučiui aktyvus papildomas modulis STRYK POS |
| Be papildomo modulio | Kiekvienas kvietimas atsako 403 ir kodu module_disabled. STRYK neįrašo jokio įrašo. |
| Kvietimų riba | 100 užklausų per 60 sekundžių kiekvienam raktui. Vėliau STRYK atsako 429. |
| Aprašymo versija | 1.3.0 |
Raktas ir saugumas
- Raktas prasideda
pos_live_. Viešbutis jį mato tik vieną kartą kuriant. - Siųsk jį tik serveryje per HTTPS antraštėje:
Authorization: Bearer <vollständiger Schlüssel>. Niekada kaip parametrą adrese. - Raktas priklauso vienam viešbučiui ir pasirinktinai vienai pardavimo vietai. Viešbutis kuria raktą kiekvienam ryšiui.
- 401 reiškia, kad STRYK negalėjo patikrinti rakto. Patikrink konfigūraciją ir veikimo būseną. Raktą automatiškai nekeisk.
- Naujas raktas yra nauja idempotentiškumo sritis. Jis neranda ir nestornuoja senojo rakto įrašų. Baik atviras užduotis ir suderink jas, prieš viešbučiui atšaukiant senąjį raktą.
- Jei raktas prarastas arba kompromituotas, viešbutis jį atšaukia su Atšaukti API raktą ir STRYK sutvarko nesaugias operacijas, prieš tavo kasai siunčiant pakaitinį raktą.
Kambario sąskaita ir sumos
| Metodas ir kelias | Paskirtis |
|---|---|
GET /ping | Tik patikrina, ar raktas priimamas. |
GET /accounts | Išvardija dabar įregistruotas kambarių sąskaitas, įskaitant užblokuotas. |
GET /room-lookup?room=105 | Susieja kambarį su įregistruotu apgyvendinimu. 404 be atitinkamo svečio, 409 esant dviprasmiškam kambariui. |
Kambario sąskaita turi šiuos laukus:
| Laukas | Reikšmė |
|---|---|
bookingId, bookingNumber, guestName, roomNumber | Apgyvendinimas ir kambarys |
allowPosting | Viešbutis leido įrašus šiam apgyvendinimui. Vien to nepakanka. |
allowCharge | Bendras patikrinimas pagal leidimą, likusį limitą ir uždarytą sąskaitą. Tikrink jį prieš pat įrašymą. |
postingBlockReason | no_post, credit_limit_reached, account_closed arba tuščia |
openChargesCount, openChargesTotal, stayChargesTotal | Atviri įrašai ir nestornuotų įrašų suma |
creditLimit, remainingCredit, currency | Limitas, likęs limitas ir viešbučio valiuta |
Parodyk svečią ir kambarį patvirtinimui ir siųsk bookingId kartu su room. Nelaikyk sąskaitų sąrašo kaip nuolatinio svečių katalogo. Sumos yra JSON skaičiai viešbučio valiuta. Apvalinimas yra HALF_UP: kiekis iki trijų, sumos iki dviejų skaitmenų po kablelio.
Įrašymas ir kartojimas
| Metodas ir kelias | Paskirtis |
|---|---|
POST /charges | Įrašo vieną įrašą į kambario sąskaitą. Atsakymas 201 su įrašu. |
POST /charges/batch | Įrašo nuo 1 iki 50 įrašų kartu. Visi nauji įrašai įrašomi arba nė vienas. Atsakymas seka užklausos tvarką. |
GET /charges/{externalRef} | Pateikia nuolatinę įrašo būseną, įskaitant cancelled ir transferred. |
Įrašo laukai:
| Laukas | Privalomas | Reikšmė |
|---|---|---|
bookingId, room | bent vienas | Kambarys kaip tekstas su raidėmis, ne kaip skaičius. Jei nurodyti abu, jie turi sutapti. |
description | taip | 1 iki 500 simbolių |
unitPrice | taip | Bruto kaina vienam vienetui, didesnė už 0, ne daugiau kaip 99999.99 |
externalRef | taip | Unikalus čekio arba įrašo raktas, 1 iki 255 simbolių, pavyzdžiui receipt-123-item-1 |
quantity | ne | 0,001 iki 9999, numatytasis 1 |
unit | ne | ne daugiau kaip 20 simbolių, numatytasis Stk. |
taxRate | ne | Aktyvus viešbučio PVM tarifas. Jei nenurodytas, galioja pardavimo vietos numatytasis, paskui centrinis. |
currency | ne | Turi būti viešbučio valiuta |
outletId | ne | Raktui su pardavimo vieta galioja ši pardavimo vieta. Kita reikšmė duoda 403. |
chargedAt | ne | Paslaugos laikas, numatytasis dabar, ne daugiau kaip 5 minutes ateityje |
notes, posRef | ne | Pastaba (1000 simbolių), čekio nuoroda recepcijai (100 simbolių) |
Bendra suma iš kiekio ir vieneto kainos yra didesnė už 0 ir ne didesnė kaip 99999999.99.
externalRef yra nekintamas viešbučio ir rakto idempotentiškumo raktas. Tiksli pakartojimas grąžina pradinį įrašą su idempotentReplay=true. Pakeistas turinys arba atšauktas raktas duoda 409.
Po pasibaigusio laiko arba 5xx pirmiausia skaityk GET /charges/{externalRef}. Tik patvirtinus 404 siųsk tą pačią užklausą be pakeitimų su tuo pačiu raktu. Išsaugok užklausas prieš siuntimą ir niekada nekeisk chargedAt, kainos, mokesčio ar nuorodos. Jei atsakyme yra duplicateWarning, įrašas jau užregistruotas. Suderink jį STRYK sistemoje ir nesiųsk iš naujo.
| Būsena | Reikšmė |
|---|---|
| 400 | Neteisingi duomenys, ištaisyk juos. |
| 401 | Raktas negali būti patikrintas |
| 403 | Sritis neleidžiama, pavyzdžiui, neteisinga pardavimo vieta |
| 404 | Sąskaita arba įrašas nerastas |
| 409 | Dalykinis konfliktas. Patikrink kodą ir nekartok aklai. |
| 429 | Kvietimų riba, palauk bent 60 sekundžių |
| 5xx | Pirmiausia suderink, tada kartok su ribotu laukimu |
Klaidų atsakymo kodai yra tarp kita ko 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 ir pos_account_closed. Nesirink veiksmų pagal vokišką tekstą. requestId padeda palaikymo komandai.
Storno ir sąskaita
DELETE /charges/{externalRef} storuoja atvirą tavo rakto įrašą. Turinyje pasirinktinai nurodomas reason (ne daugiau kaip 500 simbolių). Pakartojimas grąžina storno įrašą dar kartą.
- Įrašo būsena yra
open,cancelledarbatransferred. - Įrašas lieka
open, kol check-out sukuria sąskaitą. Tada STRYK perima atvirus įrašus į sąskaitos pozicijas ir būsena pereina įtransferred. - Perimtas įrašas duoda 409 su
pos_charge_already_invoiced. Viešbutis jį ištaiso buhalterijoje: Sąskaitos faktūros ištaisymas. - Storno nieko neištrina ir nieko negrąžina. Storno įrašas lieka atsekamas.
API įrašo tik teigiamus įrašus. Mokėjimų, kurie užbaigiami kasoje, į kambarį nesiųsk papildomai. Dalinio mokėjimo atveju siųsk tik atvirą kambario dalį su teisingai paskirstytu mokesčiu. Nuolaidas atimk iš bruto kainos prieš įrašymą.
Webhook'ai ir priėmimas
Viešbutis kuria webhook'us skiltyje Nustatymai ir POS: Sukurti webhook'us.
| Nurodymas | Reikšmė |
|---|---|
| Įvykiai | charge.posted, charge.cancelled, bandymo metu ping |
Antraštė X-STRYK-Event | Įvykio pavadinimas |
Antraštė X-STRYK-Webhook-Id | Webhook'o ID, ne pristatymo |
Antraštė X-STRYK-Signature | sha256= ir HMAC-SHA-256 nepakeistų užklausos baitų. Tik su sukonfigūruotu slaptu raktu. |
| Turinys | event, hotelId, timestamp, data su chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency ir pardavimo vieta |
| Atsakymas | 2xx po patvirtinto priėmimo per 10 sekundžių. STRYK nesekia peradresavimų. |
| Pakartojimas | Po 30 sekundžių, 5 minučių, 30 minučių ir 2 valandų, iki išsaugotos ribos |
Patikrink parašą pagal nepakeistą turinį prieš skaitydamas jį kaip JSON. Nuolat išsaugok event ir data.chargeId, kad atpažintum pakartojimus. Pristatymai gali ateiti dvigubai arba kita tvarka: senas charge.posted nepakeičia charge.cancelled. Check-in, check-out ir sąskaitų perėmimui webhook'ų nėra. Ten perskaityk būseną iš naujo.
Priėmimo sąrašas su testiniu viešbučiu ir tikru įregistruotu testiniu apgyvendinimu:
- Patikrink
/pingir svečio bei kambario priskyrimą, taip pat rezervacijoms su keliais kambariais. - Patikrink mokestį, valiutą ir raktui taikomą pardavimo vietos apribojimą.
- Tiksli pakartojimas be dvigubo įrašo, pakeistas turinys su 409, prarastas atsakymas su suderinimu.
- Paketas visas arba nė vienas, blokavimas ir limitas, storno ir storno pakartojimas.
- Sąskaitų sumos check-out metu ir storno atmetimas po perėmimo.
- Pasirašytas webhook'as, neteisingas parašas, dvigubas ir sukeistas pristatymas.
- Klaidų rodymas, rakto keitimas ir personalo suderinimas.
Techninė nuoroda
Visas aprašymas yra OpenAPI faile anglų kalba, kaip YAML adresu /developers/pos/openapi.yaml ir kaip JSON adresu /developers/pos/openapi.json STRYK svetainėje. Viešbutyje Techninė dokumentacija skiltyje Kasos technikui puslapyje Nustatymai ir POS veda į šį puslapį.
| Metodas | Kelias | Trumpas aprašymas |
|---|---|---|
| GET | /ping | Patikrinti ryšį |
| GET | /accounts | Išvardyti įregistruotas kambarių sąskaitas |
| GET | /room-lookup | Rasti apgyvendinimą pagal kambarį |
| POST | /charges | Įrašyti vieną įrašą |
| POST | /charges/batch | Įrašyti iki 50 įrašų kartu |
| GET | /charges/{externalRef} | Perskaityti įrašo būseną |
| DELETE | /charges/{externalRef} | Storno atvirą įrašą |