Teydex Backend API Dokümantasyonu

Genel Bakış

Bu doküman, Teydex KYC uygulaması için sağlanan backend servislerini tanımlamaktadır. Bu servisler hem istemci ara katmanı (veya diğer sunucu tarafı uygulamalar) hem de istemci tarafında çalışan mobil uygulamalara (iOS ve Android) gömülü olan Teydex SDK tarafından kullanılmaktadır.

Burada tanımlanan API'ler, sağlam ve güvenli bir Müşterini Tanı (KYC) iş akışı sağlar. Servisler, uygulama seviyesinde yetkilendirme, kullanıcı bazında akış başlatma, mobil SDK'dan adım gönderimi ve doğrulama ilerlemesini takip etmek ve sonuçları almak için durum sorgulama imkanı sunar.

Bu dokümanın yapısı, KYC sırasını gösteren akış şemasına uygun olarak her adımı tipik çağrılma sırasıyla sunar. İlgili bölümlerde istek ve yanıt formatları detaylandırılmıştır.

---

---

İçindekiler

a. Uygulama Seviyesi Yetkilendirme
b. Son Kullanıcı Akış Başlatma
c. SDK Giriş Noktası Çağrısı
d. KYC İşlem Başlatma
e. KYC Adım Gönderimi (İşlem İsteği)
f. Son İşlem Bilgisi Alma

---

a. Uygulama Seviyesi Yetkilendirme

Akış Şeması Referansı: Adım 1 - 3
Endpoint: POST /auth/token
Kullanan: İstemci Ara Katmanı
Amaç: Middleware uygulamasını doğrular ve diğer backend endpointleriyle güvenli etkileşim için bir token döner.

İstek Gövdesi

{
  "username": "user@example.com",
  "password": "your-password"
}

Yanıt Gövdesi

{
  "access": "access_token_xyz",
  "refresh": "refresh_token_xyz"
}

b. Son Kullanıcı Akış Başlatma

Akış Şeması Referansı: Adım 4 - 6
Endpoint: POST /flow/initialize
Kullanan: İstemci Ara Katmanı
Amaç: Bireysel son kullanıcı için yeni bir KYC işlemi başlatır. Bu endpoint, Teydex SDK tarafından kullanılacak benzersiz bir işlem ID'si ve JWT token döner. Application alanı, panelden oluşturulabilen farklı akışlar için oluşturulan UUID'dir.

İstek Başlıkları

İsim	Tip	Zorunlu	Açıklama
Authorization	string	✅	Bearer token (Bearer <access_token>)

İstek Gövdesi

{
  "application": "b8c1118a-eaa1-4c10-a2ae-eab5d7f6f131",
  "options": {
    "queue": 3,
    "identity_number": "12345678901"
  }
}

Yanıt Gövdesi

{
  "application": "b8c1118a-eaa1-4c10-a2ae-eab5d7f6f131",
  "options": {
    "queue": 3,
    "identity_number": "12345678901"
  },
  "flow": [
    { "step": "idcard_front" },
    { "step": "idcard_back" }
  ],
  "token": "user-session-token",
  "transaction": "transaction-id-xyz"
}

• application (string) — Girdiyle aynı UUID
• options (object) — Seçilen seçeneklerin aynısı
• flow (array) — Gerekli KYC adımlarının sıralı listesi
• token (string) — Bu işlem için oturum tokenı (sonraki KYC adımları için kullanılır)
• transaction (string) — Doğrulama ilerlemesi ve detayları için işlem ID'si

---

c. SDK Giriş Noktası Çağrısı

Akış Şeması Referansı: Adım 7

İşlem başlatıldıktan sonra, mobil cihazdaki Teydex SDK devreye girer.
Platforma bağlı olarak, backend tarafından sağlanan JWT kullanılarak kyc.enter() (iOS) veya kyc.process() (Android) gibi bir metod çağrılır.

SDK, kendisini doğrulamak ve adım adım rehberli KYC akışını başlatmak için bu tokenı kullanır; bu süreç belge tarama, selfie çekme veya NFC verisi okuma gibi işlemleri içerebilir.

---

d. KYC İşlem Başlatma

Akış Şeması Referansı: Adım 8 - 9
Endpoint: POST /mobile/transaction/start
Kullanan: Teydex SDK
Amaç: Cihaz meta verisi ve ortam bilgisi göndererek mobil taraf işlem başlatılır. Bu endpoint, işlem bağlamını doğrular ve mevcut adım ile tam KYC akış durumu döner.

Başlıklar

İsim	Tip	Zorunlu	Açıklama
X-Token	string	✅	Başlatma sırasında alınan işlem tokenı
X-Application-Id	string	✅	Base64 formatında Uygulama ID'si

İstek Gövdesi

{
  "device": {
    "resolution": {
      "width": 1080,
      "height": 1920
    },
    "location": {
      "lat": 41.0082,
      "lon": 28.9784
    },
    "identifier": "device-123",
    "brand": "Samsung",
    "model": "Galaxy S21",
    "sdk": "android",
    "sdk_version": "2.3.1",
    "os": "android",
    "os_version": "13",
    "nfc": true
  }
}

Yanıt Gövdesi

{
  "id": "e73f0a5a-bc8a-4a96-bb30-44ad8b9e1f7d",
  "current_step": "idcard_front",
  "flow": [
    {
      "step": "idcard_front",
      "status": "CREATED",
      "number_of_remaining_attempts": 5
    },
    {
      "step": "idcard_back",
      "status": "CREATED",
      "number_of_remaining_attempts": 5
    }
  ],
  "status": "IN_PROGRESS"
}

• id (string) — Mobil işlem UUID'si
• current_step (string) — SDK'nın sıradaki işlemesi gereken adım
• flow (array) — İşlemdeki adımlar, durumları ve deneme sayısı
• status (string) — Genel işlem durumu (IN_PROGRESS, COMPLETED, vb.)

---

e. KYC Adım Gönderimi (İşlem İsteği)

Akış Şeması Referansı: Adım 10 - 11
Endpoint: POST /mobile/transaction/process
Kullanan: Teydex SDK
Amaç: Mevcut KYC adımı için belge resimleri, video dosyaları, yüz görüntüleri veya ayrıştırılmış NFC verisi gibi veriler gönderilir. Her ardışık çağrıda adım ve durum güncellenir.

Başlıklar

İsim	Tip	Zorunlu	Açıklama
X-Token	string	Evet	Mevcut işlem için token
X-Application-Id	string	Evet	Base64 formatında Uygulama ID'si

İstek Parametreleri (multipart/form-data)

İsim	Tip	Zorunlu	Uygulama Alanı	Açıklama
image	dosya	Hayır	idcard_front/back/nfc	Belge resmi yükleme
video	dosya	Hayır	hologram	Hologram adımı için video yükleme
front_face_image	dosya	Hayır	face	Yüz taraması - ön görünüm
up_face_image	dosya	Hayır	face	Yüz taraması - üst görünüm
down_face_image	dosya	Hayır	face	Yüz taraması - alt görünüm
left_face_image	dosya	Hayır	face	Yüz taraması - sol görünüm
right_face_image	dosya	Hayır	face	Yüz taraması - sağ görünüm
birth_date	string	Hayır	nfc	NFC'den ayrıştırılmış
expiry_date	string	Hayır	nfc	NFC'den ayrıştırılmış
gender	string	Hayır	nfc	NFC'den ayrıştırılmış
issuer	string	Hayır	nfc	NFC'den ayrıştırılmış
name	string	Hayır	nfc	NFC'den ayrıştırılmış
surname	string	Hayır	nfc	NFC'den ayrıştırılmış
nationality	string	Hayır	nfc	NFC'den ayrıştırılmış
identity_number	string	Hayır	nfc	NFC'den ayrıştırılmış
serial_number	string	Hayır	nfc	NFC'den ayrıştırılmış
appointment_id	integer	Hayır	video_call	Randevu için tanımlayıcı

Yanıt Gövdesi

{
  "transaction": {
    "id": "c4fffb3a-9cd1-4b83-8a0e-55e30d192f8c",
    "current_step": "nfc",
    "flow": [
      {
        "step": "idcard_front",
        "status": "DONE",
        "number_of_remaining_attempts": 5
      },
      {
        "step": "nfc",
        "status": "CREATED",
        "number_of_remaining_attempts": 5
      }
    ],
    "status": "IN_PROGRESS"
  },
  "status": "success",
  "data": {
    // Depends on the step processed
  },
  "preparation_data": {
    "nfc_hint": "Place your card close to the NFC scanner"
  }
}

• transaction: Akış durumu dahil güncellenmiş mobil işlem detayları
• status: Gönderim sonucu (ör. "success", "retry" veya "fail")
• data: Adıma özgü sonuç verisi (adımlara göre değişebilir)
• preparation_data: Yaklaşan adımlar için isteğe bağlı talimatlar veya ipuçları

---

f. İşlem Bilgisi Alma

Akış Şeması Referansı: Adım 12 - 14
Endpoint: GET /mobile/transaction/
Kullanan: İstemci Ara Katmanı
Amaç: İşlemin en güncel durumunu, mevcut adımı, akış geçmişini ve durumu getirir. Genellikle SDK tüm adımları tamamladıktan sonra kullanılır ancak KYC akışı sırasında istediğiniz zaman kullanılabilir.

Başlıklar

İsim	Tip	Zorunlu	Açıklama
X-Token	string	Evet	Mevcut işlem için token
X-Application-Id	string	Evet	Base64 formatında Uygulama ID'si

Yanıt Gövdesi

{
  "id": "a2b06bb4-7d7a-466b-93d1-9f4d2765dbf4",
  "current_step": "completed",
  "flow": [
    {
      "step": "idcard_front",
      "status": "DONE",
      "number_of_remaining_attempts": 0
    },
    {
      "step": "idcard_back",
      "status": "DONE",
      "number_of_remaining_attempts": 0
    },
    {
      "step": "nfc",
      "status": "DONE",
      "number_of_remaining_attempts": 0
    }
  ],
  "status": "COMPLETED"
}

• id (string) — İşlem ID'si
• current_step (string) — Hangi adımın aktif olduğunu veya akışın tamamlandığını gösterir
• flow (array) — Tüm adımların ve durumlarının listesi
• status (string) — Nihai işlem durumu (COMPLETED, FAILED vb.)