Hopp til innholdet
Reference, STRYK POS

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.

Last updated: Developers
Contents
  1. Oversikt
  2. Nøkler og sikkerhet
  3. Romkonto og beløp
  4. Bokføring og gjentakelse
  5. Storno og faktura
  6. Webhooks og godkjenning
  7. Teknisk referanse

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.

AngivelseVerdi
Grunnadressehttps://app.staystryk.com/api/v1/pos/public
InnloggingHotellets bærer-nøkkel i headeren Authorization
ForutsetningHotellet har tilleggsmodulen STRYK POS aktiv
Uten tilleggsmodulHvert kall svarer med 403 og koden module_disabled. STRYK skriver ingen postering.
Kallgrense100 forespørsler per 60 sekunder og nøkkel. Deretter svarer STRYK med 429.
Versjon av beskrivelsen1.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 stiFormål
GET /pingKontrollerer bare at nøkkelen blir godtatt.
GET /accountsLister de innsjekkede romkontoene som er aktive nå, også sperrede.
GET /room-lookup?room=105Finner oppholdet for et rom som er innsjekket. 404 uten passende gjest, 409 ved tvetydig rom.

Romkontoen inneholder disse feltene:

FeltBetydning
bookingId, bookingNumber, guestName, roomNumberOpphold og rom
allowPostingHotellet har tillatt posteringer for oppholdet. Alene er det ikke nok.
allowChargeTotalkontroll av tillatelse, restgrense og lukket konto. Kontroller den rett før bokføring.
postingBlockReasonno_post, credit_limit_reached, account_closed eller tom
openChargesCount, openChargesTotal, stayChargesTotalÅpne posteringer og sum av ikke-stornerte posteringer
creditLimit, remainingCredit, currencyGrense, 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 stiFormål
POST /chargesBokfører en postering på en romkonto. Svar 201 med posteringen.
POST /charges/batchBokfø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:

FeltPåkrevdBetydning
bookingId, roomminst ettRom som tekst med bokstaver, ikke som tall. Hvis begge er oppgitt, må de passe sammen.
descriptionja1 til 500 tegn
unitPricejaBruttopris per enhet, større enn 0, høyst 99999.99
externalRefjaEntydig bilag- eller posteringsnøkkel, 1 til 255 tegn, for eksempel receipt-123-item-1
quantitynei0,001 til 9999, standard 1
unitneiHøyst 20 tegn, standard Stk.
taxRateneiAktiv MVA-sats for hotellet. Uten angivelse gjelder standarden for outletet, deretter den sentrale.
currencyneiMå være hotellvalutaen
outletIdneiVed en nøkkel med outlet gjelder dette outletet. En annen verdi gir 403.
chargedAtneiTidspunkt for ytelsen, standard nå, høyst 5 minutter frem i tid
notes, posRefneiNotat (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.

StatusBetydning
400Ugyldige opplysninger, korriger dem.
401Nøkkel kan ikke kontrolleres
403Område ikke tillatt, for eksempel feil outlet
404Konto eller postering finnes ikke
409Faglig konflikt. Kontroller koden, ikke gjenta blindt.
429Kallgrense, vent minst 60 sekunder
5xxAvstem 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, cancelled eller transferred.
  • En postering forblir open til utsjekk lager fakturaen. Da overtar STRYK åpne posteringer som fakturalinjer, og statusen endres til transferred.
  • 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.

AngivelseVerdi
Hendelsercharge.posted, charge.cancelled, ved testing ping
Header X-STRYK-EventHendelsesnavn
Header X-STRYK-Webhook-IdID for webhooken, ikke for leveransen
Header X-STRYK-Signaturesha256= og HMAC-SHA-256 av de uendrede bytene i forespørselen. Bare med konfigurert hemmelighet.
Bodyevent, hotelId, timestamp, data med chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency og outlet
Svar2xx etter varig godkjenning innen 10 sekunder. STRYK følger ikke omdirigeringer.
GjentakelseEtter 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:

  1. Kontroller /ping og gjest- og romtilordning, også ved bestillinger med flere rom.
  2. Kontroller MVA, valuta og outletbegrensningen for nøkkelen.
  3. Eksakt gjentakelse uten dobbeltposteringer, endret innhold med 409, tapt svar med avstemming.
  4. Batch enten helt eller ikke i det hele, sperre og grense, storno og gjentatt storno.
  5. Fakturasummer ved utsjekk og avvisning av storno etter overtakelse.
  6. Signert webhook, ugyldig signatur, dobbel og omvendt levering.
  7. 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.

MetodeStiKort beskrivelse
GET/pingKontroller tilkoblingen
GET/accountsList innsjekkede romkontoer
GET/room-lookupFinn opphold for et rom
POST/chargesBokfør en postering
POST/charges/batchBokfør opptil 50 posteringer samlet
GET/charges/{externalRef}Les tilstanden til en postering
DELETE/charges/{externalRef}Storner en åpen postering
Kontakt