Fiziksel POS
API Referansı
Gün Sonu Başlatma

Gün Sonu Başlatma

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:payments. Ü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.

Cihazda gün sonunu kendi sunucunuzdan başlatabilirsiniz. Lunixi cihaza imzalı bir gün sonu komutu gönderir; cihaz bankalardan gün sonunu alıp sonucu bildirir. Her başlatma bir gün sonu çalışması (run) kaydı açar. Gün sonu politikasıyla zamanlanmış gün sonları da aynı çalışma kaydını kullanır.

YöntemYolKapsam
POST/api/v1/physical-pos/devices/{deviceId}/settlementphysical_pos:payments
GET/api/v1/physical-pos/settlement-runsphysical_pos:view ya da physical_pos:payments
GET/api/v1/physical-pos/settlement-runs/{runId}physical_pos:view ya da physical_pos:payments
  • Gün sonunun sonucunu (banka satırları ve Lunixi kayıtlarıyla fark) Gün Sonu Kayıtları ucundan ve physical_pos.settlement.completed webhook'undan alırsınız. Çalışma kaydı yalnız gün sonunun başlatılmasını ve komutun durumunu izler.
  • Test anahtarı çalışmaları okur; başlatma 403 physical_pos.environment.test_key_read_only alır. → Ortamlar
  • Gün sonunu cihazda elle de alabilirsiniz; o zaman çalışma kaydı açılmaz, sonuç yine Gün Sonu Kayıtları'na ve webhook'a düşer (source: "DEVICE").

cURL örnekleri imzayı lunixi-sign.sh ile hesaplar: Kimlik Doğrulama › İmza yardımcısı.

Gün sonunu başlatma

POST /api/v1/physical-pos/devices/{deviceId}/settlement · physical_pos:payments

Gövde boştur; Idempotency-Key başlığı zorunludur. → Ortak Kurallar › Idempotency-Key

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/devices/00000000-0000-0000-0000-000000000401/settlement"
BODY='{}'
lunixi_sign POST "$REQ_PATH" "$BODY"
 
curl -X POST "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" \
  -H "Idempotency-Key: 2c8e4f1a-6b3d-4e9a-8c71-5d0f2b7e9a14" \
  --data-raw "$BODY"

Yeni çalışma 202 ile döner; aynı anahtar ve aynı cihazla tekrar edilen istek aynı çalışmayı 200 ve replayed: true ile döner. Örnekte data alanı gösterilmiştir.

{
  "run": {
    "runId": "01900000-0000-7000-8000-000000000801",
    "deviceId": "00000000-0000-0000-0000-000000000401",
    "environment": "LIVE",
    "source": "MANUAL_API",
    "runStatus": "STARTED",
    "reason": null,
    "businessDate": null,
    "commandId": "01900000-0000-7000-8000-000000000802",
    "commandStatus": "CREATED",
    "deliveryPath": "MQTT",
    "resultState": "PENDING",
    "attemptCount": 1,
    "nextAttemptAt": null,
    "windowEndsAt": null,
    "resultLineCount": 0,
    "completedAt": null,
    "createdAt": "2026-01-02T20:00:00.000Z",
    "updatedAt": "2026-01-02T20:00:00.000Z"
  },
  "replayed": false
}

Gün sonu başlatılmadan önce şunlar denetlenir:

  • Cihaz ACTIVE olmalı; değilse 409 physical_pos.payment.terminal_not_payable (details.reason: status_suspended gibi).
  • Cihaz modeli sunucudan gün sonunu desteklemeli; desteklemiyorsa 422 physical_pos.payment.operation_unsupported (details.reason: settlement_unsupported). Üretici bulutuyla bağlanan cihazlarda sunucudan gün sonu şu an kapalıdır (vendor_settlement_report_unsupported). → Bağlantı Yöntemleri
  • Cihaz bağlı olmalı: 409 physical_pos.payment.device_offline; bağlantı durumu doğrulanamazsa 503 physical_pos.presence.unavailable.
  • Cihazda yürüyen ödeme, sonucu belirsiz ödeme bekletmesi ya da başka bir gün sonu varsa 409 physical_pos.payment.device_busy (details.reason: payment_in_progress, unknown_outcome_hold ya da settlement_in_progress; details.retryAfterSeconds).

Bu denetimlerden biri reddederse çalışma kaydı açılmaz. Gün sonu sürerken cihaz yeni ödeme almaz: ödeme isteği 409 physical_pos.payment.device_busy (settlement_in_progress) alır. → Tek aktif ödeme

202 gün sonunun başladığını gösterir, bittiğini değil. Sonucu physical_pos.settlement.completed webhook'undan ya da çalışmanın resultState alanından izleyin.

Çalışmaları listeleme

GET /api/v1/physical-pos/settlement-runs · physical_pos:view ya da physical_pos:payments

En yeni çalışma önce döner. Yanıt { "items": [ … ], "pageInfo": { … } }; öğe çalışma nesnesidir.

Sorgu parametresiTipAçıklama
limitinteger1–100, varsayılan 25.
cursorstringÖnceki yanıttaki pageInfo.nextCursor.
deviceIdstring (UUID)Cihaz.
sourcestringMANUAL_API, MANUAL_PANEL ya da SCHEDULED.
runStatusstringPENDING, STARTED, SKIPPED ya da FAILED.
createdFromstringÇalışmanın açıldığı zaman için alt sınır, ISO 8601 UTC (Z ile biter). Varsayılan: son 31 gün.
createdTostringÜst sınır, aynı biçim. Varsayılan: şimdi + 5 dakika.
includeTotalbooleantrue ise ilk sayfada (cursor olmadan) pageInfo.totalCount doldurulur.

Zaman penceresi en çok 93 gündür. Biçim dışı süzgeç 400 physical_pos.input.filter_invalid (details.field) alır.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/settlement-runs?deviceId=00000000-0000-0000-0000-000000000401&runStatus=FAILED"
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"

Çalışmayı okuma

GET /api/v1/physical-pos/settlement-runs/{runId} · physical_pos:view ya da physical_pos:payments

Yanıt { "run": { … } }. Olmayan, başka organizasyona ait ya da diğer ortamdaki çalışma 404 physical_pos.settlement.run_not_found alır.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/settlement-runs/01900000-0000-7000-8000-000000000801"
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"

Çalışma nesnesi

AlanTipAçıklama
runIdstringÇalışmanın kimliği.
deviceIdstringCihaz.
environmentstringLIVE ya da TEST.
sourcestringÇalışmayı kim başlattı: MANUAL_API (API), MANUAL_PANEL (panel) ya da SCHEDULED (zamanlanmış gün sonu).
runStatusstringAşağıdaki tabloya bakın.
reasonstring | nullBekleme, atlama ya da başarısızlık sebebi. Aşağıdaki tabloya bakın.
businessDatestring | nullZamanlanmış gün sonunun iş günü (YYYY-MM-DD); elle başlatılan çalışmada null.
commandIdstring | nullCihaza gönderilen gün sonu komutu. Gün sonu kayıtlarında commandId ile eşleşir.
commandStatusstring | nullKomutun durumu: CREATED, DISPATCHING, DISPATCHED, ACKED, REJECTED, EXPIRED ya da CANCELLED.
deliveryPathstring | nullKomutun cihaza gidiş yolu; şu an MQTT.
resultStatestring | nullGün sonunun sonucu: PENDING (bekleniyor), COMPLETED (cihaz sonucu bildirdi), NOT_COMPLETED (komut reddedildi, süresi doldu ya da iptal edildi ve sonuç gelmedi). Komut yoksa null.
attemptCountintegerBaşlatma denemesi sayısı.
nextAttemptAtstring | nullZamanlanmış gün sonunda sonraki deneme zamanı.
windowEndsAtstring | nullZamanlanmış gün sonunda deneme penceresinin sonu.
resultLineCountintegerCihazın bildirdiği banka satırı sayısı.
completedAtstring | nullSonucun kaydedildiği zaman.
createdAt, updatedAtstringOluşturma ve son değişiklik zamanı.

runStatus:

DeğerAnlamı
PENDINGZamanlanmış gün sonu deneme sırasını bekliyor (ilk deneme ya da yeniden deneme).
STARTEDGün sonu komutu cihaza gönderilmek üzere kuyruğa alındı. Sonuç resultState alanındadır. Elle başlatılan çalışma bu durumla açılır.
SKIPPEDGün sonu bilerek atlandı.
FAILEDGün sonu deneme penceresi içinde başlatılamadı ya da sonuç gelmedi.

reason:

DeğerAnlamı
DEVICE_BUSYCihazda yürüyen işlem vardı; yeniden denenir.
DEVICE_OFFLINECihaz bağlı değildi.
PRESENCE_UNAVAILABLECihazın bağlantı durumu doğrulanamadı; yeniden denenir.
COMMAND_REJECTED, COMMAND_EXPIREDCihaz komutu reddetti ya da komutun süresi doldu.
RESULT_MISSINGCihaz komutu aldı ama 30 dakika içinde sonuç bildirmedi (FAILED).
WINDOW_EXPIREDDeneme penceresi doldu (FAILED).
SETTLEMENT_UNSUPPORTEDCihaz modeli sunucudan gün sonunu desteklemiyor (SKIPPED).
DEVICE_NOT_ACTIVECihaz aktif değil (SKIPPED).
DEVICE_NOT_FOUNDCihaz artık yok (SKIPPED).
ALREADY_SETTLEDO iş günü için gün sonu zaten alınmış (SKIPPED).
POLICY_CHANGEDGün sonu politikası değişti (SKIPPED).
INTERNAL_ERRORBeklenmeyen hata; yeniden denenir.

Değer kümeleri açıktır; tanımadığınız değeri yok sayın.

Hatalar

HTTPcodeNe zaman
400physical_pos.idempotency.key_required · .key_invalidIdempotency-Key yok ya da biçim dışı (8–200 boşluksuz yazdırılabilir ASCII).
400physical_pos.input.filter_invaliddeviceId UUID değil ya da liste süzgeci biçim dışı (details.field).
400physical_pos.cursor.invalidcursor bozuk.
400VALIDATION_ERRORBaşlatma gövdesinde alan var.
403physical_pos.environment.test_key_read_onlyBaşlatma test anahtarıyla yapıldı.
404physical_pos.device.not_foundCihaz yok, size ait değil ya da diğer ortamda.
404physical_pos.settlement.run_not_foundÇalışma bulunamadı.
409physical_pos.payment.terminal_not_payableCihaz aktif değil (details.reason).
409physical_pos.payment.device_offlineCihaz bağlı değil.
409physical_pos.payment.device_busyCihazda yürüyen işlem var (details.reason, details.retryAfterSeconds).
409physical_pos.idempotency_mismatchAnahtar başka bir cihazın gün sonunda kullanılmış.
422physical_pos.payment.operation_unsupportedsettlement_unsupported ya da vendor_settlement_report_unsupported.
429RATE_LIMITED60 saniyede API anahtarı başına 30 istek aşıldı; sayaç gün sonu politikası yazmalarıyla ortaktır. Retry-After kadar bekleyin.
503physical_pos.presence.unavailable · physical_pos.signing.unavailableGeçici; aynı Idempotency-Key ile yeniden deneyin.

Bütün kodlar: Hata Kodları.