POS Posting API for kassesystemprodusenter
STRYK POS Posting API bokfører posteringer fra kassen din på romkontoer for innsjekkede gjester. Referansen viser innlogging, bokføring, storno og webhooks.
Contents
Oversikt
API-et er et server-til-server-grensesnitt for posteringer på innsjekkede opphold. Hotellet kobler kassen din til under Innstillinger under POS: Koble til kasse. Der får kassen en nøkkel og Adresse for kassen.
| Angivelse | Verdi |
|---|---|
| Grunnadresse | https://app.staystryk.com/api/v1/pos/public |
| Innlogging | Hotellets bærer-nøkkel i headeren Authorization |
| Forutsetning | Hotellet har tilleggsmodulen STRYK POS aktiv |
| Uten tilleggsmodul | Hvert kall svarer med 403 og koden module_disabled. STRYK skriver ingen postering. |
| Kallgrense | 100 forespørsler per 60 sekunder og nøkkel. Deretter svarer STRYK med 429. |
| Versjon av beskrivelsen | 1.3.0 |
Nøkler og sikkerhet
- Nøkkelen starter med
pos_live_. Hotellet ser den bare én gang ved opprettelse. - Send den bare fra serveren over HTTPS i headeren:
Authorization: Bearer <vollständiger Schlüssel>. Aldri som parameter i adressen. - En nøkkel tilhører nøyaktig ett hotell og eventuelt ett outlet. Hotellet oppretter en nøkkel per tilkobling.
- 401 betyr: STRYK kunne ikke kontrollere nøkkelen. Kontroller konfigurasjonen og driftsstatusen. Bytt ikke nøkkelen automatisk.
- En ny nøkkel er et nytt idempotensområde. Den finner og stornerer ikke posteringer fra den gamle nøkkelen. Arbeid ferdig åpne oppdrag og avstem dem før hotellet trekker tilbake den gamle nøkkelen.
- Hvis en nøkkel er tapt eller kompromittert, trekker hotellet den tilbake med Tilbakekall nøkkel og avklarer usikre prosesser i STRYK før kassen din sender erstatning.
Romkonto og beløp
| Metode og sti | Formål |
|---|---|
GET /ping | Kontrollerer bare at nøkkelen blir godtatt. |
GET /accounts | Lister de innsjekkede romkontoene som er aktive nå, også sperrede. |
GET /room-lookup?room=105 | Finner oppholdet for et rom som er innsjekket. 404 uten passende gjest, 409 ved tvetydig rom. |
Romkontoen inneholder disse feltene:
| Felt | Betydning |
|---|---|
bookingId, bookingNumber, guestName, roomNumber | Opphold og rom |
allowPosting | Hotellet har tillatt posteringer for oppholdet. Alene er det ikke nok. |
allowCharge | Totalkontroll av tillatelse, restgrense og lukket konto. Kontroller den rett før bokføring. |
postingBlockReason | no_post, credit_limit_reached, account_closed eller tom |
openChargesCount, openChargesTotal, stayChargesTotal | Åpne posteringer og sum av ikke-stornerte posteringer |
creditLimit, remainingCredit, currency | Grense, restgrense og hotellvaluta |
Vis gjest og rom til bekreftelse og send bookingId sammen med room. Behold ikke kontolisten permanent som gjesteregister. Beløp er JSON-tall i hotellvaluta. Avrundingen er HALF_UP: mengde på tre, beløp på to desimaler.
Bokføring og gjentakelse
| Metode og sti | Formål |
|---|---|
POST /charges | Bokfører en postering på en romkonto. Svar 201 med posteringen. |
POST /charges/batch | Bokfører 1 til 50 posteringer samlet. Alle nye posteringer bokføres, eller ingen. Svaret følger rekkefølgen i forespørselen. |
GET /charges/{externalRef} | Gir den varige tilstanden til en postering, også cancelled og transferred. |
Felt i en bokføring:
| Felt | Påkrevd | Betydning |
|---|---|---|
bookingId, room | minst ett | Rom som tekst med bokstaver, ikke som tall. Hvis begge er oppgitt, må de passe sammen. |
description | ja | 1 til 500 tegn |
unitPrice | ja | Bruttopris per enhet, større enn 0, høyst 99999.99 |
externalRef | ja | Entydig bilag- eller posteringsnøkkel, 1 til 255 tegn, for eksempel receipt-123-item-1 |
quantity | nei | 0,001 til 9999, standard 1 |
unit | nei | Høyst 20 tegn, standard Stk. |
taxRate | nei | Aktiv MVA-sats for hotellet. Uten angivelse gjelder standarden for outletet, deretter den sentrale. |
currency | nei | Må være hotellvalutaen |
outletId | nei | Ved en nøkkel med outlet gjelder dette outletet. En annen verdi gir 403. |
chargedAt | nei | Tidspunkt for ytelsen, standard nå, høyst 5 minutter frem i tid |
notes, posRef | nei | Notat (1000 tegn), bilagsreferanse for resepsjonen (100 tegn) |
Totalbeløpet av mengde og enhetspris er større enn 0 og høyst 99999999.99.
externalRef er den uforanderlige idempotensnøkkelen for hotell og nøkkel. En eksakt gjentakelse gir den opprinnelige posteringen med idempotentReplay=true. Et endret innhold eller en stornert nøkkel gir 409.
Etter timeout eller 5xx leser du først GET /charges/{externalRef}. Bare ved bekreftet 404 sender du samme forespørsel uendret med samme nøkkel på nytt. Lagre forespørsler før sending, og endre aldri chargedAt, pris, MVA eller referanse. Viser svaret duplicateWarning, er posteringen allerede bokført. Avstem den i STRYK og send den ikke på nytt.
| Status | Betydning |
|---|---|
| 400 | Ugyldige opplysninger, korriger dem. |
| 401 | Nøkkel kan ikke kontrolleres |
| 403 | Område ikke tillatt, for eksempel feil outlet |
| 404 | Konto eller postering finnes ikke |
| 409 | Faglig konflikt. Kontroller koden, ikke gjenta blindt. |
| 429 | Kallgrense, vent minst 60 sekunder |
| 5xx | Avstem først, og prøv deretter igjen med begrenset backoff |
Feilsvarets koder er blant annet 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 og pos_account_closed. Ikke forgren etter tysk tekst. requestId hjelper supporten.
Storno og faktura
DELETE /charges/{externalRef} stornerer en åpen postering for nøkkelen din. I forespørselens body står valgfritt reason (høyst 500 tegn). En gjentakelse gir den stornerte posteringen på nytt.
- Statusen til en postering er
open,cancelledellertransferred. - En postering forblir
opentil utsjekk lager fakturaen. Da overtar STRYK åpne posteringer som fakturalinjer, og statusen endres tiltransferred. - En overtatt postering gir 409 med
pos_charge_already_invoiced. Hotellet korrigerer den i regnskapet: Korriger faktura. - En storno sletter ingenting og refunderer ikke noe. Den stornerte posteringen forblir sporbar.
API-et bokfører positive posteringer. Betalinger som fullføres i kassen, sender du ikke i tillegg til rommet. Ved delt betaling sender du bare den åpne romandelen med riktig fordelt MVA. Rabatter trekker du fra bruttoprisen før bokføring.
Webhooks og godkjenning
Hotellet oppretter webhooks under Innstillinger under POS: Opprett webhooks.
| Angivelse | Verdi |
|---|---|
| Hendelser | charge.posted, charge.cancelled, ved testing ping |
Header X-STRYK-Event | Hendelsesnavn |
Header X-STRYK-Webhook-Id | ID for webhooken, ikke for leveransen |
Header X-STRYK-Signature | sha256= og HMAC-SHA-256 av de uendrede bytene i forespørselen. Bare med konfigurert hemmelighet. |
| Body | event, hotelId, timestamp, data med chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency og outlet |
| Svar | 2xx etter varig godkjenning innen 10 sekunder. STRYK følger ikke omdirigeringer. |
| Gjentakelse | Etter 30 sekunder, 5 minutter, 30 minutter og 2 timer, til den lagrede grensen |
Verifiser signaturen over den uendrede bodyen før du leser den som JSON. Lagre event og data.chargeId varig for å gjenkjenne gjentakelser. Leveringer kan komme to ganger eller i feil rekkefølge: En gammel charge.posted overskriver ikke en charge.cancelled. For innsjekk, utsjekk og fakturaoverføring finnes det ingen webhooks. Les tilstanden der på nytt.
Godkjenningsliste med et testhotell og et ekte innsjekket testopphold:
- Kontroller
/pingog gjest- og romtilordning, også ved bestillinger med flere rom. - Kontroller MVA, valuta og outletbegrensningen for nøkkelen.
- Eksakt gjentakelse uten dobbeltposteringer, endret innhold med 409, tapt svar med avstemming.
- Batch enten helt eller ikke i det hele, sperre og grense, storno og gjentatt storno.
- Fakturasummer ved utsjekk og avvisning av storno etter overtakelse.
- Signert webhook, ugyldig signatur, dobbel og omvendt levering.
- Feilvisning, nøkkelbytte og avstemming av personalet.
Teknisk referanse
Den fullstendige beskrivelsen finnes som OpenAPI-fil på engelsk, som YAML under /developers/pos/openapi.yaml og som JSON under /developers/pos/openapi.json på nettstedet til STRYK. I hotellet fører Teknisk dokumentasjon i området For kassateknikeren under Innstillinger under POS til denne siden.
| Metode | Sti | Kort beskrivelse |
|---|---|---|
| GET | /ping | Kontroller tilkoblingen |
| GET | /accounts | List innsjekkede romkontoer |
| GET | /room-lookup | Finn opphold for et rom |
| POST | /charges | Bokfør en postering |
| POST | /charges/batch | Bokfør opptil 50 posteringer samlet |
| GET | /charges/{externalRef} | Les tilstanden til en postering |
| DELETE | /charges/{externalRef} | Storner en åpen postering |