Fiziksel POS
Ödeme İşlemleri
Kalem Bazlı İade

Kalem Bazlı İade

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: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.

Ürün satırlarıyla başlatılmış bir satışta, iade etmek istediğiniz satırları ve adetleri gönderirsiniz; iade tutarı ve vergileri sunucuda hesaplanır.

POST /api/v1/physical-pos/payments/{paymentId}/reversals · physical_pos:payments · Idempotency-Key zorunlu

İstek

Kalemli bir satışın belirli satırlarını, adet üzerinden iade edersiniz. İstek ters işlem ucuna operation: "REFUND" ve items ile gönderilir:

AlanTipZorunluAçıklama
lineNointegerEvetSatıştaki satırın numarası.
quantityMilliintegerEvetİade edilecek miktar × 1000.
amountMinorstringHayırSatırın iade tutarı için teyit. Göndermezseniz sunucu hesaplar; gönderilen değer hesaplanan tutara eşit olmalıdır. Açık null reddedilir.

lineNo 1–500, quantityMilli 1 ya da büyük JSON tam sayı, açıkça gönderilen amountMinor ise kanonik pozitif minor-unit dize olmalıdır; aksi 400 physical_pos.payment.refund_items_invalid (details.field: items.0.quantityMilli gibi noktalı yol; details.reason: line_no_invalid, quantity_invalid ya da amount_invalid; items dizi değilse ya da öğe nesne değilse invalid). Satırda tanımlanmamış bir alan 400 VALIDATION_ERROR alır.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments/01900000-0000-7000-8000-000000000501/reversals"
BODY='{"operation":"REFUND","currency":"TRY","items":[{"lineNo":1,"quantityMilli":1000}]}'
lunixi_sign POST "$REQ_PATH" "$BODY"
 
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: 1c9d3e52-7a40-4b8e-9d61-2e5f7a9c0b13" \
  --data-raw "$BODY"

Örnekte iki çaylık satırdan bir çay iade edilir; çocuk ödemede amountMinor: "1500" olur (sunucu hesapladı).

Tutar hesabı:

  • İade tutarı kalemlerden hesaplanır. Ödemenin amountMinor alanı isteğe bağlıdır; gönderirseniz hesaplanan toplamla aynı olmalıdır, aksi 400 physical_pos.payment.amount_invalid (details.reason: item_amount_mismatch, details.expectedMinor).
  • Kısmi adette satır tutarı quantityMilli × unitPriceMinor / 1000 yarım yukarı yuvarlanarak hesaplanır; kalan adetler için en az bir en küçük para birimi bırakılır. Sonuç 0'a düşerse quantity_too_small döner: kalan adedin tamamını iade edin.
  • Satırın son adetleri iade edildiğinde kalan tutarın tamamı iade edilir; satırın iade toplamı satır toplamına kuruşu kuruşuna eşit olur.
  • Vergiler satırın saklanan dökümünden orantılı hesaplanır; son adette her vergi türünün kalanı iade edilir.

Uygunluk:

  • Kalem bazlı iade, cihaz modelinin kalem bazlı iadeyi desteklemesini gerektirir; desteklenmiyorsa 422 physical_pos.payment.operation_unsupported (details.reason: itemized_unsupported). Satırın bir kısmının iadesi ya da aynı satışta ikinci iade kısmi iade sayılır ve cihaz modelinin kısmi iadeyi de desteklemesini gerektirir (partial_amount_unsupported).
  • Kök bir SALE olmalı (aksi 422 … item_refund_root_not_sale), kalemli olmalı (aksi item_refund_root_without_items) ve tam onaylanmış (APPROVED) olmalıdır. Kısmi onaylanan satışta kalem bazlı iade yapılmaz (item_refund_partially_approved); tutar bazlı iade yapın.
  • Kalem bazlı ve tutar bazlı iade aynı satışta birlikte kullanılabilir. Tutar bazlı iade kalemlerin iade edilebilir adedini azaltmaz; ama satışın iade edilebilir toplam tutarı her iadede denetlenir. Örneğin 4500 kuruşluk satışta önce 4000 kuruş tutar bazlı iade yapıldıysa, çay satırının tamamını iade etmek 400 physical_pos.payment.refund_exceeds_remaining alır.

İade kalemleri: refundItems

Kalem bazlı iadenin çocuk ödemesi okunduğunda refundItems dizisi döner:

AlanTipAçıklama
lineNointegerSatıştaki satır numarası.
name, unitCode, unitPriceMinor, taxGroupCodeSatış satırının değerleri.
quantityMilliintegerİade edilen miktar × 1000.
amountMinorstringSatırın iade tutarı.
netMinorstringİade tutarının vergiler hariç kısmı.
taxesarray{ taxType, baseMinor, amountMinor }: iade edilen vergi dökümü.

Kalem iade durumu: refundStatus

  • NONE, PARTIAL ve FULL değerleri yalnız onaylanmış kalem bazlı iadeleri yansıtır: PARTIAL, iade edilen miktar 0'dan büyük ve satış miktarından küçük; FULL, satırın tamamı iade edildi.
  • Void ve tutar bazlı iade kalem durumunu değiştirmez. Void edilmiş ya da tutar bazlı iadeyle tamamen iade edilmiş satışta refundStatus NONE kalabilir.
  • Paranın gerçek durumu köktedir: reversedMinor ve reversalStatus alanlarına bakın.
  • Sonuçlanmamış kalem iadesi reservedQuantityMilli ve reservedMinor alanlarında görünür.
  • Banka kalem bazlı iadede istenenden farklı tutar onaylarsa kalemler ayrıldıkları gibi iade edilmiş sayılır; kökün reversedMinor alanı bankanın onayladığı tutarı gösterir ve çocuk ödemede outcomeConflict: true olur.

Hatalar

400 physical_pos.payment.refund_items_invalid (iade kalemleri). details.field istekteki alanın yolunu verir (items[0].quantityMilli gibi; listenin bütünü için items; istek alınırken yapılan tür ve sınır denetiminde items.0.quantityMilli gibi noktalı yol).

details.reasonAnlamı
invaliditems dizi değil ya da satırlardan biri nesne değil.
emptyitems boş dizi.
too_many500'den fazla satır.
line_no_invalidSatır numarası geçersiz.
line_duplicateAynı satır iki kez gönderildi.
line_not_foundSatışta bu numaralı satır yok.
quantity_invalidMiktar 0 ya da geçersiz.
quantity_exceeds_remainingMiktar, satırın iade edilebilir kalan miktarını aşıyor; details.remainingQuantityMilli.
quantity_too_smallMiktarın tutarı 0'a düşüyor; kalan miktarın tamamını iade edin (details.remainingQuantityMilli).
amount_invalidSatırın amountMinor değeri geçersiz.
amount_mismatchSatırın amountMinor değeri hesaplanan tutardan farklı; details.expectedMinor.

Bütün ters işlem kuralları, cihaz ve banka seçimi ve hata sebepleri: Ters İşlem Kuralları.