Pereiti prie turinio
Reference, STRYK POS

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.

Last updated: Developers
Contents
  1. Apžvalga
  2. Raktas ir saugumas
  3. Kambario sąskaita ir sumos
  4. Įrašymas ir kartojimas
  5. Storno ir sąskaita
  6. Webhook'ai ir priėmimas
  7. Techninė nuoroda

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.

NurodymasReikšmė
Bazinis adresashttps://app.staystryk.com/api/v1/pos/public
RegistracijaViešbučio Bearer raktas antraštėje Authorization
SąlygaViešbučiui aktyvus papildomas modulis STRYK POS
Be papildomo modulioKiekvienas kvietimas atsako 403 ir kodu module_disabled. STRYK neįrašo jokio įrašo.
Kvietimų riba100 užklausų per 60 sekundžių kiekvienam raktui. Vėliau STRYK atsako 429.
Aprašymo versija1.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 keliasPaskirtis
GET /pingTik patikrina, ar raktas priimamas.
GET /accountsIšvardija dabar įregistruotas kambarių sąskaitas, įskaitant užblokuotas.
GET /room-lookup?room=105Susieja kambarį su įregistruotu apgyvendinimu. 404 be atitinkamo svečio, 409 esant dviprasmiškam kambariui.

Kambario sąskaita turi šiuos laukus:

LaukasReikšmė
bookingId, bookingNumber, guestName, roomNumberApgyvendinimas ir kambarys
allowPostingViešbutis leido įrašus šiam apgyvendinimui. Vien to nepakanka.
allowChargeBendras patikrinimas pagal leidimą, likusį limitą ir uždarytą sąskaitą. Tikrink jį prieš pat įrašymą.
postingBlockReasonno_post, credit_limit_reached, account_closed arba tuščia
openChargesCount, openChargesTotal, stayChargesTotalAtviri įrašai ir nestornuotų įrašų suma
creditLimit, remainingCredit, currencyLimitas, 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 keliasPaskirtis
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:

LaukasPrivalomasReikšmė
bookingId, roombent vienasKambarys kaip tekstas su raidėmis, ne kaip skaičius. Jei nurodyti abu, jie turi sutapti.
descriptiontaip1 iki 500 simbolių
unitPricetaipBruto kaina vienam vienetui, didesnė už 0, ne daugiau kaip 99999.99
externalReftaipUnikalus čekio arba įrašo raktas, 1 iki 255 simbolių, pavyzdžiui receipt-123-item-1
quantityne0,001 iki 9999, numatytasis 1
unitnene daugiau kaip 20 simbolių, numatytasis Stk.
taxRateneAktyvus viešbučio PVM tarifas. Jei nenurodytas, galioja pardavimo vietos numatytasis, paskui centrinis.
currencyneTuri būti viešbučio valiuta
outletIdneRaktui su pardavimo vieta galioja ši pardavimo vieta. Kita reikšmė duoda 403.
chargedAtnePaslaugos laikas, numatytasis dabar, ne daugiau kaip 5 minutes ateityje
notes, posRefnePastaba (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ūsenaReikšmė
400Neteisingi duomenys, ištaisyk juos.
401Raktas negali būti patikrintas
403Sritis neleidžiama, pavyzdžiui, neteisinga pardavimo vieta
404Sąskaita arba įrašas nerastas
409Dalykinis konfliktas. Patikrink kodą ir nekartok aklai.
429Kvietimų riba, palauk bent 60 sekundžių
5xxPirmiausia 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, cancelled arba transferred.
  • Į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.

NurodymasReikšmė
Įvykiaicharge.posted, charge.cancelled, bandymo metu ping
Antraštė X-STRYK-EventĮvykio pavadinimas
Antraštė X-STRYK-Webhook-IdWebhook'o ID, ne pristatymo
Antraštė X-STRYK-Signaturesha256= ir HMAC-SHA-256 nepakeistų užklausos baitų. Tik su sukonfigūruotu slaptu raktu.
Turinysevent, hotelId, timestamp, data su chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency ir pardavimo vieta
Atsakymas2xx po patvirtinto priėmimo per 10 sekundžių. STRYK nesekia peradresavimų.
PakartojimasPo 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:

  1. Patikrink /ping ir svečio bei kambario priskyrimą, taip pat rezervacijoms su keliais kambariais.
  2. Patikrink mokestį, valiutą ir raktui taikomą pardavimo vietos apribojimą.
  3. Tiksli pakartojimas be dvigubo įrašo, pakeistas turinys su 409, prarastas atsakymas su suderinimu.
  4. Paketas visas arba nė vienas, blokavimas ir limitas, storno ir storno pakartojimas.
  5. Sąskaitų sumos check-out metu ir storno atmetimas po perėmimo.
  6. Pasirašytas webhook'as, neteisingas parašas, dvigubas ir sukeistas pristatymas.
  7. 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į.

MetodasKeliasTrumpas aprašymas
GET/pingPatikrinti ryšį
GET/accountsIšvardyti įregistruotas kambarių sąskaitas
GET/room-lookupRasti 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šą
Kontaktas