# POS Posting API kassavalmistajille

Canonical: https://staystryk.com/fi/documentation/pos-integration/
Language: fi
Updated: 2026-11-12

Viite STRYK POS Posting API:lle kassavalmistajille: todennus, huoneen tili, veloitukset, peruutukset, webhookit ja hyväksymislista.

## 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.

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

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:

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

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:

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.

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, 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: .

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.

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 /ping sekä 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.

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
