Webhook Olayları

Sigorta siparişlerinizin sonucu değiştiğinde Lunixi endpoint'inize insurance.* olaylarını gönderir: poliçe kesildi, kesilemedi, belgesi hazır, iptal edildi, prim iadesi gerekiyor ya da tamamlandı; hasar kaydı sağlayıcıya iletildi ya da iletilemedi; talep sağlayıcıya iletildi. Olaylar Checkout Form yolunda da API yolunda da aynıdır.

Teslimat, imza doğrulama ve yeniden deneme bütün ürünlerde aynıdır: Webhook'lar.

Olaylar

insurance.policy.issued

Siparişin poliçeleri kesildiğinde gönderilir. data.policyStatus ISSUED olur; poliçe numaraları data.policies[].policyNumber alanındadır.

Belge bu anda henüz hazır olmayabilir (documentStatus: PENDING). Belge hazır olduğunda ayrıca insurance.policy.document_ready gelir.

Poliçe sonucu gecikmeli kesinleşebilir. Bir sipariş için önce insurance.policy.failed (ve insurance.refund.required) geldiyse ve iade henüz başlamadıysa, poliçe sonradan kesildiğinde insurance.policy.issued da gelir. Bu durumda data.refundStatus NONE olur; prim iadesi artık gerekmez.

insurance.policy.failed

Üç durumda gönderilir:

Prim tahsil edildiyse aynı anda insurance.refund.required da gönderilir.

insurance.refund.required

Prim tahsil edildiği hâlde poliçe kesin olarak kesilemediğinde gönderilir. Siparişte poliçe FAILED_FINAL, iade REQUIRED olur. errorCode poliçenin neden kesilemediğini gösterir.

Olayı aldığınızda siparişi sipariş ucundan okuyun:

• refundStatus PENDING ya da REFUNDED ise iade başlamıştır; tamamlandığında insurance.refund.completed gelir.
• refundStatus REQUIRED ise primi prim iadesi ucuyla iade edin. Primi Lunixi dışında tahsil ettiyseniz iadeyi kendi kanalınızdan yapıp aynı uçla bildirin.

Prim iadesi isteği tekrarlanabilir: iade zaten başladıysa sipariş olduğu gibi döner.

insurance.policy.document_ready

Siparişin kesilen poliçelerinin belgesi sağlayıcıda doğrulandığında gönderilir. data.documentStatus AVAILABLE olur.

Belgeyi data.policies[].documentUrl adresinden indirin. Bu adres Poliçe Belgesi ucudur; isteği diğer API istekleriniz gibi API anahtarınızla imzalarsınız. Adres tek başına yetki taşımaz ve belge Lunixi'de saklanmaz.

insurance.policy.cancelled

Sağlayıcı siparişin bütün poliçelerinin iptalini kesinleştirdiğinde gönderilir. data.policyStatus CANCELLED olur. İptal edilen poliçenin belgesi alınamaz; documentUrl boş metin olur.

Poliçe iptali primi iade etmez. Prim iadesi ayrı bir iştir ve tamamlandığında insurance.refund.completed gelir. Bkz. İptal ve Prim İadesi.

insurance.refund.completed

Prim iadesi tamamlandığında gönderilir. data.refundStatus REFUNDED olur.

• Prim Lunixi ödemesinde tahsil edildiyse olay, iade ödemeden yapıldığında gelir.
• Primi Lunixi dışında tahsil ettiyseniz olay, iadeyi prim iadesi ucuyla bildirdiğinizde gelir.

insurance.claim.submitted

Bir hasar kaydı sağlayıcıya ulaştığında ve sağlayıcı kaydı aldığında gönderilir. Kayıt data.claim alanındadır; data.claim.status SUBMITTED olur. Sağlayıcının hasar belgesini hasar belgesi ucundan alabilirsiniz.

Olay hasarın değerlendirme sonucunu taşımaz; değerlendirme sigorta şirketindedir.

insurance.claim.failed

Hasar kaydı sağlayıcı tarafından kabul edilmediğinde ya da sağlayıcıya ulaşmadığında gönderilir. data.claim.status FAILED olur; sebep data.claim.errorCode alanındadır:

Gerekirse aynı poliçe için yeni bir hasar kaydı açabilirsiniz: Hasar Kaydı.

insurance.lead.submitted

Bir talep sağlayıcıya ulaştığında ve sağlayıcı talebi aldığında gönderilir. Talep data.lead alanındadır; data.lead.status SUBMITTED olur. Talep bir siparişe bağlı olmadığı için bu olayın data alanı sipariş alanlarını taşımaz: Talep olayının yükü.

Olay, sağlayıcının talepten sonraki adımlarını (alıcıyla iletişim, teklif) taşımaz.

Olay gönderilmeyen durumlar

Aşağıdaki durumlar için olay gönderilmez. Bunları sipariş ucundan izleyin:

Teslimatın yapısı

Teslimatın gövdesi bir zarftır; siparişin alanları data altındadır.

Zarf

Zarfta bu tabloda olmayan alanlar da bulunabilir; kodunuzu yalnızca burada belgelenen alanlara dayandırın.

data

data, olayın anlattığı geçişten sonraki sipariş durumunu taşır. Talep olayının data alanı farklıdır: Talep olayının yükü.

Durum eksenlerinin değerleri: Kavramlar › Sipariş durumları.

policies[]:

claim (yalnızca insurance.claim.* olaylarında):

Hasar kaydı olaylarında siparişin diğer alanları olayın anındaki sipariş durumunu taşır. Belge ve sağlayıcının hasar referansı yüke girmez.

Talep olayının yükü

insurance.lead.submitted olayının data alanı yalnızca şu alanları taşır:

lead:

Talebin gövdesi, not ve kişisel veriler, sağlayıcının adı ve talep referansı yüke girmez. Talebin maskeli görüntüsü için okuma ucunu kullanın.

Webhook'ta değeri olmayan alanlar null olarak gelir; alan yine de gövdede bulunur. Kişisel veri ve sağlayıcının kendi referansları yüke girmez.

Abonelik

Olayları almak için sigorta ürünü için bir webhook endpoint'i oluşturun:

curl -X POST "https://api-gateway.lunixi.com/api/v1/organizations/$ORG_ID/webhook-endpoints" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sigorta olayları — test",
    "url": "https://merchant.example.com/webhooks/lunixi",
    "productCode": "INSURANCE_SERVICE",
    "environment": "TEST",
    "secretRef": "vault:<secretId>",
    "eventTypes": ["insurance.*"]
  }'

Endpoint oluşturma, imza secret'ı ve teslimat geçmişi: Webhook Kurulumu.

İmza, yeniden deneme ve tekilleştirme

İmzayı her teslimatta doğrulayın; imza biçimi ve yeniden deneme politikası bütün ürünlerde aynıdır: Webhook'lar.

• Teslimat en az bir kez yapılır. Aynı olay birden çok kez gelebilir. Olayı x-lunixi-event-id ile idempotent işleyin. Aynı olay her teslimatta aynı kimliği taşır; bu değer data.eventId ile de aynıdır.
• Sıraya güvenmeyin. Yeniden denenen bir teslimat, sonraki bir olaydan sonra gelebilir. Siparişin son durumunu olayın sırasından değil, data içindeki durum eksenlerinden çıkarın. Emin olamadığınızda siparişi sipariş ucundan okuyun.
• Olaya hızlı yanıt verin. İmzayı doğrulayın, olayı kendi kuyruğunuza yazın ve 2xx dönün. Belge indirme gibi işleri yanıttan sonra yapın.

Webhook'u sipariş ucuyla birlikte kullanma

Webhook, siparişin sonucunu hızlı öğrenmenin yoludur; tek kaynak değildir. Endpoint'iniz bir süre erişilemezse ya da durum olay gönderilmeyen bir yoldan değiştiyse (yukarıdaki tablo), siparişi sipariş ucundan okuyun. Webhook'tan gelen data.insuranceOrderId sipariş ucundaki orderId ile aynıdır.

İlgili

• Hata Kodları: errorCode değerlerinin anlamı
• Kavramlar ve Durumlar: durum eksenleri ve genel durum
• Sipariş ve Ödeme Bağlama: sipariş nesnesi