Reject Endorsement

Reject Endorsement

Sigorta şirketinin, EndorsementRequested (Zeyil İsteği) aşamasındaki bir işin (job) zeyil talebini reddetmesini sağlar. İstek başarılı olduğunda EndorsementRejected (Zeyil Reddedildi) state geçişi tetiklenir; red nedeni işe işlenir, red aksiyonu platforma iletilir ve ilgili taraflara bildirim e-postası gönderilir. Başarılı çağrı gövde döndürmez.

Uç Nokta (Endpoint)

POST {{baseUrl}}/api/offline/jobs/:jobId/endorsements/reject

Content-Type: application/json

Kullanım

Bu servis, platform tarafından açılmış bir zeyil isteği sigorta şirketi tarafından karşılanamadığında kullanılır. Önerilen akış:

1. POST /api/authentication/login ile token alınır.
2. GET /api/offline/jobs ile EndorsementRequested aşamasındaki işler listelenir ve işlenecek jobId belirlenir.
3. GET /api/offline/jobs/:jobId/actions ile zeyil isteğinin detayı (istenen değişiklik, ekler) okunur.
4. GET /api/offline/rejectreasons/2 ile Endorsement kategorisindeki geçerli red nedenleri çekilir. Dönen liste, token’daki sigorta şirketi için tanımlı olanlarla sınırlıdır.
5. Bu servis, seçilen rejectReasonId ve açıklama mesajıyla çağrılır.
6. 204 No Content dönerse iş EndorsementRejected aşamasına geçmiştir. Platform bu işten sonra yeniden zeyil isteği açabilir (EndorsementRejected → EndorsementRequested geçişi tanımlıdır).

Zeyil yapılabiliyorsa bu servis yerine POST /api/offline/jobs/:jobId/endorsements (Make Endorsement) çağrılır.

💡 Red nedeni listesini sabit kodlamayın: IncludedInsuranceCompanies / ExcludedInsuranceCompanies kısıtları nedeniyle geçerli nedenler sigorta şirketine göre değişir. Her zaman rejectreasons servisinden okuyun.

⚠️ İş yalnızca EndorsementRequested aşamasındayken bu servis çağrılabilir. Başka bir aşamadaki iş için çağrı 500 ile OfflineEndorsements.StateTransitionFailed döner. Stage kodları için bknz.

Kimlik Doğrulama

Bu uç nokta geçerli bir JWT erişim token’ı gerektirir. Token, Authentication Login servisinden alınır ve Authorization başlığında gönderilir.

Token’ın aşağıdaki rollerden en az birini taşıması ve Update yetkisine sahip olması gerekir:

⚠️ İşin InsuranceCompanyId değeri token’daki sigorta şirketi listesinde yoksa istek 403 ile OfflineJobs.JobInsuranceCompanyDenied döner. InsuranceCompanyAPIUser rolündeki kullanıcı, kendi sahibi olmadığı bir iş için 403 ile OfflineJobs.JobOwnershipDenied alır.

İstek Parametreleri (Path Variables)

⚠️ jobId yalnızca yoldan alınır. Gövdede jobId göndermek etkisizdir; sunucu bu alanı her zaman yol parametresiyle ezer.

İstek Gövdesi

RejectEndorsementRequest

EndorsementFileRequest (attachment)

⚠️ attachment gönderilirse fileName, contentType ve base64Content alanlarının üçü de zorunlu hâle gelir. Belge, işe DocumentType = Other tipiyle kaydedilir.

Örnek İstek (ek belgesiz):

{
  "message": "Talep edilen zeyil, poliçe şartları kapsamında yapılamamaktadır.",
  "rejectReasonId": 5
}

Örnek İstek (ek belgeli):

{
  "message": "Zeyil reddi gerekçeleri ekteki belgede detaylandırılmıştır.",
  "rejectReasonId": 5,
  "attachment": {
    "fileName": "rejection_reasons.pdf",
    "contentType": "application/pdf",
    "base64Content": "JVBERi0xLjAK"
  }
}

İstek Gövdesi Şeması (JSON Schema)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "RejectEndorsementRequest",
  "type": "object",
  "required": ["message", "rejectReasonId"],
  "properties": {
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000
    },
    "rejectReasonId": {
      "type": "integer",
      "format": "int32",
      "exclusiveMinimum": 0,
      "maximum": 2147483647,
      "$comment": "ReasonCategory = Endorsement olan kayıtlar. Liste: GET /api/offline/rejectreasons/2 — https://docs.insurgateway.com/offline-constants"
    },
    "attachment": { "$ref": "#/$defs/EndorsementFileRequest" }
  },
  "$defs": {
    "EndorsementFileRequest": {
      "type": "object",
      "required": ["fileName", "contentType", "base64Content"],
      "properties": {
        "fileName": { "type": "string", "minLength": 1 },
        "contentType": { "type": "string", "minLength": 1 },
        "base64Content": {
          "type": "string",
          "minLength": 1,
          "contentEncoding": "base64"
        }
      }
    }
  }
}

💡 Şemada additionalProperties: false bilinçli olarak yoktur: API bilinmeyen alanları yok sayar, isteği reddetmez.

Başarılı Yanıt (204 No Content)

Zeyil talebi başarıyla reddedildiğinde HTTP 204 No Content döner. Yanıt gövdesi yoktur.

Bu noktada sunucu tarafında gerçekleşenler:

💡 İşlemin sonucunu doğrulamak için GET /api/offline/jobs/:jobId/actions çağrılarak oluşan red aksiyonu okunabilir.

Hatalı Yanıt (400 Bad Request)

Alan ve red nedeni doğrulamaları başarısız olduğunda ApiResponse zarfı içinde alan bazlı hata listesi döner.

Response nesnesi:

Alan doğrulama hatası:

{
  "Status": false,
  "Code": "Validation.General",
  "Message": "One or more validation errors occurred",
  "Response": [
    { "Field": "Message", "Message": "Message is required." },
    { "Field": "RejectReasonId", "Message": "RejectReasonId must be greater than zero." }
  ]
}

Alan doğrulama mesajları:

Red nedeni doğrulama hataları — Response[].Field alanında dönen kodlar:

{
  "Status": false,
  "Code": "Validation.General",
  "Message": "One or more validation errors occurred",
  "Response": [
    {
      "Field": "JobRejectReason.InvalidRejectReasonCategory",
      "Message": "The reject reason must be in the Endorsement category."
    }
  ]
}

⚠️ Model binding hataları (örneğin rejectReasonId alanına metin gönderilmesi veya bozuk JSON) doğrulamadan önce oluşur ve ApiResponse zarfı yerine farklı bir gövdeyle 400 dönebilir. İstemci tarafında 400 yanıtları ayrıştırılırken bu durum hesaba katılmalıdır.

Hatalı Yanıt (401 Unauthorized)

Token gönderilmediğinde, geçersiz olduğunda veya süresi dolduğunda HTTP 401 Unauthorized döner. Yanıt gövdesi boştur.

💡 Token’ın süresi dolduysa yanıtta Token-Expired: true başlığı bulunur. Bu durumda POST /api/authentication/refreshtoken ile yeni token alınmalıdır.

Hatalı Yanıt (403 Forbidden)

Token geçerli olduğu hâlde yetki kapsamı yetersiz olduğunda döner.

Örnek Hatalı Yanıt:

{
  "Status": false,
  "Code": "OfflineJobs.JobInsuranceCompanyDenied",
  "Message": "You do not have permission to access jobs of this insurance company.",
  "Response": null
}

Hatalı Yanıt (404 Not Found)

Verilen :jobId ile bir iş bulunamadığında döner.

Örnek Hatalı Yanıt:

{
  "Status": false,
  "Code": "OfflineJobs.JobNotFound",
  "Message": "No job found for the requested JobId: 999999.",
  "Response": null
}

Hatalı Yanıt (500 Internal Server Error)

State machine geçişi sırasında oluşan iş kuralı ihlalleri ve beklenmeyen hatalar bu kodla döner.

Aşağıdaki örnek, red bilgisi platforma iletilemediğinde döner:

{
  "Status": false,
  "Code": "OfflineEndorsements.StateTransitionFailed",
  "Message": "Endorsement state transition failed: Aksiyon bilgileri platforma iletilemedi! Hata Mesajı: Servis yanıt vermedi.",
  "Response": null
}

⚠️ Red bilgisi platforma iletilemediğinde aksiyon geri alınır ve iş EndorsementRequested aşamasına döndürülür; istek yeniden denenebilir.

⚠️ İşin yanlış aşamada olmasından kaynaklanan OfflineEndorsements.StateTransitionFailed bir iş kuralı ihlalidir; 500 dönmesine rağmen isteği aynen tekrarlamak sonucu değiştirmez. Hata mesajındaki aşama bilgisi okunarak işin doğru aşamada olup olmadığı kontrol edilmelidir.