API Yolu

Kendi ödeme formunuzu kullanıyorsanız sigortayı alıcınıza kendi arayüzünüzde sunarsınız. Uygunluğu ve teklifi API'den alır, alıcının seçtiği teklifle sipariş oluşturursunuz. Poliçe, prim tahsil edildikten sonra kesilir.

Lunixi'nin ödeme formunu kullanıyorsanız bu bölüm yerine Checkout Form yolunu kullanın. Ödemeyi Lunixi dışında alıyorsanız adım adım rehber: Yalnız Sigorta Entegrasyonu.

Başlamadan önce

• Sigorta ve API yolu hesabınızda açık olmalıdır. API anahtarınızın sigorta ürününe erişimi olmalıdır. Yalnız sigorta akışında ödeme ürünü gerekmez.
• 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 ve bağlantıda sunacağınız ürünü açın.
• 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 kullanım modlarından en az birini seçin: ödemeyi Lunixi ile alıyorsanız API — Lunixi ödemesine bağlı, Lunixi dışında alıyorsanız API — harici tahsilat. Sigorta Tipleri ekranında sunacağınız tipi açıp kaydedin. Ayrıntı: Sigorta Menüsü › Genel, Sigorta Menüsü › Sigorta Tipleri.
• Primi kimin tahsil ettiğini seçin. Ürünü açarken Primi kim tahsil ediyor sorusunu sağlayıcınızla anlaşmanıza göre yanıtlayın. Aşağıdaki iki akış, primi sizin tahsil ettiğiniz (Siz tahsil edersiniz) siparişler içindir. Primi sağlayıcı tahsil ediyorsa (Sağlayıcı tahsil eder): Sağlayıcı Tahsilatı. Tahsilat biçimleri: Sigorta › Primi kim tahsil eder.

Test bağlantısı ve test anahtarı: Test Ortamı.

İki akış

Primi nasıl tahsil ettiğinize göre iki akıştan birini kullanırsınız:

İki akışta da teklif ve sipariş adımları aynıdır. Ayrıştıkları yer primin tahsilatıdır: Prim ve Ödeme.

Bir sepet kalemine bağlı olmayan sigorta tiplerinde teklif sepet kalemi olmadan alınır; adımlar ve tahsilat: Sepet Kalemi Olmadan Satış.

Teklif vermeyen sigorta tiplerinde teklif ve sipariş yoktur; alıcının bilgilerini sağlayıcınıza talep olarak iletirsiniz: Talep.

Lunixi ödemesine bağlı akış

Yalnız sigorta akışı

Bu akışta ödemeyi Lunixi'ye bildirirsiniz; Lunixi bildirimi bağlantınız üzerinden sağlayıcınıza iletir. Ardından poliçeyi istersiniz. Ayrıntı: Prim ve Ödeme › Lunixi dışında tahsil edilen prim. Belge, iptal, iade ve webhook dahil bütün adımlar ve uçtan uca örnek: Yalnız Sigorta Entegrasyonu.

Alıcının bilgisi sizde varsa

Teklif için gereken bilgileri (sigortalı, IMEI, rezervasyon kodu, plaka gibi) sepet kaleminin insuranceData alanıyla, kişisel olmayan bilgileri insuranceContext alanıyla gönderebilirsiniz: Sepet Kalemleri › Sigorta ön verisi.

• Uygunluk yanıtı teklif başına hangi alanların geldiğini (providedFields, kişisel değerler maskeli), bağlamdan neyin doldurulduğunu (prefill) ve teklifin ek alan gerekmeden alınıp alınamayacağını (quoteReady) gösterir: Uygunluk › Ön veri ve otomatik teklif.
• Teklif isteğinde yalnızca eksik alanları gönderirsiniz; gövde kalemlerin bilgileriyle tamamlanır. paymentIntentId ile alınan teklifte gövde boş da olabilir: Teklif › Ön veriyle teklif.
• context.items içindeki insuranceData saklanmaz; yalnızca o istekte kullanılır.

Uçlar

Taban adres https://api-gateway.lunixi.com'dur. Her ucun kimliği, istek ve yanıt alanları, hataları ve webhook olayları: Uç Referansı.

Kimlik doğrulama

Sigorta uçları yalnız API anahtarınızla imzalanmış istek kabul eder. Authorization başlığı gerekmez; Bearer erişim token'ı ya da panel oturumu bu uçlarda kimlik yerine geçmez. İmza başlıkları olmayan istek 401 AUTH_HEADERS_MISSING alır.

Tek istisna sağlayıcı tahsilatı ucudur (/pay): kart verisi taşıyabildiği için imzaya ek olarak Bearer erişim token'ı da ister. Bkz. Sağlayıcı Tahsilatı › Kimlik doğrulama.

Kanonik dize ve imzalama kuralları: Kimlik Doğrulama. İmzalanan ikinci satır, varsa sorgu dizesiyle birlikte tam istek yoludur. Gövdeyi boşluksuz JSON olarak gönderin ve Digest'i gönderdiğiniz gövdeden hesaplayın.

Bu bölümdeki cURL örnekleri aşağıdaki kabuk yardımcısını kullanır:

# lunixi-sign.sh — OpenSSL 3.0+ gerekir.
# Kullanım: source lunixi-sign.sh
#           lunixi_sign GET  "/api/v1/insurance/orders?limit=25"
#           lunixi_sign POST "/api/v1/insurance/quotes" "$BODY"
LUNIXI_KEY_ID="mk_test_..."
LUNIXI_KEY_FILE="lunixi-signing.key"
 
lunixi_sign() {
  local method="$1" req_path="$2" body="${3-}"
  DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
  NONCE=$(openssl rand -hex 16)
  if [ -n "$body" ]; then
    DIGEST="SHA-256=$(printf '%s' "$body" | openssl dgst -sha256 -binary | base64)"
    printf '%s\n%s\nX-Date:%s\nX-Nonce:%s\nDigest:%s' "$method" "$req_path" "$DATE" "$NONCE" "$DIGEST" > canonical.txt
  else
    DIGEST=""
    printf '%s\n%s\nX-Date:%s\nX-Nonce:%s' "$method" "$req_path" "$DATE" "$NONCE" > canonical.txt
  fi
  SIGNATURE=$(openssl pkeyutl -sign -inkey "$LUNIXI_KEY_FILE" -rawin -in canonical.txt | base64 | tr -d '\n')
}

Kimlik ve erişim hataları:

Idempotency-Key

Sipariş oluşturan ve siparişin durumunu değiştiren uçlar Idempotency-Key başlığını zorunlu tutar: orders, confirm-payment, issue-policy, pay, cancel, refund-premium. Hasar kaydı açan uç (policies/{policyId}/claims) ve talep açan uç (leads) da anahtarı zorunlu tutar. quotes ve bind-payment başlığı isteğe bağlı kabul eder.

• Anahtar 8-200 karakterlik, boşluksuz, yazdırılabilir ASCII bir değerdir. Eksik ya da biçim dışı anahtar 400 VALIDATION_ERROR döner.
• Anahtarı işleme bağlı üretin ve zaman aşımı ya da 5xx sonrasında isteği aynı anahtar ve aynı gövdeyle tekrarlayın. Sipariş ilk denemede oluştuysa ikinci bir sipariş açılmaz, kayıtlı sipariş döner.
• Aynı anahtarı farklı bir sipariş isteğiyle kullanırsanız 409 insurance.idempotency.conflict alırsınız. Yeni sipariş için yeni anahtar üretin.
• Sipariş üzerindeki işlemler ayrıca doğal olarak tekrarlanabilirdir: aynı ödemeyi yeniden bağlamak, aynı ödeme kimliğiyle yeniden bildirmek ya da poliçeyi, iptali veya iadeyi yeniden istemek siparişi olduğu gibi döner.

Yanıt ve hatalar

Başarılı yanıtın gövdesi data altındadır. Liste uçlarında sayfalama bilgisi pageInfo alanındadır; bkz. Sayfalama.

Hata yanıtı status: "failure", code, message, requestId ve details taşır. Kodunuzda message'a göre değil code'a göre dallanın; message dile göre değişir. Zarfın ayrıntısı: Hatalar.

Bütün sigorta uçlarında dönebilen kodlar:

Uca özgü kodlar her uç sayfasında yazılıdır. 4xx hataları aynı istekle tekrar denenerek düzelmez; önce isteği düzeltin.

Gönderdiğiniz kişisel veriler hata yanıtına yazılmaz. Yanıtlarda yalnızca Lunixi kimlikleri bulunur; sağlayıcının referansları ve hata kodları yanıta girmez.

Devamı