Platform Entegrasyon Gereksinimleri

InsurGateway’e entegre olacak platformların açması gereken HTTP servislerin ve uyulması gereken ortak sözleşmenin tanımıdır.

İletişim yönü: InsurGateway → Platform. InsurGateway, platform tarafında açılan endpoint’leri çağırır; platform standart formatta cevap döndürür.

1. Platform Tarafında Açılacak Endpoint’ler

#	Path	Amaç	Detay
1	`POST /PushNotification`	Tüm bildirimlerin tek giriş noktası. Tip ayrımı `NotificationType` ile yapılır.	ServisIhtiyaclari/PushNotification-API.md
2	`POST /GetIncomingLogPayload`	Daha önce iletilmiş incoming log gövdesinin geri okunması.	ServisIhtiyaclari/GetIncomingLogPayload-API.md
3	`POST /GetOutgoingLogPayload`	Daha önce iletilmiş outgoing log gövdesinin geri okunması. (Elastic seçeneği aktifse gerekmez.)	ServisIhtiyaclari/GetOutgoingLogPayload-API.md

Path adları yukarıdaki şekilde kullanılır. Tam URL’ler, platform tarafından bildirilen Base URL’in sonuna bu path’lerin eklenmesiyle oluşur.

2. Platform Tarafından Sağlanması Gereken Bilgiler

Test ve canlı ortam için ayrı ayrı InsurGateway operasyon ekibine iletilir:

Bilgi	Açıklama
Platform Base URL	Endpoint’lerin yayınlandığı kök URL.
API Key	Her isteğin `x-api-key` header’ında gönderilecek gizli değer. Platform tarafından üretilir.
Authorization Header değeri (opsiyonel)	Sağlandığı durumda her isteğe `Authorization: <bu değer>` olarak eklenir.

3. Header’lar

InsurGateway her isteğe aşağıdaki header’ları ekler:

Content-Type: application/json
x-api-key: <platform tarafından bildirilen API key>
Authorization: <opsiyonel; platform tarafından bildirildiyse>

Header doğrulaması platform sorumluluğundadır. Doğrulama başarısızsa 401/403 döndürülmelidir.

4. Standart İstek Zarfı

Tüm endpoint’lere gelen istekler aşağıdaki yapıdadır:

1 {
2   "ReferanceNo": "string",
3   "SubReferanceNo": "string",
4   "RequestKeyValueSet": null,
5   "RequestObject": { ... }
6 }

Alan	Açıklama
`ReferanceNo`	İş referans numarası. Aynı bildirim retry sırasında aynı değerle gönderilir; idempotency anahtarıdır.
`SubReferanceNo`	HTTP çağrısına özel ~30 karakterlik benzersiz id (loglama). Retry’da değişir.
`RequestKeyValueSet`	Kullanılmaz.
`RequestObject`	İş yükü; endpoint başına farklı yapıdadır.

5. Standart Cevap Zarfı

1 {
2   "ResultStatus": {
3     "Status": "Success",
4     "Explanation": null
5   },
6   "Result": null
7 }

Alan	Açıklama
`ResultStatus.Status`	`"Success"`, `"Error"`, `"InProgress"`, `"Info"`, `"Warning"`. Yalnızca `"Success"` başarılı kabul edilir.
`ResultStatus.Explanation`	Hata açıklaması.
`Result`	Bildirim servislerinde `null`. Sorgu servislerinde dolu döner.

6. Başarı / Hata Tablosu

HTTP Kod	Cevap Gövdesi	Sonuç	Retry?
`200`	`Status="Success"`	Başarı	Hayır
`200`	`Status≠"Success"`	Hata	Evet (yalnızca push notification)
`3xx`/`4xx`/`5xx`	—	Hata	Evet (yalnızca push notification)
Bağlantı kopması/timeout	—	Hata	Evet (yalnızca push notification)

Başarı kabul edilmesi için hem HTTP 200, hem de gövdede Status="Success" gerekir. Sorgu servislerinde (Get*) otomatik retry uygulanmaz.

7. Retry Politikası (Yalnızca Push Notification)

Bekleme süreleri: 3 sn → 10 sn → 1 dk → 1 saat (≥4. retry)

Maksimum retry sayıları (orijinal hariç):

`NotificationType`	Maksimum Retry	Toplam Deneme
`0` InsuranceCompany	10	11
`1` Proposal	10	11
`2` Policy	10	11
`3` OutgoingLogPayload	5	6
`4` IncomingLogPayload	2	3
`6` BulkPolicyTransfer	5	6
`7` AgentDisabled	5	6
`8` ParameterChange	5	6
`9` ProductUsingChange	5	6

Son retry’da HTTP başlığında IsLastAttemptToReDelivery=true gönderilir.

8. Bildirim Tipleri

`NotificationType`	İsim	Doküman
`0`	InsuranceCompany	PushNotification/0-InsuranceCompany.md
`1`	Proposal	PushNotification/1-Proposal.md
`2`	Policy	PushNotification/2-Policy.md
`3`	OutgoingLogPayload	PushNotification/3-OutgoingLogPayload.md
`4`	IncomingLogPayload	PushNotification/4-IncomingLogPayload.md
`6`	BulkPolicyTransfer	PushNotification/6-BulkPolicyTransfer.md
`7`	AgentDisabled	PushNotification/7-AgentDisabled.md

5 numaralı tip tanımlı değildir.

9. `Payload` Alanı: İki Aşamalı Parse

Bildirim isteklerinde RequestObject.Payload, JSON formatında ancak string olarak gönderilir.

1 "RequestObject": {
2   "NotificationType": 1,
3   "Payload": "{\"ProposalId\":123456,\"IsSuccess\":true}"
4 }

Parse adımları:

HTTP gövdesi JSON olarak parse edilir → RequestObject.Payload bir string’tir.
Bu string ikinci kez JSON parse edilir → ilgili tipin payload nesnesi elde edilir.

10. Idempotency

Aynı ReferanceNo ile aynı bildirim birden fazla kez gönderilebilir (cevap ulaşmadığında, ağ hatasında, Status="Error" döndüğünde). Platform tarafında ReferanceNo üzerinden tekilleştirme yapılmalıdır: aynı referansı taşıyan bir bildirim daha önce başarıyla işlenmişse iş mantığı tekrar yürütülmeden Status="Success" döndürülmelidir.

Sorgu servisleri (GetIncomingLogPayload, GetOutgoingLogPayload) salt-okuma niteliğindedir; idempotency için ek önlem gerekmez.

11. Alternatif: Outgoing Log → Elasticsearch

Outgoing log kayıtları HTTP push yerine doğrudan platform tarafındaki Elasticsearch cluster’ına yazdırılabilir (acente bazında). Bu seçenek aktif olduğunda ilgili acente için bildirim tipi 3 ve GetOutgoingLogPayload kullanılmaz.

Detay: LogStorageProviders/Elastic-Log-Provider.md