Fiziksel POS
API Referansı
Raporlar

Raporlar

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.
YöntemYolKapsam
GET/api/v1/physical-pos/reports/sales-summaryphysical_pos:view ya da physical_pos:payments
GET/api/v1/physical-pos/reports/tax-summaryphysical_pos:view ya da physical_pos:payments

Raporlar anahtarınızın ortamındaki ödemelerden üretilir; test ve canlı kayıtlar aynı raporda toplanmaz. Yanıttaki environment alanı raporun ortamını gösterir (TEST ya da LIVE).

Ortak kurallar

Sorgu parametresiTipAçıklama
dateFromstringİlk iş günü, YYYY-MM-DD (dahil). Varsayılan: dateTo'dan 6 gün önce.
dateTostringSon iş günü, YYYY-MM-DD (dahil). Varsayılan: bugün.
deviceIdstring (UUID)Yalnız bu cihazın işlemleri.
storeIdstring (UUID)Yalnız bu mağazanın işlemleri (işlem anındaki cihaz ataması).
  • İş günü Europe/Istanbul saatine göredir. Aralık en çok 93 gündür. Gerçek olmayan tarih (2026-02-30) 400 physical_pos.input.filter_invalid (details.field), ters ya da uzun aralık aynı kod ve details.reason: range_invalid alır.
  • İşlem anı: doğrudan cihazda yapılan satışta (origin: "DEVICE_DIRECT") cihazın bildirdiği satış anı; diğer işlemlerde işlemin kaydedildiği an. Her işlem kendi gününe yazılır: ertesi gün yapılan void, ertesi günün netinden düşer.
  • Kovalar:
Kovaİşlemler
SatışSALE ve PREAUTH_CLOSE
İadeREFUND ve REFUND_UNMATCHED
VoidVOID
  • Kovalara yalnız onaylanmış (APPROVED, PARTIALLY_APPROVED) işlemler, onaylanan tutarla girer. PREAUTH_OPEN ve PREAUTH_CANCEL rapora girmez.
  • Sonucu belirsiz (UNKNOWN, MANUAL_REVIEW) işlemler tutara girmez, yalnız ambiguousCount alanında sayılır.
  • Net = satış − iade − void, para birimi başına. Farklı para birimleri ayrı satırlardadır.
  • Bütün parasal toplamlar, matrahlar ve vergiler kanonik minor-unit dizelerdir. Net alanlar negatif olabilir (örneğin "-4500"); adetler ve rateBp JSON tam sayı olarak kalır. → Tutarlar

Satış özeti

GET /api/v1/physical-pos/reports/sales-summary

Ek sorgu parametresi: groupBy: DAY (varsayılan), STORE, DEVICE ya da INSTRUMENT. Başka değer 400 physical_pos.input.filter_invalid.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/reports/sales-summary?dateFrom=2026-01-01&dateTo=2026-01-07&groupBy=STORE"
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"
{
  "environment": "LIVE",
  "dateFrom": "2026-01-01",
  "dateTo": "2026-01-07",
  "groupBy": "STORE",
  "rows": [
    {
      "groupKey": "00000000-0000-0000-0000-000000000101",
      "currency": "TRY",
      "saleCount": 120,
      "saleMinor": "540000",
      "refundCount": 3,
      "refundMinor": "12000",
      "voidCount": 1,
      "voidMinor": "4500",
      "netMinor": "523500",
      "ambiguousCount": 0
    }
  ]
}

Örnekte data alanı gösterilmiştir.

AlanTipAçıklama
environmentstringRaporun ortamı.
dateFrom, dateTostringUygulanan iş günü aralığı.
groupBystringUygulanan gruplama.
rows[].groupKeystring | nullDAY: iş günü (YYYY-MM-DD); STORE: mağaza kimliği, mağazaya atanmamış cihazların işlemleri için null; DEVICE: cihaz kimliği; INSTRUMENT: ödeme aracı: CARD, MEAL_CARD, QR, WALLET, CASH, BANK_TRANSFER, OTHER (API'den başlatılan ödemeler CARD; diğerleri doğrudan cihazda yapılan satışlardan). Değer kümesi büyüyebilir.
rows[].currencystringPara birimi.
rows[].saleCount, refundCount, voidCountintegerSatış, iade ve void kovalarındaki işlem adetleri.
rows[].saleMinor, refundMinor, voidMinorstringBu kovalardaki onaylanan tutarlar; kanonik negatif olmayan minor-unit dizeler.
rows[].netMinorstringSatış − iade − void.
rows[].ambiguousCountintegerSonucu belirsiz işlem adedi.

Vergi özeti

GET /api/v1/physical-pos/reports/tax-summary

Vergi dökümü satışın kalemlerinden hesaplanır (vergi grupları). Ek sorgu parametresi yoktur.

AlanTipAçıklama
environment, dateFrom, dateToSatış özetindeki gibi.
rows[]arrayVergi türü, oran ve para birimi başına döküm.
rows[].taxTypestringKDV, KDV_TEVKIFAT, OTV_I, OTV_II, OTV_III, OTV_IV, OIV, BSMV ya da KONAKLAMA.
rows[].rateBpinteger | nullOran, baz puan; birim başına sabit vergide null.
rows[].currencystringPara birimi.
rows[].saleBaseMinor, saleTaxMinorstringSatış kovasının matrahı ve vergisi.
rows[].refundBaseMinor, refundTaxMinorstringİade kovası.
rows[].voidBaseMinor, voidTaxMinorstringVoid kovası.
rows[].netBaseMinor, netTaxMinorstringSatış − iade − void.
amountTotals[]arrayPara birimi ve kapsam başına tutar sayaçları.
amountTotals[].scopestringITEMIZED: kalemli satışlar ve onların iade ve void'leri. ITEMLESS: kalemsiz satışlar, ön provizyon kapamaları, kalemsiz satışların iade ve void'leri ve eşleşmesiz iadeler.
amountTotals[].currency, saleCount, saleMinor, refundCount, refundMinor, voidCount, voidMinor, netMinorSatış özetiyle aynı anlamda.
  • Kalem bazlı iade kendi vergi dökümüyle düşer.
  • Tutar bazlı iade satışın tahsil edilen vergisinden, iade tutarının satışın onaylanan tutarına oranıyla düşer.
  • Kısmi onaylanan satışın vergisi, dökümün onaylanan / istenen tutar oranıyla hesaplanır.
  • Void satışın tahsil edilen vergisinin aynısını düşer.
  • En küçük para birimine yuvarlama en büyük kalan yöntemiyle yapılır: satırların toplamı, yuvarlanmış toplam vergiye eşittir.
  • Kalemsiz satışların vergisi hesaplanamaz; bu satışlar yalnız amountTotals içindeki ITEMLESS sayaçlarında görünür.
  • Aynı aralık ve süzgeçlerle ITEMIZED.netMinor + ITEMLESS.netMinor, satış özetinin netMinor toplamına eşittir.

Hatalar

HTTPcodeNe zaman
400physical_pos.input.filter_invalidGeçersiz tarih, aralık, groupBy ya da kimlik; 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 (ör. limit).
500physical_pos.internal.integrity · physical_pos.gateway.response_invalidRapor üretilemedi; geri çekilerek yeniden deneyin.