VehicleCatalogChange Notification

InsurGateway’in TSB araç kasko değer listesi senkronu araç kataloğunu değiştirdiğinde, platformun kendi katalog kopyasını güncel tutabilmesi için gönderilen bildirim tipidir. Bildirim verinin kendisini değil; yeni katalog sürümünü, değişen kayıt sayısını ve senkron tarihini taşır. Platform, değişiklikleri Araç Kataloğu API’sinden sürüm parametresiyle çeker (bildirim + pull modeli).

Bildirim yalnızca senkron katalogda gerçek bir değişiklik ürettiğinde (güncellenen veya pasifleşen kayıt olduğunda) gönderilir. Katalog içeriği değişmeyen senkron turları bildirim üretmez.

Header ve zarf (envelope) yapısı için: Platform Entegrasyon Gereksinimleri. Bu bildirim tipinde cevap ve retry davranışı aşağıda ayrıca tanımlanmıştır: başarı yalnızca HTTP durum koduna göre belirlenir ve transport hatası dışında retry yapılmaz.

Endpoint

Örnek İstek

curl -X POST "https://platform.ornek.com.tr/insurgw/PushNotification" \
  -H "Content-Type: application/json" \
  -H "x-api-key: 9f3c1e8a-2b4d-1234-5678-deadbeefcafe" \
  -d '{
    "ReferanceNo": "10025_20260810111417345a1b2c_0_0",
    "SubReferanceNo": "a1b2c3d4-e5f6-7890abcdef1234567890",
    "RequestKeyValueSet": null,
    "RequestObject": {
      "NotificationType": 13,
      "Payload": "{\"Version\":\"52C958DB9124FAD5021C7AFA54F2699E0459A5B0\",\"ChangedCount\":1250,\"SyncedAt\":\"2026-08-10T11:14:17.38+03:00\"}"
    }
  }'

ReferanceNo opak bir idempotency anahtarıdır; format {AgentId}_{zamanDamgası+benzersiz}_0_0 şeklindedir ve aynı bildirimin retry’larında değişmez.

Parse Edilmiş Payload

RequestObject.Payload alanı serialize edilmiş bir JSON string’tir; ikinci bir parse sonrasında aşağıdaki yapıya ulaşılır:

{
  "Version": "52C958DB9124FAD5021C7AFA54F2699E0459A5B0",
  "ChangedCount": 1250,
  "SyncedAt": "2026-08-10T11:14:17.38+03:00"
}

Değişikliklerin Çekilmesi (Pull)

Bildirimi alan platform, değişiklikleri Araç Kataloğu API’sinden çeker:

1. GET /api/VehicleCatalogs?version=<Version> — yalnızca bu senkronda değişen kayıtlar döner (pasifleşenler IsActive=false olarak, includeDeactive parametresinden bağımsız dahil). Yanıt sayfalıdır (page, pageSize; üst sınır 1000).
2. Dönen kayıtlar Id ("{BrandCode}-{ModelCode}") üzerinden platform tarafına upsert edilir.

Bildirilen sürüm, bildirim gönderilmeden önce sürüm geçmişine işlenir; version parametresi her zaman çözülebilir. Sürüm geçmişinde bulunmayan bir version istenirse API 400 Bad Request döner.

Bildirim kaçırma ihtimaline karşı önerilen akış, tek bildirime güvenmek yerine sürüm geçmişini sırayla yürütmektir:

1. GET /api/VehicleCatalogs/versions ile sürüm listesini alın (eskiden yeniye sıralı).
2. Elinizdeki sürümü listede bulun; sonrasındaki sürümleri sırayla ?version=<hash> ile çekin.
3. Tüm sürümler işlendiğinde katalog günceldir; en son işlenen sürüm yeni “elinizdeki sürüm”dür.

Uç noktaların ayrıntıları için API referansındaki Vehicle Catalog bölümüne bakınız.

Beklenen Cevap

Platform, bildirimi aldığında HTTP 2xx dönmelidir. InsurGateway başarıyı yalnızca HTTP durum koduna göre belirler; cevap gövdesi değerlendirilmez (gövde boş olabilir).

Başarı:

HTTP/1.1 200 OK

Hata:

2xx dışı herhangi bir HTTP kodu (örn. 500) hata kabul edilir.

HTTP/1.1 500 Internal Server Error

Bildirim ReferanceNo üzerinden idempotent işlenmelidir; aynı ReferanceNo ile yeniden gelen bir bildirim tekrar uygulanmamalıdır. Pull akışı zaten Id üzerinden upsert yaptığı için aynı sürümün tekrar çekilmesi veri bozmaz.

Retry

InsurGateway, bildirimi yalnızca platforma ulaşamadığında (bağlantı hatası / timeout — yani HTTP cevabı hiç alınamadığında) yeniden gönderir. Platformdan dönen 2xx dışı bir HTTP cevabı retry üretmez; hata loglanır ve bildirim düşülür. Bildirim düşse bile değişiklikler kaybolmaz: platform bir sonraki bildirimde (ya da periyodik kontrolde) sürüm geçmişini yürüterek arayı kapatır.