Sepet Kalemleri

Sepet kalemleri (basketItems[]), ödemenin neyi kapsadığını satır satır anlatır. Bu sayfa kalem alanlarını, kuralları ve kaleme eklenebilen isteğe bağlı sigorta alanlarını tek yerde toplar.

Kalemi alan uçlar

Kalem alanları

Kurallar:

• Kalemde adet alanı yoktur; price satır toplamıdır. Aynı üründen 3 adet satıyorsanız ya tek kalemde 3 adedin toplamını ya da her adet için ayrı bir kalem gönderirsiniz. Sigorta alanı taşıyan kalemlerde her birim ayrı bir kalemdir (aşağıya bakın).
• Kalem alan bütün ödeme isteklerinde kalemlerin price toplamı isteğin amount alanına eşit olmalıdır; eşit değilse istek 400 VALIDATION_ERROR ile reddedilir. amount vade farkını içermez; taksitte vade farkını sistem çekilen tutara ekler, kalemlere yazılmaz.
• Tanımlanmamış bir alan gönderirseniz istek reddedilir. Sigorta alanlarını yalnızca kabul eden uçlarda gönderin.

Doğrulama hataları

Kalemdeki bir hata 400 VALIDATION_ERROR döner. details.errors[] içindeki field, hatalı alanı kalemin sırasıyla birlikte noktalı bir yol olarak verir. Sıra 0'dan başlar: basketItems.0.itemType, ilk kalemin itemType alanıdır.

{
  "status": "failure",
  "code": "VALIDATION_ERROR",
  "message": "Doğrulama hatası — gönderilen alanları kontrol edin.",
  "statusCode": 400,
  "requestId": "4b0e6c1a-2f3d-4e5a-9b8c-7d6e5f4a3b2c",
  "details": {
    "errors": [
      { "field": "basketItems", "errors": [] },
      { "field": "basketItems.0.itemType", "errors": ["itemType must be one of the following values: PHYSICAL, VIRTUAL"] }
    ]
  }
}

• basketItems girdisi her zaman ilk sıradadır; kalem hatalarının nedeni ondan sonra gelen yol girdilerindedir.
• İç içe alanlarda yol uzar: basketItems.0.insuranceContext.departureAt.
• Bilinmeyen bir alanın yolu da aynı biçimde döner: basketItems.1.pnr.
• Kodunuzda message'a göre değil code'a ve field'a göre dallanın. Hata zarfı: Hatalar.

Sigorta alanları

Alıcınıza hangi sigortanın sunulacağı, kalemlerinizdeki sigorta alanlarından çözülür. Teklif için gereken bilgiyi de kalemle birlikte gönderebilirsiniz; bu bilgiler alıcıya yeniden sorulmaz. Ürünün nasıl çalıştığı: Sigorta.

• Sigorta alanlarının hepsi isteğe bağlıdır. Göndermezseniz ödemeniz bugünkü gibi çalışır.
• Sigorta alanları ödeme sağlayıcınıza iletilmez.
• Sigorta sunulamasa da ödeme durmaz; yalnızca sigorta gösterilmez.
• Sigorta hiçbir durumda kendiliğinden eklenmez; alıcının teklifi açıkça onaylaması gerekir.

Kurallar:

• insuranceTypes, insuranceValueAmount, insuranceContext ya da insuranceData gönderirseniz insuranceCategory zorunludur. insuranceEligible: false tek başına gönderilebilir.
• Kalemlerden en az biri sigorta alanı taşıyorsa sepetteki id'ler tekil olmalıdır. Sigorta alanı olmayan sepette bu kural uygulanmaz.
• Sigorta birim başınadır. Her birim ayrı sigortalanır ve teminat bedeli birim fiyatıdır. Bu yüzden sigorta alanı taşıyan kalemde her birimi ayrı kalem olarak gönderin: 3 bilet, 3 kalem.
• Sigorta primi kalemi (id'si inso_ ile başlayan kalem) sigorta alanı taşımaz; taşırsa istek 400 VALIDATION_ERROR ile reddedilir.
• İstek sırasında yalnızca biçim doğrulanır. Tip kodunun tanınıp tanınmadığı, kalem türüyle uyumu ve hesabınızda açık olup olmadığı sonra kontrol edilir; uyuşmazlık ödemeyi durdurmaz, yalnızca sigorta sunulmaz.

Kalem türü sözlüğü

Sözlüğe yeni değer eklenebilir; yayınlanmış bir değer değişmez ve silinmez. Bir kalem türünün hangi sigorta tiplerine karşılık geldiğini Lunixi kataloğu belirler. Şu anki karşılıklar: TICKET → TICKET_CANCELLATION, HOTEL → HOTEL_CANCELLATION, DEVICE → DEVICE_INSURANCE ve DEVICE_PROTECTION, ELECTRONICS → EXTENDED_WARRANTY, VEHICLE → ROADSIDE_ASSISTANCE, VEHICLE_TAG_PROTECTION, MOTOR_GREEN_CARD, MOTOR_THIRD_PARTY_LIABILITY, MOTOR_COMPREHENSIVE ve MOTOR_EXCESS_LIABILITY, TRAVEL → TRAVEL_HEALTH, INBOUND_TRAVEL_HEALTH, MOTOR_GREEN_CARD ve ABROAD_STAY_HEALTH, EVENT → EVENT_ACCIDENT, MICROMOBILITY → MICROMOBILITY_ACCIDENT, MUSICAL_INSTRUMENT → MUSICAL_INSTRUMENT_PROTECTION, HEALTH → MEDICAL_COMPLICATION, PET → PET_HEALTH, EDUCATION → ABROAD_STAY_HEALTH, HOME → COMPULSORY_EARTHQUAKE ve HOME_INSURANCE. Bir kalem türü birden çok tipe karşılık geliyorsa sunulacak tipleri insuranceTypes ile daraltabilirsiniz. Karşılığı olmayan bir kalem türünde sigorta sunulmaz. Bir kalem türüne bağlı olmayan tipler sepet kalemi olmadan, yalnızca API yolunda satılır: Sepet Kalemi Olmadan Satış. Tipler için bkz. Sigorta Tipleri.

insuranceContext

Bağlam, sigorta tipinin kişisel olmayan alanlarını taşır. Anahtarlar, tip nesnesindeki alan adlarıdır. İzinli anahtarlar kalem türüne göre aşağıdadır.

TICKET:

HOTEL:

DEVICE:

ELECTRONICS:

VEHICLE:

TRAVEL:

EVENT ve MICROMOBILITY:

MUSICAL_INSTRUMENT:

HEALTH:

PET:

EDUCATION:

HOME:

SHIPMENT:

Anahtarlar kalem türleri arasında ortaktır: tablolar anahtarın en çok kullanıldığı türü gösterir. Anahtarın kalem türüyle uyumuna ödeme isteğinde bakılmaz; bir anahtar, kalemin sigorta tipinde karşılığı varsa ön doldurmada kullanılır (Ön doldurma). Değerlerin tipin şemasına göre doğrulanması (ör. çıkış gününün girişten sonra olması, model yılı aralığı) teklif sırasında yapılır: Sigorta Tipleri.

• insuranceContext kişisel veri taşımaz. Rezervasyon kodu (pnr), bilet numarası (ticketNumber), IMEI (imei), plaka (plate), UAVT adres kodu (uavtAddressCode), seri numarası (serialNumber), ikamet ülkesi (residenceCountryCode), uyruk (nationalityCountryCode) ve kişi alanları (identityNumber, firstName, birthDate gibi) burada gönderilirse istek reddedilir. Bu bilgileri göndermek istiyorsanız insuranceData alanını kullanın.
• Tutar alanları burada gönderilmez; sigortalanacak değer insuranceValueAmount'tadır. Tipin tutar alanını (ör. bilet tutarı priceAmount) insuranceData ile verebilirsiniz.
• Değer yoksa anahtarı göndermeyin. Boş metin ya da "yok" gibi yer tutucu değerler kabul edilmez.
• Havalimanı kodlarının yalnızca uçak bileti için geçerli olması gibi çapraz kurallar teklif sırasında kontrol edilir.

Zaman, tarih ve kod biçimlerinin ayrıntısı: Veri Biçimleri.

Ön doldurma

Bağlamın anahtarı, tip nesnesindeki aynı adlı alanı doldurur; değer aynen kullanılır. Checkout Form'da bu alanlar dolu gelir ve alıcı değiştirebilir. API'de Uygunluk yanıtının prefill alanında döner ve teklif isteğinde göndermediğiniz alanları tamamlar.

• Tabloda olmayan bir anahtar o tipte kullanılmaz; ör. DEVICE_PROTECTION için warrantyMonths.
• Tipin şemasına uymayan ya da o durumda geçerli olmayan bir bağlam değeri ön doldurmada kullanılmaz ve teklifi engellemez. Örneğin transportMode: BUS olan bir bilette bağlamdaki havalimanı kodu dikkate alınmaz.
• Aynı alan insuranceData'da da varsa insuranceData'daki değer geçerlidir. Teklif isteğinde gönderilen değer (alıcının formda girdiği ya da sizin API'de gönderdiğiniz) ikisinden de önce gelir.

Sigorta ön verisi: insuranceData

Teklif için gereken bilgileri, kişisel veriler dahil, sigortalanacak kalemle birlikte gönderebilirsiniz: sigortalı, cihazın IMEI'si, rezervasyon kodu, aracın plakası gibi. Ne kadarını gönderdiğinize göre:

Her durumda sigorta yalnızca alıcının açık onayıyla eklenir. Form ve API'deki davranış: Sigorta › Sepet bilgisi ve ön veri.

Biçim

• Anahtarlar, sigorta tipinin teklif isteğindeki kök alanlarıdır: policyholder, insured ve tipin nesnesi. Alan adları ve biçimleri Sigorta Tipleri ve Şemalar sayfasındakiyle aynıdır; ayrı bir sözlük yoktur.
• Tip nesnesi kalem için tek nesnedir. Teklif isteğinde dizi olan tickets de burada tek nesne olarak verilir: "tickets": { "pnr": "…" }.
• Tip nesnesinde basketItemId gönderilmez; kalemin id'si kullanılır. Gönderilirse istek reddedilir.
• insured nesne dizisidir: 1-10 öge.
• Kısmi veri serbesttir. Zorunlu alanlar burada aranmaz; eksik alanları alıcı formda doldurur ya da siz teklif isteğinde gönderirsiniz.
• Değer yoksa alanı göndermeyin. null değer ve boş nesne ({}) kabul edilmez.
• JSON olarak en fazla 16 KB (UTF-8).

• Kalem birden çok tipe uygunsa (ör. DEVICE türünde iki tip) aynı ön veri her tipte kullanılır; bir tipin şemasında olmayan alan o tipte dikkate alınmaz.
• Yalnızca sepet kalemi olmadan satılan tiplerin (PERSONAL_ACCIDENT, FOREIGN_RESIDENT_HEALTH, SUPPLEMENTARY_HEALTH) bilgilerini doğrudan teklif isteğinde gönderin: Sepet Kalemi Olmadan Satış.

Doğrulama

Ön veri iki adımda doğrulanır:

• Kalemin insuranceContext'i doğrulamada birlikte değerlendirilir: bağlamdaki transportMode: FLIGHT, ön verideki flightNumber'ı geçerli kılar.
• Kalemin ön verisinde tek bir alan uymazsa o kalemin ön verisinin tamamı kullanılmaz. Biçimleri gönderiden önce kendi tarafınızda doğrulayın: Veri Biçimleri.

İstek sırasındaki hatalarda alan yolu kökü gösterir; ileti kökün altındaki alanı söyler. Gönderdiğiniz değer hata yanıtına yazılmaz:

{
  "status": "failure",
  "code": "VALIDATION_ERROR",
  "message": "Doğrulama hatası — gönderilen alanları kontrol edin.",
  "statusCode": 400,
  "requestId": "4b0e6c1a-2f3d-4e5a-9b8c-7d6e5f4a3b2c",
  "details": {
    "errors": [
      { "field": "basketItems", "errors": [] },
      { "field": "basketItems.0.insuranceData.tickets", "errors": ["insuranceData.tickets.departureAt must be an ISO 8601 timestamp with a time zone"] },
      { "field": "basketItems.1.insuranceData.passenger", "errors": ["property passenger should not exist"] }
    ]
  }
}

Kişisel veri

• insuranceData yalnızca sigorta için kullanılır; ödeme işlemine ve ödeme sağlayıcınıza iletilmez.
• Şifreli saklanır ve ödeme oluşturulduktan 24 saat sonra, en geç bir saat içinde silinir.
• İstek kayıtlarında ödeme isteğinin insuranceData alanı gizlenir; hata yanıtları değeri değil yalnızca alan yolunu taşır. Uygunluk yanıtında kişisel değerler maskelidir.

Ayrıntı: Sigorta › Kişisel veri.

Kabul eden uçlar

Birden çok kalem

Teklif birden çok kalemi kapsıyorsa kalemlerin ön verisi şöyle birleşir:

• tickets: her kalemin nesnesi, kalemin id'siyle teklifteki bileti oluşturur.
• insured: kalemlerin listeleri kalem sırasıyla tek listede birleşir. Aynı identityType ve identityNumber ikinci kez eklenmez; tipin sigortalı üst sınırı aşılmaz.
• policyholder: ön veride sigorta ettireni veren ilk kalemden alınır.
• Tek nesneli tiplerde (device, vehicle gibi) teklif tek bir kaleme bağlıdır. Teklif isteğindeki basketItemId hangi kalemin bilgisinin kullanılacağını seçer; göndermezseniz bağlam ya da ön veri taşıyan ilk kalem kullanılır.

Örnekler

Değerler örnektir; açılı parantez içindeki değerlerin yerine alıcınızın bilgilerini, referans kodlarının yerine referans uçlarından aldığınız kodları yazın. Her örnek, kalemin teklif için gereken bütün bilgiyi taşıdığı durumu gösterir; bir kısmını göndermeniz de yeterlidir.

"basketItems": [
  {
    "id": "ticket-1",
    "name": "Ankara-İstanbul otobüs bileti",
    "price": 50000,
    "category1": "bilet",
    "itemType": "VIRTUAL",
    "insuranceCategory": "TICKET",
    "insuranceTypes": ["TICKET_CANCELLATION"],
    "insuranceContext": {
      "transportMode": "BUS",
      "carrier": "Örnek Taşıyıcı",
      "departureAt": "2025-12-23T12:50:00+03:00",
      "originCity": "Ankara",
      "destinationCity": "İstanbul"
    },
    "insuranceData": {
      "insured": [
        {
          "identityType": "PASSPORT",
          "identityNumber": "<pasaport numarası>",
          "birthDate": "<YYYY-MM-DD>",
          "email": "<e-posta>",
          "phone": "<E.164 telefon>"
        }
      ],
      "tickets": {
        "priceAmount": 50000,
        "pnr": "<rezervasyon kodu>",
        "ticketNumber": "<bilet numarası>"
      }
    }
  }
]

Kişisel veri insuranceContext'te gönderilirse kalemin yolu hatada görünür; bu bilgiyi insuranceData ile gönderin:

{ "field": "basketItems.0.insuranceContext.pnr", "errors": ["property pnr should not exist"] }

Ödeme linki kalemleri

Ödeme linki kalemleri (items[]) kendi biçimini kullanır: itemKey, name, unitPriceMinor, minQuantity, maxQuantity ve diğerleri; bkz. Link Oluşturma. Bu kalemlere de sigorta alanı ekleyebilirsiniz:

• Alanların kuralları yukarıdakiyle aynıdır: insuranceTypes ya da insuranceValueAmount gönderirseniz insuranceCategory zorunludur.
• Alıcı bir kalemden 3 adet seçerse 3 birim ayrı ayrı sigortalanır; teminat bedeli birim fiyatıdır.
• Tanımlanmamış bir alan ya da yanlış tip 400 VALIDATION_ERROR döner. Kural ihlali (ör. tür olmadan tip kodu) 422 payment_link.validation.invalid döner; details.errors hangi kalemin hangi alanının reddedildiğini gösterir.

Devamı

• Checkout Formu: kalemleri gönderdiğiniz ödeme isteği
• Sigorta: sigortanın nasıl çalıştığı
• Veri Biçimleri: zaman, tarih ve kod biçimleri