Kalo te përmbajtja
Reference, STRYK POS

STRYK POS Posting API për prodhuesit e arkave

STRYK POS Posting API regjistron ngarkesat nga arka jote në llogaritë e dhomave të mysafirëve të check-in-uar. Referenca tregon regjistrimin, anulimin dhe webhook-et.

Last updated: Developers
Contents
  1. Përmbledhje
  2. Key-t dhe siguria
  3. Llogaria e dhomës dhe shumat
  4. Regjistrimi dhe riprovimi
  5. Anulimi dhe fatura
  6. Webhook-et dhe pranimi
  7. Referenca teknike

Përmbledhje

Ky API është ndërfaqe server-to-server për ngarkesat në qëndrimet e check-in-uara. Hoteli e lidh arkën tënde te Cilësimet nën POS: Lidh arkën. Aty arka merr një key dhe Adresa për arkën.

InformacioniVlera
Adresa bazëhttps://app.staystryk.com/api/v1/pos/public
RegjistrimiÇelësi Bearer i hotelit në header-in Authorization
Kushti paraprakHoteli ka modulin shtesë STRYK POS aktiv
Pa modulin shtesëÇdo thirrje përgjigjet me 403 dhe kodin module_disabled. STRYK nuk regjistron asnjë ngarkesë.
Kufiri i thirrjeve100 kërkesa për 60 sekonda për çdo key. Pas kësaj STRYK përgjigjet me 429.
Versioni i përshkrimit1.3.0

Key-t dhe siguria

  • Key-i fillon me pos_live_. Hoteli e sheh atë vetëm një herë kur e krijon.
  • Dërgoje vetëm nga serveri përmes HTTPS-it në header: Authorization: Bearer <vollständiger Schlüssel>. Kurrë si parametër në adresë.
  • Një key i përket saktësisht një hoteli dhe opsionalisht një outleti. Hoteli krijon një key për çdo lidhje.
  • 401 do të thotë: STRYK nuk arriti ta verifikojë key-in. Kontrollo konfigurimin dhe statusin e funksionimit. Mos e ndërro key-in automatikisht.
  • Një key i ri është një fushë e re idempotencës. Ai nuk i gjen dhe nuk i anulon ngarkesat e key-it të vjetër. Përfundo porositë e hapura dhe pajtoji ato, përpara se hoteli ta revokojë key-in e vjetër.
  • Nëse një key humbet ose komprometohet, hoteli e revokon me Revoko key-in dhe sqaron veprimet e pasigurta në STRYK, përpara se arka jote të dërgojë një zëvendësim.

Llogaria e dhomës dhe shumat

Metoda dhe shteguQëllimi
GET /pingKontrollon vetëm nëse key-i pranohet.
GET /accountsListon llogaritë e dhomave që janë aktualisht në check-in, edhe ato të bllokuara.
GET /room-lookup?room=105Gjen një dhomë te qëndrimi i check-in-uar. 404 nëse nuk ka mysafir përkatës, 409 nëse dhoma është e paqartë.

Llogaria e dhomës përmban këto fusha:

FushaKuptimi
bookingId, bookingNumber, guestName, roomNumberQëndrimi dhe dhoma
allowPostingHoteli ka lejuar ngarkesat për qëndrimin. Vetëm kjo nuk mjafton.
allowChargeKontrolli i plotë nga leja, limiti i mbetur dhe llogaria e mbyllur. Kontrolloje menjëherë përpara regjistrimit.
postingBlockReasonno_post, credit_limit_reached, account_closed ose bosh
openChargesCount, openChargesTotal, stayChargesTotalNgarkesat e hapura dhe shuma e ngarkesave jo të anuluara
creditLimit, remainingCredit, currencyLimiti, limiti i mbetur dhe monedha e hotelit

Shfaq mysafirin dhe dhomën për konfirmim dhe dërgo bookingId bashkë me room. Mos e mbaj listën e llogarive si drejtori të përhershme të mysafirëve. Shumat janë numra JSON në monedhën e hotelit. Rrumbullakimi është HALF_UP: sasia në tre shifra dhjetore, shumat në dy shifra dhjetore.

Regjistrimi dhe riprovimi

Metoda dhe shteguQëllimi
POST /chargesRegjistron një ngarkesë në llogarinë e dhomës. Përgjigja 201 me ngarkesën.
POST /charges/batchRegjistron 1 deri në 50 ngarkesa bashkë. Të gjitha ngarkesat e reja regjistrohen ose asnjëra. Përgjigja ndjek radhën e kërkesës.
GET /charges/{externalRef}Kthen gjendjen e qëndrueshme të një ngarkese, edhe cancelled dhe transferred.

Fushat e një regjistrimi:

FushaE detyrueshmeKuptimi
bookingId, roomtë paktën njëDhoma si tekst me shkronja, jo si numër. Nëse jepen të dyja, duhet të përputhen.
descriptionpo1 deri në 500 karaktere
unitPricepoÇmimi bruto për njësi, më i madh se 0, deri në 99999.99
externalRefpoÇelës unik i dokumentit ose i ngarkesës, 1 deri në 255 karaktere, për shembull receipt-123-item-1
quantityjo0,001 deri në 9999, parazgjedhja 1
unitjoderi në 20 karaktere, parazgjedhja Stk.
taxRatejoNorma tatimore aktive e hotelit. Pa dhënie vlen parazgjedhja e outletit, pastaj ajo qendrore.
currencyjoDuhet të jetë monedha e hotelit
outletIdjoTe një key me outlet vlen ky outlet. Një vlerë tjetër jep 403.
chargedAtjoKoha e shërbimit, parazgjedhja tani, deri në 5 minuta në të ardhmen
notes, posRefjoShënim (1000 karaktere), referencë fature për recepsionin (100 karaktere)

Shuma totale nga sasia dhe çmimi për njësi është më e madhe se 0 dhe deri në 99999999.99.

externalRef është çelësi i pandryshueshëm i idempotencës i hotelit dhe i key-it. Një përsëritje e saktë kthen ngarkesën origjinale me idempotentReplay=true. Një përmbajtje e ndryshuar ose një key i anuluar jep 409.

Pas timeout-it ose 5xx lexo fillimisht GET /charges/{externalRef}. Vetëm pas një 404 të konfirmuar dërgo të njëjtën kërkesë pa ndryshime me të njëjtin çelës. Ruaj kërkesat përpara dërgimit dhe mos ndrysho kurrë chargedAt, çmimin, taksën ose referencën. Nëse përgjigja tregon duplicateWarning, ngarkesa është regjistruar tashmë. Pajtoje në STRYK dhe mos dërgo përsëri.

StatusiKuptimi
400Të dhëna të pavlefshme, korrigjoji ato.
401Key-i nuk mund të verifikohet
403Fushë e palejuar, për shembull outlet i gabuar
404Llogaria ose ngarkesa nuk ekziston
409Konflikt funksional. Kontrollo kodin, mos provo verbërisht përsëri.
429Kufiri i thirrjeve, prit të paktën 60 sekonda
5xxFillimisht pajto, pastaj provo përsëri me backoff të kufizuar

Kodet e përgjigjes së gabimit janë, ndër të tjera, 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 dhe pos_account_closed. Mos e bëj logjikën sipas tekstit gjerman. requestId ndihmon mbështetjen.

Anulimi dhe fatura

DELETE /charges/{externalRef} anulon një ngarkesë të hapur të key-it tënd. Në body mund të jepet opsionalisht reason (deri në 500 karaktere). Një përsëritje kthen përsëri ngarkesën e anuluar.

  • Statusi i një ngarkese është open, cancelled ose transferred.
  • Një ngarkesë mbetet open, deri sa check-out-i të krijojë faturën. Atëherë STRYK merr ngarkesat e hapura si pozicione faturë dhe statusi kalon në transferred.
  • Një ngarkesë e marrë jep 409 me pos_charge_already_invoiced. Hoteli e korrigjon atë në kontabilitet: Korrigjo faturën.
  • Një anulim nuk fshin asgjë dhe nuk kthen para. Ngarkesa e anuluar mbetet e ndjekshme.

API regjistron vetëm ngarkesa pozitive. Pagesat që mbyllen në arkë nuk i dërgon edhe në dhomë. Te pagesa e ndarë dërgon vetëm pjesën e hapur të dhomës me taksën e shpërndarë siç duhet. Zbritjet i zbret nga çmimi bruto përpara regjistrimit.

Webhook-et dhe pranimi

Hoteli krijon webhook-et te Cilësimet nën POS: Krijo webhook-et.

InformacioniVlera
Ngjarjetcharge.posted, charge.cancelled, gjatë testimit ping
Header X-STRYK-EventEmri i ngjarjes
Header X-STRYK-Webhook-IdID e webhook-ut, jo e dërgimit
Header X-STRYK-Signaturesha256= dhe HMAC-SHA-256 i bajtëve të pandryshuar të kërkesës. Vetëm me sekretin e konfiguruar.
Bodyevent, hotelId, timestamp, data me chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency dhe outlet
Përgjigja2xx pasi të pranohet përfundimisht brenda 10 sekondash. STRYK nuk ndjek ridrejtime.
PërsëritjaPas 30 sekondash, 5 minutash, 30 minutash dhe 2 orësh, deri në kufirin e ruajtur

Verifiko nënshkrimin mbi body-n e pandryshuar, përpara se ta lexosh si JSON. Ruaje përhershëm event dhe data.chargeId për të njohur përsëritjet. Dërgimet mund të vijnë të dyfishuara ose në rend tjetër: një charge.posted i vjetër nuk mbishkruan një charge.cancelled. Për check-in, check-out dhe marrjen e faturës nuk ka webhook-e. Lexo atje gjendjen përsëri.

Lista e pranimit me një hotel testues dhe një qëndrim testues real të check-in-uar:

  1. Kontrollo /ping dhe lidhjen mysafir dhe dhomë, edhe te rezervimet me disa dhoma.
  2. Kontrollo taksën, monedhën dhe kufizimin e outletit të key-it.
  3. Përsëritje e saktë pa dyfishim, përmbajtje e ndryshuar me 409, përgjigje e humbur me pajtim.
  4. Batch i plotë ose asgjë, bllokimi dhe limiti, anulimi dhe përsëritja e anulimit.
  5. Shumat e faturës në check-out dhe refuzimi i anulimit pas marrjes.
  6. Webhook i nënshkruar, nënshkrim i pavlefshëm, dërgim i dyfishtë dhe në rend të përzier.
  7. Shfaqja e gabimeve, ndërrimi i key-it dhe pajtimi nga personeli.

Referenca teknike

Përshkrimi i plotë ekziston si skedar OpenAPI në gjuhën angleze, si YAML te /developers/pos/openapi.yaml dhe si JSON te /developers/pos/openapi.json në faqen e STRYK. Në hotel, Dokumentacioni teknik në fushën Për teknikun e arkës te Cilësimet nën POS të çon në këtë faqe.

MetodaShteguPërshkrim i shkurtër
GET/pingKontrollo lidhjen
GET/accountsListo llogaritë e dhomave në check-in
GET/room-lookupGjej qëndrimin për një dhomë
POST/chargesRegjistro një ngarkesë
POST/charges/batchRegjistro deri në 50 ngarkesa bashkë
GET/charges/{externalRef}Lexo gjendjen e një ngarkese
DELETE/charges/{externalRef}Anulo një ngarkesë të hapur
Kontakti