# OBSOLUTE Contract Approval (Sözleşme Onay)

###### tags: `Dijital`

Müşterilerin oanylaması gereken sözleşmeler için onaylatma altyapısı sunar.

## Hedefler

* Müşteriden onay alınacak sözleşme ve içerikler için onay alım işi için talep yapılabilmesi.
* Belge onayının mobil uygulama veya web üzerinden yapılabilmesi.
* Hem anlık talep (*SMS veya Push*) hem de uygulamalara girişte (*on-logon*) alınacak şekilde iş emri oluşturabilmesi.

## Belge Tanımları
Kulanıcılar tarafından onaylanacak tüm belge tiplerinin sistem üzerinde tanımlıdır.

* **name** Belge tipidir. Version ile birlikte tekil anahtardır. Sorgulamalar ve ilişkiler name ve version üzerinden yapılır.
* **title** belgenin kullanıcı arabirimlerinde gösterilecek adıdır.
* **version** belgenin versiyonu [semantic versioning](https://semver.org) olarak kayıt edilir. Sorgulamalarda tilde ve range desteği sağlar.
* **min-version** belgenin minimum versiyonunu belirler. Kişi özelinde müşterinin var olan sözleşmeleri incelenerek var olan sözleşmeler için yeniden sözleşme almamak için uygulanan kontrol verisidir.
* **temlate** belge dönüşümü yapılacak içeriği taşır. Template engine tarafından tanımlı belge adı kullanılır.
* **allow-to-sign** Belgenin fiziksel olarak imzalanıp imzalanamacağı bilgisidir.

{
  "id": "2c66921c-02f4-42fc-9b19-378ee0f4decd",
  "status": "A",
  "name": "retail-digital-bhs",
  "title": "Bireysel Hizmet Sözleşmesi",
  "version": "8.0.0",
  "min-version": ">=6.x.x",
  "template": "retail-digital-bhs-8-0-0",
  "allow-to-sign": false
}

### GET : /contract-approval/document-type
Servisi ile sorgulanan tüm belge kayıtlarına erişilir.

#### Query Parameter

"page-index": 1 
"page-size": 10
"name": "retail-digital%"
"version": "latest"
"page-index": 1 
"page-size": 10
"id":"15802b18-cc2f-4b79-808f-e35b6023782c"
"reference.name":"loan-account"
"reference.id":"TR330006100519786457841326"
"status":"A"
"active-process.id":""
"active-process.name":""

**name** parametresinde SQL Like benzeri parçalı arama yapılabilir.
**version** parametresi ile range, comparison (*>5.0.0 gibi*) verilerek arama yapilabilir.

### POST : /contract-approval/document-type
> **Zeebe Init Message** : content_approval_new_document_type

Servisi ile yeni bir belge tipi kaydı oluşturulur.

#### Body

{
  "name": "retail-digital-bhs",
  "title": "Bireysel Hizmet Sözleşmesi 8.0",
  "version": "8.1.0",
  "min-version":">=6.x.x",
  "template": "retail-digital-bhs-8-1-0"
}

### PATCH : /contract-approval/document-type/{name}/{version}
> **Zeebe Init Message** : content_approval_update_document_type

Servisi ile var olan belge tipi güncelenir.

#### Body

{
  "min-version":">=6.x.x",
  "template": "retail-digital-bhs-8-1-0"
}

## Sözleşme Onay Emirleri
Uygulamalar ve süreçler müşteriden onay alınması beklenen belge tipleri için onaylama emri oluşturur. Bu onaylama emirleri bu altyapı içerisinde içerisinde işlenir.

* **reference-id** uygulamanın callback linkine geri dönerken beslenen anahtar veridir.
* **customer** müşteri TCKN veya VKN bilgisini içerir. Kullanıcı kendi adına veya temsil ettiği organizasyon adına sözleşme onayı veriyor olabilir. Bu ihtiyaç ile tüm emirlerde müşteri ve kullanıcı bilgileri ayrı ayrı gönderilir.
* **user** belgelere onay verecek kullanıcı TCKN numarası.
* **process** ve **process-state** belge onayı hangi akıştan hangi aşamada talep edildiği bilgisini içeirir. Raporlama amacıyla kullanılan verilerdir.
* **max-retry-count** kullanıcıya kaç defa hatırlatma yapılacağı bilgisini içerir. Boş geçilmesi veya 0 değeri verilmesi durumunda sözleşmeler onaylanana kadar sonsuz hatırlatma yapılacak demektir.
* **retry-frequence** hatırlatma frekansını belirlemek için kullanılır. CRON formatında frekans belirlenir. Ayrıca Internet Bankacılığı login anında sözleşme güncelleme uyarısı sunmak için *@logon* keywordu kullanılır.
* **timeout** ile emrin geçerlilik süresi dakika olarak tanımlanır. boş geçilmesi veya sıfır verilmesi durumunda emir sonsuz kabul edilir.
* Müşteriden onay istemek için ilk seferinde **notify-message-template** ile sonraki denemelerde **re-notify-message-template** ile bilgilendirme metni üretilir. Onay isteme metni mobil kullanmayan müşteriler için SMS üzerinden, mobil uygulama kullanan müşteriler için Mobile Push ile iletilir.
* **callback-url** ile işlem tamamlandığında veya işlem içerisinde emri verene sisteme bilgi döner. Eğer sadece işlem tamamlandığında bilgi isteniyorsa **callback-mode** *completed* olarak ayarlanır. Her bir aksiyon için bilgi isteniyorsa **callback-mode** *verbose* olarak ayarlanır. Eğer callback url PUT, POST veya PATCH tipinde ise sabit olarak emir durum paket bilgisi geçilir.
* **render-data** tüm belgelerin ve mesajların oluşturulması için gereken veri paketini içeririr. **render-data-for-log** ise iz kayıtlarının tutulduğu sistemlerde kritik bilgilerin ifşasını önlemek amacıyla gönderilen verilerdir. Opsiyoneldir, gönderilmemesi durumunda iz kayıtları içinde render-data kullanılır.
* **documents** onaylatma emri kapsamında onay istenen belge tanımları verilir. Her bir belge kaydında belge adı **name** ve onay istenen **version** bilgisi geçilir. Specific versiyon için onay istenebilecei gibi *latest* diyerek veya veri göndermeyerek son kayıtlı versiyon için onay istenebilir.

### Örnek Emir Emri

{
  "id": "15802b18-cc2f-4b79-808f-e35b6023782c",
  "creation-process": "document-approval-save",
  "active-process": {
    "id": "15802b18-cc2f-4b79-808f-e35b6023782c",
    "name": "document-approval-save",
    "available-transitions": [
      {
        "name": "document-approval-approve-document",
        "title": "Onayla",
        "form": "process-approve-document-approve"
      }
    ]
  },
  "reference": {
    "name": "retail-loan-vehicle",
    "id": "e39d7d85-22a3-4f35-a5ac-01fffc229635"
  },
  "customer": 38552069000,
  "max-retry-count": 3,
  "retry-frequence": "*/5 * * * *",
  "timeout": "60",
  "notify-message-template": "retail-digital-vehicle-loan-inform",
  "re-notify-message-template": "retail-digital-vehicle-loan-inform-retry",
  "callback-mode": "verbose | completed",
  "callback-url": "POST api.burgan.com.tr/retail-loan-vehicle/approve-state/756a06e1-c808-41da-9dbb-b4ac9ed7fd00",
  "render-data": {
    "name": {
      "first": "Ugur",
      "last": "Karatas"
    }
  },
  "render-data-for-log": {
    "name": {
      "first": "U*****",
      "last": "K******"
    }
  },
  "documents": [
    {
      "name": "retail-digital-bhs",
      "target-version": "latest"
    },
    {
      "name": "retail-digital-gdpr",
      "target-version": "latest"
    },
    {
      "name": "retail-digital-vehicle-loan-payment-plan",
      "target-version": "latest"
    }
  ]
}

### Callback Body

Eğer callback mode *completed* ayarlanmış ise;
* Belge imzaları tamamlandığında (*state=completed*),
* Zaman aşımına uğradığında (*state=timeout*)
* Operatör veya sistem tarafında emir iptal edildiğinde (*state=canceled*)
Callback url çağrılır.

Eğer callback mode *verbose* ayarlanmış ise yukarıda durumlara ek olarak;
* Kullanıcıya ilk onay metni gönderildiğinde,
* Kullanıcıya her hatırlatma metni gönderildiğinde
* Kullanıcının her hangi bir belgeye onay vermesi durumunda
Callback url çağrılır.

{
  "reference-id": "756a06e1-c808-41da-9dbb-b4ac9ed7fd00",
  "customer": 38552069000,
  "user": 38552069000,
  "state":"completed | in-progress | timeout | canceled",
  "retry-count": 2,
  "max-retry-count": 3,
  "channel":"mobile | sms",
  "remaing-timeout": "12",
  "documents": [
    {
      "name": "retail-digital-bhs",
      "version": "6.0.2",
      "state":"has-approved"
    },
    {
      "name": "retail-digital-gdpr",
      "version": "latest",
      "state":"approved"
    },
    {
      "name": "retail-digital-vehicle-loan-payment-plan",
      "version": "latest",
      "state":"in-progress"
    }
  ]
}

### POST : /contract-approval/contract
Yeni bir emir kaydı için kullanmılır. Emirler güncellenemez sadece iptal edilebilir.

### DELETE : /contract-approval/contract/{reference-id}
Var olan bir emri iptale çekmek için kullanılır. Emir normalde iptal edilmez *canceled* statüsüne alınır. İptal anına kadar onayladığı belgeler sistemde onaylı kalır.

### GET : /contract-approval/contract/{page-index}/{page-size}
Servisi emirler sorgulanır. Sonuçlar callback body formatında array olarak döner.

#### Query Parameters

"reference-id": "756a06e1-c808-41da-9dbb-b4ac9ed7fd00"
"customer": 38552069000
"user": 38552069000
"process": "retail-vehicle-loan-application"
"process-state": "document-approval"
"state":"in-progress"

:::warning
Query parametreler birden fazla aynı isimde parametre geçişini destekler. Örneğin "...state=timeout&state=completed..." gibi
:::

## Müşteri Sözleşme İzleme

### GET : /contract-approval/customer/{customer}/{page-index}/{page-size}
Müşteri ve kullanıcı bazında sözleşme durumlarını izlemek için ayrı bir servis sunulmaktadır.

#### Query Parameters

"user": 38552069000

#### Response

{
  "customer": 38552069000,
  "user": 38552069000,
  "documents": [
    {
      "name": "retail-digital-bhs",
      "version": "6.0.2",
      "process": "retail-vehicle-loan-application",
      "process-state": "document-approval",
      "approved-at": "2017-09-08T19:01"
    },
    {
      "name": "retail-digital-gdpr",
      "version": "4.0.2",
      "process": "retail-vehicle-loan-application",
      "process-state": "document-approval",
      "approved-at": "2017-09-08T19:01"
    },
    {
      "name": "retail-digital-vehicle-loan-payment-plan",
      "version": "2.2.0",
      "process": "retail-vehicle-loan-application",
      "process-state": "document-approval",
      "approved-at": "2017-09-08T19:01"
    }
  ]
}

:::danger
History servisleri ayrıca değerlendirip servis kümesine eklemek gerekmektedir.
:::