Kimlik belgeleri

Kimlik belge kayıtları, müşterilere ait yüklenmiş belgelerin (kimlik ön/arka, imza, ikametgâh, vergi levhası vb.) doğrulama durumunu izler. Belge içeriği API’de dönmez; kayıt ve doğrulama durumu döner.

`GET /v1/customers/identity-documents` — belge listesi

Örnek istek

curl 'https://api.sarraf.pro/v1/customers/identity-documents?idNo=1976926558&pageSize=25' \
  -u 'apiUserId:secretKey'

Sorgu parametreleri

Ortak parametreler için Genel Bakış.

Parametre	Tür	Açıklama
`idNo`	string	Belge sahibi TCKN/VKN
`type`	string	`front`, `rear`, `accord`, `signature`, `addressDoc`, `activeDoc`, `registryDoc`, `taxDoc`, `signDoc`
`channel`	string	Yükleme kanalı: `manual`, `whatsapp`, `idv`, `accord`
`idCheck`	boolean	NVİ kimlik doğrulaması geçti mi
`isApproval`	boolean	idNo doğrulaması yapıldı mı
`isDisabled`	boolean	Verilmezse yalnız geçerli belgeler döner
`startDate` / `endDate`	date-time	`createdAt` aralığı
`updatedSince`	date-time	Artımlı senkronizasyon

Sıralama whitelist’i: createdAt, updatedAt, validityDate. Varsayılan createdAt:asc.

Cevap alanları (liste öğesi)

Alan	Anlam
`id`	Belge kayıt kimliği
`idNo`	Belge sahibi TCKN/VKN
`type`	Belge türü
`channel`	Yükleme kanalı
`fileType`	Dosya türü
`validityDate`	Belge geçerlilik tarihi
`idCheck`	NVİ doğrulaması geçti mi
`isApproval`	idNo doğrulaması yapıldı mı
`isDisabled`	Belge geçersiz mi

Cevap — `200`

{
  "success": true,
  "data": [
    {
      "id": "6aa6aaf0da99cd3fa911edc7",
      "idNo": "1976926558",
      "type": "front",
      "channel": "accord",
      "fileType": "image/png",
      "validityDate": "2031-04-02",
      "idCheck": true,
      "isApproval": true,
      "isDisabled": false,
      "createdAt": "2026-09-13T12:00:00.000Z",
      "updatedAt": "2026-09-13T12:00:00.000Z"
    }
  ],
  "meta": {
    "requestId": "c6c85e42-dd06-4cb3-885b-c0ca551ee866",
    "timestamp": "2026-09-20T09:00:00.000Z",
    "page": 1,
    "limit": 25,
    "total": 114,
    "pages": 5
  }
}

`GET /v1/customers/identity-documents/{id}` — belge detayı

Liste alanlarına ek olarak description ve data (OCR / doğrulama çıkarım sonucu) döner.

Görsel referansları (imageUrl, imageId vb.) ve AI ham çıktıları hiçbir uçta dönmez. Belge içeriği indirme ucu bu sürümde yoktur.

Örnek istek

curl 'https://api.sarraf.pro/v1/customers/identity-documents/6aa6aaf0da99cd3fa911edc7' \
  -u 'apiUserId:secretKey'

Cevap — `200`

{
  "success": true,
  "data": {
    "id": "6aa6aaf0da99cd3fa911edc7",
    "idNo": "1976926558",
    "type": "front",
    "channel": "accord",
    "fileType": "image/png",
    "validityDate": "2031-04-02",
    "idCheck": true,
    "isApproval": true,
    "isDisabled": false,
    "description": null,
    "data": {
      "nameSurname": "ÖRNEK MÜŞTERİ",
      "idNo": "1976926558",
      "birthday": "1985-06-14"
    },
    "createdAt": "2026-09-13T12:00:00.000Z",
    "updatedAt": "2026-09-13T12:00:00.000Z"
  },
  "meta": {
    "requestId": "c6c85e42-dd06-4cb3-885b-c0ca551ee866",
    "timestamp": "2026-09-20T09:00:00.000Z"
  }
}

`POST /v1/customers/identity-documents` — belge görseli yükleme

Bağımsız kimlik veya pasaport belge kaydı oluşturur. Görsel, belge servisine güvenle taşınır ve belge kaydı oluşur.

E-ticaret Müşteri Tanı Formu akışında bu ucu kullanmayın. Görseli doğrudan forma bağlamak için PUT /v1/customers/verifications/{id}/identity-documents/{side} ucunu kullanın. Böylece görsel PDF’ye ve panel onayına aynı form kaydı üzerinden taşınır.

Örnek istek

curl -X POST 'https://api.sarraf.pro/v1/customers/identity-documents' \
  -u 'apiUserId:secretKey' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"idNo": "1976926558", "type": "front", "fileName": "kimlik-on.png", "mimeType": "image/png", "content": "iVBORw0KGgo..."}}'

İstek gövdesi

{
  "data": {
    "idNo": "1976926558",
    "type": "front",
    "fileName": "kimlik-on.png",
    "mimeType": "image/png",
    "content": "iVBORw0KGgo...",
    "verificationId": "6a9c7e2bf2fb39feccb3480b"
  }
}

Alan	Tür	Kural
`idNo`	string	Zorunlu — belge sahibi TCKN/VKN/pasaport no
`type`	string	Zorunlu — `front` veya `rear` (pasaport için yalnız `front` yeterlidir)
`fileName`	string	Zorunlu
`mimeType`	string	`image/jpeg` veya `image/png`
`content`	string	Zorunlu — base64 görsel içeriği, en fazla 8 MiB
`verificationId`	string	Eski entegrasyonlarla uyumluluk için opsiyonel ilişki kimliği; forma bağlı MTF yükleme ucunun yerine geçmez

Cevap — `201`

Yalnız belge metası döner; görsel içerik veya görsel adresi (imageUrl) hiçbir zaman dönmez:

{
  "success": true,
  "data": {
    "id": "6aa6aaf0da99cd3fa911edc7",
    "idNo": "1976926558",
    "type": "front",
    "channel": "accord",
    "fileName": "kimlik-on.png",
    "mimeType": "image/png",
    "createdAt": "2026-09-13T12:00:00.000Z",
    "updatedAt": "2026-09-13T12:00:00.000Z"
  },
  "meta": { "requestId": "...", "timestamp": "..." }
}

Hata	HTTP	Açıklama
Zorunlu alan eksik / tür hatası / boyut aşımı	400	`VALIDATION_FAILED`
`verificationId` bulunamadı	404	`RESOURCE_NOT_FOUND`
Belge yükleme servisi hatası	502	`UPSTREAM_ERROR`

Başlangıç

API'ye Giriş

Müşteriler

Banka

Faturalar

Giderler

KMTS

`GET /v1/customers/identity-documents` — belge listesi

Örnek istek

Sorgu parametreleri

Cevap alanları (liste öğesi)

Cevap — `200`

`GET /v1/customers/identity-documents/{id}` — belge detayı

Örnek istek

Cevap — `200`

`POST /v1/customers/identity-documents` — belge görseli yükleme

Örnek istek

İstek gövdesi

Cevap — `201`

​GET /v1/customers/identity-documents — belge listesi

​Örnek istek

​Sorgu parametreleri

​Cevap alanları (liste öğesi)

​Cevap — 200

​GET /v1/customers/identity-documents/{id} — belge detayı

​Örnek istek

​Cevap — 200

​POST /v1/customers/identity-documents — belge görseli yükleme

​Örnek istek

​İstek gövdesi

​Cevap — 201

`GET /v1/customers/identity-documents` — belge listesi

Örnek istek

Sorgu parametreleri

Cevap alanları (liste öğesi)

Cevap — `200`

`GET /v1/customers/identity-documents/{id}` — belge detayı

Örnek istek

Cevap — `200`

`POST /v1/customers/identity-documents` — belge görseli yükleme

Örnek istek

İstek gövdesi

Cevap — `201`