# POS Posting API za proizvođače blagajni

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

Referenca STRYK POS Posting API za proizvođače blagajni: prijava, račun sobe, knjiženje, storno, webhooki i lista za prihvat.

## Pregled

API je serverski interfejs za stavke na prijavljene boravke. Hotel povezuje tvoju blagajnu u Postavke pod POS: Poveži blagajnu. Tamo blagajna dobija ključ i Adresu za blagajnu.

Osnovna adresa, https://app.staystryk.com/api/v1/pos/public

Prijava, Bearer ključ hotela u zaglavlju Authorization

Preduslov, Hotel ima aktivan dodatni modul STRYK POS

Bez dodatnog modula, Svaki poziv odgovara sa 403 i kodom module\_disabled. STRYK ne knjiži nijednu stavku.

Ograničenje poziva, 100 zahtjeva po 60 sekundi i ključu. Nakon toga STRYK odgovara sa 429.

Verzija opisa, 1.3.0

## Ključ i sigurnost

Ključ počinje s pos\_live\_. Hotel ga vidi samo jednom prilikom kreiranja.

Šalji ga samo na serveru preko HTTPS-a u zaglavlju: Authorization: Bearer \<vollständiger Schlüssel\>. Nikada kao parametar u adresi.

Ključ pripada tačno jednom hotelu i opcionalno jednom outletu. Hotel kreira jedan ključ po vezi.

401 znači: STRYK nije mogao provjeriti ključ. Provjeri konfiguraciju i operativni status. Ne mijenjaj ključ automatski.

Novi ključ je novi opseg idempotentnosti. Ne pronalazi niti stornira stavke starog ključa. Obradi otvorene naloge i uskladi ih prije nego što hotel opozove stari ključ.

Ako je ključ izgubljen ili kompromitovan, hotel ga opoziva pomoću Opozovi ključ i razjašnjava nesigurne radnje u STRYK-u prije nego što tvoja blagajna pošalje zamjenu.

## Račun sobe i iznosi

GET /ping, Provjerava samo, je li ključ prihvaćen.

GET /accounts, Navodi trenutno prijavljene račune soba, uključujući blokirane.

GET /room-lookup?room=105, Povezuje sobu s prijavljenim boravkom. 404 bez odgovarajućeg gosta, 409 kod dvosmislene sobe.

Račun sobe sadrži ova polja:

bookingId, bookingNumber, guestName, roomNumber, Boravak i soba

allowPosting, Hotel je dozvolio stavke za boravak. Samo to nije dovoljno.

allowCharge, Ukupna provjera iz dozvole, preostalog limita i zatvorenog računa. Provjeri je neposredno prije knjiženja.

postingBlockReason, no\_post, credit\_limit\_reached, account\_closed ili prazno

openChargesCount, openChargesTotal, stayChargesTotal, Otvorene stavke i zbir nestornираnih stavki

creditLimit, remainingCredit, currency, Limit, preostali limit i valuta hotela

Prikaži gosta i sobu radi potvrde i pošalji bookingId zajedno s room. Ne čuvaj listu računa trajno kao adresar gostiju. Iznosi su JSON brojevi u valuti hotela. Zaokruživanje je HALF\_UP: količina na tri, iznosi na dvije decimale.

## Knjiženje i ponavljanje

POST /charges, Knjiži stavku na račun sobe. Odgovor 201 sa stavkom.

POST /charges/batch, Knjiži 1 do 50 stavki zajedno. Sve nove stavke se knjiže ili nijedna. Odgovor slijedi redoslijed zahtjeva.

GET /charges/{externalRef}, Vraća trajno stanje stavke, uključujući cancelled i transferred.

Polja jedne knjižene stavke:

bookingId, room, barem jedno, Soba kao tekst sa slovima, ne kao broj. Ako su navedena oba, moraju se slagati.

description, da, 1 do 500 znakova

unitPrice, da, Bruto cijena po jedinici, veća od 0, najviše 99999.99

externalRef, da, Jedinstveni ključ računa ili stavke, 1 do 255 znakova, na primjer receipt-123-item-1

quantity, ne, 0,001 do 9999, standard 1

unit, ne, najviše 20 znakova, standard Stk.

taxRate, ne, Aktivna poreska stopa hotela. Bez navođenja vrijedi standard outleta, zatim centralni.

currency, ne, Mora biti valuta hotela

outletId, ne, Kod ključa s outletom vrijedi taj outlet. Druga vrijednost daje 403.

chargedAt, ne, Vrijeme usluge, standard sada, najviše 5 minuta u budućnosti

notes, posRef, ne, Napomena (1000 znakova), referenca računa za recepciju (100 znakova)

Ukupni iznos iz količine i jedinične cijene je veći od 0 i najviše 99999999.99.

externalRef je nepromjenjiv ključ idempotentnosti hotela i ključa. Tačno ponavljanje vraća originalnu stavku s idempotentReplay=true. Promijenjen sadržaj ili stornirani ključ daje 409.

Nakon timeouta ili 5xx prvo čitaš GET /charges/{externalRef}. Samo kod potvrđenog 404 šalješ isti zahtjev nepromijenjen s istim ključem ponovo. Spremi zahtjeve prije slanja i nikada ne mijenjaj chargedAt, cijenu, porez ili referencu. Ako odgovor pokazuje duplicateWarning, stavka je već knjižena. Uskladi je u STRYK-u i ne šalji ponovo.

400, Neispravni podaci, ispravi ih.

401, Ključ se ne može provjeriti

403, Opseg nije dozvoljen, na primjer pogrešan outlet

404, Račun ili stavka ne postoji

409, Poslovni konflikt. Provjeri kod, ne ponavljaj slijepo.

429, Ograničenje poziva, sačekaj najmanje 60 sekundi

5xx, Prvo uskladi, zatim ponovi s ograničenim backoffom

Kodovi greške su, između ostalih, 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. Ne grani prema tekstu na njemačkom. requestId pomaže podršci.

## Storno i račun

DELETE /charges/{externalRef} stornira otvorenu stavku tvog ključa. U tijelu zahtjeva opcionalno stoji reason (najviše 500 znakova). Ponavljanje ponovo vraća stornirani stavku.

Status stavke je open, cancelled ili transferred.

Stavka ostaje open dok odjava ne kreira račun. Tada STRYK preuzima otvorene stavke u stavke računa i status prelazi u transferred.

Preuzeta stavka daje 409 s pos\_charge\_already\_invoiced. Hotel je ispravlja u računovodstvu: .

Storno ništa ne briše i ništa ne vraća. Stornirana stavka ostaje vidljiva.

API knjiži pozitivne stavke. Plaćanja koja se završe na blagajni ne šalji dodatno na sobu. Kod podijeljenog plaćanja šalji samo otvoreni udio sobe s ispravno raspoređenim porezom. Popuste oduzmi od bruto cijene prije knjiženja.

## Webhooki i prihvatanje

Hotel kreira webhooke u Postavke pod POS: Kreiraj webhooke.

Događaji, charge.posted, charge.cancelled, pri testiranju ping

Zaglavlje X-STRYK-Event, Naziv događaja

Zaglavlje X-STRYK-Webhook-Id, ID webhooka, ne isporuke

Zaglavlje X-STRYK-Signature, sha256= i HMAC-SHA-256 nepromijenjenih bajtova zahtjeva. Samo uz konfigurirani secret.

Tijelo, event, hotelId, timestamp, data s chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency i outlet

Odgovor, 2xx nakon trajnog prihvatanja unutar 10 sekundi. STRYK ne prati preusmjeravanja.

Ponavljanje, Nakon 30 sekundi, 5 minuta, 30 minuta i 2 sata, do sačuvane granice

Provjeri potpis preko nepromijenjenog tijela prije nego ga čitaš kao JSON. Trajno spremi event i data.chargeId da prepoznaš ponavljanja. Isporuke mogu stići dvostruko ili drugim redoslijedom: stari charge.posted ne prepisuje charge.cancelled. Za prijavu, odjavu i preuzimanje računa nema webhookova. Tamo ponovo pročitaj stanje.

Lista za prihvatanje s testnim hotelom i stvarnim prijavljenim testnim boravkom:

Provjeri /ping i dodjelu gosta i sobe, i kod rezervacija s više soba.

Provjeri porez, valutu i ograničenje outleta ključa.

Tačno ponavljanje bez duplog knjiženja, promijenjen sadržaj s 409, izgubljen odgovor s usklađivanjem.

Batch potpuno ili nikako, zaključavanje i limit, storno i ponovljeni storno.

Iznosi računa pri odjavi i odbijanje storna nakon preuzimanja.

Potpisan webhook, nevažeći potpis, dupla i zamijenjena isporuka.

Prikaz grešaka, promjena ključa i usklađivanje od strane osoblja.

## Tehnička referenca

Potpun opis postoji kao OpenAPI datoteka na engleskom jeziku, kao YAML na /developers/pos/openapi.yaml i kao JSON na /developers/pos/openapi.json na web stranici STRYK-a. U hotelu te Tehnička dokumentacija u području Za tehničara blagajne pod Postavke \> POS vodi na ovu stranicu.

GET, /ping, Provjeri vezu

GET, /accounts, Navedi prijavljene račune soba

GET, /room-lookup, Pronađi boravak za sobu

POST, /charges, Knjiži jednu stavku

POST, /charges/batch, Knjiži do 50 stavki zajedno

GET, /charges/{externalRef}, Čitaj stanje stavke

DELETE, /charges/{externalRef}, Storniraj otvorenu stavku
