> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.insurgateway.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.insurgateway.com/_mcp/server.

# Platform Entegrasyon Gereksinimleri

# 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:

```json
{
  "ReferanceNo": "string",
  "SubReferanceNo": "string",
  "RequestKeyValueSet": null,
  "RequestObject": { ... }
}
```

| 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ı

```json
{
  "ResultStatus": {
    "Status": "Success",
    "Explanation": null
  },
  "Result": null
}
```

| 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.

```json
"RequestObject": {
  "NotificationType": 1,
  "Payload": "{\"ProposalId\":123456,\"IsSuccess\":true}"
}
```

Parse adımları:

1. HTTP gövdesi JSON olarak parse edilir → `RequestObject.Payload` bir string'tir.
2. 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