Uç Referansı

Bu sayfa her sigorta ucunun özetini verir. Alanların tam açıklaması, kurallar ve örnekler her ucun Ayrıntı bağlantısındadır.

Taban adres https://api-gateway.lunixi.com'dur.
Bütün uçlar API anahtarınızla imzalanmış istek ister: Akışlar › Kimlik doğrulama. /pay ayrıca Bearer erişim token'ı ister.
Bütün uçlarda ortak hata kodları (VALIDATION_ERROR, insurance.validation.invalid, insurance.idempotency.conflict, insurance.dependency.unavailable, insurance.internal.integrity) ve kimlik hataları geçerlidir: Akışlar › Yanıt ve hatalar. Aşağıdaki tablolar uca özgü kodları verir.
Başarılı yanıtın gövdesi data altındadır; belge uçları PDF, dışa aktarım ucu CSV döner. Liste uçlarında sayfalama bilgisi pageInfo alanındadır: Sayfalama.

Özet

Lunixi ödemesi olmadan sütunu, ucun Lunixi'de ödeme almadan kullanılıp kullanılamayacağını gösterir: Yalnız Sigorta Entegrasyonu.

Yöntem	Yol	`Idempotency-Key`	Lunixi ödemesi olmadan
`POST`	`/api/v1/insurance/products`	—	Evet
`GET`	`/api/v1/insurance/products`	—	Evet, `paymentIntentId` olmadan
`GET`	`/api/v1/insurance/reference/{kind}`	—	Evet
`POST`	`/api/v1/insurance/quotes`	İsteğe bağlı	Evet, `paymentIntentId` olmadan
`GET`	`/api/v1/insurance/quotes/{quoteId}`	—	Evet
`GET`	`/api/v1/insurance/quotes/{quoteId}/facilities`	—	Evet
`POST`	`/api/v1/insurance/orders`	Zorunlu	Evet
`GET`	`/api/v1/insurance/orders`	—	Evet
`GET`	`/api/v1/insurance/orders/{orderId}`	—	Evet
`POST`	`/api/v1/insurance/orders/{orderId}/bind-payment`	İsteğe bağlı	Hayır
`POST`	`/api/v1/insurance/orders/{orderId}/confirm-payment`	Zorunlu	Evet
`POST`	`/api/v1/insurance/orders/{orderId}/issue-policy`	Zorunlu	Evet
`POST`	`/api/v1/insurance/orders/{orderId}/pay`	Zorunlu	Evet
`POST`	`/api/v1/insurance/orders/{orderId}/cancel`	Zorunlu	Evet
`POST`	`/api/v1/insurance/orders/{orderId}/refund-premium`	Zorunlu	Evet, `externalRefund` ile
`GET`	`/api/v1/insurance/policies/{policyId}/document`	—	Evet
`GET`	`/api/v1/insurance/policies/{policyId}/receipt`	—	Evet
`GET`	`/api/v1/insurance/policies/{policyId}/certificate`	—	Evet
`POST`	`/api/v1/insurance/policies/{policyId}/claims`	Zorunlu	Evet
`GET`	`/api/v1/insurance/claims`	—	Evet
`GET`	`/api/v1/insurance/claims/{claimId}`	—	Evet
`GET`	`/api/v1/insurance/claims/{claimId}/document`	—	Evet
`POST`	`/api/v1/insurance/leads`	Zorunlu	Evet
`GET`	`/api/v1/insurance/leads`	—	Evet
`GET`	`/api/v1/insurance/leads/{leadId}`	—	Evet
`GET`	`/api/v1/insurance/reconciliation/summary`	—	Evet
`GET`	`/api/v1/insurance/reconciliation/orders`	—	Evet
`GET`	`/api/v1/insurance/reconciliation/export`	—	Evet

Uygunluk ve referans

`POST /api/v1/insurance/products`


Ne yapar	Göndereceğiniz sepet kalemleri için sunulan sigorta tiplerini döner. Salt okumadır.
İstek	`currency`, `context.items` (1-100 kalem; `insuranceData` saklanmaz), isteğe bağlı `insuranceType`.
Yanıt	`200`; `data.products[]`: `insuranceType`, `typeObject`, `schemaVersion`, `basketItemIds`, `title`, `description`, `fields`, `prefill`, `providedFields`, `quoteReady`, `insuranceDataIssues`. Boş liste sigortanın sunulmadığını gösterir.
Hatalar	`400 VALIDATION_ERROR`, `422 insurance.validation.invalid`
Webhook	—
Ayrıntı	Uygunluk › Ödemeden önce

`GET /api/v1/insurance/products`


Ne yapar	`paymentIntentId` ile: Lunixi ödemesinin kalemleri için sunulan tipler. `paymentIntentId` olmadan: sepet kalemi olmadan satılan tipler.
İstek	Sorgu: `currency`, isteğe bağlı `paymentIntentId` ve `insuranceType`.
Yanıt	`200`; `POST` ile aynı `data.products[]`.
Hatalar	`400 VALIDATION_ERROR`, `422 insurance.validation.invalid` (`reason: currency_mismatch`)
Webhook	—
Ayrıntı	Uygunluk › Ödemeden sonra, Sepet kalemi olmadan

`GET /api/v1/insurance/reference/{kind}`


Ne yapar	Tip alanlarında kullanılan Lunixi referans kodlarını (ülke, il, ilçe, marka, model, meslek, adres zinciri gibi) listeler. Sağlayıcının kodları dönmez.
İstek	Yol: `kind`. Sorgu: `parentCode`, `limit` (1-100, varsayılan 25), `cursor`; araç listelerinde `vehicleTypeCode` ve `modelYear`; bina listesinde `outerDoorNumber`.
Yanıt	`200`; `data.items[]`: `code`, `label`, `parentCode`; `pageInfo`.
Hatalar	`400 VALIDATION_ERROR`; `422 insurance.validation.invalid` (`field: kind`, `reason: unknown_reference_kind` ya da `live_reference_unavailable`; `field: parentCode`, `reason: required`, `not_applicable`, `invalid_reference_code` ya da `invalid_enum`); `422 insurance.reference.unknown`
Webhook	—
Ayrıntı	Sigorta Tipleri ve Şemalar › Referans kodları

Teklif

`POST /api/v1/insurance/quotes`


Ne yapar	Sigorta tipini sigortalı ve sigortalanan kalemler için fiyatlar; bir ya da daha fazla seçenek döner.
İstek	`insuranceType`, `currency`, sepet kaynağı (`context.items` ya da `paymentIntentId`; sepet kalemi olmadan satılan tiplerde hiçbiri), isteğe bağlı `schemaVersion` ve `merchantOrderId`, tipe göre `policyholder`, `insured[]` ve tip nesnesi. Kalemlerin bağlamı ve ön verisi gövdeyi tamamlar; `paymentIntentId` ile gövde boş olabilir (Ön veriyle teklif).
Yanıt	`201`; `data`: `insuranceType`, `schemaVersion`, `options[]`, `excludedOptions[]`.
Hatalar	`412 insurance.type.not_available`, `412 insurance.provider.not_integrated`, `422 insurance.reference.unknown`, `422 insurance.quote.declined`, `503 insurance.provider.unavailable`
Webhook	—
Ayrıntı	Teklif › Teklif alma, Seçenek

`GET /api/v1/insurance/quotes/{quoteId}`


Ne yapar	Tek bir seçeneği döner; süresi dolan seçenek `status: EXPIRED` ile döner.
İstek	Yol: `quoteId` (`insq_…`).
Yanıt	`200`; `data`: seçenek nesnesi.
Hatalar	`404 insurance.quote.not_found`
Webhook	—
Ayrıntı	Teklif › Teklifi okuma

`GET /api/v1/insurance/quotes/{quoteId}/facilities`


Ne yapar	Seçeneğin verilen ildeki anlaşmalı sağlık kurumlarını döner.
İstek	Yol: `quoteId`. Sorgu: `cityCode` (`01`-`81`).
Yanıt	`200`; `data.items[]`: `name`, `cityCode`. Sayfalama yoktur.
Hatalar	`404 insurance.quote.not_found`, `412 insurance.facility.not_supported`, `422 insurance.validation.invalid` (`field: cityCode`)
Webhook	—
Ayrıntı	Teklif › Anlaşmalı kurumlar

Sipariş ve tahsilat

`POST /api/v1/insurance/orders`


Ne yapar	Alıcının onayladığı seçenekle sipariş oluşturur. Sağlayıcıya istek göndermez, para hareketi yapmaz.
İstek	`quoteId`, `consent.termsVersion`, `consent.termsSha256`, `consent.acceptedAt`, isteğe bağlı `merchantOrderId`.
Yanıt	`201`; `data`: sipariş nesnesi (`paymentMode: NO_PAYMENT`).
Hatalar	`404 insurance.quote.not_found`, `409 insurance.quote.expired`, `409 insurance.order.state_conflict` (`reason: quote_already_ordered`), `422 insurance.validation.invalid` (`reason: terms_mismatch`)
Webhook	—
Ayrıntı	Sipariş › Sipariş oluşturma, Sipariş nesnesi

`GET /api/v1/insurance/orders`


Ne yapar	Siparişlerinizi en yeniden eskiye listeler; Checkout Form siparişleri de dahildir.
İstek	Sorgu: `limit` (1-100, varsayılan 25), `cursor`, `paymentIntentId`, `merchantOrderId`.
Yanıt	`200`; `data.items[]`: sipariş nesnesi; `pageInfo`.
Hatalar	`422 insurance.validation.invalid` (`field: cursor`)
Webhook	—
Ayrıntı	Sipariş › Listeleme

`GET /api/v1/insurance/orders/{orderId}`


Ne yapar	Tek bir siparişi döner; poliçe ve belge durumunu bu uçla izlersiniz.
İstek	Yol: `orderId` (`inso_…`).
Yanıt	`200`; `data`: sipariş nesnesi.
Hatalar	`404 insurance.order.not_found`
Webhook	—
Ayrıntı	Sipariş › Okuma

`POST /api/v1/insurance/orders/{orderId}/bind-payment`


Ne yapar	Siparişi, sigorta alanlı kalemlerle oluşturulmuş bir Lunixi ödemesine bağlar. Yalnızca Lunixi ödemesine bağlı akışta kullanılır.
İstek	`paymentIntentId`.
Yanıt	`200`; `data`: sipariş nesnesi (`paymentMode: LUNIXI_PAYMENT`).
Hatalar	`404 insurance.order.not_found`, `409 insurance.quote.expired`, `409 insurance.quote.stale`, `409 insurance.order.state_conflict`, `409 insurance.order.premium_item_mismatch`, `412 insurance.order.payment_not_recorded`
Webhook	Ödeme tahsil edildikten sonra poliçe olayları: `insurance.policy.issued`, `insurance.policy.failed`, `insurance.refund.required`, `insurance.policy.document_ready`.
Ayrıntı	Sipariş › Ödemeye bağlama, Prim ve Ödeme › Lunixi ödemesiyle

`POST /api/v1/insurance/orders/{orderId}/confirm-payment`


Ne yapar	Lunixi dışında tahsil ettiğiniz primi bildirir; Lunixi bildirimi bağlantınız üzerinden sağlayıcınıza iletir.
İstek	`payment.externalPaymentId`, `payment.paidAmount`, `payment.paidCurrency`, `payment.paidAt`, isteğe bağlı `payment.paymentProvider`.
Yanıt	`200`; `data`: sipariş nesnesi (`paymentMode: EXTERNAL_PAYMENT`, `collectionStatus: COLLECTED`).
Hatalar	`404 insurance.order.not_found`, `409 insurance.quote.expired`, `409 insurance.order.state_conflict` (`reason: lunixi_payment`, `external_payment`, `collected_by_provider`), `422 insurance.validation.invalid` (`reason: premium_amount_mismatch` ya da `premium_currency_mismatch`)
Webhook	—
Ayrıntı	Sipariş › Lunixi dışında alınan primi bildirme

`POST /api/v1/insurance/orders/{orderId}/issue-policy`


Ne yapar	Lunixi dışında tahsil edilen primden sonra poliçeyi ister. Gövde gönderilmez.
İstek	Yol: `orderId`.
Yanıt	`200`; `data`: sipariş nesnesi (`policyStatus: PENDING`). Poliçe arka planda kesilir.
Hatalar	`404 insurance.order.not_found`, `409 insurance.order.state_conflict` (`reason: refund_started` ya da `collected_by_provider`), `412 insurance.premium.not_captured`
Webhook	`insurance.policy.issued`, `insurance.policy.failed`, `insurance.refund.required`, `insurance.policy.document_ready`
Ayrıntı	Sipariş › Poliçe isteme

`POST /api/v1/insurance/orders/{orderId}/pay`


Ne yapar	Primi sağlayıcının tahsil ettiği (`premiumCollectedBy: PROVIDER`) siparişte prim çekimini başlatır. Prim çekilince poliçe otomatik istenir.
Kimlik	Bearer erişim token'ı ve imza başlıkları birlikte.
İstek	`CARD` üründe `card` (yalnızca PCI-DSS sertifikalı merchant'lar), isteğe bağlı `returnUrl`.
Yanıt	`200`; `data.order` (sipariş nesnesi) ve `data.providerPayment` (`insurancePaymentId`, `status`, `paymentInput`, `amount`, `currency`, `failureCode`, `nextAction`).
Hatalar	`403 insurance.card.pci_required`, `404 insurance.order.not_found`, `409 insurance.order.state_conflict`, `409 insurance.quote.expired`, `412 insurance.payment.merchant_payment_not_captured`, `422 insurance.payment.method_not_supported`, `422 insurance.card.invalid`, `422 insurance.reference.unknown`, `422 insurance.quote.declined`, `503 insurance.provider.unavailable`
Webhook	Prim çekilince poliçe olayları; çekim reddedilirse `insurance.policy.failed` (`errorCode: insurance.payment.declined`).
Ayrıntı	Sağlayıcı Tahsilatı

İptal ve iade

`POST /api/v1/insurance/orders/{orderId}/cancel`


Ne yapar	Kesilmiş her poliçe için sağlayıcıda iptal talebi açar. Sonuç sonradan kesinleşir. İptal primi iade etmez. Gövde gönderilmez.
İstek	Yol: `orderId`.
Yanıt	`200`; `data`: sipariş nesnesi (`policyStatus: CANCEL_PENDING`).
Hatalar	`404 insurance.order.not_found`, `409 insurance.order.state_conflict` (`reason: policy_not_issued`), `412 insurance.provider.not_integrated`
Webhook	`insurance.policy.cancelled`. Sağlayıcı iptali reddederse olay gönderilmez; `errorCode` `insurance.policy.cancel_failed` olur.
Ayrıntı	İptal ve Prim İadesi › Poliçe iptali

`POST /api/v1/insurance/orders/{orderId}/refund-premium`


Ne yapar	Lunixi ödemesindeki primi iade eder ya da Lunixi dışında yaptığınız iadeyi kaydeder. Primi sağlayıcı tahsil ettiyse kullanılmaz.
İstek	Lunixi ödemesinde gövdesiz. Lunixi dışında tahsil edilen primde `externalRefund.externalRefundId` ve `externalRefund.refundedAt`.
Yanıt	`200`; `data`: sipariş nesnesi (`refundStatus: PENDING` ya da `REFUNDED`).
Hatalar	`404 insurance.order.not_found`, `409 insurance.order.state_conflict` (`reason: policy_active`, `policy_in_progress`, `already_refunded`, `collected_by_provider`), `412 insurance.premium.not_captured`, `422 insurance.validation.invalid`
Webhook	`insurance.refund.completed`
Ayrıntı	İptal ve Prim İadesi › Prim iadesi

Poliçe belgeleri

Belgeler Lunixi'de saklanmaz; her istekte sağlayıcıdan alınır. Başarılı yanıt PDF dosyasının kendisidir (Content-Type: application/pdf, Cache-Control: no-store); hata yanıtı JSON hata zarfıdır. Belge, poliçe ISSUED ya da CANCEL_PENDING iken alınabilir.

`GET /api/v1/insurance/policies/{policyId}/document`


Ne yapar	Poliçe belgesini PDF olarak döner.
İstek	Yol: `policyId` (`insp_…`).
Yanıt	`200`; PDF, dosya adı `<policyId>.pdf`.
Hatalar	`404 insurance.policy.not_found`, `409 insurance.order.state_conflict` (`reason: policy_not_issued` ya da `policy_cancelled`), `503 insurance.document.unavailable`
Webhook	Belge hazır olduğunda `insurance.policy.document_ready`.
Ayrıntı	Poliçe Belgesi

`GET /api/v1/insurance/policies/{policyId}/receipt`


Ne yapar	Ürün makbuz sunuyorsa poliçenin prim makbuzunu PDF olarak döner.
İstek	Yol: `policyId`.
Yanıt	`200`; PDF, dosya adı `<policyId>-receipt.pdf`.
Hatalar	Poliçe belgesindekiler ve `412 insurance.document.not_supported`
Webhook	—
Ayrıntı	Poliçe Belgesi › Makbuz

`GET /api/v1/insurance/policies/{policyId}/certificate`


Ne yapar	Ürün sertifika veriyorsa poliçenin sertifikasını PDF olarak döner.
İstek	Yol: `policyId`.
Yanıt	`200`; PDF, dosya adı `<policyId>-certificate.pdf`.
Hatalar	Poliçe belgesindekiler ve `412 insurance.document.not_supported`
Webhook	—
Ayrıntı	Poliçe Belgesi › Sertifika

Hasar kaydı

`POST /api/v1/insurance/policies/{policyId}/claims`


Ne yapar	Yürürlükteki poliçe için hasarı sağlayıcıya bildirir. Belgeler bu istekte sağlayıcıya iletilir ve Lunixi'de saklanmaz.
İstek	Yol: `policyId`. Gövde: `incidentAt`, `documents[]`.
Yanıt	`201`; `data`: hasar kaydı (`status: SUBMITTED` ya da `UNKNOWN`).
Hatalar	`404 insurance.policy.not_found`, `409 insurance.claim.state_conflict`, `412 insurance.claim.not_supported`, `422 insurance.claim.rejected`, `503 insurance.provider.unavailable`
Webhook	`insurance.claim.submitted`, `insurance.claim.failed`
Ayrıntı	Hasar Kaydı › Hasar kaydı açma

`GET /api/v1/insurance/claims`


Ne yapar	Hasar kayıtlarınızı en yeniden eskiye listeler.
İstek	Sorgu: `limit` (1-100, varsayılan 25), `cursor`, `orderId`, `policyId`, `status`.
Yanıt	`200`; `data.items[]`: hasar kaydı; `pageInfo`.
Hatalar	`422 insurance.validation.invalid` (`field: cursor`)
Webhook	—
Ayrıntı	Hasar Kaydı › Listeleme

`GET /api/v1/insurance/claims/{claimId}`


Ne yapar	Tek bir hasar kaydını döner.
İstek	Yol: `claimId` (`insclm_…`).
Yanıt	`200`; `data`: hasar kaydı.
Hatalar	`404 insurance.claim.not_found`
Webhook	—
Ayrıntı	Hasar Kaydı › Okuma

`GET /api/v1/insurance/claims/{claimId}/document`


Ne yapar	Sağlayıcının hasar kaydı için verdiği belgeyi PDF olarak döner; kayıt `SUBMITTED` olmalıdır.
İstek	Yol: `claimId`.
Yanıt	`200`; PDF, dosya adı `<claimId>.pdf`.
Hatalar	`404 insurance.claim.not_found`, `409 insurance.claim.state_conflict` (`reason: claim_not_submitted`), `503 insurance.document.unavailable`
Webhook	—
Ayrıntı	Hasar Kaydı › Sağlayıcının hasar belgesi

Talep

`POST /api/v1/insurance/leads`


Ne yapar	Teklif vermeyen sigorta tiplerinde alıcının bilgilerini sağlayıcıya talep olarak iletir. Teklif, prim, poliçe ve belge yoktur.
İstek	`insuranceType`, isteğe bağlı `schemaVersion`, tipe göre `policyholder`, tip nesnesi ve `company`, isteğe bağlı `note`.
Yanıt	`201`; `data`: talep (`status: SUBMITTED` ya da `UNKNOWN`).
Hatalar	`412 insurance.type.not_available`, `422 insurance.lead.rejected`, `503 insurance.provider.unavailable`
Webhook	`insurance.lead.submitted`
Ayrıntı	Talep › Talep açma

`GET /api/v1/insurance/leads`


Ne yapar	Taleplerinizi en yeniden eskiye listeler; kişisel veriler maskelidir.
İstek	Sorgu: `limit` (1-100, varsayılan 25), `cursor`, `insuranceType`, `status`.
Yanıt	`200`; `data.items[]`: talep; `pageInfo`.
Hatalar	`422 insurance.validation.invalid` (`field: cursor`)
Webhook	—
Ayrıntı	Talep › Listeleme

`GET /api/v1/insurance/leads/{leadId}`


Ne yapar	Tek bir talebi döner; kişisel veriler maskelidir.
İstek	Yol: `leadId`.
Yanıt	`200`; `data`: talep.
Hatalar	`404 insurance.lead.not_found`
Webhook	—
Ayrıntı	Talep › Okuma

Mutabakat

`GET /api/v1/insurance/reconciliation/summary`


Ne yapar	Dönemin poliçe ve prim toplamlarını bağlantı, para birimi ve primi tahsil eden başına döner.
İstek	Sorgu: `from`, `to`, isteğe bağlı `connectionId`, `insuranceType`, `currency`.
Yanıt	`200`; `data`: `period`, `filters`, `groups[]`, `generatedAt`.
Hatalar	`422 insurance.validation.invalid` (`field: filter.from` ya da `filter.to`)
Webhook	—
Ayrıntı	Mutabakat Raporu › Özet

`GET /api/v1/insurance/reconciliation/orders`


Ne yapar	Özetin arkasındaki siparişleri poliçeleriyle birlikte listeler.
İstek	Süzgeç parametreleri, `limit` (1-100, varsayılan 100), `cursor`.
Yanıt	`200`; `data.items[]`: rapor satırı; `pageInfo`.
Hatalar	`422 insurance.validation.invalid` (`field: filter.*` ya da `cursor`)
Webhook	—
Ayrıntı	Mutabakat Raporu › Satırlar

`GET /api/v1/insurance/reconciliation/export`


Ne yapar	Rapor satırlarını CSV olarak döner; her poliçe bir satırdır.
İstek	Süzgeç parametreleri, kesilen dosyayı sürdürmek için `cursor`.
Yanıt	`200`; `text/csv`, dosyada en fazla 20.000 sipariş.
Hatalar	`422 insurance.validation.invalid` (`field: filter.*`)
Webhook	—
Ayrıntı	Mutabakat Raporu › CSV

İlgili

Yalnız Sigorta Entegrasyonu: Lunixi ödemesi olmadan uçtan uca akış
Akışlar: kimlik doğrulama, Idempotency-Key ve hata zarfı
Webhook Olayları: olayların yükü ve abonelik
Hata Kodları: bütün kodların anlamı

Mutabakat Raporu Sigorta Tipleri ve Şemalar