Preskoči na sadržaj
Reference, STRYK POS

POS Posting API za proizvođače blagajni

STRYK POS Posting API knjiži stavke s tvoje blagajne na račune sobe prijavljenih gostiju. Referenca prikazuje prijavu, knjiženje, storno i webhooke.

Last updated: Developers
Contents
  1. Pregled
  2. Ključ i sigurnost
  3. Račun sobe i iznosi
  4. Knjiženje i ponavljanje
  5. Storno i račun
  6. Webhooki i prihvatanje
  7. Tehnička referenca

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.

PodatakVrijednost
Osnovna adresahttps://app.staystryk.com/api/v1/pos/public
PrijavaBearer ključ hotela u zaglavlju Authorization
PreduslovHotel ima aktivan dodatni modul STRYK POS
Bez dodatnog modulaSvaki poziv odgovara sa 403 i kodom module_disabled. STRYK ne knjiži nijednu stavku.
Ograničenje poziva100 zahtjeva po 60 sekundi i ključu. Nakon toga STRYK odgovara sa 429.
Verzija opisa1.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

Metoda i putanjaSvrha
GET /pingProvjerava samo, je li ključ prihvaćen.
GET /accountsNavodi trenutno prijavljene račune soba, uključujući blokirane.
GET /room-lookup?room=105Povezuje sobu s prijavljenim boravkom. 404 bez odgovarajućeg gosta, 409 kod dvosmislene sobe.

Račun sobe sadrži ova polja:

PoljeZnačenje
bookingId, bookingNumber, guestName, roomNumberBoravak i soba
allowPostingHotel je dozvolio stavke za boravak. Samo to nije dovoljno.
allowChargeUkupna provjera iz dozvole, preostalog limita i zatvorenog računa. Provjeri je neposredno prije knjiženja.
postingBlockReasonno_post, credit_limit_reached, account_closed ili prazno
openChargesCount, openChargesTotal, stayChargesTotalOtvorene stavke i zbir nestornираnih stavki
creditLimit, remainingCredit, currencyLimit, 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

Metoda i putanjaSvrha
POST /chargesKnjiži stavku na račun sobe. Odgovor 201 sa stavkom.
POST /charges/batchKnjiž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:

PoljeObaveznoZnačenje
bookingId, roombarem jednoSoba kao tekst sa slovima, ne kao broj. Ako su navedena oba, moraju se slagati.
descriptionda1 do 500 znakova
unitPricedaBruto cijena po jedinici, veća od 0, najviše 99999.99
externalRefdaJedinstveni ključ računa ili stavke, 1 do 255 znakova, na primjer receipt-123-item-1
quantityne0,001 do 9999, standard 1
unitnenajviše 20 znakova, standard Stk.
taxRateneAktivna poreska stopa hotela. Bez navođenja vrijedi standard outleta, zatim centralni.
currencyneMora biti valuta hotela
outletIdneKod ključa s outletom vrijedi taj outlet. Druga vrijednost daje 403.
chargedAtneVrijeme usluge, standard sada, najviše 5 minuta u budućnosti
notes, posRefneNapomena (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.

StatusZnačenje
400Neispravni podaci, ispravi ih.
401Ključ se ne može provjeriti
403Opseg nije dozvoljen, na primjer pogrešan outlet
404Račun ili stavka ne postoji
409Poslovni konflikt. Provjeri kod, ne ponavljaj slijepo.
429Ograničenje poziva, sačekaj najmanje 60 sekundi
5xxPrvo 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: Ispravi račun.
  • 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.

PodatakVrijednost
Događajicharge.posted, charge.cancelled, pri testiranju ping
Zaglavlje X-STRYK-EventNaziv događaja
Zaglavlje X-STRYK-Webhook-IdID webhooka, ne isporuke
Zaglavlje X-STRYK-Signaturesha256= i HMAC-SHA-256 nepromijenjenih bajtova zahtjeva. Samo uz konfigurirani secret.
Tijeloevent, hotelId, timestamp, data s chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency i outlet
Odgovor2xx nakon trajnog prihvatanja unutar 10 sekundi. STRYK ne prati preusmjeravanja.
PonavljanjeNakon 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:

  1. Provjeri /ping i dodjelu gosta i sobe, i kod rezervacija s više soba.
  2. Provjeri porez, valutu i ograničenje outleta ključa.
  3. Tačno ponavljanje bez duplog knjiženja, promijenjen sadržaj s 409, izgubljen odgovor s usklađivanjem.
  4. Batch potpuno ili nikako, zaključavanje i limit, storno i ponovljeni storno.
  5. Iznosi računa pri odjavi i odbijanje storna nakon preuzimanja.
  6. Potpisan webhook, nevažeći potpis, dupla i zamijenjena isporuka.
  7. 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.

MetodaPutanjaKratki opis
GET/pingProvjeri vezu
GET/accountsNavedi prijavljene račune soba
GET/room-lookupPronađi boravak za sobu
POST/chargesKnjiži jednu stavku
POST/charges/batchKnjiži do 50 stavki zajedno
GET/charges/{externalRef}Čitaj stanje stavke
DELETE/charges/{externalRef}Storniraj otvorenu stavku
Kontakt