Fiziksel POS
API Referansı
Gün Sonu Kayıtları

Gün Sonu Kayıtları

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.

GET /api/v1/physical-pos/settlements · kapsam physical_pos:view ya da physical_pos:payments

POS cihazı gün sonu aldığında her banka için bir satır bildirir: satış, iade ve void adetleri ile tutarları. Lunixi her satırı kendi kayıtlarıyla karşılaştırır ve sonucu bu uçta listeler. Kayıtlar anahtarınızın ortamındadır; en yeni gün sonu önce döner.

Sorgu parametresiTipAçıklama
limitinteger1–100, varsayılan 25.
cursorstringÖnceki yanıttaki pageInfo.nextCursor. İmleci olduğu gibi kullanın.
createdFromstringGün sonu işleminin 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.
deviceIdstring (UUID)Cihaz.
lineStatusstringMATCHED, MISMATCH ya da UNMAPPED.
includeTotalbooleantrue ise ilk sayfada (cursor olmadan) pageInfo.totalCount süzgece uyan kayıt sayısıyla doldurulur; sonraki sayfalarda null.

Zaman penceresi en çok 93 gündür; aksi 400 physical_pos.input.filter_invalid (details.reason: range_invalid).

{
  "items": [
    {
      "commandId": "01900000-0000-7000-8000-000000000701",
      "settlementRef": null,
      "lineNo": 1,
      "deviceId": "00000000-0000-0000-0000-000000000401",
      "acquirerCode": "0000",
      "acquirerRefRaw": "0000",
      "acquirerName": "Örnek Bank",
      "deviceName": "Kasa 1 POS",
      "batchNo": "000123",
      "bankTerminalNumber": "PS000001",
      "currency": "TRY",
      "lineStatus": "MISMATCH",
      "reported": { "saleCount": 42, "saleMinor": "189000", "refundCount": 1, "refundMinor": "1500", "voidCount": 0, "voidMinor": "0" },
      "system": { "saleCount": 41, "saleMinor": "184500", "refundCount": 1, "refundMinor": "1500", "voidCount": 0, "voidMinor": "0" },
      "difference": { "saleCount": 1, "saleMinor": "4500", "refundCount": 0, "refundMinor": "0", "voidCount": 0, "voidMinor": "0" },
      "periodFrom": "2026-01-01T20:00:05.000Z",
      "periodTo": "2026-01-02T20:00:03.000Z",
      "deviceClosedAt": "2026-01-02T20:00:01.000Z",
      "recordedAt": "2026-01-02T20:00:04.000Z"
    }
  ],
  "pageInfo": { "hasMore": false, "nextCursor": null, "totalCount": null }
}

Örnekte data alanı gösterilmiştir.

AlanTipAçıklama
commandIdstring | nullGün sonu Lunixi'nin gönderdiği gün sonu komutuyla alındıysa komutun kimliği; cihazda başlatılan gün sonunda null.
settlementRefstring | nullCihazda başlatılan gün sonunda cihazın verdiği gün sonu kimliği; komutla alınan gün sonunda null. Her kayıtta commandId ile settlementRef'ten yalnız biri doludur.
lineNointegerCihazın gün sonundaki satır numarası; numaralar ardışık olmayabilir.
deviceIdstringGün sonunu alan cihaz.
acquirerCodestring | nullBankanın dört haneli kodu; cihazın bildirdiği banka tanınmadıysa null.
acquirerRefRawstring | nullCihazın bildirdiği banka kodu, olduğu gibi. Banka tanınmadığında (UNMAPPED) hangi kodun tanınmadığını bu alandan görürsünüz; tanınan satırda da doludur.
acquirerNamestring | nullBankanın görünen adı; banka tanınmadıysa null.
deviceNamestring | nullCihazın güncel görünen adı (displayName).
batchNostring | nullBankanın grup (batch) numarası.
bankTerminalNumberstring | nullBankanın terminal numarası (TID).
currencystringPara birimi.
lineStatusstringMATCHED: bildirilen ve hesaplanan toplamlar aynı. MISMATCH: en az bir sayı farklı. UNMAPPED: cihazın bildirdiği banka tanınmadı; satır karşılaştırılmaz, system toplamları 0'dır.
reportedobjectCihazın bildirdiği toplamlar: saleCount, saleMinor, refundCount, refundMinor, voidCount, voidMinor.
systemobjectLunixi kayıtlarından hesaplanan toplamlar, aynı alanlar.
differenceobjectBildirilen − hesaplanan, aynı alanlar; negatif olabilir.
periodFrom, periodTostringKarşılaştırma penceresi. periodFrom, aynı cihazın bir önceki gün sonudur (en çok 31 gün geri).
deviceClosedAtstring | nullCihazın bildirdiği kapanış anı.
recordedAtstringGün sonu sonucunun kaydedildiği an.

reported, system ve difference içinde saleCount, refundCount ve voidCount JSON tam sayıdır; saleMinor, refundMinor ve voidMinor kanonik minor-unit dizelerdir. Bildirilen ve hesaplanan tutarlar negatif olamaz; parasal farklar işaretli olabilir. UNMAPPED satırlarda sistem adetleri 0, sistem tutarları "0" olur.

Hesaplanan toplam (system) şu işlemlerden oluşur:

  • aynı cihazda, aynı bankada ve aynı para biriminde yapılan işlemler; ters işlemin bankası belli değilse satışın bankası kullanılır;
  • yalnız kartla ödemeler; nakit, QR ve yemek kartı ödemeleri banka gün sonuna girmez;
  • periodFrom'dan sonra ve periodTo'ya kadar (dahil) tamamlanan işlemler; doğrudan cihazda yapılan satışta cihazın bildirdiği satış anı esas alınır;
  • kova ve tutar kuralları raporlardakiyle aynıdır. → Raporlar › Ortak kurallar

UNMAPPED satır gördüğünüzde bankanın tanınması için destekle iletişime geçin; acquirerRefRaw değerini iletin.

Gün sonuna giren ödemelere artık void yapılamaz; iade yapın. → Ödeme Akışı › Gün sonu ve void

Hatalar

HTTPcodeNe zaman
400physical_pos.validation.invalidlimit aralık dışı.
400physical_pos.cursor.invalidBozuk imleç.
400physical_pos.input.filter_invalidGeçersiz süzgeç; details.field, gerekirse details.reason.
400physical_pos.input.environment_invalidİstekte environment.
400physical_pos.payment.card_data_rejectedSorgu parametresinin adı kart verisine benziyor.
400VALIDATION_ERRORTanımlanmamış sorgu parametresi.
500physical_pos.gateway.response_invalidBeklenmeyen yanıt; geri çekilerek yeniden deneyin.