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.
Contents
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.
| Parametrs | Vērtība |
|---|---|
| Bāzes adrese | https://app.staystryk.com/api/v1/pos/public |
| Reģistrācija | Viesnīcas Bearer atslēga galvenē Authorization |
| Prasība | Viesnīcai ir aktīvs papildmodulis STRYK POS |
| Bez papildmoduļa | Katrs izsaukums atbild ar 403 un kodu module_disabled. STRYK neieraksta nevienu pozīciju. |
| Izsaukumu ierobežojums | 100 pieprasījumi 60 sekundēs katrai atslēgai. Pēc tam STRYK atbild ar 429. |
| Apraksta versija | 1.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 /ping | Pārbauda tikai, vai atslēga tiek pieņemta. |
GET /accounts | Uzskaita pašlaik reģistrētos numuru kontus, arī bloķētos. |
GET /room-lookup?room=105 | Atrisina numuru uz reģistrēto uzturēšanos. 404 bez atbilstoša viesa, 409 neskaidra numura gadījumā. |
Numura kontā ir šādi lauki:
| Lauks | Nozīme |
|---|---|
bookingId, bookingNumber, guestName, roomNumber | Uzturēšanās un numurs |
allowPosting | Viesnīca ir atļāvusi pozīcijas uzturēšanās reizei. Tikai tas vien nepietiek. |
allowCharge | Kopējā pārbaude no atļaujas, atlikušā limita un slēgta konta. Pārbaudi to tieši pirms ierakstīšanas. |
postingBlockReason | no_post, credit_limit_reached, account_closed vai tukšs |
openChargesCount, openChargesTotal, stayChargesTotal | Atvērtās pozīcijas un visu neanulēto pozīciju summa |
creditLimit, remainingCredit, currency | Limits, 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 /charges | Ieraksta vienu pozīciju uz numura konta. Atbilde 201 ar pozīciju. |
POST /charges/batch | Ieraksta 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:
| Lauks | Obligāts | Nozīme |
|---|---|---|
bookingId, room | vismaz viens | Numurs kā teksts ar burtiem, nevis kā skaitlis. Ja norādīti abi, tiem jāsakrīt. |
description | jā | 1 līdz 500 rakstzīmes |
unitPrice | jā | Bruto cena par vienību, lielāka par 0, ne vairāk kā 99999.99 |
externalRef | jā | Unikāls čeka vai pozīcijas atslēgs, 1 līdz 255 rakstzīmes, piemēram receipt-123-item-1 |
quantity | nē | 0,001 līdz 9999, noklusējums 1 |
unit | nē | ne vairāk kā 20 rakstzīmes, noklusējums Stk. |
taxRate | nē | Viesnīcas aktīvā PVN likme. Ja nav norādīta, piemēro outlet noklusējumu, tad centrālo. |
currency | nē | Jābūt viesnīcas valūtai |
outletId | nē | Atslēgai ar outlet piemēro šo outlet. Cita vērtība dod 403. |
chargedAt | nē | Pakalpojuma laiks, noklusējums tagad, ne vairāk kā 5 minūtes nākotnē |
notes, posRef | nē | 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.
| Statuss | Nozīme |
|---|---|
| 400 | Nederīgi dati, izlabo tos. |
| 401 | Atslēgu nevar pārbaudīt |
| 403 | Joma nav atļauta, piemēram nepareizs outlet |
| 404 | Konts vai pozīcija nav atrasta |
| 409 | Biznesa konflikts. Pārbaudi kodu, neatkārto aklī. |
| 429 | Izsaukumu ierobežojums, pagaidi vismaz 60 sekundes |
| 5xx | Vispirms 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,cancelledvaitransferred. - 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 uztransferred. - 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.
| Parametrs | Vērtība |
|---|---|
| Notikumi | charge.posted, charge.cancelled, testējot ping |
Galvene X-STRYK-Event | Notikuma nosaukums |
Galvene X-STRYK-Webhook-Id | Webhook ID, nevis piegādes ID |
Galvene X-STRYK-Signature | sha256= un HMAC-SHA-256 no nemainītiem pieprasījuma baitiem. Tikai ar konfigurētu slepeno atslēgu. |
| Saturs | event, hotelId, timestamp, data ar chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency un outlet |
| Atbilde | 2xx pēc pastāvīgas pieņemšanas 10 sekunžu laikā. STRYK neseko pārsūtīšanai. |
| Atkārtojums | Pē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:
- Pārbaudi
/pingun viesa un numura piesaisti, arī rezervācijām ar vairākiem numuriem. - Pārbaudi nodokli, valūtu un atslēgas outlet ierobežojumu.
- Precīza atkārtošana bez dubultām pozīcijām, mainīts saturs ar 409, pazaudēta atbilde ar saskaņošanu.
- Pakete pilnīgi vai nemaz, bloķēšana un limits, anulēšana un anulēšanas atkārtojums.
- Rēķinu summas izrakstīšanās brīdī un anulēšanas noraidījums pēc pārņemšanas.
- Parakstīts webhook, nederīgs paraksts, dubultā un samainīta piegāde.
- 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.
| Metode | Ceļš | Īss apraksts |
|---|---|---|
| GET | /ping | Pārbaudīt savienojumu |
| GET | /accounts | Uzskaitīt reģistrētos numuru kontus |
| GET | /room-lookup | Atrast uzturēšanos pēc numura |
| POST | /charges | Ierakstīt vienu pozīciju |
| POST | /charges/batch | Ierakstī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 |