Sipariş ve Ödeme Bağlama

Sipariş, alıcının onayladığı teklif seçeneğinin satın alınmasıdır. Prim tahsilatı, poliçe, iade ve belge süreçleri sipariş üzerinden izlenir. Siparişin durum eksenleri ve genel durumu: Kavramlar ve Durumlar › Sipariş durumları.

Kimlik doğrulama, Idempotency-Key ve hata zarfı: Akışlar.

Sipariş oluşturma: POST /api/v1/insurance/orders

Idempotency-Key zorunludur. Sipariş oluşturmak sağlayıcıya istek göndermez ve para hareketi yapmaz; seçeneği ve alıcının onayını kaydeder.

Onay

• consent, alıcının seçeneğin şartlarını kabul ettiğini ve bilgilerinin sigorta işlemi için sağlayıcıyla paylaşılmasına onay verdiğini kaydeder.
• Şartname değerleri seçeneğinkiyle aynı olmalıdır. Başka bir seçeneğin ya da eski bir teklifin şartnamesi onaylanmış sayılmaz: istek 422 insurance.validation.invalid (field: consent.termsSha256, reason: terms_mismatch) döner.
• acceptedAt sunucu saatinin en fazla birkaç dakika ilerisinde olabilir; daha ilerideki bir zaman reddedilir.

Kurallar

• Seçenek geçerli olmalıdır: süresi dolan seçenek 409 insurance.quote.expired döner.
• Bir seçenekle yalnızca bir sipariş oluşturulur. İkinci sipariş 409 insurance.order.state_conflict (reason: quote_already_ordered) döner.
• Yalnızca API'den aldığınız teklifler siparişe dönüştürülebilir.

{
  "quoteId": "insq_<32 onaltılık hane>",
  "merchantOrderId": "order-1001",
  "consent": {
    "termsVersion": "<seçeneğin terms.version değeri>",
    "termsSha256": "<seçeneğin terms.sha256 değeri>",
    "acceptedAt": "2025-12-20T10:15:00+03:00"
  }
}

source lunixi-sign.sh
BODY='<sipariş isteği, boşluksuz JSON>'
lunixi_sign POST "/api/v1/insurance/orders" "$BODY"
 
curl -X POST "https://api-gateway.lunixi.com/api/v1/insurance/orders" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: insurance-order-1001" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  --data-raw "$BODY"

Başarılı istek 201 ve data içinde sipariş nesnesini döner. Yeni siparişte paymentMode NO_PAYMENT, tahsilat NOT_STARTED, poliçe NOT_REQUESTED'dir.

Sonraki adım primin tahsilatıdır: Prim ve Ödeme.

Sipariş nesnesi

policies[]:

Poliçeler, prim tahsil edildikten sonra kalem başına oluşur. Yeni siparişte policies boş bir dizidir.

Listeleme: GET /api/v1/insurance/orders

Siparişlerinizi en yeniden eskiye, cursor tabanlı sayfalar hâlinde döner. Checkout Form'da oluşan siparişler de listede yer alır (surface: CHECKOUT_FORM).

Yanıtta siparişler data.items dizisindedir; sayfalama bilgisi pageInfo alanındadır. Bozuk bir cursor 422 insurance.validation.invalid (field: cursor) döner.

source lunixi-sign.sh
REQ_PATH="/api/v1/insurance/orders?limit=25&merchantOrderId=order-1001"
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"

Okuma: GET /api/v1/insurance/orders/{orderId}

Tek bir siparişi döner; data sipariş nesnesidir. Siparişin poliçe ve belge durumunu bu uçla izlersiniz. Kimlik bulunamazsa ya da başka bir hesaba aitse 404 insurance.order.not_found döner.

Ödemeye bağlama: POST /api/v1/insurance/orders/{orderId}/bind-payment

Siparişi, primi sepetinde taşıyan Lunixi ödemesine bağlar. Idempotency-Key isteğe bağlıdır.

Bağlama şu sırayla doğrulanır:

1. Sipariş API'den oluşturulmuş, başka bir ödemeye bağlanmamış ve Lunixi dışında ödenmemiş olmalıdır. Tahsilatı başlamış sipariş bağlanmaz.
2. Siparişin seçeneği geçerli olmalıdır (409 insurance.quote.expired).
3. Ödeme sigorta alanlı kalemlerle oluşturulmuş olmalıdır (412 insurance.order.payment_not_recorded).
4. Ödemenin para birimi siparişinkiyle aynı olmalıdır.
5. Ödemenin sigorta alanlı kalemleri teklifteki kalemlerle aynı olmalıdır (409 insurance.quote.stale).
6. Ödemenin sepetinde prim kalemi tam bir kez bulunmalıdır: id sipariş kimliği, itemType VIRTUAL, price prim (409 insurance.order.premium_item_mismatch). Primi sağlayıcı tahsil ediyorsa (premiumCollectedBy: PROVIDER) sepette prim kalemi bulunmaz: Sağlayıcı Tahsilatı.

Aynı ödemeyi yeniden bağlamak siparişi olduğu gibi döner. Başarılı yanıtta paymentMode LUNIXI_PAYMENT olur. Prim kalemi ve ödeme isteği: Prim ve Ödeme › Lunixi ödemesi.

insurance.order.premium_item_mismatch yanıtında details.reason:

Lunixi dışında alınan primi bildirme: POST /api/v1/insurance/orders/{orderId}/confirm-payment

Primi Lunixi dışında tahsil ettiyseniz ödemeyi bildirirsiniz. Lunixi bildirimi bağlantınız üzerinden sağlayıcınıza iletir. Idempotency-Key zorunludur.

• Sipariş Lunixi ödemesine bağlıysa bildirim alınmaz (409 insurance.order.state_conflict, reason: lunixi_payment).
• Siparişin seçeneği geçerli olmalıdır (409 insurance.quote.expired).
• Tutar ya da para birimi tutmazsa 422 insurance.validation.invalid döner (reason: premium_amount_mismatch ya da premium_currency_mismatch).
• Başarılı yanıtta paymentMode EXTERNAL_PAYMENT, tahsilat COLLECTED olur. Aynı externalPaymentId ile tekrar siparişi olduğu gibi döner; farklı bir kimlik 409 (reason: external_payment) döner.

{
  "payment": {
    "externalPaymentId": "pay-1001",
    "paidAmount": 3980,
    "paidCurrency": "TRY",
    "paidAt": "2025-12-20T10:16:00+03:00"
  }
}

Tutar örnektir; paidAmount siparişin premiumAmount değeridir.

Poliçe isteme: POST /api/v1/insurance/orders/{orderId}/issue-policy

Lunixi dışında tahsil edilen primden sonra poliçeyi ister. Gövde gönderilmez. Idempotency-Key zorunludur.

• Prim tahsil edilmemişse 412 insurance.premium.not_captured döner.
• Yanıt isteğin kaydedildiği hâldir: policyStatus PENDING. Poliçe arka planda kesilir; sonucu sipariş ucundan izleyin.
• Poliçe zaten istenmiş ya da sonuçlanmışsa sipariş olduğu gibi döner.
• Primin iadesi başlamışsa poliçe istenemez (409, reason: refund_started).

Lunixi ödemesine bağlı siparişte bu uca gerek yoktur: poliçe, ödeme tahsil edildiğinde otomatik olarak istenir.

Durum çakışması

409 insurance.order.state_conflict, siparişin durumunun işleme izin vermediğini gösterir. Sebep details.reason alanındadır; aynı istekle tekrar denemek sonucu değiştirmez.

İptal, iade ve belge uçlarına özgü sebepler kendi sayfalarındadır.

Hatalar

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

İlgili

• Prim ve Ödeme: prim kalemi ve Lunixi dışında tahsilat
• Poliçe Belgesi: kesilen poliçenin belgesi
• İptal ve Prim İadesi: poliçe iptali ve prim iadesi