Yalnız Sigorta Entegrasyonu

Ödemelerinizi Lunixi dışında alıyorsanız ya da yalnızca sigorta satmak istiyorsanız sigortayı tek başına, API ile entegre edersiniz. Bu entegrasyonda Lunixi'de ödeme oluşturmazsınız; Lunixi teklif, sipariş, poliçe, belge, iptal ve webhook altyapısını sağlar.

Bu sayfa entegrasyonun bütün adımlarını sırayla verir. Her adımın alanları ve kuralları bağlantı verilen uç sayfasındadır.

Başlamadan önce

• Hesabınızda sigorta ürünü açık olmalıdır. Ödeme ürünü gerekmez; sigorta uçları yalnızca sigorta ürününü arar.
• API anahtarınızın sigorta ürününe erişimi olmalıdır. Anahtarınızda sigorta ürünü yoksa her istek 403 PRODUCT_NOT_ENABLED döner.
• Sağlayıcınızı panelden bağlayın. Panelde POS Merkezi > Sigorta sayfasında anlaştığınız sağlayıcının bağlantısını ekleyin, sunacağınız ürünü açın ve Primi kim tahsil ediyor sorusunu anlaşmanıza göre yanıtlayın: Sağlayıcı Bağlantısı.
• Sigortayı açın ve sunacağınız tipi seçin. Panelin sol menüsündeki Sigorta ürününde, Genel ekranında Sigorta açık ayarını açın ve API — harici tahsilat kullanım modunu seçin; Sigorta Tipleri ekranında sunacağınız tipi açıp kaydedin. Sigorta kapalıysa, API modu seçili değilse ya da tip kapalıysa sigorta sunulmaz: Sigorta Menüsü › Genel.
• Webhook endpoint'inizi oluşturun. Sigorta olayları için productCode: INSURANCE_SERVICE ile bir endpoint oluşturun: Webhook Olayları › Abonelik.
• Önce test edin. Test anahtarınızla ve Test ortamındaki bağlantınızla deneyin: Test Ortamı.

Akış

1. İstekleri imzalayın

Sigorta uçları API anahtarınızla imzalanmış istek kabul eder: X-Key-Id, X-Date, X-Nonce, gövdeli isteklerde Digest ve X-Signature. Bu sayfadaki örnekler aynı kabuk yardımcısını (lunixi_sign) kullanır: Akışlar › Kimlik doğrulama.

• Sipariş oluşturan ve siparişin durumunu değiştiren uçlar Idempotency-Key başlığını zorunlu tutar: Akışlar › Idempotency-Key.
• Primi sağlayıcı tahsil ediyorsa kullandığınız /pay ucu, imzaya ek olarak Bearer erişim token'ı ister: Sağlayıcı Tahsilatı › Kimlik doğrulama.

2. Sunulan sigorta tiplerini öğrenin

Alıcıya hangi sigortayı sunabileceğinizi uygunluk ucu söyler. Uç salt okumadır; sağlayıcıya istek göndermez.

• Sigorta bir ürünü koruyorsa (bilet, cihaz, araç gibi) ürünü sepet kalemi olarak gönderin: POST /api/v1/insurance/products, gövdede currency ve context.items. Lunixi'de ödeme oluşturmazsınız; kalemler yalnızca sigortanın neyi koruduğunu belirtir. Kalemin biçimi ve sigorta alanları: Sepet Kalemleri › Sigorta alanları.
• Sigorta bir ürüne bağlı değilse (ferdi kaza gibi) GET /api/v1/insurance/products?currency=TRY çağırın; yanıt sepet kalemi olmadan satılan tipleri döner.

paymentIntentId göndermeyin; bu alan Lunixi ödemesine bağlı akış içindir. Yanıt ve boş listenin anlamı: Uygunluk.

Tip alanlarında kullanılan kodları (ülke, il, ilçe, marka, model, meslek gibi) referans ucundan alın: Sigorta Tipleri ve Şemalar › Referans kodları.

3. Teklif alın

POST /api/v1/insurance/quotes ile alıcının ve sigortalanan şeyin bilgilerini gönderin.

• Sepet kaynağı olarak 2. adımda gönderdiğiniz context.items kalemlerini gönderin. Sepet kalemi olmadan satılan tiplerde ne context.items ne paymentIntentId gönderin: Sepet Kalemi Olmadan Satış.
• Poliçe için gereken alanları da teklif isteğinde gönderin. Poliçe teklifin bilgileriyle kesilir; sipariş ve poliçe isteklerinde alan gönderilmez.
• Yanıt bir ya da daha fazla seçenek döner. Alıcıya her seçeneğin sağlayıcısını, primini, teminat özetini ve şartnamesini gösterin; sigortayı önceden seçili getirmeyin.
• Seçeneğin premiumCollectedBy değeri 5. adımda hangi yolu izleyeceğinizi gösterir.

Alanlar, seçenek nesnesi ve geçerlilik süresi: Teklif. Tipin alanları: Sigorta Tipleri ve Şemalar.

4. Sipariş oluşturun

Alıcı bir seçeneği onaylayınca POST /api/v1/insurance/orders ile sipariş oluşturun. Gövdede seçeneğin quoteId'si ve alıcının onayı (consent) bulunur; Idempotency-Key zorunludur.

• Sipariş oluşturmak sağlayıcıya istek göndermez ve para hareketi yapmaz.
• Yeni siparişte paymentMode NO_PAYMENT, tahsilat NOT_STARTED, poliçe NOT_REQUESTED'dir.
• Siparişi bir Lunixi ödemesine bağlamayın; bind-payment bu entegrasyonda kullanılmaz.

Alanlar ve kurallar: Sipariş ve Ödeme Bağlama › Sipariş oluşturma.

5. Primi tahsil edin

Primi siz tahsil ediyorsanız (MERCHANT)

1. Primi alın. Siparişin premiumAmount tutarını ve currency para birimini kendi ödeme kanalınızdan tahsil edin.
2. Ödemeyi bildirin. POST /api/v1/insurance/orders/{orderId}/confirm-payment ile ödemenin kimliğini, tutarını, para birimini ve zamanını bildirin. Tutar ve para birimi siparişin primiyle aynı olmalıdır; bildirimi seçeneğin süresi dolmadan yapın. Lunixi bildirimi bağlantınız üzerinden sağlayıcınıza iletir. Yanıtta paymentMode EXTERNAL_PAYMENT, tahsilat COLLECTED olur: Lunixi dışında alınan primi bildirme.
3. Poliçeyi isteyin. POST /api/v1/insurance/orders/{orderId}/issue-policy gövdesiz çağrılır. Yanıtta poliçe PENDING olur; poliçe arka planda kesilir: Poliçe isteme.

Primi sağlayıcı tahsil ediyorsa (PROVIDER)

confirm-payment ve issue-policy kullanılmaz. Primi POST /api/v1/insurance/orders/{orderId}/pay ile sağlayıcıya çektirirsiniz; prim çekildiğinde poliçe otomatik olarak istenir.

• Sipariş bir Lunixi ödemesine bağlı olmadığı için /pay bir Lunixi ödemesinin tahsilatını beklemez.
• Ürün primi kartla çekiyorsa (CARD) alıcının kart bilgisini gövdede gönderirsiniz. Ham kart verisini yalnızca PCI-DSS sertifikalı merchant'lar gönderebilir. Kart Lunixi'de saklanmaz.
• Ürün primi sağlayıcının ödeme sayfasında çekiyorsa (HOSTED) kart göndermezsiniz; alıcıyı yanıttaki nextAction.redirectUrl adresine yönlendirir, returnUrl ile kendi sayfanıza döndürürsünüz.

Kimlik, istek, sonuçlar ve hatalar: Sağlayıcı Tahsilatı.

6. Poliçeyi izleyin

Poliçenin sonucunu webhook ile alın; emin olamadığınızda siparişi GET /api/v1/insurance/orders/{orderId} ile okuyun.

Olayları x-lunixi-event-id ile tekilleştirin ve siparişin son durumunu olayın sırasından değil durum eksenlerinden çıkarın: Webhook Olayları. Durum eksenleri: Kavramlar ve Durumlar.

7. Belgeyi alın

Poliçe kesildiğinde belgesini GET /api/v1/insurance/policies/{policyId}/document ile PDF olarak alın. policyId siparişin policies[] dizisindedir; her sigortalanan kalem için ayrı poliçe ve belge vardır.

• Belge Lunixi'de saklanmaz; her istekte sağlayıcıdan alınır. Sağlayıcı o an veremezse 503 insurance.document.unavailable döner; bir süre sonra tekrar deneyin.
• Ürün sunuyorsa prim makbuzunu /receipt, sertifikayı /certificate ucundan alırsınız.

Ayrıntı: Poliçe Belgesi.

8. İptal ve iade

• İptal: POST /api/v1/insurance/orders/{orderId}/cancel kesilmiş poliçeler için sağlayıcıda iptal talebi açar. Sonuç sonradan kesinleşir: yanıtta CANCEL_PENDING, sağlayıcı iptali kesinleştirince insurance.policy.cancelled gelir. İptal primi iade etmez.
• Primi siz tahsil ettiyseniz: iadeyi kendi kanalınızdan yaparsınız ve POST /api/v1/insurance/orders/{orderId}/refund-premium ile externalRefund göndererek bildirirsiniz. Lunixi'de para hareketi olmaz; iade REFUNDED olur ve insurance.refund.completed gelir.
• Primi sağlayıcı tahsil ettiyse: prim iadesi Lunixi üzerinden yapılmaz; refund-premium bu siparişlerde 409 (reason: collected_by_provider) döner. İade sağlayıcınızın iptal sürecindedir.

Yürürlükteki poliçenin primini iade etmeden önce poliçeyi iptal edin. Kurallar: İptal ve Prim İadesi.

9. Mutabakat

Sağlayıcınızla mutabakat için bağlantı bazlı poliçe ve prim raporunu API'den alın: Mutabakat Raporu.

Diğer uçlar

Uçtan uca örnek

Primi sizin tahsil ettiğiniz, iki biletli bir bilet iptal sigortası satışı. Değerler örnektir; açılı parantez içindeki değerlerin yerine kendi değerlerinizi, kişisel alanların yerine alıcınızın bilgilerini yazın. Her istekte gövdeyi boşluksuz JSON olarak gönderin.

source lunixi-sign.sh
BODY='{"currency":"TRY","context":{"items":[{"id":"ticket-1","name":"İzmir-Ankara tren bileti","price":50000,"category1":"bilet","itemType":"VIRTUAL","insuranceCategory":"TICKET","insuranceTypes":["TICKET_CANCELLATION"]},{"id":"ticket-2","name":"İzmir-Ankara tren bileti","price":50000,"category1":"bilet","itemType":"VIRTUAL","insuranceCategory":"TICKET","insuranceTypes":["TICKET_CANCELLATION"]}]}}'
lunixi_sign POST "/api/v1/insurance/products" "$BODY"
 
curl -X POST "https://api-gateway.lunixi.com/api/v1/insurance/products" \
  -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" \
  --data-raw "$BODY"

BODY='<teklif isteği, boşluksuz JSON>'
lunixi_sign POST "/api/v1/insurance/quotes" "$BODY"
 
curl -X POST "https://api-gateway.lunixi.com/api/v1/insurance/quotes" \
  -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" \
  --data-raw "$BODY"

BODY='{"quoteId":"<quoteId>","merchantOrderId":"order-1001","consent":{"termsVersion":"<terms.version>","termsSha256":"<terms.sha256>","acceptedAt":"<alıcının onay anı, ISO 8601>"}}'
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"

REQ_PATH="/api/v1/insurance/orders/<orderId>/confirm-payment"
BODY='{"payment":{"externalPaymentId":"pay-1001","paidAmount":3980,"paidCurrency":"TRY","paidAt":"<ödeme anı, ISO 8601>"}}'
lunixi_sign POST "$REQ_PATH" "$BODY"
 
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: insurance-confirm-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"

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

REQ_PATH="/api/v1/insurance/policies/<policyId>/document"
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" \
  -o police.pdf

Alıcı sonradan vazgeçerse poliçeyi cancel ile iptal edin, insurance.policy.cancelled geldikten sonra primi kendi kanalınızdan iade edip refund-premium ile bildirin: İptal ve Prim İadesi.

Sık karşılaşılan hatalar

Bütün kodlar: Hata Kodları.

İlgili

• Uç Referansı: bütün sigorta uçları
• Kavramlar ve Durumlar: sipariş durum eksenleri
• Webhook Olayları: insurance.* olayları
• Test Ortamı: test bağlantısı ve test anahtarı