Gün Sonu Başlatma
- 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:payments. Ü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.
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öntem | Yol | Kapsam |
|---|---|---|
POST | /api/v1/physical-pos/devices/{deviceId}/settlement | physical_pos:payments |
GET | /api/v1/physical-pos/settlement-runs | physical_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.completedwebhook'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_onlyalı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
ACTIVEolmalı; değilse409 physical_pos.payment.terminal_not_payable(details.reason:status_suspendedgibi). - 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ğrulanamazsa503 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_holdya dasettlement_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 parametresi | Tip | Açıklama |
|---|---|---|
limit | integer | 1–100, varsayılan 25. |
cursor | string | Önceki yanıttaki pageInfo.nextCursor. |
deviceId | string (UUID) | Cihaz. |
source | string | MANUAL_API, MANUAL_PANEL ya da SCHEDULED. |
runStatus | string | PENDING, STARTED, SKIPPED ya da FAILED. |
createdFrom | string | Çalışmanın açıldığı zaman için alt sınır, ISO 8601 UTC (Z ile biter). Varsayılan: son 31 gün. |
createdTo | string | Üst sınır, aynı biçim. Varsayılan: şimdi + 5 dakika. |
includeTotal | boolean | true 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
| Alan | Tip | Açıklama |
|---|---|---|
runId | string | Çalışmanın kimliği. |
deviceId | string | Cihaz. |
environment | string | LIVE ya da TEST. |
source | string | Çalışmayı kim başlattı: MANUAL_API (API), MANUAL_PANEL (panel) ya da SCHEDULED (zamanlanmış gün sonu). |
runStatus | string | Aşağıdaki tabloya bakın. |
reason | string | null | Bekleme, atlama ya da başarısızlık sebebi. Aşağıdaki tabloya bakın. |
businessDate | string | null | Zamanlanmış gün sonunun iş günü (YYYY-MM-DD); elle başlatılan çalışmada null. |
commandId | string | null | Cihaza gönderilen gün sonu komutu. Gün sonu kayıtlarında commandId ile eşleşir. |
commandStatus | string | null | Komutun durumu: CREATED, DISPATCHING, DISPATCHED, ACKED, REJECTED, EXPIRED ya da CANCELLED. |
deliveryPath | string | null | Komutun cihaza gidiş yolu; şu an MQTT. |
resultState | string | null | Gü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. |
attemptCount | integer | Başlatma denemesi sayısı. |
nextAttemptAt | string | null | Zamanlanmış gün sonunda sonraki deneme zamanı. |
windowEndsAt | string | null | Zamanlanmış gün sonunda deneme penceresinin sonu. |
resultLineCount | integer | Cihazın bildirdiği banka satırı sayısı. |
completedAt | string | null | Sonucun kaydedildiği zaman. |
createdAt, updatedAt | string | Oluşturma ve son değişiklik zamanı. |
runStatus:
| Değer | Anlamı |
|---|---|
PENDING | Zamanlanmış gün sonu deneme sırasını bekliyor (ilk deneme ya da yeniden deneme). |
STARTED | Gü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. |
SKIPPED | Gün sonu bilerek atlandı. |
FAILED | Gün sonu deneme penceresi içinde başlatılamadı ya da sonuç gelmedi. |
reason:
| Değer | Anlamı |
|---|---|
DEVICE_BUSY | Cihazda yürüyen işlem vardı; yeniden denenir. |
DEVICE_OFFLINE | Cihaz bağlı değildi. |
PRESENCE_UNAVAILABLE | Cihazın bağlantı durumu doğrulanamadı; yeniden denenir. |
COMMAND_REJECTED, COMMAND_EXPIRED | Cihaz komutu reddetti ya da komutun süresi doldu. |
RESULT_MISSING | Cihaz komutu aldı ama 30 dakika içinde sonuç bildirmedi (FAILED). |
WINDOW_EXPIRED | Deneme penceresi doldu (FAILED). |
SETTLEMENT_UNSUPPORTED | Cihaz modeli sunucudan gün sonunu desteklemiyor (SKIPPED). |
DEVICE_NOT_ACTIVE | Cihaz aktif değil (SKIPPED). |
DEVICE_NOT_FOUND | Cihaz artık yok (SKIPPED). |
ALREADY_SETTLED | O iş günü için gün sonu zaten alınmış (SKIPPED). |
POLICY_CHANGED | Gün sonu politikası değişti (SKIPPED). |
INTERNAL_ERROR | Beklenmeyen hata; yeniden denenir. |
Değer kümeleri açıktır; tanımadığınız değeri yok sayın.
Hatalar
| HTTP | code | Ne zaman |
|---|---|---|
400 | physical_pos.idempotency.key_required · .key_invalid | Idempotency-Key yok ya da biçim dışı (8–200 boşluksuz yazdırılabilir ASCII). |
400 | physical_pos.input.filter_invalid | deviceId UUID değil ya da liste süzgeci biçim dışı (details.field). |
400 | physical_pos.cursor.invalid | cursor bozuk. |
400 | VALIDATION_ERROR | Başlatma gövdesinde alan var. |
403 | physical_pos.environment.test_key_read_only | Başlatma test anahtarıyla yapıldı. |
404 | physical_pos.device.not_found | Cihaz yok, size ait değil ya da diğer ortamda. |
404 | physical_pos.settlement.run_not_found | Çalışma bulunamadı. |
409 | physical_pos.payment.terminal_not_payable | Cihaz aktif değil (details.reason). |
409 | physical_pos.payment.device_offline | Cihaz bağlı değil. |
409 | physical_pos.payment.device_busy | Cihazda yürüyen işlem var (details.reason, details.retryAfterSeconds). |
409 | physical_pos.idempotency_mismatch | Anahtar başka bir cihazın gün sonunda kullanılmış. |
422 | physical_pos.payment.operation_unsupported | settlement_unsupported ya da vendor_settlement_report_unsupported. |
429 | RATE_LIMITED | 60 saniyede API anahtarı başına 30 istek aşıldı; sayaç gün sonu politikası yazmalarıyla ortaktır. Retry-After kadar bekleyin. |
503 | physical_pos.presence.unavailable · physical_pos.signing.unavailable | Geçici; aynı Idempotency-Key ile yeniden deneyin. |
Bütün kodlar: Hata Kodları.