İçeriğe atla
Reference, STRYK POS

Kasa üreticileri için POS Posting API

STRYK POS Posting API, kasandaki kalemleri check-in yapmış misafirlerin oda hesaplarına kaydeder. Bu referans kimlik doğrulamayı, kayıt, iptal ve webhook'ları gösterir.

Last updated: Developers
Contents
  1. Genel bakış
  2. Anahtar ve güvenlik
  3. Oda hesabı ve tutarlar
  4. Kaydetme ve yeniden deneme
  5. İptal ve fatura
  6. Webhook'lar ve kabul
  7. Teknik referans

Genel bakış

API, check-in yapmış konaklamalara kalem kaydetmek için sunucudan sunucuya bir arayüzdür. Otel kasanı Ayarlar altında POS üzerinden bağlar: Kasa bağlantısı. Orada kasa bir anahtar ve Kasa için adres alır.

BilgiDeğer
Temel adreshttps://app.staystryk.com/api/v1/pos/public
Kimlik doğrulamaOtelin Bearer anahtarı, Authorization başlığında
GereksinimOtelde STRYK POS ek modülü etkin
Ek modül yoksaHer çağrı 403 ve module_disabled koduyla yanıt verir. STRYK kalem yazmaz.
Çağrı sınırıAnahtar başına 60 saniyede 100 istek. Sonrasında STRYK 429 yanıtı verir.
Açıklama sürümü1.3.0

Anahtar ve güvenlik

  • Anahtar pos_live_ ile başlar. Otel onu yalnızca oluşturulurken bir kez görür.
  • Yalnızca sunucu tarafında HTTPS üzerinden başlıkta gönder: Authorization: Bearer <vollständiger Schlüssel>. Asla adreste parametre olarak kullanma.
  • Bir anahtar tam olarak bir otele ve isteğe bağlı olarak bir outlet'e aittir. Otel her bağlantı için bir anahtar oluşturur.
  • 401, STRYK'ın anahtarı doğrulayamadığı anlamına gelir. Yapılandırmayı ve işletim durumunu kontrol et. Anahtarı kendiliğinden değiştirme.
  • Yeni bir anahtar yeni bir idempotensi alanıdır. Eski anahtarın kayıtlarını bulmaz ve iptal etmez. Açık işlemleri tamamla ve otel eski anahtarı iptal etmeden önce bunları uzlaştır.
  • Anahtar kaybolduysa veya ele geçirildiyse otel bunu API anahtarını iptal et ile iptal eder ve kasan yenisini göndermeden önce STRYK'taki güvenli olmayan işlemleri netleştirir.

Oda hesabı ve tutarlar

Yöntem ve yolAmaç
GET /pingYalnızca anahtarın kabul edilip edilmediğini kontrol eder.
GET /accountsŞu anda check-in yapmış oda hesaplarını listeler, kilitli olanlar dahil.
GET /room-lookup?room=105Bir odayı check-in yapılmış konaklamaya çözer. Eşleşen misafir yoksa 404, oda belirsizse 409 döner.

Oda hesabı şu alanları içerir:

AlanAnlamı
bookingId, bookingNumber, guestName, roomNumberKonaklama ve oda
allowPostingOtel bu konaklama için kalem kaydına izin verdi. Tek başına yeterli değildir.
allowChargeİzin, kalan limit ve kapalı hesaptan oluşan genel kontrol. Kaydetmeden hemen önce kontrol et.
postingBlockReasonno_post, credit_limit_reached, account_closed veya boş
openChargesCount, openChargesTotal, stayChargesTotalAçık kalemler ve iptal edilmemiş kalemlerin toplamı
creditLimit, remainingCredit, currencyLimit, kalan limit ve otel para birimi

Onay için misafiri ve odayı göster, bookingId değerini room ile birlikte gönder. Hesap listesini kalıcı bir misafir rehberi olarak saklama. Tutarlar otel para biriminde JSON sayıları. Yuvarlama HALF_UP: miktar üç, tutarlar iki ondalık basamağa yuvarlanır.

Kaydetme ve yeniden deneme

Yöntem ve yolAmaç
POST /chargesBir kalemi oda hesabına kaydeder. Yanıt 201 ile kalemi döner.
POST /charges/batch1 ila 50 kalemi birlikte kaydeder. Tüm yeni kalemler kaydedilir ya da hiçbiri. Yanıt istek sırasını izler.
GET /charges/{externalRef}cancelled ve transferred dahil, bir kalemin kalıcı durumunu döner.

Bir kaydın alanları:

AlanZorunluAnlamı
bookingId, roomen az biriOda, sayı değil harflerden oluşan metin olarak. İkisi birlikte verilirse birbirini tutmalıdır.
descriptionevet1 ila 500 karakter
unitPriceevetBirim başına brüt fiyat, 0'dan büyük, en fazla 99999.99
externalRefevetBenzersiz fiş veya kalem anahtarı, 1 ila 255 karakter, örneğin receipt-123-item-1
quantityhayır0,001 ila 9999, varsayılan 1
unithayıren fazla 20 karakter, varsayılan Stk.
taxRatehayırOtelin etkin KDV oranı. Belirtilmezse önce outlet'in varsayılanı, sonra merkezi varsayılan geçerlidir.
currencyhayırOtel para birimi olmalıdır
outletIdhayırOutlet'li bir anahtarda bu outlet geçerlidir. Başka bir değer 403 verir.
chargedAthayırHizmet zamanı, varsayılan şimdi, en fazla 5 dakika ileride
notes, posRefhayırNot (1000 karakter), resepsiyon için fiş referansı (100 karakter)

Miktar ve birim fiyattan oluşan toplam tutar 0'dan büyük ve en fazla 99999999.99 olmalıdır.

externalRef, otel ve anahtar için değişmez idempotensi anahtarıdır. Birebir tekrar, idempotentReplay=true ile özgün kalemi döner. Değişen içerik veya iptal edilmiş bir anahtar 409 verir.

Zaman aşımı veya 5xx sonrasında önce GET /charges/{externalRef} çağır. Yalnızca 404 doğrulandığında aynı isteği aynı anahtarla değiştirmeden tekrar gönder. İstekleri göndermeden önce kaydet ve chargedAt, fiyat, vergi veya referansı asla değiştirme. Yanıt duplicateWarning içeriyorsa kalem zaten kaydedilmiştir. STRYK'ta uzlaştır ve yeniden gönderme.

DurumAnlamı
400Geçersiz bilgiler, düzelt.
401Anahtar doğrulanamadı
403Alan izinli değil, örneğin yanlış outlet
404Hesap veya kalem bulunamadı
409İş kuralı çakışması. Kodu kontrol et, körlemesine tekrarlama.
429Çağrı sınırı, en az 60 saniye bekle
5xxÖnce uzlaştır, sonra sınırlı bekleme ile tekrarla

Hata yanıtındaki kodlar arasında 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 ve pos_account_closed bulunur. Dalını Almanca metne göre belirleme. Destek için requestId yardımcı olur.

İptal ve fatura

DELETE /charges/{externalRef} anahtarının açık bir kalemini iptal eder. Gövdede isteğe bağlı reason (en fazla 500 karakter) bulunabilir. Tekrar gönderim iptal edilmiş kalemi yeniden döner.

  • Bir kalemin durumu open, cancelled veya transferred olabilir.
  • Bir kalem, check-out faturayı oluşturana kadar open kalır. Ardından STRYK açık kalemleri fatura kalemlerine aktarır ve durum transferred olur.
  • Aktarılmış bir kalem 409 ve pos_charge_already_invoiced döner. Otel bunu muhasebede düzeltir: Faturayı düzelt.
  • İptal hiçbir şeyi silmez ve iade yapmaz. İptal edilen kalem izlenebilir kalır.

API pozitif kalemleri kaydeder. Kasada tamamlanan ödemeleri odaya ayrıca gönderme. Bölünmüş ödemede yalnızca doğru vergi dağılımıyla açık oda payını gönder. İndirimleri kaydetmeden önce brüt fiyattan düş.

Webhook'lar ve kabul

Otel webhook'ları Ayarlar altında POS üzerinden oluşturur: Webhook'ları oluştur.

BilgiDeğer
Olaylarcharge.posted, charge.cancelled, testte ping
Başlık X-STRYK-EventOlay adı
Başlık X-STRYK-Webhook-IdWebhook'un kimliği, teslimatın değil
Başlık X-STRYK-Signaturesha256= ve değiştirilmemiş istek baytlarının HMAC-SHA-256 değeri. Yalnızca yapılandırılmış bir gizli anahtar varsa.
Gövdeevent, hotelId, timestamp, data içinde chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency ve outlet
YanıtKalıcı kabulden sonra 10 saniye içinde 2xx. STRYK yönlendirmeleri takip etmez.
Yeniden deneme30 saniye, 5 dakika, 30 dakika ve 2 saat sonra, kayıtlı sınıra kadar

İmzayı JSON olarak okumadan önce değiştirilmemiş gövde üzerinden doğrula. Yinelemeleri tanımak için event ve data.chargeId değerlerini kalıcı olarak sakla. Teslimatlar çift gelebilir veya farklı sırada ulaşabilir: eski bir charge.posted, charge.cancelled kaydının üzerine yazmaz. Check-in, check-out ve fatura aktarımı için webhook yoktur. Bu durumları orada yeniden oku.

Bir test otelinde ve gerçek bir check-in yapmış test konaklamasıyla kabul listesi:

  1. /ping ile misafir ve oda eşlemesini kontrol et, birden çok odalı rezervasyonlarda da.
  2. Anahtarın vergi, para birimi ve outlet kısıtlamasını kontrol et.
  3. Çift kayıt olmadan birebir tekrar, değişen içerikte 409, kaybolan yanıtta uzlaştırma.
  4. Batch ya tamamen ya hiç, kilit ve limit, iptal ve iptal tekrarı.
  5. Check-out'ta fatura toplamları ve aktarımdan sonra iptalin reddedilmesi.
  6. İmzalı webhook, geçersiz imza, çift ve ters sıralı teslimat.
  7. Hata göstergesi, anahtar değişimi ve personelin uzlaştırması.

Teknik referans

Tam açıklama İngilizce bir OpenAPI dosyası olarak mevcuttur: YAML olarak /developers/pos/openapi.yaml ve JSON olarak /developers/pos/openapi.json adresinde, STRYK web sitesinde. Otelde Ayarlar içinde POS altındaki Kasa teknisyeni için bölümünde yer alan Teknik dokümantasyon bu sayfaya götürür.

YöntemYolKısa açıklama
GET/pingBağlantıyı kontrol et
GET/accountsCheck-in yapmış oda hesaplarını listele
GET/room-lookupBir oda için konaklamayı bul
POST/chargesBir kalem kaydet
POST/charges/batchEn fazla 50 kalemi birlikte kaydet
GET/charges/{externalRef}Bir kalemin durumunu oku
DELETE/charges/{externalRef}Açık bir kalemi iptal et
İletişim