Müşteriler

Cari hesaplar (müşteriler) SarrafPro’nun temel kaydıdır. Bu kaynak okuma uçlarının yanında hızlı cari ekleme ucu da sunar. Müşteri tanı (KYC) süreci için Müşteri tanı formları kaynağını kullanın.

`GET /v1/customers` — müşteri listesi

Şirkete ait cari hesapları sayfalı, filtreli ve sıralı listeler.

Örnek istek

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

Sorgu parametreleri

Ortak parametreler (page, pageSize, sort, q) için Genel Bakış sayfasına bakın.

Parametre	Tür	Açıklama
`idType`	string	`person` veya `company`
`idCardType`	string	`idCard`, `passport`, `dlCard`, `other`. `idCard` seçimi; belge türü alanı eksik/null/boş olan eski kayıtları da kapsar.
`recordLevel`	integer	`0` kayıt yok, `1` normal, `2` güvenli, `3` riskli, `4` yasaklı. `0` seçimi alanı olmayan kayıtları da kapsar.
`isVerify`	boolean	Müşteri tanı (doğrulama) durumu
`isValid`	boolean	Kimlik doğrulama (NVİ) durumu
`isPhoto`	boolean	Belge görseli varlığı
`saveType`	string	Kayıt kaynağı: `bank`, `manual`, `idCard`, `accord`
`label`	string	Tekil etiket
`updatedSince`	date-time	Artımlı senkronizasyon

Sıralama whitelist’i: createdDate, lastDate, updatedAt, nameSurname. Varsayılan createdDate:asc.

Cevap alanları (liste öğesi)

id, idNo, idType, idCardType, nameSurname, phone, email, nationality, countries, states, cities, labels, recordLevel, isVerify, isValid, isPhoto, saveType, createdDate, lastDate, updatedAt

Cevap — `200`

{
  "success": true,
  "data": [
    {
      "id": "6a9c7e2bf2fb39feccb3480b",
      "idNo": "1976926558",
      "idType": "tckn",
      "nameSurname": "ÖRNEK MÜŞTERİ",
      "phone": "5001234567",
      "email": "ornek@example.com",
      "nationality": "TR",
      "states": "İstanbul",
      "cities": "Bahçelievler",
      "recordLevel": "normal",
      "isVerify": true,
      "isValid": true,
      "isPhoto": true,
      "saveType": "panel",
      "createdDate": "2026-04-11T08:20:00.000Z",
      "updatedAt": "2026-09-18T14:05: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/{id}` — müşteri detayı

Tek cari hesabın geniş kaydını döner. Liste alanlarına ek olarak: name, surname, ownerName, birthplace, birthday, year, phone2, taxOffice, registryNo, cmpNo, activityName, naceCode, countriesCode, statesCode, address, motherName, fatherName, isAbroad, jobName, ibans, bankCodes, docTypes, customerRelation

Kimlik numarası (idNo) fatura/eşleştirme gereksinimleri nedeniyle tam ve maskesiz döner. PII alanları yalnızca detay ucunda yer alır.

Örnek istek

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

Gömülü uyum özeti

Detay cevabı, ek uç çağırmaya gerek bırakmayan üç uyum bölümü de içerir:

Bölüm	İçerik
`verification`	Müşteri tanı formu durumu: `latestId`, `isApproval`, `isSigned`, `lastFormAt`, `hasPendingForm`
`masak`	idNo bazlı son MASAK sorgusu: `lastQueriedAt`, `types`, `isError` — hiç sorgu yoksa `null`
`events`	Sicil özeti: `count` (toplam olay) ve `latest` (en yeni olay, yoksa `null`). Tam liste için Müşteri sicil olayları

Cevap — `200`

{
  "success": true,
  "data": {
    "id": "6a9c7e2bf2fb39feccb3480b",
    "idNo": "1976926558",
    "idType": "tckn",
    "nameSurname": "ÖRNEK MÜŞTERİ",
    "phone": "5001234567",
    "email": "ornek@example.com",
    "nationality": "TR",
    "states": "İstanbul",
    "cities": "Bahçelievler",
    "recordLevel": "normal",
    "isVerify": true,
    "isValid": true,
    "isPhoto": true,
    "saveType": "panel",
    "createdDate": "2026-04-11T08:20:00.000Z",
    "updatedAt": "2026-09-18T14:05:00.000Z",
    "name": "ÖRNEK",
    "surname": "MÜŞTERİ",
    "birthday": "1985-06-14",
    "taxOffice": "BAHÇELİEVLER",
    "address": "ÖRNEK MAH. ÖRNEK SOK. NO:1",
    "verification": {
      "latestId": "6aa1c2f0da99cd3fa911edc7",
      "isApproval": true,
      "isSigned": true,
      "lastFormAt": "2026-08-02T10:12:00.000Z",
      "hasPendingForm": false
    },
    "masak": {
      "lastQueriedAt": "2026-09-01T07:40:00.000Z",
      "types": [
        "masak",
        "wanted"
      ],
      "isError": false
    },
    "events": {
      "count": 2,
      "latest": {
        "id": "6a90bb11da99cd3fa911aa02",
        "eventDate": "2026-07-19T00:00:00.000Z",
        "recordLevel": "normal",
        "comment": "Sicil güncellemesi"
      }
    }
  },
  "meta": {
    "requestId": "c6c85e42-dd06-4cb3-885b-c0ca551ee866",
    "timestamp": "2026-09-20T09:00:00.000Z"
  }
}

`POST /v1/customers` — hızlı cari ekleme

Doğrudan kullanılabilir cari kaydı oluşturur; kayıt saveType: "api" ile doğar ve entegrasyonunuz tarafından anında kullanılabilir. Müşteri tanı (KYC) formu açmak için Müşteri tanı formları sayfasındaki POST /v1/customers/verifications ucunu kullanın.

Örnek istek

curl -X POST 'https://api.sarraf.pro/v1/customers' \
  -u 'apiUserId:secretKey' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"idNo": "1976926558", "nameSurname": "ÖRNEK MÜŞTERİ", "phone": "5001234567", "email": "ornek@example.com"}}'

İstek gövdesi

{
  "data": {
    "idNo": "12345678901",
    "nameSurname": "ÖRNEK KUYUMCULUK A.Ş.",
    "idType": "company",
    "idCardType": "idCard",
    "phone": "5551234567",
    "customerRelation": {
      "types": "representative",
      "nameSurname": "Yetkili Adı",
      "idNo": "98765432109"
    }
  }
}

Alan	Tür	Kural
`idNo`	string	Zorunlu
`nameSurname`	string	Zorunlu
`idType`	string	`person` (varsayılan) veya `company`
`idCardType`	string	`idCard` (varsayılan), `passport`, `dlCard`, `other`
`customerRelation`	object	Yalnız `idType=company` iken kabul edilir; temsilci/ortak kaydı da oluşur
diğer cari alanlar	string	`birthplace`, `birthday`, `phone`, `phone2`, `email`, `iban`, `taxOffice`, `registryNo`, `activityName`, `naceCode`, `countriesCode`, `countries`, `statesCode`, `states`, `cities`, `address`, `motherName`, `fatherName`, `jobName`
`isAbroad`	boolean	Opsiyonel

Salt okunur alanlar (recordLevel, isVerify, isValid, isPhoto, saveType, sourceDeviceId, sourcePosId, docTypes, year, companiesId, userId vb.) veya sözleşmede olmayan alanlar gönderilirse istek 400 VALIDATION_FAILED ile reddedilir.

Cevap — `201`

Oluşan cari kaydın liste öğesi döner:

{
  "success": true,
  "data": {
    "id": "6a9d12c4bf2fb39feccb3411",
    "idNo": "12345678901",
    "idType": "company",
    "idCardType": "idCard",
    "nameSurname": "ÖRNEK KUYUMCULUK A.Ş.",
    "saveType": "api",
    "recordLevel": 0,
    "isVerify": false,
    "isValid": false,
    "isPhoto": false,
    "createdDate": "2026-09-13T16:00:00.000Z",
    "lastDate": "2026-09-13T16:00:00.000Z",
    "updatedAt": "2026-09-13T16:00:00.000Z"
  },
  "meta": { "requestId": "...", "timestamp": "..." }
}

Çift kayıt — `409 CONFLICT`

Aynı idNo ile müşteri kaydı zaten varsa istek reddedilir ve mevcut kaydın kimliği döner:

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Bu idNo icin zaten bir musteri kaydi var.",
    "details": [ { "field": "data.idNo", "rule": "duplicate", "existingId": "6a9d12c4bf2fb39feccb3411" } ]
  },
  "traceId": "..."
}

Başlangıç

API'ye Giriş

Banka

Faturalar

Giderler

KMTS

Müşteriler

`GET /v1/customers` — müşteri listesi

Örnek istek

Sorgu parametreleri

Cevap alanları (liste öğesi)

Cevap — `200`

`GET /v1/customers/{id}` — müşteri detayı

Örnek istek

Gömülü uyum özeti

Cevap — `200`

`POST /v1/customers` — hızlı cari ekleme

Örnek istek

İstek gövdesi

Cevap — `201`

Çift kayıt — `409 CONFLICT`

​GET /v1/customers — müşteri listesi

​Örnek istek

​Sorgu parametreleri

​Cevap alanları (liste öğesi)

​Cevap — 200

​GET /v1/customers/{id} — müşteri detayı

​Örnek istek

​Gömülü uyum özeti

​Cevap — 200

​POST /v1/customers — hızlı cari ekleme

​Örnek istek

​İstek gövdesi

​Cevap — 201

​Çift kayıt — 409 CONFLICT

`GET /v1/customers` — müşteri listesi

Örnek istek

Sorgu parametreleri

Cevap alanları (liste öğesi)

Cevap — `200`

`GET /v1/customers/{id}` — müşteri detayı

Örnek istek

Gömülü uyum özeti

Cevap — `200`

`POST /v1/customers` — hızlı cari ekleme

Örnek istek

İstek gövdesi

Cevap — `201`

Çift kayıt — `409 CONFLICT`