# Kasa üreticileri için POS Posting API

Canonical: https://staystryk.com/tr/documentation/pos-integration/
Language: tr
Updated: 2026-11-12

Kasa üreticileri için STRYK POS Posting API referansı: kimlik doğrulama, oda hesabı, kayıt, iptal, webhook'lar ve kabul listesi.

## 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.

Temel adres, https://app.staystryk.com/api/v1/pos/public

Kimlik doğrulama, Otelin Bearer anahtarı, Authorization başlığında

Gereksinim, Otelde STRYK POS ek modülü etkin

Ek modül yoksa, Her ç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

GET /ping, Yalnı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=105, Bir odayı check-in yapılmış konaklamaya çözer. Eşleşen misafir yoksa 404, oda belirsizse 409 döner.

Oda hesabı şu alanları içerir:

bookingId, bookingNumber, guestName, roomNumber, Konaklama ve oda

allowPosting, Otel 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.

postingBlockReason, no\_post, credit\_limit\_reached, account\_closed veya boş

openChargesCount, openChargesTotal, stayChargesTotal, Açık kalemler ve iptal edilmemiş kalemlerin toplamı

creditLimit, remainingCredit, currency, Limit, 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

POST /charges, Bir kalemi oda hesabına kaydeder. Yanıt 201 ile kalemi döner.

POST /charges/batch, 1 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ı:

bookingId, room, en az biri, Oda, sayı değil harflerden oluşan metin olarak. İkisi birlikte verilirse birbirini tutmalıdır.

description, evet, 1 ila 500 karakter

unitPrice, evet, Birim başına brüt fiyat, 0'dan büyük, en fazla 99999.99

externalRef, evet, Benzersiz fiş veya kalem anahtarı, 1 ila 255 karakter, örneğin receipt-123-item-1

quantity, hayır, 0,001 ila 9999, varsayılan 1

unit, hayır, en fazla 20 karakter, varsayılan Stk.

taxRate, hayır, Otelin etkin KDV oranı. Belirtilmezse önce outlet'in varsayılanı, sonra merkezi varsayılan geçerlidir.

currency, hayır, Otel para birimi olmalıdır

outletId, hayır, Outlet'li bir anahtarda bu outlet geçerlidir. Başka bir değer 403 verir.

chargedAt, hayır, Hizmet zamanı, varsayılan şimdi, en fazla 5 dakika ileride

notes, posRef, hayır, Not (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.

400, Geçersiz bilgiler, düzelt.

401, Anahtar doğrulanamadı

403, Alan izinli değil, örneğin yanlış outlet

404, Hesap 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: .

İ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.

Olaylar, charge.posted, charge.cancelled, testte ping

Başlık X-STRYK-Event, Olay adı

Başlık X-STRYK-Webhook-Id, Webhook'un kimliği, teslimatın değil

Başlık X-STRYK-Signature, sha256= ve değiştirilmemiş istek baytlarının HMAC-SHA-256 değeri. Yalnızca yapılandırılmış bir gizli anahtar varsa.

Gövde, event, hotelId, timestamp, data içinde chargeId, externalRef, bookingId, roomNumber, guestName, description, grossAmount, currency ve outlet

Yanıt, Kalıcı kabulden sonra 10 saniye içinde 2xx. STRYK yönlendirmeleri takip etmez.

Yeniden deneme, 30 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:

/ping ile misafir ve oda eşlemesini kontrol et, birden çok odalı rezervasyonlarda da.

Anahtarın vergi, para birimi ve outlet kısıtlamasını kontrol et.

Çift kayıt olmadan birebir tekrar, değişen içerikte 409, kaybolan yanıtta uzlaştırma.

Batch ya tamamen ya hiç, kilit ve limit, iptal ve iptal tekrarı.

Check-out'ta fatura toplamları ve aktarımdan sonra iptalin reddedilmesi.

İmzalı webhook, geçersiz imza, çift ve ters sıralı teslimat.

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.

GET, /ping, Bağlantıyı kontrol et

GET, /accounts, Check-in yapmış oda hesaplarını listele

GET, /room-lookup, Bir oda için konaklamayı bul

POST, /charges, Bir kalem kaydet

POST, /charges/batch, En fazla 50 kalemi birlikte kaydet

GET, /charges/{externalRef}, Bir kalemin durumunu oku

DELETE, /charges/{externalRef}, Açık bir kalemi iptal et
