Kalem Bazlı İade
- 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: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.
Ü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:
| Alan | Tip | Zorunlu | Açıklama |
|---|---|---|---|
lineNo | integer | Evet | Satıştaki satırın numarası. |
quantityMilli | integer | Evet | İade edilecek miktar × 1000. |
amountMinor | string | Hayır | Satı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
amountMinoralanı isteğe bağlıdır; gönderirseniz hesaplanan toplamla aynı olmalıdır, aksi400 physical_pos.payment.amount_invalid(details.reason:item_amount_mismatch,details.expectedMinor). - Kısmi adette satır tutarı
quantityMilli × unitPriceMinor / 1000yarı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üşersequantity_too_smalldö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
SALEolmalı (aksi422 … item_refund_root_not_sale), kalemli olmalı (aksiitem_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_remainingalır.
İade kalemleri: refundItems
Kalem bazlı iadenin çocuk ödemesi okunduğunda refundItems dizisi döner:
| Alan | Tip | Açıklama |
|---|---|---|
lineNo | integer | Satıştaki satır numarası. |
name, unitCode, unitPriceMinor, taxGroupCode | Satış satırının değerleri. | |
quantityMilli | integer | İade edilen miktar × 1000. |
amountMinor | string | Satırın iade tutarı. |
netMinor | string | İade tutarının vergiler hariç kısmı. |
taxes | array | { taxType, baseMinor, amountMinor }: iade edilen vergi dökümü. |
Kalem iade durumu: refundStatus
NONE,PARTIALveFULLdeğ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
refundStatusNONEkalabilir. - Paranın gerçek durumu köktedir:
reversedMinorvereversalStatusalanlarına bakın. - Sonuçlanmamış kalem iadesi
reservedQuantityMillivereservedMinoralanları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
reversedMinoralanı bankanın onayladığı tutarı gösterir ve çocuk ödemedeoutcomeConflict: trueolur.
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.reason | Anlamı |
|---|---|
invalid | items dizi değil ya da satırlardan biri nesne değil. |
empty | items boş dizi. |
too_many | 500'den fazla satır. |
line_no_invalid | Satır numarası geçersiz. |
line_duplicate | Aynı satır iki kez gönderildi. |
line_not_found | Satışta bu numaralı satır yok. |
quantity_invalid | Miktar 0 ya da geçersiz. |
quantity_exceeds_remaining | Miktar, satırın iade edilebilir kalan miktarını aşıyor; details.remainingQuantityMilli. |
quantity_too_small | Miktarın tutarı 0'a düşüyor; kalan miktarın tamamını iade edin (details.remainingQuantityMilli). |
amount_invalid | Satırın amountMinor değeri geçersiz. |
amount_mismatch | Satı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ı.