STRYK POS Posting API għall-manifatturi tal-kaxxa
Il-STRYK POS Posting API ippostja ċarġ mill-kaxxa tiegħek fuq kontijiet tal-kmamar ta' klijenti li għamlu check-in. Ir-referenza turi r-reġistrazzjoni, iċ-ċarġ, il-kanċellazzjoni u l-webhooks.
Contents
Ħarsa ġenerali
L-API hija interface bejn server u server għal ċarġi fuq soġġorni b'check-in. Il-lukanda tgħaqqad il-kaxxa tiegħek fis-Impostazzjonijiet taħt POS: Qabbad il-kaxxa. Hemm il-kaxxa tirċievi ċavetta u l-Indirizz għall-kaxxa.
| Dettall | Valur |
|---|---|
| Indirizz bażi | https://app.staystryk.com/api/v1/pos/public |
| Reġistrazzjoni | Ċavetta bearer tal-lukanda fl-header Authorization |
| Kundizzjoni | Il-lukanda għandha l-modulu addizzjonali STRYK POS attiv |
| Mingħajr modulu addizzjonali | Kull talba tirrispondi b'403 bil-kodiċi module_disabled. STRYK ma tirreġistra l-ebda ċarġ. |
| Limitu tat-talbiet | 100 talba kull 60 sekonda u kull ċavetta. Wara dan STRYK tirrispondi b'429. |
| Verżjoni tad-deskrizzjoni | 1.3.0 |
Ċavetta u sigurtà
- Iċ-ċavetta tibda b'
pos_live_. Il-lukanda tarah darba biss meta tinħoloq. - Ibgħatu biss fuq is-server permezz ta' HTTPS fl-header:
Authorization: Bearer <vollständiger Schlüssel>. Qatt bħala parametru fl-indirizz. - Ċavetta waħda tappartjeni lil lukanda waħda u, b'mod fakultattiv, lil outlet wieħed. Il-lukanda toħloq ċavetta għal kull konnessjoni.
- 401 ifisser: STRYK ma setgħetx tivverifika ċ-ċavetta. Iċċekkja l-konfigurazzjoni u l-istatus operattiv. Tibdilx iċ-ċavetta awtomatikament.
- Ċavetta ġdida hija qasam ġdid tal-idempotenza. Ma ssibx u ma tikkanċellax ċarġi taċ-ċavetta l-qadima. Ipproċessa l-ordnijiet miftuħa u aqbilhom qabel ma l-lukanda tirrevoka ċ-ċavetta l-qadima.
- Jekk ċavetta tintilef jew tiġi kompromessa, il-lukanda tirrevokaha bil-Irrevoka l-Key u tiċċara l-operazzjonijiet mhux sikuri f'STRYK qabel il-kaxxa tiegħek tibgħat sostitut.
Kont tal-kamra u ammonti
| Metodu u percors | Skop |
|---|---|
GET /ping | Jiċċekkja biss jekk iċ-ċavetta tiġix aċċettata. |
GET /accounts | Jelenka l-kontijiet tal-kmamar bi check-in bħalissa, anke dawk imblukkati. |
GET /room-lookup?room=105 | Isib soġġorn b'check-in għal kamra. 404 mingħajr klijent korrispondenti, 409 f'każ ta' kamra ambigwa. |
Il-kont tal-kamra fih dawn il-oqsma:
| Qasam | Tifsira |
|---|---|
bookingId, bookingNumber, guestName, roomNumber | Soġġorn u kamra |
allowPosting | Il-lukanda ppermettiet ċarġi għas-soġġorn. Dan waħdu mhux biżżejjed. |
allowCharge | Kontroll globali minn permess, limitu residwu u kont magħluq. Iċċekkjah immedjatament qabel ma tippostja. |
postingBlockReason | no_post, credit_limit_reached, account_closed jew vojt |
openChargesCount, openChargesTotal, stayChargesTotal | Ċarġi miftuħa u somma taċ-ċarġi mhux ikkanċellati |
creditLimit, remainingCredit, currency | Limitu, limitu residwu u munita tal-lukanda |
Uri l-klijent u l-kamra għall-konferma u ibgħat bookingId flimkien ma' room. Tużax il-lista tal-kontijiet bħala direttorju permanenti tal-klijenti. L-ammonti huma numri JSON fil-munita tal-lukanda. L-arrotondament huwa HALF_UP: il-kwantità sa tliet postijiet deċimali, l-ammonti sa tnejn.
Ippostja u erġa' ipprova
| Metodu u percors | Skop |
|---|---|
POST /charges | Jippostja ċarġ fuq kont ta' kamra. Tweġiba 201 biċ-ċarġ. |
POST /charges/batch | Jippostja minn 1 sa 50 ċarġ flimkien. Iċ-ċarġi ġodda kollha jiġu ppostjati jew xejn. It-tweġiba ssegwi l-ordni tat-talba. |
GET /charges/{externalRef} | Jagħti l-istat permanenti ta' ċarġ, anke cancelled u transferred. |
Oqsma ta' ċarġ:
| Qasam | Obbligatorju | Tifsira |
|---|---|---|
bookingId, room | wieħed tal-inqas | Kamra bħala test b'ittri, mhux bħala numru. Jekk jintużaw it-tnejn, iridu jaqblu. |
description | iva | 1 sa 500 karattru |
unitPrice | iva | Prezz bruttu għal kull unità, akbar minn 0 u sa massimu ta' 99999.99 |
externalRef | iva | Ċavetta unika tal-irċevuta jew taċ-ċarġ, 1 sa 255 karattru, pereżempju receipt-123-item-1 |
quantity | le | 0,001 sa 9999, standard 1 |
unit | le | sa 20 karattru, standard Stk. |
taxRate | le | Aliquota tat-taxxa attiva tal-lukanda. Jekk ma tiġix indikata, tapplika l-istandard tal-outlet, imbagħad dak ċentrali. |
currency | le | Trid tkun il-munita tal-lukanda |
outletId | le | B'ċavetta b'outlet, dak l-outlet japplika. Valur ieħor jirriżulta f'403. |
chargedAt | le | Ħin tas-servizz, standard issa, sa 5 minuti fil-futur |
notes, posRef | le | Nota (1000 karattri), referenza tal-irċevuta għar-reċeptjon (100 karattri) |
Is-somma totali tal-kwantità u tal-prezz ta' unità hija akbar minn 0 u sa massimu ta' 99999999.99.
externalRef huwa l-ċavetta tal-idempotenza bla bidla tal-lukanda u taċ-ċavetta. Replika eżatta tagħti lura ċ-ċarġ oriġinali b'idempotentReplay=true. Kontenut mibdul jew ċavetta kkanċellata jirriżultaw f'409.
Wara timeout jew 5xx, aqra l-ewwel GET /charges/{externalRef}. Ibgħat mill-ġdid it-talba identika, bl-istess ċavetta, biss meta 404 tkun ikkonfermata. Aħżen it-talbiet qabel tibgħathom u qatt ma tibdel chargedAt, il-prezz, it-taxxa jew ir-referenza. Jekk it-tweġiba turi duplicateWarning, iċ-ċarġ diġà ġie ppostjat. Aqbilu f'STRYK u tibgħathux mill-ġdid.
| Status | Tifsira |
|---|---|
| 400 | Dettalji mhux validi, ikkoreġi. |
| 401 | Ċavetta ma tistax tiġi vverifikata |
| 403 | Erja mhux permessa, pereżempju outlet ħażin |
| 404 | Kont jew ċarġ ma jeżistux |
| 409 | Kunflitt tan-negozju. Iċċekkja l-kodiċi u terġax tipprova bla ma tara. |
| 429 | Limitu tat-talbiet, stenna mill-inqas 60 sekonda |
| 5xx | L-ewwel aqbel, imbagħad erġa' ipprova b'backoff limitat |
Il-kodiċi tar-risposta tal-iżball jinkludu, fost oħrajn, 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 u pos_account_closed. Tibqax tiddeċiedi skont it-test bil-Ġermaniż. requestId jgħin lis-support.
Kanċellazzjoni u fattura
DELETE /charges/{externalRef} ikkanċella ċarġ miftuħ taċ-ċavetta tiegħek. Fil-body hemm reason fakultattiv (sa 500 karattru). Repetizzjoni tagħti lura ċ-ċarġ ikkanċellat mill-ġdid.
- L-istat ta' ċarġ huwa
open,cancelledjewtransferred. - Ċarġ jibqa'
opensakemm il-check-out joħloq il-fattura. Imbagħad STRYK tieħu ċ-ċarġi miftuħa f'pożizzjonijiet tal-fattura u l-istat jinbidel għaltransferred. - Ċarġ ittrasferit jirriżulta f'409 bi
pos_charge_already_invoiced. Il-lukanda tikkoreġih fil-kontabilità: Ikkoreġi fattura. - Kanċellazzjoni ma tħassar xejn u ma tirrimborsax xejn. Iċ-ċarġ ikkanċellat jibqa' traċċabbli.
L-API tippostja ċarġi pożittivi. Pagamenti li jitlestew fil-kaxxa ma tibgħathomx barra minn hekk fuq il-kamra. Fil-pagament maqsum tibgħat biss is-sehem miftuħ tal-kamra b'taxxa mqassma tajjeb. Naqqas l-iskontijiet mill-prezz bruttu qabel ma tippostja.
Webhooks u aċċettazzjoni
Il-lukanda toħloq webhooks fis-Impostazzjonijiet taħt POS: Oħloq webhooks.
| Dettall | Valur |
|---|---|
| Avvenimenti | charge.posted, charge.cancelled, meta tittestja ping |
Header X-STRYK-Event | Isem l-avveniment |
Header X-STRYK-Webhook-Id | ID tal-webhook, mhux tal-kunsinna |
Header X-STRYK-Signature | sha256= u HMAC-SHA-256 tal-bytes mhux mibdula tat-talba. Biss b'sigriet ikkonfigurat. |
| Body | event, hotelId, timestamp, data b'chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency u outlet |
| Tweġiba | 2xx wara aċċettazzjoni permanenti fi żmien 10 sekondi. STRYK ma ssegwix redirects. |
| Repetizzjoni | Wara 30 sekonda, 5 minuti, 30 minuta u sagħtejn, sal-limitu maħżun |
Ivverifika l-firma fuq il-body mhux mibdul qabel taqrah bħala JSON. Aħżen event u data.chargeId permanentement biex tagħraf ir-repetizzazzjonijiet. Il-kunsinni jistgħu jaslu darbtejn jew b'ordni differenti: charge.posted qadim ma jisboqx charge.cancelled. Ma hemmx webhooks għall-check-in, check-out u t-trasferiment tal-fattura. Aqra hemm l-istat mill-ġdid.
Lista tal-aċċettazzjoni b'lukanda ta' prova u soġġorn ta' prova bi check-in attiv:
- Iċċekkja
/pingu l-assenjazzjoni tal-klijent u tal-kamra, anke għal riżervi b'diversi kmamar. - Iċċekkja t-taxxa, il-munita u r-restrizzjoni tal-outlet taċ-ċavetta.
- Repetizzjoni eżatta mingħajr ċarġi doppji, kontenut mibdul b'409, tweġiba mitlufa b'aqbil.
- Batch kollu jew xejn, blokk u limitu, kanċellazzjoni u repetizzjoni tal-kanċellazzjoni.
- Totali tal-fattura fil-check-out u rifjut tal-kanċellazzjoni wara t-trasferiment.
- Webhook iffirmat, firma invalida, kunsinna doppja u kunsinna b'ordni maqluba.
- Wirja tal-iżbalji, bidla taċ-ċavetta u aqbil mill-persunal.
Referenza teknika
Id-deskrizzjoni sħiħa tinsab bħala fajl OpenAPI bl-Ingliż, bħala YAML fuq /developers/pos/openapi.yaml u bħala JSON fuq /developers/pos/openapi.json fuq il-websajt ta' STRYK. Fil-lukanda, Dokumentazzjoni teknika taħt Għat-tekniku tal-kaxxa fis-Impostazzjonijiet taħt POS iwassal għal din il-paġna.
| Metodu | Path | Deskrizzjoni qasira |
|---|---|---|
| GET | /ping | Iċċekkja l-konnessjoni |
| GET | /accounts | Jelenka l-kontijiet tal-kmamar bi check-in |
| GET | /room-lookup | Sib is-soġġorn għal kamra |
| POST | /charges | Ippostja ċarġ |
| POST | /charges/batch | Ippostja sa 50 ċarġ flimkien |
| GET | /charges/{externalRef} | Aqra l-istat ta' ċarġ |
| DELETE | /charges/{externalRef} | Ikkanċella ċarġ miftuħ |