İşlemler
- 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.
İşlem, bir kök ödeme (satış, ön provizyon ya da eşleşmesiz iade) ile ona bağlı ters işlemlerin (void, iade, ön provizyon kapama ve iptali) bütünüdür. Bu uçlar işlemleri ağaç olarak döndürür; tek tek ödeme kayıtları için Ödemeler ucunu kullanın.
| Yöntem | Yol | Kapsam |
|---|---|---|
GET | /api/v1/physical-pos/transactions | physical_pos:view ya da physical_pos:payments |
GET | /api/v1/physical-pos/transactions/ambiguous | physical_pos:view ya da physical_pos:payments |
GET | /api/v1/physical-pos/transactions/{paymentId} | physical_pos:view ya da physical_pos:payments |
- Uçlar yalnız okur; iki kapsamdan biri yeterlidir.
Idempotency-Keyve oran sınırı yoktur. - Kayıtlar anahtarınızın ortamındadır: test anahtarı yalnız test kayıtlarını, canlı anahtar yalnız canlı kayıtları görür.
- Ödeme nesnesinin alanları: Ödemeler › Ödeme nesnesi.
İşlemleri listeleme
GET /api/v1/physical-pos/transactions
Her satır bir kök ödeme ve onun ters işlemleridir; en yeni kök önce döner.
| Sorgu parametresi | Tip | Açıklama |
|---|---|---|
limit | integer | Sayfa başına işlem, 1–100. Varsayılan 25. |
cursor | string | Önceki yanıttaki pageInfo.nextCursor. |
createdFrom | string | Kökün oluşturulma zamanı alt sınırı, ISO 8601 UTC (Z ile biter, en çok 3 ondalık). Varsayılan: son 31 gün. |
createdTo | string | Üst sınır, aynı biçim. Varsayılan: şimdi + 5 dakika. |
paymentStatus | string | Kökün durumu. → Durumlar |
deviceId | string (UUID) | Kökü yürüten cihaz. |
storeId | string (UUID) | Ödeme anında cihazın atandığı mağaza. |
registerId | string (UUID) | Ödeme anında cihazın atandığı kasa. |
merchantReference | string | Kökün referansıyla tam eşleşme. |
amountFromMinor | string | Kökün istenen tutarı için alt sınır (dahil), en küçük birimde, 1 ya da büyük. |
amountToMinor | string | Üst sınır (dahil). |
origin | string | API ya da DEVICE_DIRECT (doğrudan cihazda yapılan satış). |
operation | string | Kökün işlemi: SALE, PREAUTH_OPEN ya da REFUND_UNMATCHED. |
- Zaman penceresi en çok 93 gündür ve
createdFromcreatedTo'dan önce olmalıdır; aksi400 physical_pos.input.filter_invalid(details.reason:range_invalid).amountFromMinoramountToMinor'dan büyükse de aynı sebep döner. - Değer kümeleri büyük/küçük harfe duyarlı değildir.
- Mağaza ve kasa süzgeçleri, cihazın ödeme anındaki atamasına bakar: cihaz sonradan başka mağazaya taşınsa da işlem ilk mağazada kalır.
Yanıt öğesi:
| Alan | Tip | Açıklama |
|---|---|---|
root | object | Kök ödeme. |
children | array | Ters işlemler, eskiden yeniye, en çok 50. |
childrenTruncated | boolean | 50'den fazla ters işlem varsa true; tamamı için işlem ayrıntısını okuyun. |
itemSummary | object | { lineCount, refundStatus, refundedMinor }: kalem sayısı, kalem bazlı iade durumu (NONE, PARTIAL, FULL) ve kalem bazlı iade edilen tutar. Kalemsiz satışta lineCount 0'dır. |
storeId | string | null | Ödeme anında cihazın mağazası; atanmamışsa null. |
registerId | string | null | Ödeme anında cihazın kasası. |
Listede root ve children ödemelerinin items ve refundItems dizileri boştur.
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/transactions?storeId=00000000-0000-0000-0000-000000000101&operation=SALE"
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"{
"status": "success",
"code": "SUCCESS",
"data": {
"items": [
{
"root": { "paymentId": "01900000-0000-7000-8000-000000000501", "operation": "SALE", "paymentStatus": "APPROVED", "amountMinor": "4500", "reversedMinor": "1500", "reversalStatus": "PARTIALLY_REFUNDED" },
"children": [
{ "paymentId": "01900000-0000-7000-8000-000000000502", "operation": "REFUND", "paymentStatus": "APPROVED", "amountMinor": "1500", "originalPaymentId": "01900000-0000-7000-8000-000000000501" }
],
"childrenTruncated": false,
"itemSummary": { "lineCount": 2, "refundStatus": "PARTIAL", "refundedMinor": "1500" },
"storeId": "00000000-0000-0000-0000-000000000101",
"registerId": "00000000-0000-0000-0000-000000000201"
}
],
"pageInfo": { "hasMore": false, "nextCursor": null, "totalCount": null }
},
"pageInfo": { "hasMore": false, "nextCursor": null, "totalCount": null },
"statusCode": 200,
"requestId": "00000000-0000-0000-0000-000000000000"
}Örnekte ödeme nesneleri kısaltılmıştır; yanıt ödeme nesnesinin bütün alanlarını içerir.
Sonucu belirsiz ödemeler
GET /api/v1/physical-pos/transactions/ambiguous
UNKNOWN ve MANUAL_REVIEW durumundaki ödemeleri (kökler ve ters işlemler) en yeni önce listeler. Zaman penceresi yoktur: belirsiz ödemelerinizin tamamı bu listededir.
| Sorgu parametresi | Tip | Açıklama |
|---|---|---|
limit | integer | 1–100, varsayılan 25. |
cursor | string | Önceki yanıttaki pageInfo.nextCursor. |
deviceId | string (UUID) | Cihaz. |
paymentStatus | string | UNKNOWN ya da MANUAL_REVIEW; başka değer 400 physical_pos.input.filter_invalid. |
includeTotal | boolean | true ise ilk sayfada (cursor olmadan) pageInfo.totalCount süzgece uyan belirsiz ödeme sayısıyla doldurulur; sonraki sayfalarda null. |
Yanıt öğesi ödeme nesnesidir. resolvable: true olan ödeme panelden çözülebilir. Belirsiz ödemede ne yapmanız gerektiği: Sonucu belirsiz ödeme.
İşlem ayrıntısı
GET /api/v1/physical-pos/transactions/{paymentId}
Bir işlemin kökünü, bütün ters işlemlerini ve zaman çizelgesini döndürür. paymentId kök ya da ters işlem kimliği olabilir; ters işlem kimliği verirseniz kökün ağacı döner. Bu uç sorgu parametresi almaz.
rootPaymentId). reservedMinor burada reversalReservedMinor alanıdır. Kökte aynı anda tek bekleyen ters işlem olur.{
"transaction": {
"requestedPaymentId": "01900000-0000-7000-8000-000000000502",
"root": { "paymentId": "01900000-0000-7000-8000-000000000501", "items": [ { "lineNo": 1, "name": "Çay" } ] },
"children": [ { "paymentId": "01900000-0000-7000-8000-000000000502", "refundItems": [ { "lineNo": 1, "quantityMilli": 1000 } ] } ],
"timeline": [
{ "kind": "PAYMENT", "paymentId": "01900000-0000-7000-8000-000000000501", "commandId": "01900000-0000-7000-8000-000000000601", "commandType": null, "seq": 1, "eventType": "STATUS_CHANGED", "fromStatus": null, "toStatus": "NOT_STARTED", "reasonCode": null, "source": "API", "actorType": "API_KEY", "evidenceStrength": "NONE", "occurredAt": null, "recordedAt": "2026-01-02T09:00:00.000Z" }
],
"timelineTruncated": false,
"childrenTruncated": false,
"storeId": "00000000-0000-0000-0000-000000000101",
"registerId": "00000000-0000-0000-0000-000000000201"
}
}Örnekte data alanı gösterilmiştir ve ödeme nesneleri kısaltılmıştır.
| Alan | Tip | Açıklama |
|---|---|---|
requestedPaymentId | string | İstekte verdiğiniz kimlik. |
root | object | Kök ödeme; kalemleri (items) dahil. |
children | array | Ters işlemler, eskiden yeniye, en çok 50; kalem bazlı iadelerin refundItems dizisi dahil. |
childrenTruncated | boolean | 50'den fazla ters işlem varsa true. |
timeline | array | Ödeme ve cihaz komutu olayları, eskiden yeniye. En çok 500 satır; daha fazlası varsa en yeni 500 satır döner. |
timelineTruncated | boolean | Zaman çizelgesi kısaltıldıysa true. |
storeId, registerId | string | null | Ödeme anında cihazın mağazası ve kasası. |
Zaman çizelgesi satırı:
| Alan | Tip | Açıklama |
|---|---|---|
kind | string | PAYMENT (ödeme olayı), COMMAND (cihaz komutu olayı) ya da FISCAL_DOCUMENT (mali belge olayı). |
paymentId | string | Olayın ödemesi. |
commandId | string | null | Olayla ilişkili cihaz komutunun kimliği. |
commandType | string | null | Komut olayında komutun türü; ödeme olayında null. |
seq | integer | Olayın kendi kaydındaki sıra numarası. |
eventType | string | Olayın türü (ör. STATUS_CHANGED). Değer kümesi açıktır. |
fromStatus, toStatus | string | null | Durum değiştiren olayda önceki ve yeni durum. |
reasonCode | string | null | Olayın sebebi. Değer kümesi açıktır; ör. DEVICE_QUERY_ANSWER_REJECTED: cihazın sonuç sorgusuna verdiği cevap doğrulanamadı ve yok sayıldı (evidenceStrength: "ADVISORY", ödeme değişmez). |
source | string | Olayın kaynağı (ör. API, DEVICE, USER, SYSTEM). |
actorType | string | Olayı tetikleyen tarafın türü: USER, API_KEY, DEVICE, OPERATOR ya da SYSTEM. |
evidenceStrength | string | Sonuç kanıtının gücü: DEFINITIVE, ADVISORY ya da NONE. |
occurredAt | string | null | Olayın kaynağında gerçekleştiği an (cihaz bildirdiyse). |
recordedAt | string | Olayın kaydedildiği an. |
Olmayan, başka organizasyona ait ya da diğer ortamdaki işlem 404 physical_pos.payment.not_found alır.
Hatalar
| HTTP | code | Ne zaman |
|---|---|---|
400 | physical_pos.validation.invalid | limit aralık dışı (details.field: limit). |
400 | physical_pos.cursor.invalid | Bozuk imleç; ilk sayfadan yeniden başlayın. |
400 | physical_pos.input.filter_invalid | Geçersiz süzgeç; details.field, gerekirse details.reason (range_invalid, too_long, invalid). |
400 | physical_pos.payment.card_data_rejected | Sorgu parametresinin adı ya da merchantReference değeri kart verisine benziyor. |
400 | physical_pos.input.environment_invalid | İstekte environment. |
400 | VALIDATION_ERROR | Tanımlanmamış sorgu parametresi. |
404 | physical_pos.payment.not_found | İşlem bulunamadı. |
500 | physical_pos.gateway.response_invalid | Beklenmeyen yanıt; geri çekilerek yeniden deneyin. |
Sağlayıcı raporu ve tarama kapsamı
GET /api/v1/physical-pos/provider-transactions mevcut rapor satırlarını döndürür; bu uç yeni ödeme başlatmaz. Yetki physical_pos:view; kiracı/ortam imzalı anahtardan gelir. Panel karşılığı /api/panel/v1/physical-pos/provider-transactions aynı sonucu merchant oturumuyla okur.
Liste süzgeçleri: limit (1–100, varsayılan 25), cursor, businessDateFrom, businessDateTo (sağlayıcının rapor iş günü YYYY-MM-DD; varsayılan son 7 gün İstanbul bugünüyle hesaplanır; pencere en çok 93 gün), unmatched (yalnız Lunixi dışı satırlar) ve includeSandbox (varsayılan false). Tarih penceresi listeye aittir; sunucunun geçmiş tarama sınırı değildir. items ve pageInfo yanında eklemeli reportCoverage döner:
{
"items": [],
"pageInfo": { "hasMore": false, "nextCursor": null },
"reportCoverage": {
"status": "PENDING",
"trackedScopes": 2,
"pendingDays": 8,
"waitingFinalityDays": 1,
"targetBusinessDate": "2026-11-05",
"completedThrough": "2026-10-15",
"oldestPendingDate": "2026-10-16"
}
}Sentetik örnektir. reportCoverage, liste sayfası/tarih/unmatched süzgecinden bağımsız bütün takip kapsamlarına aittir; includeSandbox seçimini korur.
| Alan | Anlam |
|---|---|
status | UNAVAILABLE: henüz kapsam yok. PENDING: uygun geçmişte tamamlanmamış veya henüz planlanmamış gün var. CURRENT: hedefe kadar planlanmış bütün uygun rapor günleri tamamlandı. |
trackedScopes | organization/environment + hesap + merchant kapsamı sayısı. |
pendingDays | Kuyruğa girmiş ve kesinlik süresi dolmuş açık günler; henüz planlanmamış günleri saymaz. Sıfır olması tek başına CURRENT demek değildir. |
waitingFinalityDays | Henüz kesinlik süresi dolmadığı için bekleyen günler. |
targetBusinessDate | Kapanmış ve kesinlik süresi dolmuş UTC hedef tarihi; varsayılan 24 saat ile bugün eksi 2 gün. |
completedThrough | İlgili kapsamlarda kanıtlanmış kesintisiz tamamlanma sınırı; kanıt yoksa null. Plan cursor'ı değildir. |
oldestPendingDate | En eski açık veya henüz planlanmamış uygun gün; yoksa null. |
Eski backend henüz bu alanı sağlamıyorsa reportCoverage: null gelir; CURRENT varsaymayın. CURRENT bir sağlayıcı finansal tamlık/retention garantisi değildir. COMPLETE günlerin sürekli yeniden denetimi, kesin gün içi aktivasyon sınırı, üretici saat dilimi/retention teyidi ve gerçek SDK kabulü açık kalır. Bu ek alan kaynak dalında doğrulanmıştır; prod yayını ayrıca bildirilir.
Panelde sağlayıcı raporlarını izleme
Fiziksel POS → Raporlar → Sağlayıcı raporları sekmesi yalnız physical_pos:view yetkisiyle açılır. Yalnız physical_pos:payments yetkisi satış/vergi özetine erişebilir; sağlayıcı raporuna erişim sağlamaz.
- Üstte taramanın hedefi, kesintisiz tamamlanan tarih, takip kapsamı, açık ve kesinleşmesi beklenen günler gösterilir. Bu tarihler UTC tarama takvimidir. Alttaki liste süzgeci sağlayıcının rapor iş günü değerini aynen gönderir; ISO saate çevrilmez. Varsayılan liste penceresi sunucudaki gibi İstanbul bugünüyle hesaplanır.
- Tarama bilgisi, sekme açıkken listeden ayrı yenilenir. Tarih/sayfa veya “Yalnız Lunixi dışı işlemler” seçimi genel tarama durumunu daraltmaz. “Deneme kayıtlarını da göster” seçimi hem listeyi hem kapsamı canlı + sandbox olarak genişletir; varsayılan yalnız canlıdır.
- Son başarılı panel okuma zamanı gösterilir. Yenileme sürerken, bağlantı hatasında veya bilgi eskidiğinde önceki
CURRENTsonucu güncel başarı olarak sunulmaz. Alanı sağlamayan eski sunucu veya tutarsız sayaç/tarih bilinmeyen durum olarak görünür. Boş liste ve sıfır açık gün, eksiksiz tarama kanıtı değildir. - Satır kimliği, sağlayıcı işlem kimliği ve bağlı Lunixi ödeme kimliği ayrıdır. Tutarlar en küçük birim metninden kayıpsız gösterilir.
CANDIDATEyalnız eşleştirme ipucudur;MISMATCHuyuşmazlığı gösterir.EXTERNALsatırı yeni Lunixi ödemesi veya tahsilat oluşturmaz. Bağlı ödeme varsa ayrıntısı ayrıca açılabilir.
Yenile yalnız paneldeki okumaları yeniler; yeni tarama işi veya ödeme başlatmaz. Kaynak kod teslimi, panelin ya da sunucunun canlı yayınının doğrulaması değildir.