Fiziksel POS
API Referansı
Gün Sonu Politikası

Gün Sonu Politikası

Bu uçları kim çağırır?Dış API (s2s)
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ıca Digest. 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 anahtar 403 PRODUCT_NOT_ENABLED, kapsamı olmayan anahtar 403 API_INSUFFICIENT_SCOPE alı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üzeyYolOkumaYazma
Hesap/api/v1/physical-pos/settlement-policyphysical_pos:viewphysical_pos:manage
Mağaza/api/v1/physical-pos/stores/{storeId}/settlement-policyphysical_pos:viewphysical_pos:manage
Cihaz/api/v1/physical-pos/devices/{deviceId}/settlement-policyphysical_pos:viewphysical_pos:manage
Cihazın etkin politikasıGET /api/v1/physical-pos/devices/{deviceId}/settlement-policy/effectivephysical_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_only alır.
  • PUT ve DELETE, gün sonu başlatma ile aynı oran sınırını paylaşır: 60 saniyede API anahtarı başına 30 istek.

Modlar

modeNe olur
MANUALGün sonunu siz başlatırsınız: cihazda, panelde ya da API'den. Varsayılan.
SCHEDULEDLunixi gün sonunu scheduleTime saatinde başlatır. Cihaz meşgul ya da bağlı değilse deneme penceresi içinde yeniden dener.
DEVICE_AUTOCihaz 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.

AlanTipAçıklama
scopeTypestringACCOUNT, STORE ya da DEVICE.
storeId, deviceIdstring | nullMağaza ya da cihaz düzeyinde hedef.
activebooleanBu düzeyde politika yazılı mı. false ise düzey üstten devralır.
modestringMANUAL, SCHEDULED ya da DEVICE_AUTO.
scheduleTimestring | nullSCHEDULED'da başlatma saati, HH:mm (24 saat).
timeZonestringSaat dilimi (IANA adı). Varsayılan Europe/Istanbul.
scheduleDaysstring[]SCHEDULED'da günler: MON…SUN. Her gün için yedi gün de listelenir.
retryWindowMinutesinteger | nullSCHEDULED'da deneme penceresi, dakika.
retryIntervalMinutesinteger | nullSCHEDULED'da denemeler arası süre, dakika.
offlineBehaviorstring | nullSCHEDULED'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).
overdueAlertHoursinteger | nullSon gün sonundan bu kadar saat geçince gecikme bildirimi gönderilir; null ise kapalı.
rowVersionintegerKaydın sürümü; yazarken expectedRowVersion olarak gönderin. Yazılmamış düzeyde 0.
updatedAtstring | nullSon 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.

AlanTipZorunluAçıklama
modestringEvetMANUAL, SCHEDULED ya da DEVICE_AUTO.
scheduleTimestringSCHEDULED'daHH:mm. Diğer modlarda gönderilmez.
timeZonestringHayırIANA saat dilimi. Varsayılan Europe/Istanbul.
scheduleDaysstring[]HayırMON, TUE, WED, THU, FRI, SAT, SUN; tekrarsız. Boş ya da gönderilmezse her gün. Yalnız SCHEDULED'da.
retryWindowMinutesintegerHayır5–720, varsayılan 120. Yalnız SCHEDULED'da.
retryIntervalMinutesintegerHayır1–120, varsayılan 15; retryWindowMinutes'tan küçük olmalı. Yalnız SCHEDULED'da.
offlineBehaviorstringHayırRETRY_IN_WINDOW (varsayılan) ya da ALERT_IMMEDIATELY. Yalnız SCHEDULED'da.
overdueAlertHoursintegerHayır1–168. Her modda kullanılabilir; gönderilmezse gecikme bildirimi kapalı.
expectedRowVersionintegerHayırOkuduğ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
  }
}
AlanTipAçıklama
sourceScopeTypestringPolitikanın geldiği düzey: DEVICE, STORE, ACCOUNT ya da DEFAULT (hiç politika yok, MANUAL).
policyobjectUygulanan politika.
serverSettlementSupportedbooleanCihaz sunucudan başlatılan gün sonunu destekliyor mu.
deviceAutoSupportedbooleanCihazın kendi otomatik gün sonu sonucu kaydedilebiliyor mu.
nextScheduledAtstring | nullSonraki zamanlanmış gün sonu (UTC). SCHEDULED değilse, 8 gün içinde zaman yoksa ya da scheduleWarning doluysa null.
lastSettlementAtstring | nullCihazın son gün sonu.
overduebooleanoverdueAlertHours tanımlıysa ve son gün sonu bu süreden eskiyse (ya da hiç yoksa) true.
scheduleWarningstring | nullSCHEDULED_UNSUPPORTED: politika SCHEDULED ama cihaz sunucudan gün sonunu desteklemiyor; zamanlanmış gün sonu atlanacak.

Gecikme ve başarısızlık bildirimleri

WebhookNe zaman
physical_pos.settlement.completedCihaz gün sonu sonucunu bildirdi (elle, zamanlanmış ya da cihazın kendi gün sonu).
physical_pos.settlement.failedZamanlanmış gün sonu deneme penceresinde alınamadı.
physical_pos.settlement.skippedZamanlanmış gün sonu atlandı: cihaz desteklemiyor ya da aktif değil.
physical_pos.settlement.overdueSon gün sonundan overdueAlertHours saat geçti.

Yükler: Webhook Olayları › Gün sonu olayları.

Hatalar

HTTPcodeNe zaman
400physical_pos.settlement.policy_invalidPolitika kuralına uymayan alan (details.field, details.reason: required, invalid, not_allowed, out_of_range, duplicate, not_less_than_window).
400VALIDATION_ERRORTanımsız alan ya da sayı JSON tam sayısı değil.
403physical_pos.environment.test_key_read_onlyYazma test anahtarıyla yapıldı.
404physical_pos.store.not_found · physical_pos.device.not_foundMağaza ya da cihaz yok, size ait değil ya da diğer ortamda.
409physical_pos.settlement.policy_version_conflictexpectedRowVersion güncel değil; politikayı yeniden okuyun.
422physical_pos.settlement.scheduled_unsupportedCihaz düzeyinde SCHEDULED; cihaz sunucudan gün sonunu desteklemiyor.
422physical_pos.settlement.device_auto_unsupportedCihaz düzeyinde DEVICE_AUTO; cihaz kendi gün sonu sonucunu bildiremiyor.
429RATE_LIMITEDGün sonu yazma sınırı aşıldı.

Bütün kodlar: Hata Kodları.