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.
Contents
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.
| Informacioni | Vlera |
|---|---|
| Adresa bazë | https://app.staystryk.com/api/v1/pos/public |
| Regjistrimi | Çelësi Bearer i hotelit në header-in Authorization |
| Kushti paraprak | Hoteli 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 thirrjeve | 100 kërkesa për 60 sekonda për çdo key. Pas kësaj STRYK përgjigjet me 429. |
| Versioni i përshkrimit | 1.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 shtegu | Qëllimi |
|---|---|
GET /ping | Kontrollon vetëm nëse key-i pranohet. |
GET /accounts | Liston llogaritë e dhomave që janë aktualisht në check-in, edhe ato të bllokuara. |
GET /room-lookup?room=105 | Gjen 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:
| Fusha | Kuptimi |
|---|---|
bookingId, bookingNumber, guestName, roomNumber | Qëndrimi dhe dhoma |
allowPosting | Hoteli ka lejuar ngarkesat për qëndrimin. Vetëm kjo nuk mjafton. |
allowCharge | Kontrolli i plotë nga leja, limiti i mbetur dhe llogaria e mbyllur. Kontrolloje menjëherë përpara regjistrimit. |
postingBlockReason | no_post, credit_limit_reached, account_closed ose bosh |
openChargesCount, openChargesTotal, stayChargesTotal | Ngarkesat e hapura dhe shuma e ngarkesave jo të anuluara |
creditLimit, remainingCredit, currency | Limiti, 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 shtegu | Qëllimi |
|---|---|
POST /charges | Regjistron një ngarkesë në llogarinë e dhomës. Përgjigja 201 me ngarkesën. |
POST /charges/batch | Regjistron 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:
| Fusha | E detyrueshme | Kuptimi |
|---|---|---|
bookingId, room | të paktën një | Dhoma si tekst me shkronja, jo si numër. Nëse jepen të dyja, duhet të përputhen. |
description | po | 1 deri në 500 karaktere |
unitPrice | po | Çmimi bruto për njësi, më i madh se 0, deri në 99999.99 |
externalRef | po | Çelës unik i dokumentit ose i ngarkesës, 1 deri në 255 karaktere, për shembull receipt-123-item-1 |
quantity | jo | 0,001 deri në 9999, parazgjedhja 1 |
unit | jo | deri në 20 karaktere, parazgjedhja Stk. |
taxRate | jo | Norma tatimore aktive e hotelit. Pa dhënie vlen parazgjedhja e outletit, pastaj ajo qendrore. |
currency | jo | Duhet të jetë monedha e hotelit |
outletId | jo | Te një key me outlet vlen ky outlet. Një vlerë tjetër jep 403. |
chargedAt | jo | Koha e shërbimit, parazgjedhja tani, deri në 5 minuta në të ardhmen |
notes, posRef | jo | Shë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.
| Statusi | Kuptimi |
|---|---|
| 400 | Të dhëna të pavlefshme, korrigjoji ato. |
| 401 | Key-i nuk mund të verifikohet |
| 403 | Fushë e palejuar, për shembull outlet i gabuar |
| 404 | Llogaria ose ngarkesa nuk ekziston |
| 409 | Konflikt funksional. Kontrollo kodin, mos provo verbërisht përsëri. |
| 429 | Kufiri i thirrjeve, prit të paktën 60 sekonda |
| 5xx | Fillimisht 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,cancelledosetransferred. - 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.
| Informacioni | Vlera |
|---|---|
| Ngjarjet | charge.posted, charge.cancelled, gjatë testimit ping |
Header X-STRYK-Event | Emri i ngjarjes |
Header X-STRYK-Webhook-Id | ID e webhook-ut, jo e dërgimit |
Header X-STRYK-Signature | sha256= dhe HMAC-SHA-256 i bajtëve të pandryshuar të kërkesës. Vetëm me sekretin e konfiguruar. |
| Body | event, hotelId, timestamp, data me chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency dhe outlet |
| Përgjigja | 2xx pasi të pranohet përfundimisht brenda 10 sekondash. STRYK nuk ndjek ridrejtime. |
| Përsëritja | Pas 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:
- Kontrollo
/pingdhe lidhjen mysafir dhe dhomë, edhe te rezervimet me disa dhoma. - Kontrollo taksën, monedhën dhe kufizimin e outletit të key-it.
- Përsëritje e saktë pa dyfishim, përmbajtje e ndryshuar me 409, përgjigje e humbur me pajtim.
- Batch i plotë ose asgjë, bllokimi dhe limiti, anulimi dhe përsëritja e anulimit.
- Shumat e faturës në check-out dhe refuzimi i anulimit pas marrjes.
- Webhook i nënshkruar, nënshkrim i pavlefshëm, dërgim i dyfishtë dhe në rend të përzier.
- 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.
| Metoda | Shtegu | Përshkrim i shkurtër |
|---|---|---|
| GET | /ping | Kontrollo lidhjen |
| GET | /accounts | Listo llogaritë e dhomave në check-in |
| GET | /room-lookup | Gjej qëndrimin për një dhomë |
| POST | /charges | Regjistro një ngarkesë |
| POST | /charges/batch | Regjistro deri në 50 ngarkesa bashkë |
| GET | /charges/{externalRef} | Lexo gjendjen e një ngarkese |
| DELETE | /charges/{externalRef} | Anulo një ngarkesë të hapur |