POS Posting API kassavalmistajille
STRYK POS Posting API kirjaa kassasi veloitukset sisään kirjautuneiden vieraiden huoneen tileille. Viite näyttää todennuksen, kirjaamisen, peruutuksen ja webhookit.
Contents
Yleiskatsaus
Palvelimien välinen rajapinta veloituksille sisään kirjautuneisiin majoituksiin. Hotelli yhdistää kassasi kohdassa Asetukset osiossa POS: Yhdistä kassa. Siellä kassa saa avaimen ja Kassan osoite.
| Tieto | Arvo |
|---|---|
| Perusosoite | https://app.staystryk.com/api/v1/pos/public |
| Todennus | Hotellin Bearer-avain otsakkeessa Authorization |
| Edellytys | Hotellilla on lisämoduuli STRYK POS käytössä |
| Ilman lisämoduulia | Jokainen kutsu vastaa tilalla 403 ja koodilla module_disabled. STRYK ei kirjaa veloitusta. |
| Kutsurajoitus | 100 pyyntöä 60 sekunnissa ja avainta kohden. Sen jälkeen STRYK vastaa tilalla 429. |
| Kuvauksen versio | 1.3.0 |
Avaimet ja turvallisuus
- Avain alkaa etuliitteellä
pos_live_. Hotelli näkee sen vain kerran luonnin yhteydessä. - Lähetä se vain palvelimelta HTTPS-yhteydellä otsakkeessa:
Authorization: Bearer <vollständiger Schlüssel>. Älä koskaan osoitteessa parametrina. - Avain kuuluu täsmälleen yhdelle hotellille ja valinnaisesti yhdelle outletille. Hotelli luo yhden avaimen jokaista yhteyttä kohden.
- 401 tarkoittaa, että STRYK ei voinut tarkistaa avainta. Tarkista asetukset ja käyttötila. Älä vaihda avainta automaattisesti.
- Uusi avain on uusi idempotenssialue. Se ei löydä eikä peruuta vanhan avaimen veloituksia. Käsittele avoimet tehtävät ja täsmäytä ne ennen kuin hotelli mitätöi vanhan avaimen.
- Jos avain katoaa tai vaarantuu, hotelli mitätöi sen painikkeella Mitätöi avain ja selvittää epävarmat tapahtumat STRYKissä ennen kuin kassasi lähettää korvaavan avaimen.
Huoneen tili ja summat
| Metodi ja polku | Tarkoitus |
|---|---|
GET /ping | Tarkistaa vain, hyväksytäänkö avain. |
GET /accounts | Luettelee tällä hetkellä sisäänkirjautuneiden huoneiden tilit, myös lukitut. |
GET /room-lookup?room=105 | Selvittää huoneen sisäänkirjautuneen majoituksen. 404, jos sopivaa vierasta ei ole, 409, jos huone on epäselvä. |
Huoneen tili sisältää nämä kentät:
| Kenttä | Merkitys |
|---|---|
bookingId, bookingNumber, guestName, roomNumber | Majoitus ja huone |
allowPosting | Hotelli on sallinut veloitukset majoitukselle. Pelkkä tämä ei riitä. |
allowCharge | Kokonaistarkistus, joka koostuu luvasta, jäljellä olevasta limiitistä ja suljetusta tilistä. Tarkista se juuri ennen kirjaamista. |
postingBlockReason | no_post, credit_limit_reached, account_closed tai tyhjä |
openChargesCount, openChargesTotal, stayChargesTotal | Avoimet veloitukset ja peruuttamattomien veloitusten summa |
creditLimit, remainingCredit, currency | Limiitti, jäljellä oleva limiitti ja hotellin valuutta |
Näytä vieras ja huone vahvistusta varten ja lähetä bookingId yhdessä room-kentän kanssa. Älä säilytä tililuetteloa pysyvästi vieraskirjana. Summat ovat JSON-lukuja hotellin valuutassa. Pyöristys on HALF_UP: määrä kolmeen ja summat kahteen desimaaliin.
Kirjaaminen ja toistaminen
| Metodi ja polku | Tarkoitus |
|---|---|
POST /charges | Kirjaa yhden veloituksen huoneen tilille. Vastaus 201 veloituksen kanssa. |
POST /charges/batch | Kirjaa 1 ja 50 veloitusta yhdessä. Kaikki uudet veloitukset kirjataan tai ei yhtään. Vastaus noudattaa pyynnön järjestystä. |
GET /charges/{externalRef} | Palauttaa veloituksen pysyvän tilan, myös tilat cancelled ja transferred. |
Kirjauksen kentät:
| Kenttä | Pakollinen | Merkitys |
|---|---|---|
bookingId, room | vähintään yksi | Huone tekstinä kirjaimilla, ei numerona. Jos molemmat annetaan, niiden on täsmättävä. |
description | kyllä | Vähintään 1, enintään 500 merkkiä |
unitPrice | kyllä | Bruttohinta yksikköä kohden, suurempi kuin 0, enintään 99999.99 |
externalRef | kyllä | Yksilöllinen kuitti- tai veloitusavain, vähintään 1 ja enintään 255 merkkiä, esimerkiksi receipt-123-item-1 |
quantity | ei | Vähintään 0,001, enintään 9999, oletus 1 |
unit | ei | enintään 20 merkkiä, oletus Stk. |
taxRate | ei | Hotellin aktiivinen ALV-kanta. Jos sitä ei anneta, käytetään outletin oletusta ja sen jälkeen keskitettyä arvoa. |
currency | ei | On oltava hotellin valuutta |
outletId | ei | Avaimella, jolla on outlet, käytetään tätä outletia. Muu arvo antaa tilan 403. |
chargedAt | ei | Palvelun ajankohta, oletus nyt, enintään 5 minuuttia tulevaisuudessa |
notes, posRef | ei | Muistiinpano (enintään 1000 merkkiä), kuittiviite vastaanotolle (enintään 100 merkkiä) |
Määrän ja yksikköhinnan kokonaissumma on suurempi kuin 0 ja enintään 99999999.99.
externalRef on hotellin ja avaimen muuttumaton idempotenssiavain. Täsmällinen toisto palauttaa alkuperäisen veloituksen arvolla idempotentReplay=true. Muuttunut sisältö tai peruutettu avain antaa tilan 409.
Aikakatkaisun tai tilan 5xx jälkeen lue ensin GET /charges/{externalRef}. Lähetä sama pyyntö muuttamattomana samalla avaimella uudelleen vain, kun 404 on vahvistettu. Tallenna pyynnöt ennen lähettämistä äläkä koskaan muuta chargedAt-, hinta-, vero- tai viitetietoa. Jos vastauksessa on duplicateWarning, veloitus on jo kirjattu. Täsmäytä se STRYKissä äläkä lähetä uudelleen.
| Tila | Merkitys |
|---|---|
| 400 | Virheelliset tiedot, korjaa ne. |
| 401 | Avainta ei voi tarkistaa |
| 403 | Alue ei ole sallittu, esimerkiksi väärä outlet |
| 404 | Tiliä tai veloitusta ei ole |
| 409 | Liiketoiminnallinen ristiriita. Tarkista koodi äläkä toista sokkona. |
| 429 | Kutsurajoitus, odota vähintään 60 sekuntia |
| 5xx | Täsmäytä ensin, toista sitten rajoitetulla viiveellä |
Virhevastauksen koodeja ovat muun muassa 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 ja pos_account_closed. Älä haarauta koodia saksankielisen tekstin mukaan. requestId auttaa tukea.
Peruutus ja lasku
DELETE /charges/{externalRef} peruuttaa avaimesi avoimen veloituksen. Rungossa voi olla valinnaisena reason (enintään 500 merkkiä). Toisto palauttaa peruutetun veloituksen uudelleen.
- Veloituksen tila on
open,cancelledtaitransferred. - Veloitus pysyy tilassa
open, kunnes lähtö luo laskun. Sen jälkeen STRYK siirtää avoimet veloitukset laskurivyiksi ja tila vaihtuu tilaantransferred. - Siirretty veloitus antaa tilan 409 koodilla
pos_charge_already_invoiced. Hotelli korjaa sen kirjanpidossa: Laskun korjaaminen. - Peruutus ei poista mitään eikä hyvitä mitään. Peruutettu veloitus säilyy jäljitettävänä.
API kirjaa positiivisia veloituksia. Maksuja, jotka suoritetaan kassalla, ei lähetetä huoneelle lisäksi. Jaetussa maksussa lähetät vain avoimen huoneosuuden oikein jaetulla verolla. Alennukset vähennät bruttohinnasta ennen kirjaamista.
Webhookit ja hyväksyntä
Hotelli luo webhookit kohdassa Asetukset osiossa POS: Luo webhookit.
| Tieto | Arvo |
|---|---|
| Tapahtumat | charge.posted, charge.cancelled, testauksessa ping |
Otsake X-STRYK-Event | Tapahtuman nimi |
Otsake X-STRYK-Webhook-Id | Webhookin tunniste, ei toimituksen |
Otsake X-STRYK-Signature | sha256= ja pyynnön muuttumattomien tavujen HMAC-SHA-256. Vain määritetyllä salaisuudella. |
| Runko | event, hotelId, timestamp, data, jossa chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency ja outlet |
| Vastaus | 2xx pysyvän hyväksynnän jälkeen 10 sekunnin sisällä. STRYK ei seuraa uudelleenohjauksia. |
| Uudelleenyritys | 30 sekunnin, 5 minuutin, 30 minuutin ja 2 tunnin kuluttua, tallennettuun rajaan asti |
Varmista allekirjoitus muuttumattomasta rungosta ennen kuin luet sen JSONina. Tallenna event ja data.chargeId pysyvästi, jotta toistot tunnistetaan. Toimitukset voivat tulla kahdesti tai eri järjestyksessä: vanha charge.posted ei korvaa charge.cancelled-tilaa. Sisään- ja uloskirjautumiselle sekä laskun siirrolle ei ole webhookeja. Lue tila niissä uudelleen.
Hyväksymislista testihotellilla ja oikealla sisäänkirjautuneella testimajoituksella:
- Tarkista
/pingsekä vieras- ja huonemääritys, myös varauksilla, joissa on useita huoneita. - Tarkista veroa, valuuttaa ja avaimen outlet-rajoitusta.
- Täsmällinen toisto ilman kaksoisveloitusta, muuttunut sisältö tilalla 409, kadonnut vastaus täsmäytyksellä.
- Erä kokonaan tai ei lainkaan, lukitus ja limiitti, peruutus ja peruutuksen toisto.
- Laskusummat uloskirjautumisessa ja peruutuksen hylkääminen siirron jälkeen.
- Allekirjoitettu webhook, virheellinen allekirjoitus, kaksinkertainen ja väärään järjestykseen mennyt toimitus.
- Virhenäkymä, avaimen vaihto ja henkilökunnan tekemä täsmäytys.
Tekninen viite
Täydellinen kuvaus on englanninkielisenä OpenAPI-tiedostona, YAML-muodossa osoitteessa /developers/pos/openapi.yaml ja JSON-muodossa osoitteessa /developers/pos/openapi.json STRYKin verkkosivustolla. Hotellissa Tekninen dokumentaatio osiossa Kassateknikolle kohdassa Asetukset osiossa POS vie tälle sivulle.
| Metodi | Polku | Lyhyt kuvaus |
|---|---|---|
| GET | /ping | Tarkista yhteys |
| GET | /accounts | Luettele sisäänkirjautuneiden huoneiden tilit |
| GET | /room-lookup | Etsi huoneen majoitus |
| POST | /charges | Kirjaa yksi veloitus |
| POST | /charges/batch | Kirjaa enintään 50 veloitusta yhdessä |
| GET | /charges/{externalRef} | Lue veloituksen tila |
| DELETE | /charges/{externalRef} | Peruuta yksi avoin veloitus |