Pređi na sadržaj
Reference, STRYK POS

STRYK POS Posting API za proizvođače kasa

STRYK POS Posting API knjiži stavke sa tvoje kase na sobne konte prijavljenih gostiju. Referenca prikazuje prijavu, knjiženje, storno i webhookove.

Last updated: Developers
Contents
  1. Pregled
  2. Ključ i bezbednost
  3. Sobni konto i iznosi
  4. Knjiženje i ponavljanje
  5. Storno i račun
  6. Webhookovi i prijem
  7. Tehnička referenca

Pregled

API je veza server-server za stavke na prijavljene boravke. Hotel povezuje tvoju kasu u Podešavanja pod POS: Poveži kasu. Tamo kasa dobija ključ i Adresu za kasu.

PodatakVrednost
Osnovna adresahttps://app.staystryk.com/api/v1/pos/public
PrijavaHotelov Bearer ključ u zaglavlju Authorization
PreduslovHotel ima aktivan dodatni modul STRYK POS
Bez dodatnog modulaSvaki poziv odgovara sa 403 i kodom module_disabled. STRYK ne upisuje stavku.
Ograničenje poziva100 zahteva po 60 sekundi po ključu. Posle toga STRYK odgovara sa 429.
Verzija opisa1.3.0

Ključ i bezbednost

  • Ključ počinje sa pos_live_. Hotel ga vidi samo jednom, pri kreiranju.
  • Šalji ga samo sa servera preko HTTPS-a u zaglavlju: Authorization: Bearer <vollständiger Schlüssel>. Nikad kao parametar u adresi.
  • Ključ pripada tačno jednom hotelu i opciono jednom outletu. Hotel kreira jedan ključ za svaku vezu.
  • 401 znači: STRYK nije mogao da proveri ključ. Proveri podešavanja i stanje rada. Ne menjaj ključ automatski.
  • Novi ključ je novi opseg idempotentnosti. On ne nalazi i ne stornira stavke starog ključa. Obradi otvorene zadatke i uskladi ih pre nego što hotel opozove stari ključ.
  • Ako je ključ izgubljen ili kompromitovan, hotel ga opoziva sa Opozovi ključ i razjasni nesigurne radnje u STRYK-u pre nego što tvoja kasa pošalje zamenu.

Sobni konto i iznosi

Metoda i putanjaSvrha
GET /pingProverava samo da li je ključ prihvaćen.
GET /accountsPrikazuje trenutno prijavljene sobne konte, uključujući blokirane.
GET /room-lookup?room=105Pronalazi prijavljeni boravak za sobu. 404 bez odgovarajućeg gosta, 409 kod nejasne sobe.

Sobni konto sadrži ova polja:

PoljeZnačenje
bookingId, bookingNumber, guestName, roomNumberBoravak i soba
allowPostingHotel je dozvolio stavke za boravak. Samo to nije dovoljno.
allowChargeUkupna provera iz dozvole, preostalog limita i zatvorenog konta. Proveri je neposredno pre knjiženja.
postingBlockReasonno_post, credit_limit_reached, account_closed ili prazno
openChargesCount, openChargesTotal, stayChargesTotalOtvorene stavke i zbir stavki koje nisu stornirane
creditLimit, remainingCredit, currencyLimit, preostali limit i valuta hotela

Prikaži gosta i sobu na potvrdu i šalji bookingId zajedno sa room. Listu konta ne čuvaj trajno kao adresar gostiju. Iznosi su JSON brojevi u valuti hotela. Zaokruživanje je HALF_UP: količina na tri, iznosi na dve decimale.

Knjiženje i ponavljanje

Metoda i putanjaSvrha
POST /chargesKnjiži stavku na sobni konto. Odgovor 201 sa stavkom.
POST /charges/batchKnjiži 1 do 50 stavki zajedno. Sve nove stavke se knjiže ili nijedna. Odgovor prati redosled zahteva.
GET /charges/{externalRef}Vraća trajno stanje stavke, uključujući cancelled i transferred.

Polja jedne knjižene stavke:

PoljeObaveznoZnačenje
bookingId, roomnajmanje jednoSoba kao tekst sa slovima, ne kao broj. Ako su navedena oba, moraju se poklapati.
descriptionda1 do 500 znakova
unitPricedaBruto cena po jedinici, veća od 0, najviše 99999.99
externalRefdaJedinstven ključ dokumenta ili stavke, 1 do 255 znakova, na primer receipt-123-item-1
quantityne0,001 do 9999, podrazumevano 1
unitnenajviše 20 znakova, podrazumevano Stk.
taxRateneAktivna poreska stopa hotela. Bez navođenja važi podrazumevana stopa outleta, pa centralna.
currencyneMora biti valuta hotela
outletIdneKod ključa sa outletom važi taj outlet. Druga vrednost daje 403.
chargedAtneVreme pružene usluge, podrazumevano sada, najviše 5 minuta u budućnosti
notes, posRefneNapomena (1000 znakova), referenca računa za recepciju (100 znakova)

Ukupan iznos iz količine i jedinične cene mora biti veći od 0 i najviše 99999999.99.

externalRef je nepromenljivi ključ idempotentnosti hotela i ključa. Tačno ponavljanje vraća originalnu stavku sa idempotentReplay=true. Izmenjen sadržaj ili storniran ključ daje 409.

Posle isteka vremena ili 5xx prvo čitaš GET /charges/{externalRef}. Samo kod potvrđenog 404 šalješ isti zahtev ponovo, nepromenjen, sa istim ključem. Sačuvaj zahteve pre slanja i nikada ne menjaj chargedAt, cenu, porez ili referencu. Ako odgovor sadrži duplicateWarning, stavka je već knjižena. Uskladi je u STRYK-u i ne šalji ponovo.

StatusZnačenje
400Nevažeći podaci, ispravi ih.
401Ključ se ne može proveriti
403Opseg nije dozvoljen, na primer pogrešan outlet
404Konto ili stavka ne postoji
409Poslovni konflikt. Proveri kod, ne ponavljaj slepo.
429Ograničenje poziva, sačekaj najmanje 60 sekundi
5xxPrvo uskladi, zatim ponovi uz ograničeno čekanje

Kodovi greške su između ostalog 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 logiku prema nemačkom tekstu. requestId pomaže podršci.

Storno i račun

DELETE /charges/{externalRef} stornira otvorenu stavku tvog ključa. U telu zahteva opciono stoji reason (najviše 500 znakova). Ponavljanje vraća ponovo storniranu stavku.

  • Status stavke je open, cancelled ili transferred.
  • Stavka ostaje open dok check-out ne napravi račun. Tada STRYK preuzima otvorene stavke u stavke računa i status prelazi na transferred.
  • Preuzeta stavka daje 409 sa pos_charge_already_invoiced. Hotel je ispravlja u knjigovodstvu: Ispravi fakturu.
  • Storno ništa ne briše i ništa ne vraća. Storirana stavka ostaje vidljiva u tragu.

API knjiži pozitivne stavke. Plaćanja zaključena na kasi ne šalji dodatno na sobu. Kod podeljenog plaćanja šalji samo otvoreni udeo sobe sa pravilno raspoređenim porezom. Popuste oduzmi od bruto cene pre knjiženja.

Webhookovi i prijem

Hotel kreira webhookove u Podešavanja pod POS: Kreiraj webhookove.

PodatakVrednost
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 nepromenjenih bajtova zahteva. Samo uz podešen tajni ključ.
Teloevent, hotelId, timestamp, data sa chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency i outletom
Odgovor2xx posle trajnog prihvatanja u roku od 10 sekundi. STRYK ne prati preusmeravanja.
PonavljanjePosle 30 sekundi, 5 minuta, 30 minuta i 2 sata, do sačuvane granice

Proveri potpis nad nepromenjenim telom pre nego što ga pročitaš kao JSON. Trajno sačuvaj event i data.chargeId da bi prepoznao ponavljanja. Isporuke mogu stići duplo ili drugim redosledom: stariji charge.posted ne prepisuje charge.cancelled. Za check-in, check-out i preuzimanje računa webhookovi ne postoje. Tamo ponovo čitaj stanje.

Lista za prijem sa test hotelom i pravim test boravkom sa prijavom:

  1. /ping i dodelu gosta i sobe proveri, i kod rezervacija sa više soba.
  2. Proveri porez, valutu i ograničenje ključa na outlet.
  3. Tačno ponavljanje bez duplih stavki, izmenjen sadržaj sa 409, izgubljen odgovor sa usklađivanjem.
  4. Batch sve ili ništa, zaključavanje i limit, storno i ponovljeni storno.
  5. Zbirovi računa pri check-outu i odbijanje storna posle preuzimanja.
  6. Potpisan webhook, nevažeći potpis, duplirana i zamenjena isporuka.
  7. Prikaz grešaka, promena ključa i usklađivanje od strane osoblja.

Tehnička referenca

Potpun opis postoji kao OpenAPI datoteka na engleskom, kao YAML na /developers/pos/openapi.yaml i kao JSON na /developers/pos/openapi.json na veb sajtu STRYK-a. U hotelu Tehnička dokumentacija u delu Za tehničara kase u Podešavanja pod POS vodi na ovu stranicu.

MetodaPutanjaKratak opis
GET/pingProveri vezu
GET/accountsNavedi prijavljene sobne konte
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 jednu otvorenu stavku
Kontakt