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.
Contents
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.
| Podatak | Vrijednost |
|---|---|
| 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
| Metoda i putanja | Svrha |
|---|---|
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:
| Polje | Značenje |
|---|---|
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
| Metoda i putanja | Svrha |
|---|---|
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:
| Polje | Obavezno | Značenje |
|---|---|---|
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.
| Status | Značenje |
|---|---|
| 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,cancelledilitransferred. - Stavka ostaje
opendok odjava ne kreira račun. Tada STRYK preuzima otvorene stavke u stavke računa i status prelazi utransferred. - 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.
| Podatak | Vrijednost |
|---|---|
| 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
/pingi 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.
| Metoda | Putanja | Kratki opis |
|---|---|---|
| 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 |