Teklif

Teklif, belirli bir sepet ve sigortalı bilgisi için verilen fiyattır. Teklif isteği bir ya da daha fazla seçenek döner; her seçeneğin kendi kimliği (quoteId), primi ve geçerlilik süresi vardır. Alıcının onayladığı seçenekle sipariş oluşturursunuz.

Teklif para hareketi değildir ve poliçe kesmez. Hangi sağlayıcının teklif vereceğini isteğiniz değil, sağlayıcı bağlantılarınız belirler. Tek bir istek, bağlantılarınızdaki birden çok üründen ve sigorta şirketinden seçenek döndürebilir: Birden çok seçenek.

Kimlik doğrulama ve imzalama: Akışlar › Kimlik doğrulama.

Teklif alma: POST /api/v1/insurance/quotes

Idempotency-Key isteğe bağlıdır. Her istek yeni ve süreli bir fiyat döner.

• Sepet kaynağı olarak context.items ya da paymentIntentId gönderin; ikisi birlikte gönderilirse istek reddedilir.
• İkisini de göndermezseniz teklif sepet kalemi olmadan alınır. Bu yalnızca sepet kalemi olmadan satılan tiplerde geçerlidir: Sepet Kalemi Olmadan Satış.
• policyholder, insured ve tip nesnesinin alanları ile zorunlulukları tipin şemasındadır: Sigorta Tipleri ve Şemalar. Şemada olmayan bir alan reddedilir.
• Tip nesnesindeki her ögeyi basketItemId ile sigortalanan sepet kalemine bağlayın. paymentIntentId ile alınan teklifte basketItemId zorunludur. context.items ile alınan teklifte basketItemId gönderilmezse tip, sunulduğu bütün kalemleri kapsar.
• Kalemlerde insuranceContext ya da insuranceData varsa gövde bu bilgilerle tamamlanır ve basketItemId kalemden alınabilir; kurallar: Ön veriyle teklif.

TICKET_CANCELLATION için iki biletli bir teklif isteği. Değerler örnektir; açılı parantez içindeki değerlerin yerine alıcınızın bilgilerini yazın:

{
  "insuranceType": "TICKET_CANCELLATION",
  "currency": "TRY",
  "merchantOrderId": "order-1001",
  "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"]
      }
    ]
  },
  "insured": [
    {
      "identityType": "TCKN",
      "identityNumber": "<kimlik numarası>",
      "birthDate": "<YYYY-MM-DD>",
      "email": "<e-posta>",
      "phone": "<E.164 telefon>"
    }
  ],
  "tickets": [
    {
      "basketItemId": "ticket-1",
      "transportMode": "TRAIN",
      "carrier": "Örnek Taşıyıcı",
      "priceAmount": 50000,
      "departureAt": "2025-12-23T12:50:00+03:00",
      "originCity": "İzmir",
      "destinationCity": "Ankara",
      "pnr": "<rezervasyon kodu>",
      "ticketNumber": "<bilet numarası>"
    },
    {
      "basketItemId": "ticket-2",
      "transportMode": "TRAIN",
      "carrier": "Örnek Taşıyıcı",
      "priceAmount": 50000,
      "departureAt": "2025-12-23T12:50:00+03:00",
      "originCity": "İzmir",
      "destinationCity": "Ankara",
      "pnr": "<rezervasyon kodu>",
      "ticketNumber": "<bilet numarası>"
    }
  ]
}

source lunixi-sign.sh
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"

Yanıt

Başarılı istek 201 döner. data şu alanları taşır:

Hiçbir bağlantınızdan seçenek alınamazsa istek hata döner; boş seçenek listesi dönmez.

Ön veriyle teklif

Sepet kalemlerinde insuranceContext ya da insuranceData varsa teklif gövdesi bu bilgilerle tamamlanır. İstekte yalnızca eksik alanları ya da değiştirmek istediklerinizi gönderirsiniz. Ön verinin biçimi: Sepet Kalemleri › Sigorta ön verisi.

Teklif için gereken her şeyin kalemlerde olup olmadığını Uygunluk yanıtındaki quoteReady gösterir. Kalemlerde her şey varsa teklifi yalnızca tip, para birimi ve ödeme kimliğiyle alabilirsiniz:

{
  "insuranceType": "TICKET_CANCELLATION",
  "currency": "TRY",
  "paymentIntentId": "<ödeme kimliği>"
}

Bir kısmı eksikse yalnızca eksikleri gönderin. Örnekte poliçe için gereken rezervasyon kodu ve bilet numarası ekleniyor; sefer, yolcu ve bilet tutarı kalemden gelir:

{
  "insuranceType": "TICKET_CANCELLATION",
  "currency": "TRY",
  "paymentIntentId": "<ödeme kimliği>",
  "tickets": [
    {
      "basketItemId": "ticket-1",
      "pnr": "<rezervasyon kodu>",
      "ticketNumber": "<bilet numarası>"
    }
  ]
}

Birleştirme kuralları

• İstek kazanır. Taban, kalemlerin bağlamı ve ön verisidir; istek gövdesi tabanın üstüne yazılır. Aynı alanda istekte gönderdiğiniz değer geçerlidir. Bağlam ile ön veride aynı alan varsa ön veri geçerlidir.
• Tip nesnesini göndermezseniz tip nesnesi, bağlam ya da ön veri taşıyan kalemlerden kurulur; basketItemId kalemin id'sidir. Bu bilgileri taşımayan kalem teklife girmez. O kalemi de kapsamak için tip nesnesinde o kalemin basketItemId'siyle bir öge gönderin.
• Dizi olan tip nesnesi (tickets): gönderirseniz teklif yalnızca gönderdiğiniz biletleri kapsar. basketItemId'si bir kaleme eşleşen bilet, o kalemin bilgileriyle tamamlanır.
• Tek nesneli tipler (device, vehicle gibi): nesnedeki basketItemId hangi kalemin bilgisinin kullanılacağını seçer. Göndermezseniz bağlam ya da ön veri taşıyan ilk kalem kullanılır ve teklif o kaleme bağlanır.
• insured: kalemlerin sigortalıları kalem sırasıyla tek listede birleşir; aynı identityType ve identityNumber tekrar edilmez, tipin üst sınırı aşılmaz. İstekte gönderdiğiniz insured listesinin her ögesi aynı sıradaki sigortalının üstüne yazılır.
• policyholder: ön veride sigorta ettireni veren ilk kalemden alınır; istekte gönderdiğiniz alanlar üstüne yazılır.

Doğrulama:

• Birleşik gövde tipin şemasına göre bütünüyle doğrulanır. Ön veride ya da istekte kurala uymayan alan, alan yoluyla 422 insurance.validation.invalid alır.
• Bağlamdan gelen ve tipe uymayan bir değer kullanılmaz; teklifi engellemez.
• Kalemlerde bağlam ya da ön veri varsa önce tipin bu sepete sunulup sunulmadığına bakılır; sunulmuyorsa 412 insurance.type.not_available döner.
• Kalemlerde bağlam ve ön veri yoksa teklif bugünkü gibi yalnızca istek gövdesiyle alınır.

Birden çok seçenek

Teklif isteği, tipin açık olduğu bütün bağlantı ürünlerinize aynı anda gönderilir. Her ürün kendi seçeneğini döner.

• Aynı sigorta şirketinden birden çok seçenek dönebilir; örneğin aynı ürünün farklı paketleri.
• Aynı sigorta şirketinin teklifi iki farklı sağlayıcı bağlantınızdan gelirse iki ayrı seçenek döner. Lunixi bunlardan birini sizin yerinize seçmez.
• Seçenekler bağlantılarınızın sırasıyla döner.
• Yanıt, bağlantıları belirli bir süreye kadar bekler. Bu sürede yanıt vermeyen bağlantının seçeneği insurance.provider.unavailable ile elenir; diğer seçenekler döner. İstemcinizin zaman aşımını 30 saniyeden kısa tutmayın.

Sağlayıcı ve sigorta şirketi

Seçenekte sağlayıcı ve sigorta şirketi ayrı alanlardır:

• provider, teklifi aldığınız sağlayıcı bağlantısıdır.
• underwriter, poliçeyi düzenleyen sigorta şirketidir. Aynı sigorta şirketi farklı sağlayıcılardan gelebilir; underwriter.code hangi sağlayıcıdan gelirse gelsin aynı şirket için aynıdır.
• Ürün bir sigorta şirketi bildirmiyorsa underwriter null döner.
• underwriter.disclosureText, sigorta şirketinin alıcıya gösterilecek bilgilendirme metnidir. İsteğin dilinde döner (x-lang ya da Accept-Language: tr, en); o dilde metin yoksa diğer dildeki metin döner.

Elenen seçenekler

Bir ürün teklif veremezse yalnızca o ürünün seçeneği elenir; diğer seçenekler etkilenmez. Elenen seçenekler excludedOptions dizisindedir:

• En sık sebep, ürünün teklif aşamasında istediği bir alanın eksik olmasıdır. Eksik alanları ekleyip yeni teklif alırsanız o ürünün seçeneği de döner. Ürüne göre zorunlu alanlar: Uygunluk › Ürüne göre zorunlu alanlar.
• Elenen seçeneğin quoteId'si yoktur; onunla sipariş oluşturulamaz.
• excludedOptions yalnızca teklif alma yanıtında bulunur; teklifi okuma yanıtında yoktur.
• Gönderdiğiniz değerler ve sağlayıcının kendi hata kodları bu diziye yazılmaz.
• Bütün seçenekler elenirse istek hata döner: ürünlerin istediği alanlar eksikse 422 insurance.validation.invalid (bütün eksik alan yollarıyla), değilse sağlayıcıların ret ya da erişim hatası.

Seçenek

Alıcıya gösterim ve onay

• Alıcıya her seçenek için sağlayıcının adını, primi, teminat özetini, sigorta şirketinin adını (underwriter.name) ve varsa bilgilendirme metnini (underwriter.disclosureText) ve şartname sürümünü gösterin.
• Sigortayı önceden seçili getirmeyin. Alıcı, şartları kabul ettiğini ve bilgilerinin sigorta işlemi için sağlayıcıyla paylaşılmasına onay verdiğini açıkça işaretlemelidir.
• Sipariş oluştururken alıcının onayladığı seçeneğin terms.version ve terms.sha256 değerlerini aynen geri gönderirsiniz: Sipariş › Onay.

Geçerlilik süresi

• Her seçenek expiresAt anına kadar geçerlidir. Süre sağlayıcının ürününe göre belirlenir.
• Süresi dolan seçenekle sipariş oluşturulamaz (409 insurance.quote.expired); yeni teklif alın.
• Sepet ya da sigortalı bilgisi değişirse yeni teklif alın. Sipariş ödemeye bağlanırken ödemenin sepeti teklifteki sepetle karşılaştırılır; uyuşmazsa 409 insurance.quote.stale döner.
• Bir seçenekle yalnızca bir sipariş oluşturulur.

Teklifi okuma: GET /api/v1/insurance/quotes/{quoteId}

Tek bir seçeneği döner. data, yukarıdaki seçenek nesnesidir. Süresi dolan seçenek status: EXPIRED ile döner.

source lunixi-sign.sh
REQ_PATH="/api/v1/insurance/quotes/<quoteId>"
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"

Kimlik bulunamazsa ya da başka bir hesaba aitse 404 insurance.quote.not_found döner.

Anlaşmalı kurumlar: GET /api/v1/insurance/quotes/{quoteId}/facilities

Bazı sigorta tiplerinde seçenek, anlaşmalı sağlık kurumlarından oluşan bir ağla gelir; örneğin tamamlayıcı sağlık sigortası (SUPPLEMENTARY_HEALTH). Bu uç, bir seçeneğin verilen ildeki anlaşmalı kurumlarını döner. Alıcıya planları karşılaştırırken kurumları gösterebilirsiniz.

source lunixi-sign.sh
REQ_PATH="/api/v1/insurance/quotes/<quoteId>/facilities?cityCode=06"
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"

Yanıtta kurumlar data.items dizisindedir:

{
  "data": {
    "items": [
      { "name": "<kurum adı>", "cityCode": "06" }
    ]
  }
}

• Liste, seçeneğin sağlayıcı bağlantınızdan her istekte okunur ve saklanmaz; zamanla değişebilir. Kurumlar ada göre sıralıdır; bir istekte en fazla 500 kurum döner. Sayfalama yoktur.
• Seçeneğin geçerlilik süresi dolmuş olsa da liste okunabilir.
• Seçeneğin anlaşmalı kurum listesi yoksa istek sağlayıcıya gönderilmeden 412 insurance.facility.not_supported döner.
• Kimlik bulunamazsa ya da başka bir hesaba aitse 404 insurance.quote.not_found döner.
• cityCode eksikse ya da iki haneli değilse 400 VALIDATION_ERROR, 01-81 dışındaysa cityCode alan yoluyla 422 insurance.validation.invalid döner.

Hatalar

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

İlgili

• Sipariş ve Ödeme Bağlama: seçenekle sipariş oluşturma
• Sigorta Tipleri ve Şemalar: tip alanları ve aşamalar
• Sepet Kalemi Olmadan Satış: sepet kaynağı olmadan teklif
• Veri Biçimleri: tutar, zaman ve kimlik biçimleri