---
# System prepended metadata

title: 'Kontrat Yönetimi Projesi [TR]'

---

## Kontrat Yönetimi

Doküman ve Kontrat Yönetimi projesi, tüm dokümanların verimli bir şekilde yönetilmesini sağlamayı hedeflemektedir. Bu projede, belgelerin dijital olarak saklanması, sınıflandırılması ve erişilebilirliği kolaylaştırılacaktır. 

Dokümanlar üzerinde yapılan değişikliklerin sürüm kontrolü yapılacak ve geçmiş versiyonlara erişim sağlanabilecektir. 

Tek bir platform üzerinden versiyon, personel, servis kontrolü gibi kontrollerin gerçekleştirilerek doküman süreçlerinin takip edilmesini sağlayan bir modül tasarlanacaktır.

Yeni teknolojiler kullanılarak oluşturulacak Doküman ve Kontrat Yönetimi projesi, parametrik bir yapıda hazırlanacak ve özel hizmet olarak sunulacaktır.

Döküman veya döküman grupları, belirli kontroller ile eksik belgelerin veya güncellenmesi gereken sözleşmelerin müşteriye bildirim hizmeti olarak parametrik olarak oluşturulmayı hedeflemektedir.

Bu proje kapsamında mevcut DMS'nin gerçekleştirdiği kontroller ve görüntüleyici kontrollerini yönetme işlemlerini gerçekleştireceğiz.

Bu proje ile şirketin doküman yönetimi süreçlerinin optimize edilmesi ve verimlilik artışı sağlanması hedeflenmektedir.


## Hedefler
- Uçtan uca kontrat yönetiminin sağlanması.
- Ayrı bir platformun oluşturulması ve doküman yönetimini desteklemesi.
- Dokümanların kaydedilmesi ve kurallara uygunluğunun kontrol edilmesi.
- Doküman setlerinin hazırlanması ve yönetimi.
- Doküman şablonlarının oluşturulması ve kullanılması.
- Dokümanların saklandığı platform ile entegrasyonun sağlanması.
- Endorsement entegrasyonu ile kural setlerimize uyan dokümanların onay mekanizmalarının çalıştırılması.
- Clientlar'ın sözleşme ve doküman süreçlerinde kullanabilecekleri API'lerin geliştirilmesi.
- Kural Yönetim Modülü.
- Doküman Yüzdesi Modülü: Müşterilere belirli bir doküman kısmını (örneğin, imza sayfası gibi) izleyebilme imkanı sunulması.
- Format Dönüştürücü Modülü.


## Definitions

- Doküman Türü: Belirli bir dokümanın kategori veya tipi.
- Doküman Dili: Dokümanın dilini ifade eden bir parametre (Türkçe, İngilizce, Arapça vb.).
- Kurallar: Dokümanların uyması gereken belirli yönergeler veya kriterler.
- Versiyon (Kural Seti): Kuralların ve yönergelerin belirli bir sürümü veya varyasyonu.
- Kanal (Kural Seti): Kuralların uygulanacağı izin verilecek olan dağıtım kanalı (örneğin, mobil, bayii).
- Doküman için Servis Kontrolü: Belirli bir dokümanın eksik veya güncellenmesi gereken sözleşmeler gibi kontrolleri.
- Doküman Grupları: İlgili dokümanların belirli kategorilere veya gruplara ayrıldığı yapılar.


# Definition


### Document Definitions
**3 type document definitions** 
1. Şeması Olmayan, Render Edilmeyen, İmage Olarak Eklenen Doküman Tipi:
Bu doküman tipi, görüntü olarak eklenebilen, render edilmeyen ve belirli bir şemaya sahip olmayan dokümanları ifade eder. Örneğin, bayi sürecindeki kimlik fotokopisi gibi belgeler bu kategoriye örnek olarak verilebilir. 


```json= 
{
  "name": "identification-certificate-nc",
  "title": {
    "tr-TR": "Nufus Cuzdani",
    "en-EN": "Birth Certificate"
  },
  "tags": [
    {
      "tag": "id-card",
      "id": "reference"
    },
    {
      "tag": "customer-info",
      "id": "#mernis.response.$.tcknno"
    },
    {
      "tag": "mernis",
      "id": "owner"
    }
  ],
  "upload": {
    "sca-required": false,
    "allowed-clients": [
      "web-ib",
      "mobile-ib",
      "dealer",
      "direct-sales"
    ],
    "allowed-formats": [
      {
        "format": "png",
        "max-size-kilobytes": 512
      },
      {
        "format": "jpg",
        "max-size-kilobytes": 1024
      }
    ]
  },
  "optimize": [
    {
      "transform-to": "jpg",
      "size": true
    }
  ],
  "starting-transition-name" : "trx-upload-document",
  "operation": {
    "control-layout": {
      "view-tags": [
        {
          "tag": "mernis",
          "parameter-key": "owner"
        }
      ]
    },
    "[OBSOLUTE]document-manuel-control": true
 
  },
  "metadata": {
    "form":"",
    "template":"",
    "valid-after-upload": "6M",
    "offical-expiry": "#mernis.response.$.information.expiryAt"
  },
  "status": "active",
  "base-status": "active"
}
```
* **valid-after-upload**: validity period of document for contract validation after upload. Values can be *days ex:5d, months ex:5m, and years ex:2y. Operator can alter this datre manually.
* **offical-expiry**: Offical document expiry date comes from tag data. Operator can alter this date manually.
    * Direct input sample "1997-07-16T19:20+01:00"
* **max-size-kilobytes**: Allowed maximum size(kilobyte) per document. This limit controlled while uploding document in client side and also server side.
* **transform-to**: If some formats have to converted to another format before storing, target format has to suplied.
* **optimize**: If the file is to be optimized before it is saved, it is set to true.
* **tags**: dokumanı alabilcegime dair sorulari cevaplayan service entegrasyonu (örneğin müşteri 70 yaş üstüyse ekstra belge alımı için)
* **allowed-clients**: hangi clientlar bu dokumanı yükleyebilir.
* **sca-required**: 2 factor banka herhangi bir talimatı 2 birleşenli alabilir.
* **allowed-formats**:izin verilen format ve max sizeleri
* **metadata**: birden fazla kural field i istenebilir.
* **operation**: operasyon kontrollerinin tanımlandıgı alan


2. Şeması Olan Dijital Olarak Onaylanan Doküman Tipi:
Bu doküman tipi, belirli bir şemaya sahip olan ve dijital olarak onaylanabilen dokümanları ifade eder. Örneğin, KVKK (Kişisel Verilerin Korunması Kanunu) gibi onay formları bu kategoriye örnek olarak verilebilir. Bu dokümanlar sabit bir şemaya sahiptir ve versiyonlarının tanımlanması gerekmektedir.



```json= 
{
  "name": "gdpr-consent",
  "title": {
    "tr-TR": "KVKK Bilgilendirme Onayi",
    "en-EN": "GDPR Approval"
  },
  "tags": [
    {
      "tag": "gdpr",
      "id": "reference"
    }
  ],
  "online-sign": {
    "version": 2.2,
    "sca-required": false,
    "template": {
      "tr-TR": "consent-gdpr-2.2-tr-html",
      "en-EN": "consent-gdpr-2.2-en-html"
    },
    "allowed-clients": [
      "ib",
      "mobile-ib",
      "idm-account"
    ]
  },
  "status": "active",
  "base-status": "active"
}
```
3. Şeması Olan ve Islak İmzalı Olarak Yüklenen Doküman Tipi:
Bu doküman tipi, belirli bir şemaya sahip olan ve aynı zamanda ıslak imzalı olarak yüklenen dokümanları ifade eder. Bu tip dokümanlar genellikle şubenin ilgilendiği belgelerdir. Örneğin, müşteriye imzalatılan belgelerin taranarak yüklenmesi bu kategoriye örnek olarak verilebilir.


```json= 
{
  "name": "address-statement",
  "title": {
    "tr-TR": "Adres Beyanı",
    "en-EN": "Address Statement"
  },
  "tags": [
    {
      "tag": "address-statement-tag",
      "id": "reference"
    }
  ],
  "upload": {
    "sca-required": false,
    "allowed-clients": [
      "web-ib",
      "mobile-ib",
      "dealer",
      "direct-sales"
    ],
    "allowed-formats": [
      {
        "format": "png",
        "max-size-kilobytes": 512
      },
      {
        "format": "jpg",
        "max-size-kilobytes": 1024
      }
    ]
  },
  
  "render": {
    "version": 6.2,
    "template": {
      "tr-TR": "address-statement-6.2-tr-html",
      "en-EN": "address-statement-6.2-en-html"
    },
    "allowed-clients": [
      "ib",
      "mobile-ib",
      "idm-account"
    ]
  },
  "optimize": [
    {
      "transform-to": "jpg",
      "size": true
    }
  ],
  "status": "active"
}
```


## Document Group

```json=
{
  "name": "address-confirmation-group",
  "status": "active",
  "title": {
    "tr-TR": "Adres Teyit Grubu",
    "en-EN": "Address Confirmation Group"
  },
  "document": [
    "gas-bill",
    "water-bill",
    "electricity-bill",
    "residence-certificate",
    "property-deeds"
  ]
}
```

* **at-least-required-document**: At least document count to validate to document group reqirement.

## Contract Definition

```json=
{
  "name": "ekyc-customer-application",
  "status": "active",
  "tags": [
    {
      "tag": "ekyc-application",
      "id": "reference"
    }
    
  ],
  "documents": [
      {
        "name": "gdpr-consent",
        "use-existing": "any-valid | uploaded-by-contract | never",
        "required": true
      },
      {
        "name": "channel-usage-consent",
        "use-existing": "any-valid",
        "min-version": 2.2,
        "required": true
      },
      {
        "name": "salary-certificate",
        "use-existing": "never",
        "required": false
      }
    ],
  "document-group": [
      {
        "name": "address-confirmation-group",
        "at-least-required-document": 2,
        "required": true
      },
      {
        "name": "identification-certificate-group",
          "at-least-required-document": 1,
        "required": true
      }
    ],
  "validations": [
      {
        "type": "all-valid"
      },
      {
        "type": "decision-table",
        "decision-table": "dmn-ekyc-document-validation"
      }
    ]
  
}
```
* **validations** The contract can different include multiple validation methods. All validation methods return validation status and a multilingual message set.
    * **all-valid** just checks all reqired document is uploaded.
    * ~~script is expression (C# ? Javscript ? FEEL ?) based valdiation~~
    * **decision-table** is DMN table.


## Callback Definition

Workflow un her step ınde call back tanımlanabılır.
```json=
[
  {
    "name": "ekyc-callback",
    "url": "https://api.burgan.com.tr/ekyc/..../document-tracking",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
      
  },
  {
    "name": "loan-callback",
    "url": "https://api.burgan.com.tr/retail-loan/..../document-tracking",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
  }
]
```

# Instance (Application)

## Lifecycles (Status)

### Document

#### (Upload) Document

```mermaid
stateDiagram-v2
    ns: not-started
    up: uploaded
    wc: waiting-control
    ac: auto-control
    v: validated
    nv: not-validated

    ns --> up : upload-document
    up --> wc : auto
    up --> ac : auto
    ac --> v : valid
    wc --> v : valid
    ac --> nv : not-valid
    wc --> nv : not-valid
    nv --> v : valid
```

#### (Render & Wet-Sign & Upload) Document

```mermaid
stateDiagram-v2
    ns: not-started
    r: rendered
    up: uploaded
    wc: waiting-control
    ac: auto-control
    v: validated
    nv: not-validated

    ns --> r : render
    r --> up : upload-document
    up --> wc : auto
    up --> ac : auto
    ac --> v : valid
    wc --> v : valid
    ac --> nv : not-valid
    wc --> nv : not-valid
    nv --> v : valid
    ns --> v : validated-with-existing
```


#### (Render & Online-Sign) Document

```mermaid
stateDiagram-v2
    ns: not-started
    r: rendered
    v: validated
    nv: not-validated

    ns --> r : render
    r --> v : valid
    r --> nv : not-valid
```


### Document Group

```mermaid
stateDiagram-v2

    ns: not-started
    ip: in-progress
    v: validated
    nv: not-validated

    ns --> ip : start
    ip --> v : valid
    ip --> nv : not-valid
    
```

### Contract

```mermaid
stateDiagram-v2

    ns: not-started
    ip: in-progress
    v: validated
    nv: not-validated

    ns --> ip : start
    ip --> v : valid
    ip --> nv : not-valid
    
```


## Start Instance


POST https://api.burgan.com.tr/amorphie.contract/contract/
Header **Accept-Language** has to set
### Request
```json=
{
  "id": "439b2e3a-4e40-4d44-a933-4eb1ef3bd887",
  "contract-name": "ekyc-customer-application",
  "reference": "38552069000",
  "owner": "38552069008",
  "callback-name": "web-ui-ekyc-callback"
  "process": {
    "client": "ekyc-application",
    "user": "34455667789",
    "behalf-of-user": "34455667789",
    "name": "ekyc-process",
    "id": "f220740a-5466-4bbd-8b82-3eaa97c2c15f",
    "state": "load-document",
    "action": "web-ui-document-load",
  }
}
```

* **reference** müşteri no olabilir, login name(u05762) olabilir. 
* **owner** required sadece tckn/vkn alabilir.
* **user** işlemi yapan kişi
* **behalf-of-user** vekalet eden kişi


### Generic Response for Contract Status
```json=
{
  "id": "88acf003-94f6-497e-90dc-bdd90c45fd12",
  "status": "in-progress",
  "document": [
    {
      "name": "identification-certificate-nc",
      "title": "Nufus Cüzdanı",
      "status": "validated",
      "required": "true",
      "upload": {
        "sca-required": false,
        "allowed-clients": [
          "web-ib",
          "mobile-ib",
          "dealer",
          "direct-sales"
        ],
        "allowed-formats": [
          {
            "format": "png",
            "max-size-kilobytes": 512
          },
          {
            "format": "pdf",
            "max-size-kilobytes": 1024
          }
        ]
      }
    },
    {
      "name": "gdpr-cosent",
      "title": "KVKK Bilgilendirme Onayi",
      "status": "not-started",
      "required": "true",
      "render": true,
      "online-sign": {
        "version": 2.2,
        "sca-required": false,
        "alloved-clients": [
          [
            "ib",
            "mobile-ib",
            "idm-account"
          ]
        ]
      }
    },
    {
      "name": "address-statement",
      "title": "Adres Beyanı",
      "status": "not-started",
      "required": "true",
      "render": true,
      "upload": {
        "sca-required": false,
        "allowed-clients": [
          "web-ib",
          "mobile-ib",
          "dealer",
          "direct-sales"
        ],
        "allowed-formats": [
          {
            "format": "png",
            "max-size-kilobytes": 512
          },
          {
            "format": "pdf",
            "max-size-kilobytes": 1024
          }
        ]
      }
    }
  ],
  "document-groups": [
    {
      "name": "address-confirmation-group",
      "status": "in-progress",
      "title": "Adres Teyit Grup Belgeleri",
      "at-least-required-document": 1,
      "document": [
        {
          "name": "water-bill",
          "title": "Su faturasi",
          "status": "waiting-control",
          "upload": {
            "sca-required": false,
            "allowed-clients": [
              "web-ib",
              "mobile-ib",
              "dealer",
              "direct-sales"
            ],
            "allowed-formats": [
              {
                "format": "png",
                "max-size-kilobytes": 512
              },
              {
                "format": "pdf",
                "max-size-kilobytes": 1024
              }
            ]
          }
        },
        {
          "name": "gass-bill",
          "title": "Dogalgaz Faturasi",
          "status": "not-started",
          "upload": {
            "sca-required": false,
            "allowed-clients": [
              "web-ib",
              "mobile-ib",
              "dealer",
              "direct-sales"
            ],
            "allowed-formats": [
              {
                "format": "png",
                "max-size-kilobytes": 512
              },
              {
                "format": "pdf",
                "max-size-kilobytes": 1024
              }
            ]
          }
        }
      ]
    }
  ]
}
```



## Render Document

POST https://api.burgan.com.tr/amorphie.contract/contract/{id}/documents/{name}/render
POST https://api.burgan.com.tr/amorphie.contract/contract/{id}/documents/{name}/render/pdf

POST https://api.burgan.com.tr/amorphie.contract/document/{name}/owner/{owner}/render
POST https://api.burgan.com.tr/amorphie.contract/document/{name}/owner/{owner}/render/pdf

### Request

All requests must include json data body for support templating while render.

```json=
{
  "data": {
    "customer": {
      "firstName": "Ahmet",
      "lastName": "Halil"
    }
  }
}
```

### Response 

Client display or prints rendered document.

```json=
{
  "content": "base64;pdf 0xsdad"
}
```

## Upload Document

POST https://api.burgan.com.tr/amorphie.contract/contract/{id}/documents/{name}
POST https://api.burgan.com.tr/amorphie.contract/document/{name}/owner/{owner}

### Request

Content-Type: application/pdf
Content-Transfer-Encoding: base64

> https://www.w3.org/Graphics/JPEG/

### Response
```json=
{
  "status": "uploaded"
}
```
### Additional Properties of Document
PATCH  https://api.burgan.com.tr/amorphie.contract/contract/{id}/documents/{name}
PATCH https://api.burgan.com.tr/amorphie.contract/document/{name}/owner/{owner}


```json=
{
  "data": {
    "customer": {
      "notes": "sgk belgesi eklenmelir."
    }
  }
}
```

## Get Instance

GET https://api.burgan.com.tr/amorphie.contract/contract/{id}


[Response ](/Instance (Application))


## Query Instance

GET https://api.burgan.com.tr/amorphie.contract/contract/

Query Params
* contract-name
* owner
* process...
* page-size & page


## Get Document

GET https://api.burgan.com.tr/amorphie.contract/contract/{id}/documents/{name}
GET https://api.burgan.com.tr/amorphie.contract/document/{name}/owner/{owner}

GET https://api.burgan.com.tr/amorphie.contract/contract/{id}/documents/{name}/schema
GET https://api.burgan.com.tr/amorphie.contract/document/{name}/owner/{owner}/schema


## Callback 
When state of any document is changed, callback url is consumed with below body.

```json=
{
  "name": "ekyc-customer-application",
  "status": "in-progress",
  "id": "1180d691-f53d-48fa-a960-aea265267d1d",
  "document": [
    {
      "name": "identification-certificate-nc",
      "status": "waiting-control"
    },
    {
      "name": "gdpr-consent",
      "status": "valid"
    }
  ],
  "document-groups": [
    {
      "name": "address-confirmation-group",
      "status": "in-progress",
      "document": [
        {
          "name": "water-bill",
          "status": "waiting-control"
        },
        {
          "name": "gas-bill",
          "status": "not-started"
        }
      ]
    }
  ]
}
```

# Instance (Manuel Ops)



## Approve/Reject Document

POST https://api.burgan.com.tr/amorphie.contract/contract/{id}/documents/{name}/transition/{transition-name}
POST https://api.burgan.com.tr/amorphie.contract/documents/{id}/transition/{transition-name}



## Request More Document

POST https://api.burgan.com.tr/amorphie.contract/contract/{id}/documents
{
    document tipi
}





# Rule Management Module
Biz ve iş birimimiz için kullanabileceğimiz bir kural (rule) modülü geliştirilecektir.

Uygulama (APP) içerisinde, yapılacak tüm işlemlerin tanımları tutulacak ve bir belgenin dönüştürüleceği bilgisi, küçültme işleminin gerekip gerekmediği ve ne kadar küçültülebileceği gibi bilgiler müşterilerden hangi formatlarda alınabilir ve hangi formatta saklanmalıdır sorularına yanıt sağlayacaktır.

Uygulama (APP) dışında, versiyon, son kullanma tarihi (expritedate), geliş kanalı, doküman tipi gibi alanlara bakarak, sonuç tag servisiyle iletişim kurup mob onayının gerekip gerekmediğini, gerekiyorsa hangi rule koduyla mob'a sorulacağını belirleyebileceğimiz bir tasarım kurgulayacağız.

Admin tarafından oluşturulan kural tanımına (rule definition) göre doküman alanlarını da belirleyeceğiz. Her doküman için kendine özgü bir kural tanımı yapılabilir, bu nedenle her doküman için farklı bir alan seti beklenmesi mümkündür.

Örneğin, aynı doküman grubunda yer alan bir doküman için kural seti 3 farklı alandan oluşabilirken, aynı gruptaki başka bir doküman için farklı bir alan seti bekleniyor olabilir. Bu nedenle, her doküman için özel bir kural tanımı yapılacaktır.

olası kullanılacak teknolojiler

esicion-table
zeebe-comand-dmn
c# roslyn–
zeebe feel expression
# Format Converter Module (Format Dönüştürücü Modülü)

Gönderilen dokümanı istenilen formata dönüştürebilen teknik bir modül geliştirilecektir. Bu modül, doküman dönüşümü için uygun formatların belirlenmesi ve dönüşüm işlemlerinin gerçekleştirilmesini sağlayacaktır.

Modül, Rule Manager kullanarak hangi dokümanın hangi formata dönüştürülebileceğini belirleyecektir. Bu kapsamda, dokümanın mevcut formatı ve hedef format bilgisi incelenerek dönüşüm işlemi yapılacak formata karar verilecektir.

Dönüştürme işlemleri, ilgili dönüştürme kütüphaneleri veya servisler kullanılarak gerçekleştirilecektir. Örneğin, PDF dosyalarının JPG formatına dönüştürülmesi için uygun bir PDF dönüştürme kütüphanesi veya servisi kullanılacaktır.

Örnek olarak:

- PDF dosyalarının JPG formatına dönüştürülmesi
- DOCX dosyalarının JPG formatına dönüştürülmesi
- XLSX dosyalarının JPG formatına dönüştürülmesi
# 
# Document Percentage Module (Doküman Yüzdesi Modülü)

Dosya boyutlarını gereklilikleri kadar küçültebilen bir modül geliştirilecektir. Bu modül, Rule Manager kullanılarak gereken boyutlarının sorgulanmasını yapacak ve küçültme işlemine izin veren ve tanımlanan kurallara uygun olan dosyaları küçültecektir.

Örneğin, bir dosyanın boyutu 5000px * 5000px ise ve belirlenen kurala göre boyutun 2000px * 2000px'e küçültülmesi gerekiyorsa, modül bu küçültme işlemini gerçekleştirecektir.

# Dosya Gerekli Kısım Belirleme
40 sayfalık bir PDF içerisinde bizim için gerekli olan sayfaların belirlenip saklanacağı bir modül geliştirilecektir. Bu modül, belirli sayfaların seçilmesine ve saklanmasına olanak sağlayacaktır.

sorular:
Bu kısımda şimdilik mob a yaptırabilirsin ekran tasarlanmalı aslı saklanmalı mı?(sorgula)
Burada saklama 2 yöne ayrılabilir birinci aslı saklanır 2.seçili olanda saklanır bizim için birinci tc altında dosyada tutulur 2 dosya documant defination karsılığı olur birinci bişi ifade etmiyor hale gelir.
40 sayfa > 1 sayfa

# Callback Module (Geribildirim Modülü)

Clientlar kendi API'leri için tanımladıkları URL ve güvenlik bilgileriyle geri bildirim (callback) çalıştırmamızı sağlayacak bir modül geliştirilecektir. Bu modül, geri bildirim senaryolarını yönetmek için kullanılacaktır.

Bir geri bildirim senaryosu için 3 istekte bulunmak mümkün olacaktır. Varsayılan olarak beklediğimiz istekler, tarafımızdan tanımlanmış olan requestlerdir. Ancak istenirse, geri bildirim isteği, müşteriler tarafından callback tanımı (JSON modeli) ile üzerine yazılabilir hale getirilebilecektir.

Workflow içerisinden doğrudan bir geri bildirim atmak yerine, kendi callback API'mizi çağıracağız. API, bu isteği ilk aldığında tanımlamalara bakarak bir kuyruk kaydı oluşturacak ve bu kayıtları işleyen bir worker yazılacaktır.

Clientlar istedikleri takdirde, son bir aylık veya örneğe dayalı geri bildirimleri tekrar çalıştırmak için bir istekte bulunabilecekler.









