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.
Contents
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.
| Dada | Valor |
|---|---|
| Adreça base | https://app.staystryk.com/api/v1/pos/public |
| Autenticació | Clau Bearer de l'hotel a la capçalera Authorization |
| Requisit | L'hotel té activat el mòdul addicional STRYK POS |
| Sense mòdul addicional | Cada crida respon amb 403 i el codi module_disabled. STRYK no registra cap càrrec. |
| Límit de crides | 100 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 ruta | Finalitat |
|---|---|
GET /ping | Només comprova si la clau és acceptada. |
GET /accounts | Llista els comptes d'habitació amb check-in actualment, també els bloquejats. |
GET /room-lookup?room=105 | Relaciona 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:
| Camp | Significat |
|---|---|
bookingId, bookingNumber, guestName, roomNumber | Estada i habitació |
allowPosting | L'hotel ha permès els càrrecs per a l'estada. Només això no és suficient. |
allowCharge | Comprovació global de permís, límit restant i compte tancat. Comprova-la just abans de registrar. |
postingBlockReason | no_post, credit_limit_reached, account_closed o buit |
openChargesCount, openChargesTotal, stayChargesTotal | Càrrecs oberts i suma dels càrrecs no anulats |
creditLimit, remainingCredit, currency | Lí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 ruta | Finalitat |
|---|---|
POST /charges | Registra un càrrec en un compte d'habitació. Resposta 201 amb el càrrec. |
POST /charges/batch | Registra 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:
| Camp | Obligatori | Significat |
|---|---|---|
bookingId, room | almenys un | Habitació com a text amb lletres, no com a número. Si s'envien tots dos, han de coincidir. |
description | sí | De 1 a 500 caràcters |
unitPrice | sí | Preu brut per unitat, més gran que 0, com a màxim 99999.99 |
externalRef | sí | Clau única del justificant o del càrrec, de 1 a 255 caràcters, per exemple receipt-123-item-1 |
quantity | no | De 0,001 a 9999, per defecte 1 |
unit | no | Com a màxim 20 caràcters, per defecte Stk. |
taxRate | no | Tipus impositiu actiu de l'hotel. Si no s'indica, s'aplica el del punt de venda i, després, el central. |
currency | no | Ha de ser la moneda de l'hotel |
outletId | no | Si la clau té un punt de venda, s'aplica aquest. Un altre valor dona 403. |
chargedAt | no | Moment de la prestació, per defecte ara, com a màxim 5 minuts en el futur |
notes, posRef | no | Nota (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.
| Estat | Significat |
|---|---|
| 400 | Dades no vàlides, corregeix-les. |
| 401 | Clau no verificable |
| 403 | Àmbit no permès, per exemple punt de venda incorrecte |
| 404 | Compte o càrrec inexistent |
| 409 | Conflicte funcional. Revisa el codi i no repeteixis a cegues. |
| 429 | Límit de crides, espera almenys 60 segons |
| 5xx | Concilia 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,cancelledotransferred. - Un càrrec es manté
openfins que el check-out genera la factura. Després, STRYK passa els càrrecs oberts a les posicions de factura i l'estat canvia atransferred. - 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.
| Dada | Valor |
|---|---|
| Esdeveniments | charge.posted, charge.cancelled, en provar ping |
Capçalera X-STRYK-Event | Nom de l'esdeveniment |
Capçalera X-STRYK-Webhook-Id | ID del webhook, no de l'enviament |
Capçalera X-STRYK-Signature | sha256= i HMAC-SHA-256 dels bytes sense canvis de la petició. Només amb un secret configurat. |
| Cos | event, hotelId, timestamp, data amb chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency i punt de venda |
| Resposta | 2xx 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:
- Comprova
/pingi l'assignació d'hoste i habitació, també en reserves amb diverses habitacions. - Comprova l'impost, la moneda i la restricció de punt de venda de la clau.
- Repetició exacta sense duplicats, contingut modificat amb 409, resposta perduda amb conciliació.
- Lot tot o res, bloqueig i límit, anulació i repetició d'anulació.
- Totals de factura al check-out i rebuig de l'anulació després de la transferència.
- Webhook signat, signatura no vàlida, lliurament duplicat i en ordre invertit.
- 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ètode | Ruta | Descripció breu |
|---|---|---|
| GET | /ping | Comprova la connexió |
| GET | /accounts | Llista els comptes d'habitació amb check-in |
| GET | /room-lookup | Troba l'estada d'una habitació |
| POST | /charges | Registra un càrrec |
| POST | /charges/batch | Registra fins a 50 càrrecs junts |
| GET | /charges/{externalRef} | Llegeix l'estat d'un càrrec |
| DELETE | /charges/{externalRef} | Anula un càrrec obert |