Mine sisu juurde
Reference, STRYK POS

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.

Last updated: Developers
Contents
  1. Ülevaade
  2. Võtmed ja turvalisus
  3. Toakonto ja summad
  4. Kandmine ja kordamine
  5. Tühistamine ja arve
  6. Webhookid ja vastuvõtt
  7. Tehniline viide

Ü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.

AndmedVäärtus
Baasaadresshttps://app.staystryk.com/api/v1/pos/public
RegistreerimineHotelli Bearer-võti päises Authorization
EeldusHotellil on aktiivne lisamoodul STRYK POS
Ilma lisamoduligaIga päring saab vastuseks 403 ja koodi module_disabled. STRYK ei kanna ühtegi kannet.
Päringupiirang100 päringut 60 sekundi kohta ja võtme kohta. Pärast seda vastab STRYK koodiga 429.
Kirjelduse versioon1.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 teeEesmärk
GET /pingKontrollib ainult, kas võti on vastu võetud.
GET /accountsLoetleb praegu sisseregistreeritud toakontod, sealhulgas blokeeritud.
GET /room-lookup?room=105Seob toa sisseregistreeritud viibimisega. 404 ilma sobiva külaliseta, 409 mitmetähenduslikul toal.

Toakonto sisaldab neid välju:

VäliTähendus
bookingId, bookingNumber, guestName, roomNumberViibimine ja tuba
allowPostingHotell on lubanud viibimisele kanded. Ainuüksi sellest ei piisa.
allowChargeÜldkontroll, mis koosneb loast, jääklimiidist ja suletud kontost. Kontrolli seda vahetult enne kandmist.
postingBlockReasonno_post, credit_limit_reached, account_closed või tühi
openChargesCount, openChargesTotal, stayChargesTotalAvatud kanded ja tühistamata kannete summa
creditLimit, remainingCredit, currencyLimiit, 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 teeEesmärk
POST /chargesKannab ühe kande toakontole. Vastus 201 koos kandega.
POST /charges/batchKannab 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äliKohustuslikTähendus
bookingId, roomvähemalt üksTuba tekstina tähtedega, mitte arvuna. Kui on mõlemad, peavad need kokku sobima.
descriptionjah1 kuni 500 märki
unitPricejahBrutohind ühiku kohta, suurem kui 0, maksimaalselt 99999.99
externalRefjahAinulaadne dokumendi- või kandevõti, 1 kuni 255 märki, näiteks receipt-123-item-1
quantityei0,001 kuni 9999, vaikimisi 1
uniteikuni 20 märki, vaikimisi Stk.
taxRateeiHotelli aktiivne maksumäär. Kui seda ei anna, kehtib outleti vaikimisi, seejärel keskne.
currencyeiPeab olema hotelli valuuta
outletIdeiVõtme puhul, millel on outlet, kehtib see outlet. Muu väärtus annab 403.
chargedAteiTeenuse ajahetk, vaikimisi praegu, kõige rohkem 5 minutit tulevikus
notes, posRefeiMä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.

OlekTähendus
400Kehtetud andmed, paranda need.
401Võtit ei saa kontrollida
403Ala pole lubatud, näiteks vale outlet
404Kontot või kannet ei ole
409Sisuline konflikt. Kontrolli koodi, ära kordu pimesi.
429Päringupiirang, oota vähemalt 60 sekundit
5xxEsmalt 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, cancelled või transferred.
  • Kanne jääb open olekusse, kuni check-out loob arve. Seejärel võtab STRYK avatud kanded arve ridadele üle ja olek muutub transferred olekuks.
  • Ü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.

AndmedVäärtus
Sündmusedcharge.posted, charge.cancelled, testimisel ping
Päis X-STRYK-EventSündmuse nimi
Päis X-STRYK-Webhook-IdWebhooki ID, mitte edastuse ID
Päis X-STRYK-Signaturesha256= ja päringu muutmata baitide HMAC-SHA-256. Ainult seadistatud saladusega.
Kehaevent, hotelId, timestamp, data koos väljadega chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency ja outlet
Vastus2xx pärast püsivat vastuvõttu 10 sekundi jooksul. STRYK ei järgi ümbersuunamisi.
KordusPä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:

  1. Kontrolli /ping ning külalise ja toa seost, ka mitme toaga broneeringute puhul.
  2. Kontrolli võtme maksu, valuuta ja outletipiirangut.
  3. Täpne kordus ilma topeltkandeta, muudetud sisu 409-ga, kadunud vastus koos võrdlusega.
  4. Partii kas täielikult või mitte üldse, blokeering ja limiit, tühistamine ja tühistamise kordus.
  5. Arve summad check-outil ja tühistamise tagasilükkamine pärast üleviimist.
  6. Allkirjastatud webhook, kehtetu allkiri, topelt ja vahetatud järjekorras edastus.
  7. 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.

MeetodTeeLühikirjeldus
GET/pingÜhenduse kontrollimine
GET/accountsSisseregistreeritud toakontode loend
GET/room-lookupToa viibimise leidmine
POST/chargesKande kandmine
POST/charges/batchKuni 50 kande korraga kandmine
GET/charges/{externalRef}Kande oleku lugemine
DELETE/charges/{externalRef}Avatud kande tühistamine
Kontakt