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ı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.
| Yöntem | Yol | Kapsam |
|---|---|---|
GET | /api/v1/physical-pos/reports/sales-summary | physical_pos:view ya da physical_pos:payments |
GET | /api/v1/physical-pos/reports/tax-summary | physical_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 parametresi | Tip | Açıklama |
|---|---|---|
dateFrom | string | İlk iş günü, YYYY-MM-DD (dahil). Varsayılan: dateTo'dan 6 gün önce. |
dateTo | string | Son iş günü, YYYY-MM-DD (dahil). Varsayılan: bugün. |
deviceId | string (UUID) | Yalnız bu cihazın işlemleri. |
storeId | string (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 vedetails.reason: range_invalidalı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 |
| İade | REFUND ve REFUND_UNMATCHED |
| Void | VOID |
- Kovalara yalnız onaylanmış (
APPROVED,PARTIALLY_APPROVED) işlemler, onaylanan tutarla girer.PREAUTH_OPENvePREAUTH_CANCELrapora girmez. - Sonucu belirsiz (
UNKNOWN,MANUAL_REVIEW) işlemler tutara girmez, yalnızambiguousCountalanı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 verateBpJSON 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.
| Alan | Tip | Açıklama |
|---|---|---|
environment | string | Raporun ortamı. |
dateFrom, dateTo | string | Uygulanan iş günü aralığı. |
groupBy | string | Uygulanan gruplama. |
rows[].groupKey | string | null | DAY: 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[].currency | string | Para birimi. |
rows[].saleCount, refundCount, voidCount | integer | Satış, iade ve void kovalarındaki işlem adetleri. |
rows[].saleMinor, refundMinor, voidMinor | string | Bu kovalardaki onaylanan tutarlar; kanonik negatif olmayan minor-unit dizeler. |
rows[].netMinor | string | Satış − iade − void. |
rows[].ambiguousCount | integer | Sonucu 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.
| Alan | Tip | Açıklama |
|---|---|---|
environment, dateFrom, dateTo | Satış özetindeki gibi. | |
rows[] | array | Vergi türü, oran ve para birimi başına döküm. |
rows[].taxType | string | KDV, KDV_TEVKIFAT, OTV_I, OTV_II, OTV_III, OTV_IV, OIV, BSMV ya da KONAKLAMA. |
rows[].rateBp | integer | null | Oran, baz puan; birim başına sabit vergide null. |
rows[].currency | string | Para birimi. |
rows[].saleBaseMinor, saleTaxMinor | string | Satış kovasının matrahı ve vergisi. |
rows[].refundBaseMinor, refundTaxMinor | string | İade kovası. |
rows[].voidBaseMinor, voidTaxMinor | string | Void kovası. |
rows[].netBaseMinor, netTaxMinor | string | Satış − iade − void. |
amountTotals[] | array | Para birimi ve kapsam başına tutar sayaçları. |
amountTotals[].scope | string | ITEMIZED: 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, netMinor | Satış ö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
amountTotalsiçindekiITEMLESSsayaçlarında görünür. - Aynı aralık ve süzgeçlerle
ITEMIZED.netMinor + ITEMLESS.netMinor, satış özetininnetMinortoplamına eşittir.
Hatalar
| HTTP | code | Ne zaman |
|---|---|---|
400 | physical_pos.input.filter_invalid | Geçersiz tarih, aralık, groupBy ya da kimlik; details.field, gerekirse details.reason. |
400 | physical_pos.input.environment_invalid | İstekte environment. |
400 | physical_pos.payment.card_data_rejected | Sorgu parametresinin adı kart verisine benziyor. |
400 | VALIDATION_ERROR | Tanımlanmamış sorgu parametresi (ör. limit). |
500 | physical_pos.internal.integrity · physical_pos.gateway.response_invalid | Rapor üretilemedi; geri çekilerek yeniden deneyin. |