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.
Contents
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.
| Podatak | Vrednost |
|---|---|
| Osnovna adresa | https://app.staystryk.com/api/v1/pos/public |
| Prijava | Hotelov Bearer ključ 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 upisuje stavku. |
| Ograničenje poziva | 100 zahteva po 60 sekundi po ključu. Posle toga STRYK odgovara sa 429. |
| Verzija opisa | 1.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 putanja | Svrha |
|---|---|
GET /ping | Proverava samo da li je ključ prihvaćen. |
GET /accounts | Prikazuje trenutno prijavljene sobne konte, uključujući blokirane. |
GET /room-lookup?room=105 | Pronalazi prijavljeni boravak za sobu. 404 bez odgovarajućeg gosta, 409 kod nejasne sobe. |
Sobni konto sadrži ova polja:
| Polje | Značenje |
|---|---|
bookingId, bookingNumber, guestName, roomNumber | Boravak i soba |
allowPosting | Hotel je dozvolio stavke za boravak. Samo to nije dovoljno. |
allowCharge | Ukupna provera iz dozvole, preostalog limita i zatvorenog konta. Proveri je neposredno pre knjiženja. |
postingBlockReason | no_post, credit_limit_reached, account_closed ili prazno |
openChargesCount, openChargesTotal, stayChargesTotal | Otvorene stavke i zbir stavki koje nisu stornirane |
creditLimit, remainingCredit, currency | Limit, 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 putanja | Svrha |
|---|---|
POST /charges | Knjiži stavku na sobni konto. Odgovor 201 sa stavkom. |
POST /charges/batch | Knjiž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:
| Polje | Obavezno | Značenje |
|---|---|---|
bookingId, room | najmanje jedno | Soba kao tekst sa slovima, ne kao broj. Ako su navedena oba, moraju se poklapati. |
description | da | 1 do 500 znakova |
unitPrice | da | Bruto cena po jedinici, veća od 0, najviše 99999.99 |
externalRef | da | Jedinstven ključ dokumenta ili stavke, 1 do 255 znakova, na primer receipt-123-item-1 |
quantity | ne | 0,001 do 9999, podrazumevano 1 |
unit | ne | najviše 20 znakova, podrazumevano Stk. |
taxRate | ne | Aktivna poreska stopa hotela. Bez navođenja važi podrazumevana stopa outleta, pa centralna. |
currency | ne | Mora biti valuta hotela |
outletId | ne | Kod ključa sa outletom važi taj outlet. Druga vrednost daje 403. |
chargedAt | ne | Vreme pružene usluge, podrazumevano sada, najviše 5 minuta u budućnosti |
notes, posRef | ne | Napomena (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.
| Status | Značenje |
|---|---|
| 400 | Nevažeći podaci, ispravi ih. |
| 401 | Ključ se ne može proveriti |
| 403 | Opseg nije dozvoljen, na primer pogrešan outlet |
| 404 | Konto ili stavka ne postoji |
| 409 | Poslovni konflikt. Proveri kod, ne ponavljaj slepo. |
| 429 | Ograničenje poziva, sačekaj najmanje 60 sekundi |
| 5xx | Prvo 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,cancelledilitransferred. - Stavka ostaje
opendok check-out ne napravi račun. Tada STRYK preuzima otvorene stavke u stavke računa i status prelazi natransferred. - 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.
| Podatak | Vrednost |
|---|---|
| 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 nepromenjenih bajtova zahteva. Samo uz podešen tajni ključ. |
| Telo | event, hotelId, timestamp, data sa chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency i outletom |
| Odgovor | 2xx posle trajnog prihvatanja u roku od 10 sekundi. STRYK ne prati preusmeravanja. |
| Ponavljanje | Posle 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:
/pingi dodelu gosta i sobe proveri, i kod rezervacija sa više soba.- Proveri porez, valutu i ograničenje ključa na outlet.
- Tačno ponavljanje bez duplih stavki, izmenjen sadržaj sa 409, izgubljen odgovor sa usklađivanjem.
- Batch sve ili ništa, zaključavanje i limit, storno i ponovljeni storno.
- Zbirovi računa pri check-outu i odbijanje storna posle preuzimanja.
- Potpisan webhook, nevažeći potpis, duplirana i zamenjena isporuka.
- 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.
| Metoda | Putanja | Kratak opis |
|---|---|---|
| GET | /ping | Proveri vezu |
| GET | /accounts | Navedi prijavljene sobne konte |
| 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 jednu otvorenu stavku |