POS Posting API kassatootjatele
STRYK POS Posting API kannab sinu kassast kanded sisseregistreeritud külaste toakontodele. Viide näitab registreerimist, kandmist, tühistamist ja webhooke.
Contents
Ülevaade
API on serverist serverisse liides kannetele, mis tehakse sisseregistreeritud viibimistele. Hotell ühendab sinu kassa lehel Seaded all POS: Kassa ühendamine. Seal saab kassa võtme ja aadressi jaotisest Kassa aadress.
| Andmed | Väärtus |
|---|---|
| Baasaadress | https://app.staystryk.com/api/v1/pos/public |
| Registreerimine | Hotelli Bearer-võti päises Authorization |
| Eeldus | Hotellil on aktiivne lisamoodul STRYK POS |
| Ilma lisamoduliga | Iga päring saab vastuseks 403 ja koodi module_disabled. STRYK ei kanna ühtegi kannet. |
| Päringupiirang | 100 päringut 60 sekundi kohta ja võtme kohta. Pärast seda vastab STRYK koodiga 429. |
| Kirjelduse versioon | 1.3.0 |
Võtmed ja turvalisus
- Võti algab tähega
pos_live_. Hotell näeb seda ainult üks kord loomisel. - Saada see ainult serveripoolselt HTTPS-i kaudu päises:
Authorization: Bearer <vollständiger Schlüssel>. Ära kunagi aadressis parameetrina. - Võti kuulub täpselt ühele hotellile ja valikuliselt ühele outletile. Hotell loob ühenduse kohta ühe võtme.
- 401 tähendab, et STRYK ei suutnud võtit kontrollida. Kontrolli seadistust ja töö olekut. Ära vaheta võtit automaatselt.
- Uus võti on uus idempotentsusala. See ei leia ega tühista vana võtme kandeid. Töötle avatud tellimused ja võrdle need läbi enne, kui hotell vana võtme tühistab.
- Kui võti on kadunud või kompromiteeritud, tühistab hotell selle nupuga Tühista võti ja selgitab STRYKis ebakindlad toimingud enne, kui sinu kassa saadab asendusvõtme.
Toakonto ja summad
| Meetod ja tee | Eesmärk |
|---|---|
GET /ping | Kontrollib ainult, kas võti on vastu võetud. |
GET /accounts | Loetleb praegu sisseregistreeritud toakontod, sealhulgas blokeeritud. |
GET /room-lookup?room=105 | Seob toa sisseregistreeritud viibimisega. 404 ilma sobiva külaliseta, 409 mitmetähenduslikul toal. |
Toakonto sisaldab neid välju:
| Väli | Tähendus |
|---|---|
bookingId, bookingNumber, guestName, roomNumber | Viibimine ja tuba |
allowPosting | Hotell on lubanud viibimisele kanded. Ainuüksi sellest ei piisa. |
allowCharge | Üldkontroll, mis koosneb loast, jääklimiidist ja suletud kontost. Kontrolli seda vahetult enne kandmist. |
postingBlockReason | no_post, credit_limit_reached, account_closed või tühi |
openChargesCount, openChargesTotal, stayChargesTotal | Avatud kanded ja tühistamata kannete summa |
creditLimit, remainingCredit, currency | Limiit, jääklimiit ja hotelli valuuta |
Näita kinnitamiseks külalist ja tuba ning saada bookingId koos väärtusega room. Ära hoia kontode loendit pidevalt külaliste kataloogina. Summad on JSON-arvud hotelli valuutas. Ümardus on HALF_UP: kogus kolme ja summad kahe komakohani.
Kandmine ja kordamine
| Meetod ja tee | Eesmärk |
|---|---|
POST /charges | Kannab ühe kande toakontole. Vastus 201 koos kandega. |
POST /charges/batch | Kannab korraga 1 kuni 50 kannet. Kõik uued kanded kantakse või ei kanta ühtegi. Vastus järgib päringu järjekorda. |
GET /charges/{externalRef} | Tagastab kande püsiva oleku, sealhulgas cancelled ja transferred. |
Kande väljad:
| Väli | Kohustuslik | Tähendus |
|---|---|---|
bookingId, room | vähemalt üks | Tuba tekstina tähtedega, mitte arvuna. Kui on mõlemad, peavad need kokku sobima. |
description | jah | 1 kuni 500 märki |
unitPrice | jah | Brutohind ühiku kohta, suurem kui 0, maksimaalselt 99999.99 |
externalRef | jah | Ainulaadne dokumendi- või kandevõti, 1 kuni 255 märki, näiteks receipt-123-item-1 |
quantity | ei | 0,001 kuni 9999, vaikimisi 1 |
unit | ei | kuni 20 märki, vaikimisi Stk. |
taxRate | ei | Hotelli aktiivne maksumäär. Kui seda ei anna, kehtib outleti vaikimisi, seejärel keskne. |
currency | ei | Peab olema hotelli valuuta |
outletId | ei | Võtme puhul, millel on outlet, kehtib see outlet. Muu väärtus annab 403. |
chargedAt | ei | Teenuse ajahetk, vaikimisi praegu, kõige rohkem 5 minutit tulevikus |
notes, posRef | ei | Märkus (1000 märki), dokumendi viide vastuvõtule (100 märki) |
Kogusumma koguse ja ühikuhinna järgi on suurem kui 0 ja kõige rohkem 99999999.99.
externalRef on hotelli ja võtme muutumatu idempotentsusvõti. Täpne kordus annab algse kande väärtusega idempotentReplay=true. Muudetud sisu või tühistatud võti annab 409.
Pärast ajalõppu või 5xx-viga loe sa esmalt GET /charges/{externalRef}. Saada sama päring muutmata kujul sama võtmega uuesti ainult siis, kui 404 on kinnitatud. Salvesta päringud enne saatmist ja ära kunagi muuda chargedAt, hinda, maksu ega viidet. Kui vastus näitab duplicateWarning, on kanne juba kantud. Võrdle see STRYKis läbi ja ära saada uuesti.
| Olek | Tähendus |
|---|---|
| 400 | Kehtetud andmed, paranda need. |
| 401 | Võtit ei saa kontrollida |
| 403 | Ala pole lubatud, näiteks vale outlet |
| 404 | Kontot või kannet ei ole |
| 409 | Sisuline konflikt. Kontrolli koodi, ära kordu pimesi. |
| 429 | Päringupiirang, oota vähemalt 60 sekundit |
| 5xx | Esmalt võrdle, seejärel proovi uuesti piiratud ooteajaga |
Vastuse veakoodid on muu hulgas 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 ja pos_account_closed. Ära tee harusid saksakeelse teksti järgi. requestId aitab tugiteenust.
Tühistamine ja arve
DELETE /charges/{externalRef} tühistab sinu võtme avatud kande. Kehas on valikuliselt reason (kuni 500 märki). Kordus annab tühistatud kande uuesti.
- Kande olek on
open,cancelledvõitransferred. - Kanne jääb
openolekusse, kuni check-out loob arve. Seejärel võtab STRYK avatud kanded arve ridadele üle ja olek muutubtransferredolekuks. - Üleviidud kanne annab 409 koodiga
pos_charge_already_invoiced. Hotell parandab selle raamatupidamises: Arve parandamine. - Tühistamine ei kustuta midagi ega tagasta raha. Tühistatud kanne jääb jälgitavaks.
API kannab positiivseid kandeid. Makseid, mis kassas lõpetatakse, ei saada lisaks toale. Jagatud maksmise korral saada ainult avatud toaosa õigesti jaotatud maksuga. Soodustused lahuta brutohinnast enne kandmist.
Webhookid ja vastuvõtt
Hotell loob webhookid lehel Seaded all POS: Webhookide lisamine.
| Andmed | Väärtus |
|---|---|
| Sündmused | charge.posted, charge.cancelled, testimisel ping |
Päis X-STRYK-Event | Sündmuse nimi |
Päis X-STRYK-Webhook-Id | Webhooki ID, mitte edastuse ID |
Päis X-STRYK-Signature | sha256= ja päringu muutmata baitide HMAC-SHA-256. Ainult seadistatud saladusega. |
| Keha | event, hotelId, timestamp, data koos väljadega chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency ja outlet |
| Vastus | 2xx pärast püsivat vastuvõttu 10 sekundi jooksul. STRYK ei järgi ümbersuunamisi. |
| Kordus | Pärast 30 sekundit, 5 minutit, 30 minutit ja 2 tundi, kuni salvestatud piirini |
Kontrolli allkirja muutmata kehal enne, kui loed seda JSONina. Salvesta event ja data.chargeId püsivalt, et tuvastada kordused. Edastused võivad tulla topelt või vales järjekorras: vana charge.posted ei kirjuta üle charge.cancelled olekut. Sisse- ja väljaregistreerimise ning arve üleviimise kohta webhooke ei ole. Loe seal olek uuesti.
Vastuvõtu kontrollnimekiri testhotelli ja tõelise sisseregistreeritud testviibimisega:
- Kontrolli
/pingning külalise ja toa seost, ka mitme toaga broneeringute puhul. - Kontrolli võtme maksu, valuuta ja outletipiirangut.
- Täpne kordus ilma topeltkandeta, muudetud sisu 409-ga, kadunud vastus koos võrdlusega.
- Partii kas täielikult või mitte üldse, blokeering ja limiit, tühistamine ja tühistamise kordus.
- Arve summad check-outil ja tühistamise tagasilükkamine pärast üleviimist.
- Allkirjastatud webhook, kehtetu allkiri, topelt ja vahetatud järjekorras edastus.
- Veateade, võtmevahetus ja personali poolne võrdlus.
Tehniline viide
Täielik kirjeldus on ingliskeelse OpenAPI failina, YAML-ina aadressil /developers/pos/openapi.yaml ja JSON-ina aadressil /developers/pos/openapi.json STRYKi veebisaidil. Hotellis viib jaotis Tehniline dokumentatsioon jaotises Kassatehnikule lehel Seaded all POS sellele lehele.
| Meetod | Tee | Lühikirjeldus |
|---|---|---|
| GET | /ping | Ühenduse kontrollimine |
| GET | /accounts | Sisseregistreeritud toakontode loend |
| GET | /room-lookup | Toa viibimise leidmine |
| POST | /charges | Kande kandmine |
| POST | /charges/batch | Kuni 50 kande korraga kandmine |
| GET | /charges/{externalRef} | Kande oleku lugemine |
| DELETE | /charges/{externalRef} | Avatud kande tühistamine |