Fiziksel POS
API Referansı
İşlemler

İşlemler

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.

İş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öntemYolKapsam
GET/api/v1/physical-pos/transactionsphysical_pos:view ya da physical_pos:payments
GET/api/v1/physical-pos/transactions/ambiguousphysical_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-Key ve 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 parametresiTipAçıklama
limitintegerSayfa başına işlem, 1–100. Varsayılan 25.
cursorstringÖnceki yanıttaki pageInfo.nextCursor.
createdFromstringKö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.
createdTostringÜst sınır, aynı biçim. Varsayılan: şimdi + 5 dakika.
paymentStatusstringKökün durumu. → Durumlar
deviceIdstring (UUID)Kökü yürüten cihaz.
storeIdstring (UUID)Ödeme anında cihazın atandığı mağaza.
registerIdstring (UUID)Ödeme anında cihazın atandığı kasa.
merchantReferencestringKökün referansıyla tam eşleşme.
amountFromMinorstringKökün istenen tutarı için alt sınır (dahil), en küçük birimde, 1 ya da büyük.
amountToMinorstringÜst sınır (dahil).
originstringAPI ya da DEVICE_DIRECT (doğrudan cihazda yapılan satış).
operationstringKökün işlemi: SALE, PREAUTH_OPEN ya da REFUND_UNMATCHED.
  • Zaman penceresi en çok 93 gündür ve createdFrom createdTo'dan önce olmalıdır; aksi 400 physical_pos.input.filter_invalid (details.reason: range_invalid). amountFromMinor amountToMinor'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:

AlanTipAçıklama
rootobjectKök ödeme.
childrenarrayTers işlemler, eskiden yeniye, en çok 50.
childrenTruncatedboolean50'den fazla ters işlem varsa true; tamamı için işlem ayrıntısını okuyun.
itemSummaryobject{ 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.
storeIdstring | nullÖdeme anında cihazın mağazası; atanmamışsa null.
registerIdstring | 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 parametresiTipAçıklama
limitinteger1–100, varsayılan 25.
cursorstringÖnceki yanıttaki pageInfo.nextCursor.
deviceIdstring (UUID)Cihaz.
paymentStatusstringUNKNOWN ya da MANUAL_REVIEW; başka değer 400 physical_pos.input.filter_invalid.
includeTotalbooleantrue 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.

İşlem: kök ödeme ve ters işlemleriKök satış 45000 kuruş onaylanmış; 10000 kuruşluk iade onaylanmış ve reversedMinor alanına yansımış; 5000 kuruşluk iade sürüyor ve tutarı kökte ayrılmış; iade edilebilir kalan 35000 kuruş.Kök · SALEapprovedAmountMinor "45000"reversedMinor "10000"reservedMinor "5000"PARTIALLY_REFUNDEDİade · onaylandı"10000" · APPROVEDrootPaymentId = kökİade · sürüyor"5000" · IN_PROGRESStutar kökte ayrıldıİade edilebilirkalanapproved − reversed45000 − 10000= 35000LEJANTKÖKBİTEN İADEBEKLEYEN İADE
Ters işlemler köke bağlı ayrı ödeme kayıtlarıdır (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.

AlanTipAçıklama
requestedPaymentIdstringİstekte verdiğiniz kimlik.
rootobjectKök ödeme; kalemleri (items) dahil.
childrenarrayTers işlemler, eskiden yeniye, en çok 50; kalem bazlı iadelerin refundItems dizisi dahil.
childrenTruncatedboolean50'den fazla ters işlem varsa true.
timelinearrayÖdeme ve cihaz komutu olayları, eskiden yeniye. En çok 500 satır; daha fazlası varsa en yeni 500 satır döner.
timelineTruncatedbooleanZaman çizelgesi kısaltıldıysa true.
storeId, registerIdstring | nullÖdeme anında cihazın mağazası ve kasası.

Zaman çizelgesi satırı:

AlanTipAçıklama
kindstringPAYMENT (ödeme olayı), COMMAND (cihaz komutu olayı) ya da FISCAL_DOCUMENT (mali belge olayı).
paymentIdstringOlayın ödemesi.
commandIdstring | nullOlayla ilişkili cihaz komutunun kimliği.
commandTypestring | nullKomut olayında komutun türü; ödeme olayında null.
seqintegerOlayın kendi kaydındaki sıra numarası.
eventTypestringOlayın türü (ör. STATUS_CHANGED). Değer kümesi açıktır.
fromStatus, toStatusstring | nullDurum değiştiren olayda önceki ve yeni durum.
reasonCodestring | nullOlayı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).
sourcestringOlayın kaynağı (ör. API, DEVICE, USER, SYSTEM).
actorTypestringOlayı tetikleyen tarafın türü: USER, API_KEY, DEVICE, OPERATOR ya da SYSTEM.
evidenceStrengthstringSonuç kanıtının gücü: DEFINITIVE, ADVISORY ya da NONE.
occurredAtstring | nullOlayın kaynağında gerçekleştiği an (cihaz bildirdiyse).
recordedAtstringOlayı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

HTTPcodeNe zaman
400physical_pos.validation.invalidlimit aralık dışı (details.field: limit).
400physical_pos.cursor.invalidBozuk imleç; ilk sayfadan yeniden başlayın.
400physical_pos.input.filter_invalidGeçersiz süzgeç; details.field, gerekirse details.reason (range_invalid, too_long, invalid).
400physical_pos.payment.card_data_rejectedSorgu parametresinin adı ya da merchantReference değeri kart verisine benziyor.
400physical_pos.input.environment_invalidİstekte environment.
400VALIDATION_ERRORTanımlanmamış sorgu parametresi.
404physical_pos.payment.not_foundİşlem bulunamadı.
500physical_pos.gateway.response_invalidBeklenmeyen 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.

AlanAnlam
statusUNAVAILABLE: 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ı.
trackedScopesorganization/environment + hesap + merchant kapsamı sayısı.
pendingDaysKuyruğ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.
waitingFinalityDaysHenüz kesinlik süresi dolmadığı için bekleyen günler.
targetBusinessDateKapanmış 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.
oldestPendingDateEn 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 CURRENT sonucu 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. CANDIDATE yalnız eşleştirme ipucudur; MISMATCH uyuşmazlığı gösterir. EXTERNAL satı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.