# Müşteri Belgeleri

https://dev.wisecp.com/tr/musteri-belgeleri

Müşterinin gönderdiği belgeleri okuyan, onaylayan ya da reddeden ve hazır red nedenlerini yöneten altı uç.

## Genel Bakış

Müşteri, belge şemasının istediği alanları doldurup gönderir; bu uçlar o gönderimleri okur ve karara bağlar. Şemanın kendisi ayrı bir iştir ve **Belge Şeması** makalesinde anlatılır.

Her kayıt tek bir alana karşılık gelir ve kendi durumunu taşır. Bir müşterinin bazı belgeleri onaylı, bazıları beklemede olabilir.

## Referans

### Belgeleri Getirme

get/api/v1/admin/clients/{id}/documents

`Clients/GetClientDocuments` admin okundu işaretler

Müşterinin gönderdiği belge kayıtlarını döndürür. Kayıtlar alan kimliğine bağlıdır, filtrelerin tamamı birleşik gelir.

Sorgu parametresi 1

filter_idintVerilirse liste yalnız o filtreden doğan kayıtlara daralır.

Dönen alanlar data — 2

filtersobject[]Dönen kayıtların doğduğu filtreler: `[{ id, name }]`.

recordsobject[] 8 alanBelge kayıtları.

idintBelge kaydının kimliği. İnceleme isteğinde anahtar olarak bunu kullanırsınız.

field_keyintPaylaşılan havuzdaki alanın kimliği.

field_namestringAlan etiketi. Havuzdan tazelenir; alan silinmişse gönderim anındaki kopya döner.

field_typestringGiriş tipi: `input`, `textarea`, `selectbox`, `radio`, `checkbox`, `file`.

field_valuestringMüşterinin gönderdiği değer. Dosya alanlarında yükleme tanımlayıcısını taşıyan JSON.

filter_idintKaydın doğduğu filtre.

statusstring`awaiting`, `verified` ya da `unverified`.

status_msgstringİnceleme notu; red sebebi buraya yazılır.

Hatalar 2

not_found404Müşteri ya da kayıt bulunamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/clients/42/documents' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.ornek.com/api/v1/admin/clients/42/documents', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();

const waiting = body.data.records.filter((r) => r.status === 'awaiting');
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/clients/42/documents');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
$response = Api::Clients()->GetClientDocuments(['id' => 42]);

$waiting = [];
foreach ($response['data']['records'] as $record) {
    if ($record['status'] === 'awaiting') {
        $waiting[] = $record['id'];
    }
}
```

### Belgeleri İnceleme

patch/api/v1/admin/clients/{id}/documents

`Clients/ReviewClientDocuments` admin müşteriye bildirim gider

Kayıtların doğrulama durumunu toplu günceller. Durumu değişen her kayıt için müşteriye bildirim gönderilir.

Gövde 1

statusesobjectzorunlu 2 alanKayıt kimliğine göre durum haritası: `{"<recordId>": {"status": …, "message": …}}`.

statusstringzorunlu`verified`, `unverified` ya da `awaiting`. Başka bir değer taşıyan kayıt sessizce atlanır.

messagestringİnceleme notu. Reddederken sebebi buraya yazın; müşteri bunu görür.

Dönen alanlar data — 3

reviewedboolİnceleme işlendi mi.

verifiedintOnaylanan kayıt sayısı.

rejectedintReddedilen kayıt sayısı.

Hatalar 2

not_found404Müşteri bulunamadı ya da müşterinin hiç kaydı yok.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X PATCH 'https://panel.ornek.com/api/v1/admin/clients/42/documents' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"statuses":{"51":{"status":"verified"},"52":{"status":"unverified","message":"Belge okunmuyor, lutfen daha net bir kopya gonderin"}}}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/clients/42/documents', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    statuses: {
      51: { status: 'verified' },
      52: { status: 'unverified', message: 'Belge okunmuyor, lutfen daha net bir kopya gonderin' },
    },
  }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/clients/42/documents');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'statuses' => [
            51 => ['status' => 'verified'],
            52 => ['status' => 'unverified', 'message' => 'Belge okunmuyor, lutfen daha net bir kopya gonderin'],
        ],
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
$response = Api::Clients()->ReviewClientDocuments([
    'id'       => 42,
    'statuses' => [
        51 => ['status' => 'verified'],
        52 => ['status' => 'unverified', 'message' => 'Belge okunmuyor, lutfen daha net bir kopya gonderin'],
    ],
]);

$rejected = $response['data']['rejected'] ?? 0;
```

Yanıt 200

```json
{
  "data": {
    "reviewed": true,
    "verified": 1,
    "rejected": 1
  }
}
```

### Belge Kaydını Silme

delete/api/v1/admin/clients/{id}/documents/{record_id}

`Clients/DeleteClientDocument` admin

Müşterinin belge gönderimini siler: o müşterinin bütün doğrulama kayıtları, yüklediği dosyalarla birlikte gider. `record_id` gönderimi belirtir ve yoldaki müşteriye ait olmalıdır.

Dönen alanlar data — 2

deletedboolSilme başarılı mı.

idintGönderilen `record_id` değeri.

Hatalar 3

not_found404Müşteri bulunamadı ya da kayıt yok veya başka bir müşteriye ait.

record_required422Kayıt kimliği eksik.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X DELETE 'https://panel.ornek.com/api/v1/admin/clients/42/documents/51' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/clients/42/documents/51', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/clients/42/documents/51');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
$response = Api::Clients()->DeleteClientDocument([
    'id'        => 42,
    'record_id' => 51,
]);
```

### Red Nedenlerini Listeleme

get/api/v1/admin/clients/document-rejection-reasons

`Clients/GetDocumentRejectionReasons` admin

Hazır red nedenlerini döndürür. Bunlar inceleme sırasında kullanılan sabit metinlerdir.

Dönen alanlar data[]

datastring[]Düz bir metin listesi — burada kimlik yoktur, metnin kendisi kimliktir.

Hatalar 1

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/clients/document-rejection-reasons' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.ornek.com/api/v1/admin/clients/document-rejection-reasons', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/clients/document-rejection-reasons');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
$response = Api::Clients()->GetDocumentRejectionReasons();
```

### Red Nedeni Ekleme

post/api/v1/admin/clients/document-rejection-reasons

`Clients/AddDocumentRejectionReason` admin

Listeye yeni bir hazır neden ekler.

Gövde 1

valuestringzorunluRed nedeni metni.

Dönen alanlar data[]

datastring[]Ekleme sonrası listenin tamamı; eklenen metin tek başına dönmez.

Hatalar 2

value_required422`value` boş.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/clients/document-rejection-reasons' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"value":"Belge okunmuyor, lutfen daha net bir kopya gonderin"}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/clients/document-rejection-reasons', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ value: 'Belge okunmuyor, lutfen daha net bir kopya gonderin' }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/clients/document-rejection-reasons');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['value' => 'Belge okunmuyor, lutfen daha net bir kopya gonderin']),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
$response = Api::Clients()->AddDocumentRejectionReason(['value' => 'Belge okunmuyor, lutfen daha net bir kopya gonderin']);
```

### Red Nedeni Silme

delete/api/v1/admin/clients/document-rejection-reasons

`Clients/DeleteDocumentRejectionReason` admin metinle silinir

Bir nedeni listeden çıkarır. Kimlik değil, metnin kendisi gönderilir.

Gövde 1

valuestringzorunluSilinecek nedenin metni. Listedekiyle birebir aynı olmalı.

Dönen alanlar data[]

datastring[]Geriye kalan nedenler. Eşleşmeyen bir metin listeyi değiştirmez — bir şeyin gidip gitmediğini karşılaştırarak anlarsınız.

Hatalar 2

value_required422`value` boş.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X DELETE 'https://panel.ornek.com/api/v1/admin/clients/document-rejection-reasons' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"value":"Belge okunmuyor, lutfen daha net bir kopya gonderin"}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/clients/document-rejection-reasons', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ value: 'Belge okunmuyor, lutfen daha net bir kopya gonderin' }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/clients/document-rejection-reasons');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['value' => 'Belge okunmuyor, lutfen daha net bir kopya gonderin']),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
$response = Api::Clients()->DeleteDocumentRejectionReason(['value' => 'Belge okunmuyor, lutfen daha net bir kopya gonderin']);
```

## Tuzaklar

> **Listelemek kayıtları okundu işaretler**
> 
> Getirme ucu salt okuma değildir: çağırdığınızda kayıtlar okundu sayılır. Panelde bekleyen belge rozetini izleyen bir entegrasyon, listeyi her yoklamada o rozeti düşürür.

> **İnceleme müşteriye bildirim gönderir**
> 
> Durumu değişen her kayıt için onay ya da red bildirimi gider. Aynı durumu ikinci kez göndermek değişiklik saymaz, ama bir kaydı yanlışlıkla reddedip düzeltmek **iki** bildirim üretir.

> **Red nedeni metniyle silinir**
> 
> Silme isteği kimlik değil `value` alır ve metin birebir eşleşmelidir. Bir boşluk farkı bile kaydı bulamaz.

## İlgili Makaleler

- [Belge Şeması](https://dev.wisecp.com/tr/belge-semasi)
- [Müşteri Uçları](https://dev.wisecp.com/tr/musteri-uclari)