Siirry sisältöön
Reference, STRYK POS

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.

Last updated: Developers
Contents
  1. Yleiskatsaus
  2. Avaimet ja turvallisuus
  3. Huoneen tili ja summat
  4. Kirjaaminen ja toistaminen
  5. Peruutus ja lasku
  6. Webhookit ja hyväksyntä
  7. Tekninen viite

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.

TietoArvo
Perusosoitehttps://app.staystryk.com/api/v1/pos/public
TodennusHotellin Bearer-avain otsakkeessa Authorization
EdellytysHotellilla on lisämoduuli STRYK POS käytössä
Ilman lisämoduuliaJokainen kutsu vastaa tilalla 403 ja koodilla module_disabled. STRYK ei kirjaa veloitusta.
Kutsurajoitus100 pyyntöä 60 sekunnissa ja avainta kohden. Sen jälkeen STRYK vastaa tilalla 429.
Kuvauksen versio1.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 polkuTarkoitus
GET /pingTarkistaa vain, hyväksytäänkö avain.
GET /accountsLuettelee tällä hetkellä sisäänkirjautuneiden huoneiden tilit, myös lukitut.
GET /room-lookup?room=105Selvittää 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, roomNumberMajoitus ja huone
allowPostingHotelli on sallinut veloitukset majoitukselle. Pelkkä tämä ei riitä.
allowChargeKokonaistarkistus, joka koostuu luvasta, jäljellä olevasta limiitistä ja suljetusta tilistä. Tarkista se juuri ennen kirjaamista.
postingBlockReasonno_post, credit_limit_reached, account_closed tai tyhjä
openChargesCount, openChargesTotal, stayChargesTotalAvoimet veloitukset ja peruuttamattomien veloitusten summa
creditLimit, remainingCredit, currencyLimiitti, 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 polkuTarkoitus
POST /chargesKirjaa yhden veloituksen huoneen tilille. Vastaus 201 veloituksen kanssa.
POST /charges/batchKirjaa 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äPakollinenMerkitys
bookingId, roomvähintään yksiHuone tekstinä kirjaimilla, ei numerona. Jos molemmat annetaan, niiden on täsmättävä.
descriptionkylläVähintään 1, enintään 500 merkkiä
unitPricekylläBruttohinta yksikköä kohden, suurempi kuin 0, enintään 99999.99
externalRefkylläYksilöllinen kuitti- tai veloitusavain, vähintään 1 ja enintään 255 merkkiä, esimerkiksi receipt-123-item-1
quantityeiVähintään 0,001, enintään 9999, oletus 1
uniteienintään 20 merkkiä, oletus Stk.
taxRateeiHotellin aktiivinen ALV-kanta. Jos sitä ei anneta, käytetään outletin oletusta ja sen jälkeen keskitettyä arvoa.
currencyeiOn oltava hotellin valuutta
outletIdeiAvaimella, jolla on outlet, käytetään tätä outletia. Muu arvo antaa tilan 403.
chargedAteiPalvelun ajankohta, oletus nyt, enintään 5 minuuttia tulevaisuudessa
notes, posRefeiMuistiinpano (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.

TilaMerkitys
400Virheelliset tiedot, korjaa ne.
401Avainta ei voi tarkistaa
403Alue ei ole sallittu, esimerkiksi väärä outlet
404Tiliä tai veloitusta ei ole
409Liiketoiminnallinen ristiriita. Tarkista koodi äläkä toista sokkona.
429Kutsurajoitus, odota vähintään 60 sekuntia
5xxTä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, cancelled tai transferred.
  • Veloitus pysyy tilassa open, kunnes lähtö luo laskun. Sen jälkeen STRYK siirtää avoimet veloitukset laskurivyiksi ja tila vaihtuu tilaan transferred.
  • 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.

TietoArvo
Tapahtumatcharge.posted, charge.cancelled, testauksessa ping
Otsake X-STRYK-EventTapahtuman nimi
Otsake X-STRYK-Webhook-IdWebhookin tunniste, ei toimituksen
Otsake X-STRYK-Signaturesha256= ja pyynnön muuttumattomien tavujen HMAC-SHA-256. Vain määritetyllä salaisuudella.
Runkoevent, hotelId, timestamp, data, jossa chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency ja outlet
Vastaus2xx pysyvän hyväksynnän jälkeen 10 sekunnin sisällä. STRYK ei seuraa uudelleenohjauksia.
Uudelleenyritys30 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:

  1. Tarkista /ping sekä vieras- ja huonemääritys, myös varauksilla, joissa on useita huoneita.
  2. Tarkista veroa, valuuttaa ja avaimen outlet-rajoitusta.
  3. Täsmällinen toisto ilman kaksoisveloitusta, muuttunut sisältö tilalla 409, kadonnut vastaus täsmäytyksellä.
  4. Erä kokonaan tai ei lainkaan, lukitus ja limiitti, peruutus ja peruutuksen toisto.
  5. Laskusummat uloskirjautumisessa ja peruutuksen hylkääminen siirron jälkeen.
  6. Allekirjoitettu webhook, virheellinen allekirjoitus, kaksinkertainen ja väärään järjestykseen mennyt toimitus.
  7. 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.

MetodiPolkuLyhyt kuvaus
GET/pingTarkista yhteys
GET/accountsLuettele sisäänkirjautuneiden huoneiden tilit
GET/room-lookupEtsi huoneen majoitus
POST/chargesKirjaa yksi veloitus
POST/charges/batchKirjaa enintään 50 veloitusta yhdessä
GET/charges/{externalRef}Lue veloituksen tila
DELETE/charges/{externalRef}Peruuta yksi avoin veloitus
Yhteystiedot