İptal ve Prim İadesi

Poliçe iptali ile prim iadesi ayrı işlemlerdir:

İşlem	Uç	Ne yapar
Poliçe iptali	`POST /api/v1/insurance/orders/{orderId}/cancel`	Kesilmiş poliçeler için sağlayıcıda iptal talebi açar. Primi iade etmez.
Prim iadesi	`POST /api/v1/insurance/orders/{orderId}/refund-premium`	Primi alıcıya iade eder ya da Lunixi dışında yaptığınız iadeyi kaydeder.

Yürürlükteki bir poliçenin primini iade etmek için önce poliçeyi iptal edin, ardından primi iade edin. Böylece alıcı primsiz sigortalı kalmaz.

İki uçta da Idempotency-Key zorunludur. Kimlik doğrulama ve imzalama: Akışlar › Kimlik doğrulama.

Poliçe iptali

POST /api/v1/insurance/orders/{orderId}/cancel gövde almaz.

Siparişin poliçe durumu ISSUED ya da PARTIALLY_ISSUED olmalıdır. Kesilmiş her poliçe için sağlayıcıda iptal talebi açılır.
Poliçe hiç kesilmediyse iptal edilecek poliçe yoktur: 409 insurance.order.state_conflict (reason: policy_not_issued). Kesilmeyen poliçenin primini prim iadesiyle iade edin.
İptal zaten istenmiş ya da sonuçlanmışsa sipariş olduğu gibi döner.

source lunixi-sign.sh
REQ_PATH="/api/v1/insurance/orders/<orderId>/cancel"
lunixi_sign POST "$REQ_PATH"
 
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "Idempotency-Key: cancel-order-1001" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

Sonuç sonradan kesinleşir

Sağlayıcı iptal talebini kendi sürecinde işler; sonuç hemen dönmez.

Sağlayıcı kendi sürecinde karar verir; sonucu sipariş ucundan, poliçe bazında policies[].policyStatus alanından izleyin.

An	Siparişin poliçe durumu
Yanıt	`CANCEL_PENDING`: iptal istendi, sonuç bekleniyor.
Sağlayıcı bütün poliçeleri iptal etti	`CANCELLED`
Sağlayıcı iptali reddetti	Poliçe yürürlükte kalır: `ISSUED` ya da `PARTIALLY_ISSUED`. `errorCode` `insurance.policy.cancel_failed` olur.

Sonucu sipariş ucundan izleyin. Poliçe başına durum policies[].policyStatus alanındadır. İptal bekleyen poliçenin belgesi alınabilir; iptal edilen poliçenin belgesi alınamaz.

Prim iadesi

POST /api/v1/insurance/orders/{orderId}/refund-premium primi tahsil edilmiş siparişin primini iade eder.

Poliçe durumu	Sonuç
`FAILED_FINAL`, `CANCEL_PENDING`, `CANCELLED`	İade başlar.
`NOT_REQUESTED`	İade başlar. Sağlayıcıdaki adımlar (ör. ödeme bildiriminin iletilmesi) henüz sürüyorsa `409`, `reason: policy_in_progress`; bir süre sonra tekrar deneyin.
`ISSUED`, `PARTIALLY_ISSUED`	`409`, `reason: policy_active`. Önce poliçeyi iptal edin.
`PENDING`, `UNKNOWN`, `FAILED_RETRYABLE`	`409`, `reason: policy_in_progress`. Poliçenin kesin sonucunu bekleyin.

Prim tahsil edilmemişse iade edilecek prim yoktur: 412 insurance.premium.not_captured.
İade sürüyor ya da tamamlanmışsa sipariş olduğu gibi döner.
İade başladıktan sonra poliçe istenemez. İade başladıktan sonra poliçe yine de kesilirse iade geri alınmaz; poliçe için otomatik olarak iptal istenir. Bkz. Kavramlar › İade gerekiyor.

Lunixi ödemesindeki prim

Prim bir Lunixi ödemesinde tahsil edildiyse gövde göndermeyin. Prim tutarı kadar kısmi iade o ödemeden yapılır.

An	İade durumu
Yanıt	`PENDING`: iade başlatıldı.
İade tamamlandı	`REFUNDED`; `refundedAt` dolar.
İade reddedildi	`FAILED`; `refundErrorCode` `insurance.refund.rejected` olur. İadeyi yeniden başlatabilirsiniz.

Bu siparişte externalRefund gönderirseniz istek 422 insurance.validation.invalid (field: externalRefund, reason: not_allowed) döner.

Lunixi dışında iade

Primi Lunixi dışında tahsil ettiyseniz (confirm-payment) iadeyi de kendi kanalınızdan yaparsınız ve API'ye bildirirsiniz. externalRefund zorunludur.

Alan	Tip	Zorunlu	Açıklama
`externalRefund.externalRefundId`	string	Evet	Sizin tarafınızdaki iade kimliği; 1-128 yazdırılabilir ASCII karakter.
`externalRefund.refundedAt`	string	Evet	İade anı. ISO 8601, saat dilimi zorunlu; gelecekte ve ödeme anından önce olamaz.

{
  "externalRefund": {
    "externalRefundId": "refund-1001",
    "refundedAt": "2025-12-21T09:00:00+03:00"
  }
}

Yanıtta iade durumu REFUNDED olur.
Aynı externalRefundId ile tekrar siparişi olduğu gibi döner. Tamamlanmış iadeye farklı bir kimlik gönderirseniz 409 (reason: already_refunded) döner.

İade gerekiyor

Prim tahsil edildiği hâlde poliçe kesin olarak kesilemediyse siparişte:

poliçe FAILED_FINAL,
iade REQUIRED,
genel durum FAILED olur ve errorCode hatanın Lunixi kodunu taşır.

Bu durumda primin alıcıya iade edilmesi gerekir. Primi prim iadesi ucuyla iade edin. Siparişlerinizin refundStatus alanını sipariş ucundan izleyin.

Hatalar

HTTP	`code`	Ne yapmalı
`404`	`insurance.order.not_found`	Sipariş bulunamadı.
`409`	`insurance.order.state_conflict`	`details.reason` alanına bakın: `policy_not_issued`, `policy_active`, `policy_in_progress`, `already_refunded`, `collected_by_provider`.
`412`	`insurance.premium.not_captured`	Prim tahsil edilmemiş; iade edilecek prim yok.
`412`	`insurance.provider.not_integrated`	Bağlantınızdaki sağlayıcıda iptal şu anda kullanılamıyor.
`422`	`insurance.validation.invalid`	`externalRefund` alanlarını düzeltin; `details.errors[]` ihlalleri listeler.

Ortak kodlar: Akışlar › Yanıt ve hatalar.

İlgili

Prim ve Ödeme: primin tahsilatı
Kavramlar ve Durumlar: poliçe ve iade eksenleri

Poliçe Belgesi Hasar Kaydı