Salta al contingut
Reference, STRYK POS

POS Posting API per a fabricants de caixes

La STRYK POS Posting API registra càrrecs de la teva caixa en comptes d'habitació d'hostes amb check-in fet. La referència mostra l'autenticació, el registre, l'anulació i els webhooks.

Last updated: Developers
Contents
  1. Resum
  2. Clau i seguretat
  3. Compte d'habitació i imports
  4. Registrar i repetir
  5. Anulació i factura
  6. Webhooks i acceptació
  7. Referència tècnica

Resum

L'API és una interfície de servidor a servidor per a càrrecs en estades amb check-in fet. L'hotel connecta la teva caixa a Configuració dins de POS: Connecta la caixa. Allà la caixa rep una clau i l'Adreça per a la caixa.

DadaValor
Adreça basehttps://app.staystryk.com/api/v1/pos/public
AutenticacióClau Bearer de l'hotel a la capçalera Authorization
RequisitL'hotel té activat el mòdul addicional STRYK POS
Sense mòdul addicionalCada crida respon amb 403 i el codi module_disabled. STRYK no registra cap càrrec.
Límit de crides100 peticions cada 60 segons per clau. Després, STRYK respon amb 429.
Versió de la descripció1.3.0

Clau i seguretat

  • La clau comença amb pos_live_. L'hotel la veu només una vegada en crear-la.
  • Envia'l només des del servidor per HTTPS a la capçalera: Authorization: Bearer <vollständiger Schlüssel>. Mai com a paràmetre a l'adreça.
  • Una clau pertany a exactament un hotel i, opcionalment, a un punt de venda. L'hotel crea una clau per cada connexió.
  • 401 vol dir que STRYK no ha pogut comprovar la clau. Revisa la configuració i l'estat del servei. No canviïs la clau automàticament.
  • Una clau nova és un àmbit d'idempotència nou. No troba ni anula càrrecs de la clau antiga. Acaba els encàrrecs oberts i concilia'ls abans que l'hotel revoqui la clau antiga.
  • Si una clau es perd o es compromet, l'hotel la revoca amb Revoca la clau i aclareix les operacions insegures a STRYK abans que la teva caixa n'enviï una de nova.

Compte d'habitació i imports

Mètode i rutaFinalitat
GET /pingNomés comprova si la clau és acceptada.
GET /accountsLlista els comptes d'habitació amb check-in actualment, també els bloquejats.
GET /room-lookup?room=105Relaciona una habitació amb l'estada amb check-in. 404 si no hi ha cap hoste corresponent, 409 si l'habitació és ambigua.

El compte d'habitació conté aquests camps:

CampSignificat
bookingId, bookingNumber, guestName, roomNumberEstada i habitació
allowPostingL'hotel ha permès els càrrecs per a l'estada. Només això no és suficient.
allowChargeComprovació global de permís, límit restant i compte tancat. Comprova-la just abans de registrar.
postingBlockReasonno_post, credit_limit_reached, account_closed o buit
openChargesCount, openChargesTotal, stayChargesTotalCàrrecs oberts i suma dels càrrecs no anulats
creditLimit, remainingCredit, currencyLímit, límit restant i moneda de l'hotel

Mostra l'hoste i l'habitació per confirmar i envia bookingId juntament amb room. No guardis la llista de comptes com a directori d'hostes de manera permanent. Els imports són números JSON en la moneda de l'hotel. L'arrodoniment és HALF_UP: la quantitat a tres decimals i els imports a dos.

Registrar i repetir

Mètode i rutaFinalitat
POST /chargesRegistra un càrrec en un compte d'habitació. Resposta 201 amb el càrrec.
POST /charges/batchRegistra de 1 a 50 càrrecs junts. Tots els càrrecs nous es registren o cap. La resposta segueix l'ordre de la petició.
GET /charges/{externalRef}Retorna l'estat permanent d'un càrrec, també cancelled i transferred.

Camps d'un registre:

CampObligatoriSignificat
bookingId, roomalmenys unHabitació com a text amb lletres, no com a número. Si s'envien tots dos, han de coincidir.
descriptionsíDe 1 a 500 caràcters
unitPricesíPreu brut per unitat, més gran que 0, com a màxim 99999.99
externalRefsíClau única del justificant o del càrrec, de 1 a 255 caràcters, per exemple receipt-123-item-1
quantitynoDe 0,001 a 9999, per defecte 1
unitnoCom a màxim 20 caràcters, per defecte Stk.
taxRatenoTipus impositiu actiu de l'hotel. Si no s'indica, s'aplica el del punt de venda i, després, el central.
currencynoHa de ser la moneda de l'hotel
outletIdnoSi la clau té un punt de venda, s'aplica aquest. Un altre valor dona 403.
chargedAtnoMoment de la prestació, per defecte ara, com a màxim 5 minuts en el futur
notes, posRefnoNota (1000 caràcters), referència del justificant per a recepció (100 caràcters)

L'import total de quantitat per preu unitari és més gran que 0 i com a màxim 99999999.99.

externalRef és la clau d'idempotència immutable de l'hotel i de la clau. Una repetició exacta retorna el càrrec original amb idempotentReplay=true. Un contingut modificat o una clau anulada dona 409.

Després d'un temps d'espera o d'un 5xx, llegeix primer GET /charges/{externalRef}. Només si es confirma un 404 envia la mateixa petició sense canvis amb la mateixa clau. Desa les peticions abans d'enviar-les i no canviïs mai chargedAt, preu, impost ni referència. Si la resposta mostra duplicateWarning, el càrrec ja està registrat. Concilia'l a STRYK i no l'enviïs de nou.

EstatSignificat
400Dades no vàlides, corregeix-les.
401Clau no verificable
403Àmbit no permès, per exemple punt de venda incorrecte
404Compte o càrrec inexistent
409Conflicte funcional. Revisa el codi i no repeteixis a cegues.
429Límit de crides, espera almenys 60 segons
5xxConcilia primer i després repeteix amb una espera limitada

Els codis de la resposta d'error són, entre d'altres, 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 i pos_account_closed. No condicionis la lògica al text en alemany. requestId ajuda el suport.

Anulació i factura

DELETE /charges/{externalRef} anula un càrrec obert de la teva clau. Al cos hi pots indicar opcionalment reason (com a màxim 500 caràcters). Una repetició retorna de nou el càrrec anulat.

  • L'estat d'un càrrec és open, cancelled o transferred.
  • Un càrrec es manté open fins que el check-out genera la factura. Després, STRYK passa els càrrecs oberts a les posicions de factura i l'estat canvia a transferred.
  • Un càrrec transferit dona 409 amb pos_charge_already_invoiced. L'hotel el corregeix a la comptabilitat: Corregeix una factura.
  • Una anulació no esborra ni reembossa res. El càrrec anulat continua sent traçable.

L'API registra càrrecs positius. Els pagaments que es tanquen a la caixa no els enviïs també a l'habitació. En un pagament dividit, envia només la part oberta de l'habitació amb l'impost repartit correctament. Els descomptes els restes del preu brut abans de registrar.

Webhooks i acceptació

L'hotel crea webhooks a Configuració dins de POS: Crea webhooks.

DadaValor
Esdevenimentscharge.posted, charge.cancelled, en provar ping
Capçalera X-STRYK-EventNom de l'esdeveniment
Capçalera X-STRYK-Webhook-IdID del webhook, no de l'enviament
Capçalera X-STRYK-Signaturesha256= i HMAC-SHA-256 dels bytes sense canvis de la petició. Només amb un secret configurat.
Cosevent, hotelId, timestamp, data amb chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency i punt de venda
Resposta2xx després d'acceptar-lo de manera permanent en 10 segons. STRYK no segueix redireccions.
RepeticióDesprés de 30 segons, 5 minuts, 30 minuts i 2 hores, fins al límit desat

Verifica la signatura sobre el cos sense canvis abans de llegir-lo com a JSON. Desa de manera permanent event i data.chargeId per reconèixer les repeticions. Els lliuraments poden arribar duplicats o en un altre ordre: un charge.posted antic no sobreescriu un charge.cancelled. Per a check-in, check-out i transferència de factures no hi ha webhooks. Llegeix-hi l'estat de nou.

Llista d'acceptació amb un hotel de prova i una estada de prova real amb check-in:

  1. Comprova /ping i l'assignació d'hoste i habitació, també en reserves amb diverses habitacions.
  2. Comprova l'impost, la moneda i la restricció de punt de venda de la clau.
  3. Repetició exacta sense duplicats, contingut modificat amb 409, resposta perduda amb conciliació.
  4. Lot tot o res, bloqueig i límit, anulació i repetició d'anulació.
  5. Totals de factura al check-out i rebuig de l'anulació després de la transferència.
  6. Webhook signat, signatura no vàlida, lliurament duplicat i en ordre invertit.
  7. Indicació d'error, canvi de clau i conciliació per part del personal.

Referència tècnica

La descripció completa és un fitxer OpenAPI en anglès, com a YAML a /developers/pos/openapi.yaml i com a JSON a /developers/pos/openapi.json al lloc web de STRYK. A l'hotel, Documentació tècnica a l'àmbit Per al tècnic de caixa de Configuració, sota POS, porta a aquesta pàgina.

MètodeRutaDescripció breu
GET/pingComprova la connexió
GET/accountsLlista els comptes d'habitació amb check-in
GET/room-lookupTroba l'estada d'una habitació
POST/chargesRegistra un càrrec
POST/charges/batchRegistra fins a 50 càrrecs junts
GET/charges/{externalRef}Llegeix l'estat d'un càrrec
DELETE/charges/{externalRef}Anula un càrrec obert
Contacte