Gün Sonu Politikası
- Taban yol
/api/v1/physical-pos- Kimlik
- Her istekte Ed25519 istek imzası —
X-Key-Id,X-Date,X-Nonce,X-Signature; gövdeli isteklerde ayrıcaDigest. Zaman penceresi ±5 dk, nonce tek kullanımlık. Bearer jetonu ya da panel oturumu bu uçlarda kabul edilmez. - Yetki
- Anahtarınız Fiziksel POS ürününü (
PHYSICAL_POS) ve bu sayfadaki uçların kapsamını taşımalıdır:physical_pos:view·physical_pos:manage. Ürünü olmayan anahtar403 PRODUCT_NOT_ENABLED, kapsamı olmayan anahtar403 API_INSUFFICIENT_SCOPEalır. Bkz. Kimlik Doğrulama ve Kapsamlar. - Çapraz yüzey
- Bu uçlar s2s yüzeyindedir; kendi sunucunuzdan imzalı istekle çağırırsınız. Aynı kayıtların panelde ekranları var, ama panel uçları API anahtarıyla çağrılamaz; bu uçlar da panel oturumuyla çağrılamaz.
Gün sonu politikası cihazların gün sonunu nasıl alacağını belirler: elle, Lunixi'nin belirlediğiniz saatte başlatmasıyla ya da cihazın kendi otomatik gün sonuyla. Politikayı üç düzeyde tanımlarsınız; alt düzey üst düzeyi tamamen geçersiz kılar, alanlar birleştirilmez.
| Düzey | Yol | Okuma | Yazma |
|---|---|---|---|
| Hesap | /api/v1/physical-pos/settlement-policy | physical_pos:view | physical_pos:manage |
| Mağaza | /api/v1/physical-pos/stores/{storeId}/settlement-policy | physical_pos:view | physical_pos:manage |
| Cihaz | /api/v1/physical-pos/devices/{deviceId}/settlement-policy | physical_pos:view | physical_pos:manage |
| Cihazın etkin politikası | GET /api/v1/physical-pos/devices/{deviceId}/settlement-policy/effective | physical_pos:view | — |
Her düzeyde GET okur, PUT yazar, DELETE düzeyi temizler (üst düzeye bırakır). Hiç politika yazılmamışsa geçerli olan MANUAL'dır. Panelde aynı ayar Otomatik Gün Sonu ekranındadır.
- Test anahtarı politikaları okur; yazma
403 physical_pos.environment.test_key_read_onlyalır. PUTveDELETE, gün sonu başlatma ile aynı oran sınırını paylaşır: 60 saniyede API anahtarı başına 30 istek.
Modlar
mode | Ne olur |
|---|---|
MANUAL | Gün sonunu siz başlatırsınız: cihazda, panelde ya da API'den. Varsayılan. |
SCHEDULED | Lunixi gün sonunu scheduleTime saatinde başlatır. Cihaz meşgul ya da bağlı değilse deneme penceresi içinde yeniden dener. |
DEVICE_AUTO | Cihaz gün sonunu kendisi alır; Lunixi yalnız sonucu kaydeder ve gecikmeyi izler. |
Sunucudan gün sonunu desteklemeyen cihaza cihaz düzeyinde SCHEDULED yazılamaz (422 physical_pos.settlement.scheduled_unsupported); DEVICE_AUTO için de aynı denetim yapılır (422 physical_pos.settlement.device_auto_unsupported). Hesap ya da mağaza düzeyindeki SCHEDULED böyle bir cihaza uygulanırsa o günün gün sonu atlanır ve physical_pos.settlement.skipped gönderilir; etkin politika bu durumu scheduleWarning ile önceden gösterir.
Politika nesnesi
Okuma ve yazma yanıtı { "policy": { … } } döner.
| Alan | Tip | Açıklama |
|---|---|---|
scopeType | string | ACCOUNT, STORE ya da DEVICE. |
storeId, deviceId | string | null | Mağaza ya da cihaz düzeyinde hedef. |
active | boolean | Bu düzeyde politika yazılı mı. false ise düzey üstten devralır. |
mode | string | MANUAL, SCHEDULED ya da DEVICE_AUTO. |
scheduleTime | string | null | SCHEDULED'da başlatma saati, HH:mm (24 saat). |
timeZone | string | Saat dilimi (IANA adı). Varsayılan Europe/Istanbul. |
scheduleDays | string[] | SCHEDULED'da günler: MON…SUN. Her gün için yedi gün de listelenir. |
retryWindowMinutes | integer | null | SCHEDULED'da deneme penceresi, dakika. |
retryIntervalMinutes | integer | null | SCHEDULED'da denemeler arası süre, dakika. |
offlineBehavior | string | null | SCHEDULED'da cihaz bağlı değilse: RETRY_IN_WINDOW (pencere içinde yeniden dene) ya da ALERT_IMMEDIATELY (hemen başarısız say ve bildir). |
overdueAlertHours | integer | null | Son gün sonundan bu kadar saat geçince gecikme bildirimi gönderilir; null ise kapalı. |
rowVersion | integer | Kaydın sürümü; yazarken expectedRowVersion olarak gönderin. Yazılmamış düzeyde 0. |
updatedAt | string | null | Son değişiklik zamanı. |
Politika yazma
PUT …/settlement-policy · physical_pos:manage
PUT düzeyin politikasını bütünüyle değiştirir; göndermediğiniz alan varsayılan değerine döner.
| Alan | Tip | Zorunlu | Açıklama |
|---|---|---|---|
mode | string | Evet | MANUAL, SCHEDULED ya da DEVICE_AUTO. |
scheduleTime | string | SCHEDULED'da | HH:mm. Diğer modlarda gönderilmez. |
timeZone | string | Hayır | IANA saat dilimi. Varsayılan Europe/Istanbul. |
scheduleDays | string[] | Hayır | MON, TUE, WED, THU, FRI, SAT, SUN; tekrarsız. Boş ya da gönderilmezse her gün. Yalnız SCHEDULED'da. |
retryWindowMinutes | integer | Hayır | 5–720, varsayılan 120. Yalnız SCHEDULED'da. |
retryIntervalMinutes | integer | Hayır | 1–120, varsayılan 15; retryWindowMinutes'tan küçük olmalı. Yalnız SCHEDULED'da. |
offlineBehavior | string | Hayır | RETRY_IN_WINDOW (varsayılan) ya da ALERT_IMMEDIATELY. Yalnız SCHEDULED'da. |
overdueAlertHours | integer | Hayır | 1–168. Her modda kullanılabilir; gönderilmezse gecikme bildirimi kapalı. |
expectedRowVersion | integer | Hayır | Okuduğunuz rowVersion. Gönderirseniz kayıt bu arada değiştiyse 409 physical_pos.settlement.policy_version_conflict alırsınız; gönderilmezse son yazan kazanır. |
Sayılar JSON tam sayısı olmalıdır ("120" reddedilir).
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/stores/00000000-0000-0000-0000-000000000101/settlement-policy"
BODY='{"mode":"SCHEDULED","scheduleTime":"23:30","scheduleDays":["MON","TUE","WED","THU","FRI","SAT"],"retryWindowMinutes":120,"retryIntervalMinutes":15,"offlineBehavior":"RETRY_IN_WINDOW","overdueAlertHours":26,"expectedRowVersion":2}'
lunixi_sign PUT "$REQ_PATH" "$BODY"
curl -X PUT "https://api-gateway.lunixi.com$REQ_PATH" \
-H "Content-Type: application/json" \
-H "X-Key-Id: $LUNIXI_KEY_ID" \
-H "X-Date: $DATE" \
-H "X-Nonce: $NONCE" \
-H "Digest: $DIGEST" \
-H "X-Signature: $SIGNATURE" \
--data-raw "$BODY"{
"policy": {
"scopeType": "STORE",
"storeId": "00000000-0000-0000-0000-000000000101",
"deviceId": null,
"active": true,
"mode": "SCHEDULED",
"scheduleTime": "23:30",
"timeZone": "Europe/Istanbul",
"scheduleDays": ["MON", "TUE", "WED", "THU", "FRI", "SAT"],
"retryWindowMinutes": 120,
"retryIntervalMinutes": 15,
"offlineBehavior": "RETRY_IN_WINDOW",
"overdueAlertHours": 26,
"rowVersion": 3,
"updatedAt": "2026-01-02T09:00:00.000Z"
}
}Politikayı temizleme
DELETE …/settlement-policy?expectedRowVersion=3 · physical_pos:manage
Düzeyin politikasını kaldırır; düzey üstten devralır (active: false). Hesap düzeyi temizlenirse varsayılan MANUAL geçerli olur. timeZone korunur. expectedRowVersion isteğe bağlıdır. Yanıt düzeyin güncel hâlidir: { "policy": { … } }.
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/devices/00000000-0000-0000-0000-000000000401/settlement-policy?expectedRowVersion=1"
lunixi_sign DELETE "$REQ_PATH"
curl -X DELETE "https://api-gateway.lunixi.com$REQ_PATH" \
-H "X-Key-Id: $LUNIXI_KEY_ID" \
-H "X-Date: $DATE" \
-H "X-Nonce: $NONCE" \
-H "X-Signature: $SIGNATURE"Cihazın etkin politikası
GET /api/v1/physical-pos/devices/{deviceId}/settlement-policy/effective · physical_pos:view
Cihaza hangi düzeyin politikasının uygulandığını, sonraki zamanlanmış gün sonunu ve gecikme durumunu gösterir.
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/devices/00000000-0000-0000-0000-000000000401/settlement-policy/effective"
lunixi_sign GET "$REQ_PATH"
curl "https://api-gateway.lunixi.com$REQ_PATH" \
-H "X-Key-Id: $LUNIXI_KEY_ID" \
-H "X-Date: $DATE" \
-H "X-Nonce: $NONCE" \
-H "X-Signature: $SIGNATURE"{
"effective": {
"deviceId": "00000000-0000-0000-0000-000000000401",
"sourceScopeType": "STORE",
"policy": { "scopeType": "STORE", "storeId": "00000000-0000-0000-0000-000000000101", "deviceId": null, "active": true, "mode": "SCHEDULED", "scheduleTime": "23:30", "timeZone": "Europe/Istanbul", "scheduleDays": ["MON", "TUE", "WED", "THU", "FRI", "SAT"], "retryWindowMinutes": 120, "retryIntervalMinutes": 15, "offlineBehavior": "RETRY_IN_WINDOW", "overdueAlertHours": 26, "rowVersion": 3, "updatedAt": "2026-01-02T09:00:00.000Z" },
"serverSettlementSupported": true,
"deviceAutoSupported": true,
"nextScheduledAt": "2026-01-02T20:30:00.000Z",
"lastSettlementAt": "2026-01-01T20:31:12.000Z",
"overdue": false,
"scheduleWarning": null
}
}| Alan | Tip | Açıklama |
|---|---|---|
sourceScopeType | string | Politikanın geldiği düzey: DEVICE, STORE, ACCOUNT ya da DEFAULT (hiç politika yok, MANUAL). |
policy | object | Uygulanan politika. |
serverSettlementSupported | boolean | Cihaz sunucudan başlatılan gün sonunu destekliyor mu. |
deviceAutoSupported | boolean | Cihazın kendi otomatik gün sonu sonucu kaydedilebiliyor mu. |
nextScheduledAt | string | null | Sonraki zamanlanmış gün sonu (UTC). SCHEDULED değilse, 8 gün içinde zaman yoksa ya da scheduleWarning doluysa null. |
lastSettlementAt | string | null | Cihazın son gün sonu. |
overdue | boolean | overdueAlertHours tanımlıysa ve son gün sonu bu süreden eskiyse (ya da hiç yoksa) true. |
scheduleWarning | string | null | SCHEDULED_UNSUPPORTED: politika SCHEDULED ama cihaz sunucudan gün sonunu desteklemiyor; zamanlanmış gün sonu atlanacak. |
Gecikme ve başarısızlık bildirimleri
| Webhook | Ne zaman |
|---|---|
physical_pos.settlement.completed | Cihaz gün sonu sonucunu bildirdi (elle, zamanlanmış ya da cihazın kendi gün sonu). |
physical_pos.settlement.failed | Zamanlanmış gün sonu deneme penceresinde alınamadı. |
physical_pos.settlement.skipped | Zamanlanmış gün sonu atlandı: cihaz desteklemiyor ya da aktif değil. |
physical_pos.settlement.overdue | Son gün sonundan overdueAlertHours saat geçti. |
Yükler: Webhook Olayları › Gün sonu olayları.
Hatalar
| HTTP | code | Ne zaman |
|---|---|---|
400 | physical_pos.settlement.policy_invalid | Politika kuralına uymayan alan (details.field, details.reason: required, invalid, not_allowed, out_of_range, duplicate, not_less_than_window). |
400 | VALIDATION_ERROR | Tanımsız alan ya da sayı JSON tam sayısı değil. |
403 | physical_pos.environment.test_key_read_only | Yazma test anahtarıyla yapıldı. |
404 | physical_pos.store.not_found · physical_pos.device.not_found | Mağaza ya da cihaz yok, size ait değil ya da diğer ortamda. |
409 | physical_pos.settlement.policy_version_conflict | expectedRowVersion güncel değil; politikayı yeniden okuyun. |
422 | physical_pos.settlement.scheduled_unsupported | Cihaz düzeyinde SCHEDULED; cihaz sunucudan gün sonunu desteklemiyor. |
422 | physical_pos.settlement.device_auto_unsupported | Cihaz düzeyinde DEVICE_AUTO; cihaz kendi gün sonu sonucunu bildiremiyor. |
429 | RATE_LIMITED | Gün sonu yazma sınırı aşıldı. |
Bütün kodlar: Hata Kodları.