# POS Posting API per a fabricants de caixes

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

Referència de la STRYK POS Posting API per a fabricants de caixes: autenticació, compte d'habitació, registre, anulació, webhooks i llista d'acceptació.

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

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

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:

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

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:

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.

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

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.

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 /ping i 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.

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
