Pāriet uz saturu
Reference, STRYK POS

POS Posting API kasu ražotājiem

STRYK POS Posting API ieraksta pozīcijas no tavas kases uz reģistrētu viesu numuru kontiem. Atsauce parāda reģistrāciju, ierakstīšanu, anulēšanu un webhook.

Last updated: Developers
Contents
  1. Pārskats
  2. Atslēga un drošība
  3. Numura konts un summas
  4. Ierakstīšana un atkārtošana
  5. Anulēšana un rēķins
  6. Webhook un pieņemšana
  7. Tehniskā atsauce

Pārskats

API ir servera-servera saskarne pozīcijām reģistrētām uzturēšanās reizēm. Viesnīca savieno tavu kasi sadaļā Iestatījumi zem POS: Savienot kasi. Tur kase saņem atslēgu un Adrese kasei.

ParametrsVērtība
Bāzes adresehttps://app.staystryk.com/api/v1/pos/public
ReģistrācijaViesnīcas Bearer atslēga galvenē Authorization
PrasībaViesnīcai ir aktīvs papildmodulis STRYK POS
Bez papildmoduļaKatrs izsaukums atbild ar 403 un kodu module_disabled. STRYK neieraksta nevienu pozīciju.
Izsaukumu ierobežojums100 pieprasījumi 60 sekundēs katrai atslēgai. Pēc tam STRYK atbild ar 429.
Apraksta versija1.3.0

Atslēga un drošība

  • Atslēga sākas ar pos_live_. Viesnīca to redz tikai vienreiz, kad to ģenerē.
  • Sūti to tikai serverī pa HTTPS galvenē: Authorization: Bearer <vollständiger Schlüssel>. Nekad kā parametru adresē.
  • Viena atslēga pieder tieši vienai viesnīcai un pēc izvēles vienam outlet. Viesnīca ģenerē vienu atslēgu katram savienojumam.
  • 401 nozīmē: STRYK nevarēja pārbaudīt atslēgu. Pārbaudi konfigurāciju un darbības statusu. Nemaini atslēgu automātiski.
  • Jauna atslēga ir jauns idempotences apgabals. Tā neatrod un neanulē vecās atslēgas pozīcijas. Apstrādā atvērtos uzdevumus un saskaņo tos, pirms viesnīca atsauc veco atslēgu.
  • Ja atslēga ir pazaudēta vai kompromitēta, viesnīca to atsauc ar Atsaukt atslēgu un izskata nedrošas darbības STRYK, pirms tava kase sūta aizstājēju.

Numura konts un summas

Metode un ceļšMērķis
GET /pingPārbauda tikai, vai atslēga tiek pieņemta.
GET /accountsUzskaita pašlaik reģistrētos numuru kontus, arī bloķētos.
GET /room-lookup?room=105Atrisina numuru uz reģistrēto uzturēšanos. 404 bez atbilstoša viesa, 409 neskaidra numura gadījumā.

Numura kontā ir šādi lauki:

LauksNozīme
bookingId, bookingNumber, guestName, roomNumberUzturēšanās un numurs
allowPostingViesnīca ir atļāvusi pozīcijas uzturēšanās reizei. Tikai tas vien nepietiek.
allowChargeKopējā pārbaude no atļaujas, atlikušā limita un slēgta konta. Pārbaudi to tieši pirms ierakstīšanas.
postingBlockReasonno_post, credit_limit_reached, account_closed vai tukšs
openChargesCount, openChargesTotal, stayChargesTotalAtvērtās pozīcijas un visu neanulēto pozīciju summa
creditLimit, remainingCredit, currencyLimits, atlikušais limits un viesnīcas valūta

Parādi viesi un numuru apstiprināšanai un sūti bookingId kopā ar room. Nesaglabā kontu sarakstu pastāvīgi kā viesu katalogu. Summas ir JSON skaitļi viesnīcas valūtā. Noapaļošana ir HALF_UP: daudzumu uz trim, summas uz diviem decimāldaļām.

Ierakstīšana un atkārtošana

Metode un ceļšMērķis
POST /chargesIeraksta vienu pozīciju uz numura konta. Atbilde 201 ar pozīciju.
POST /charges/batchIeraksta no 1 līdz 50 pozīcijām kopā. Visas jaunās pozīcijas tiek ierakstītas vai neviena. Atbilde seko pieprasījuma secībai.
GET /charges/{externalRef}Atgriež pozīcijas pastāvīgo stāvokli, arī cancelled un transferred.

Ierakstīšanas lauki:

LauksObligātsNozīme
bookingId, roomvismaz viensNumurs kā teksts ar burtiem, nevis kā skaitlis. Ja norādīti abi, tiem jāsakrīt.
descriptionjā1 līdz 500 rakstzīmes
unitPricejāBruto cena par vienību, lielāka par 0, ne vairāk kā 99999.99
externalRefjāUnikāls čeka vai pozīcijas atslēgs, 1 līdz 255 rakstzīmes, piemēram receipt-123-item-1
quantitynē0,001 līdz 9999, noklusējums 1
unitnēne vairāk kā 20 rakstzīmes, noklusējums Stk.
taxRatenēViesnīcas aktīvā PVN likme. Ja nav norādīta, piemēro outlet noklusējumu, tad centrālo.
currencynēJābūt viesnīcas valūtai
outletIdnēAtslēgai ar outlet piemēro šo outlet. Cita vērtība dod 403.
chargedAtnēPakalpojuma laiks, noklusējums tagad, ne vairāk kā 5 minūtes nākotnē
notes, posRefnēPiezīme (1000 rakstzīmes), čeka atsauce recepcijai (100 rakstzīmes)

Kopējā summa no daudzuma un vienības cenas ir lielāka par 0 un ne vairāk kā 99999999.99.

externalRef ir viesnīcas un atslēgas nemainīgs idempotences atslēgs. Precīza atkārtošana atgriež sākotnējo pozīciju ar idempotentReplay=true. Mainīts saturs vai anulēta atslēga dod 409.

Pēc noilguma vai 5xx vispirms lasi GET /charges/{externalRef}. Tikai pēc apstiprinātas 404 sūti to pašu pieprasījumu neizmainītu ar to pašu atslēgu. Saglabā pieprasījumus pirms sūtīšanas un nekad nemaini chargedAt, cenu, nodokli vai atsauci. Ja atbildē ir duplicateWarning, pozīcija jau ir ierakstīta. Saskaņo to STRYK un nesūti atkārtoti.

StatussNozīme
400Nederīgi dati, izlabo tos.
401Atslēgu nevar pārbaudīt
403Joma nav atļauta, piemēram nepareizs outlet
404Konts vai pozīcija nav atrasta
409Biznesa konflikts. Pārbaudi kodu, neatkārto aklī.
429Izsaukumu ierobežojums, pagaidi vismaz 60 sekundes
5xxVispirms saskaņo, tad atkārto ar ierobežotu pauzi

Kļūdas atbildes kodi ir starp citiem 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 un pos_account_closed. Nezari pēc vācu teksta. requestId palīdz atbalstam.

Anulēšana un rēķins

DELETE /charges/{externalRef} anulē atvērtu tavas atslēgas pozīciju. Pieprasījumā var būt pēc izvēles reason (ne vairāk kā 500 rakstzīmes). Atkārtojums atgriež anulēto pozīciju vēlreiz.

  • Pozīcijas statuss ir open, cancelled vai transferred.
  • Pozīcija paliek open, kamēr izrakstīšanās neizveido rēķinu. Tad STRYK pārņem atvērtās pozīcijas rēķina pozīcijās un statuss mainās uz transferred.
  • Pārņemta pozīcija dod 409 ar pos_charge_already_invoiced. Viesnīca to labo grāmatvedībā: Rēķina labošana.
  • Anulēšana neko nedzēš un neatmaksā naudu. Anulētā pozīcija paliek izsekojama.

API ieraksta pozitīvas pozīcijas. Maksājumus, kas tiek pabeigti kasē, uz numuru papildus nesūti. Dalītā maksājuma gadījumā sūti tikai atvērto numura daļu ar pareizi sadalītu nodokli. Atlaides atskaiti no bruto cenas pirms ierakstīšanas.

Webhook un pieņemšana

Viesnīca izveido webhook sadaļā Iestatījumi zem POS: Izveidot webhook.

ParametrsVērtība
Notikumicharge.posted, charge.cancelled, testējot ping
Galvene X-STRYK-EventNotikuma nosaukums
Galvene X-STRYK-Webhook-IdWebhook ID, nevis piegādes ID
Galvene X-STRYK-Signaturesha256= un HMAC-SHA-256 no nemainītiem pieprasījuma baitiem. Tikai ar konfigurētu slepeno atslēgu.
Satursevent, hotelId, timestamp, data ar chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency un outlet
Atbilde2xx pēc pastāvīgas pieņemšanas 10 sekunžu laikā. STRYK neseko pārsūtīšanai.
AtkārtojumsPēc 30 sekundēm, 5 minūtēm, 30 minūtēm un 2 stundām, līdz saglabātajai robežai

Pārbaudi parakstu pēc nemainīta satura, pirms to lasi kā JSON. Saglabā event un data.chargeId pastāvīgi, lai atpazītu atkārtojumus. Piegādes var nākt divreiz vai citā secībā: vecs charge.posted nepārraksta charge.cancelled. Ieiešanai, izrakstīšanai un rēķina pārņemšanai webhook nav. Tur lasi stāvokli no jauna.

Pieņemšanas saraksts ar testa viesnīcu un vienu reālu reģistrētu testa uzturēšanos:

  1. Pārbaudi /ping un viesa un numura piesaisti, arī rezervācijām ar vairākiem numuriem.
  2. Pārbaudi nodokli, valūtu un atslēgas outlet ierobežojumu.
  3. Precīza atkārtošana bez dubultām pozīcijām, mainīts saturs ar 409, pazaudēta atbilde ar saskaņošanu.
  4. Pakete pilnīgi vai nemaz, bloķēšana un limits, anulēšana un anulēšanas atkārtojums.
  5. Rēķinu summas izrakstīšanās brīdī un anulēšanas noraidījums pēc pārņemšanas.
  6. Parakstīts webhook, nederīgs paraksts, dubultā un samainīta piegāde.
  7. Kļūdu rādījums, atslēgas nomaiņa un personāla saskaņošana.

Tehniskā atsauce

Pilns apraksts ir pieejams kā OpenAPI fails angļu valodā: kā YAML zem /developers/pos/openapi.yaml un kā JSON zem /developers/pos/openapi.json STRYK vietnē. Viesnīcā šo lapu atver Tehniskā dokumentācija sadaļā Kases tehniķim cilnē Iestatījumi zem POS.

MetodeCeļšĪss apraksts
GET/pingPārbaudīt savienojumu
GET/accountsUzskaitīt reģistrētos numuru kontus
GET/room-lookupAtrast uzturēšanos pēc numura
POST/chargesIerakstīt vienu pozīciju
POST/charges/batchIerakstīt līdz 50 pozīcijām kopā
GET/charges/{externalRef}Nolasīt pozīcijas stāvokli
DELETE/charges/{externalRef}Anulēt vienu atvērtu pozīciju
Kontakts