Hızlı başlangıç

Bir entegrasyon üç parçadan oluşur:

1. Sunucunuz Prove ID’ye giriş yapar ve kullanıcı için bir işlem token’ı oluşturur.
2. Sayfanız SDK’yı bu token ile başlatır. SDK, Prove ID ile kendisi konuşur.
3. Sunucunuz sayfanın geri gönderdiği transactionId ile doğrulama sonucunu Prove ID’den okur.

1. Token’ı sunucunuzda alın

SDK, Prove ID’ye kullanıcı adına bağlanmak için bir işlem token’ı kullanır. Sunucunuz bu token’ı iki çağrıyla oluşturur:

Çağrı	Amaç	Geçerlilik
POST /oauth/access_token	Sunucunuzu API kimlik bilgilerinizle giriş yaptırır (form-encoded, client_credentials grant).	Varsayılan 30 dakika (expires_in). Önbelleğe alın ve tüm kullanıcılar için yeniden kullanın.
POST /link/create-token	Tek bir doğrulama için tek bir işlem token’ı oluşturur.	Yanıttaki expiresAt anına kadar ve yalnızca o akış bitene kadar: biten bir akış aynı token ile yeniden başlatılamaz.

İsteğe bağlı idTypes alanı bu işlemde kabul edilecek belgeleri sınırlar (IDCARD, OLDIDCARD, DRIVERCARD, PASSPORT, BLUECARD, FOREIGNID). customerId, işlemi Prove ID’de daha önce oluşturduğunuz bir müşteriye bağlar.

Kimlik bilgilerinizi tarayıcıya eklemeyin

Prove ID API kullanıcı adı ve şifrenizi istemci koduna eklemeyin. Token’ı URL’de (query string) taşımayın.

Node.js

// Node.js 18+ (yerleşik fetch)
const API = process.env.PROVEID_API ?? 'https://demo.api.proveid.io';

let cached; // { token, expiresAt }

async function accessToken() {
  if (cached && cached.expiresAt > Date.now() + 60_000) return cached.token;
  const res = await fetch(`${API}/oauth/access_token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: process.env.PROVEID_CLIENT_ID,
      client_secret: process.env.PROVEID_CLIENT_SECRET,
    }),
  });
  if (!res.ok) throw new Error(`Prove ID girişi başarısız: ${res.status}`);
  const data = await res.json();
  cached = { token: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 };
  return cached.token;
}

export async function createTransactionToken() {
  const res = await fetch(`${API}/link/create-token`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${await accessToken()}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ idTypes: ['IDCARD'] }),
  });
  if (!res.ok) throw new Error(`İşlem token'ı oluşturulamadı: ${res.status}`);
  return res.json(); // { transactionToken, expiresAt }
}

Python

import os
import time

import requests

API = os.environ.get("PROVEID_API", "https://demo.api.proveid.io")
_cached = {"token": None, "expires_at": 0.0}


def access_token():
    if _cached["token"] and _cached["expires_at"] > time.time() + 60:
        return _cached["token"]
    res = requests.post(
        f"{API}/oauth/access_token",
        data={  # form-encoded
            "grant_type": "client_credentials",
            "client_id": os.environ["PROVEID_CLIENT_ID"],
            "client_secret": os.environ["PROVEID_CLIENT_SECRET"],
        },
        timeout=30,
    )
    res.raise_for_status()
    data = res.json()
    _cached.update(token=data["access_token"], expires_at=time.time() + data["expires_in"])
    return _cached["token"]


def create_transaction_token():
    res = requests.post(
        f"{API}/link/create-token",
        headers={"Authorization": f"Bearer {access_token()}"},
        json={"idTypes": ["IDCARD"]},
        timeout=30,
    )
    res.raise_for_status()
    return res.json()  # {"transactionToken": ..., "expiresAt": ...}

C#

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

// http.BaseAddress = new Uri("https://demo.api.proveid.io/") (sondaki eğik çizgiyi koruyun)
public sealed class ProveIdClient(HttpClient http, string clientId, string clientSecret)
{
    private string? _token;
    private DateTimeOffset _expiresAt;

    private async Task<string> AccessTokenAsync()
    {
        if (_token is not null && _expiresAt > DateTimeOffset.UtcNow.AddMinutes(1)) return _token;
        var res = await http.PostAsync("oauth/access_token", new FormUrlEncodedContent(new Dictionary<string, string>
        {
            ["grant_type"] = "client_credentials",
            ["client_id"] = clientId,
            ["client_secret"] = clientSecret,
        }));
        res.EnsureSuccessStatusCode();
        var data = await res.Content.ReadFromJsonAsync<JsonElement>();
        _token = data.GetProperty("access_token").GetString()!;
        _expiresAt = DateTimeOffset.UtcNow.AddSeconds(data.GetProperty("expires_in").GetInt32());
        return _token;
    }

    private async Task<HttpRequestMessage> AuthorizedAsync(HttpMethod method, string path)
    {
        var req = new HttpRequestMessage(method, path);
        req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", await AccessTokenAsync());
        return req;
    }

    public async Task<string> CreateTransactionTokenAsync()
    {
        using var req = await AuthorizedAsync(HttpMethod.Post, "link/create-token");
        req.Content = JsonContent.Create(new { idTypes = new[] { "IDCARD" } });
        var res = await http.SendAsync(req);
        res.EnsureSuccessStatusCode();
        var data = await res.Content.ReadFromJsonAsync<JsonElement>();
        return data.GetProperty("transactionToken").GetString()!;
    }
}

curl

API=https://demo.api.proveid.io

# 1. Giriş (form-encoded)
ACCESS_TOKEN=$(curl -s -X POST "$API/oauth/access_token" \
  -d grant_type=client_credentials \
  -d client_id="$PROVEID_CLIENT_ID" \
  -d client_secret="$PROVEID_CLIENT_SECRET" | jq -r .access_token)

# 2. İşlem token'ı oluşturma
curl -s -X POST "$API/link/create-token" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"idTypes": ["IDCARD"]}'
# → {"transactionToken": "…", "expiresAt": "…"}

Bunu yalnızca giriş yapmış kullanıcıların çağırabildiği kendi uç noktanız üzerinden sunun (örneğin POST /api/kyc/token) ve sayfaya yalnızca transactionToken değerini döndürün. Her doğrulama için yeni bir token oluşturun.

2. Bileşeni sayfaya ekleyin

<!DOCTYPE html>
<html lang="tr">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover" />
  <title>Kimlik doğrulama</title>
  <style>
    html, body, techsign-kyc { margin: 0; height: 100%; }
  </style>
</head>
<body>
  <techsign-kyc
    token="TRANSACTION_TOKEN"
    domain="https://demo.api.proveid.io"
    lang="tr"
    enable-face="true"
  ></techsign-kyc>

  <script type="module">
    import '/sdk/techsign-kyc.js';

    const kyc = document.querySelector('techsign-kyc');

    kyc.addEventListener('complete', (e) => {
      // e.detail.transactionId değerini sunucunuza iletin
      console.log('tamamlandı', e.detail);
    });

    kyc.addEventListener('error', (e) => {
      // e.detail.code, e.detail.message, e.detail.retryable
      console.error('hata', e.detail);
    });
  </script>
</body>
</html>

Bileşen sayfaya eklendiği anda akışı başlatır. domain değerini kullandığınız ortama göre ayarlayın.

TRANSACTION_TOKEN değerini sunucu şablonunuzdan sayfaya yazın ya da önce token’ı alıp bileşeni sonra ekleyin:

const res = await fetch('/api/kyc/token', { method: 'POST' });
const { transactionToken } = await res.json();

const kyc = document.createElement('techsign-kyc');
kyc.setAttribute('token', transactionToken);
kyc.setAttribute('domain', 'https://demo.api.proveid.io');
kyc.setAttribute('lang', 'tr');
// complete / error dinleyicilerini yukarıdaki gibi ekleyin, ardından:
document.body.append(kyc);

3. Sonucu sunucunuzda doğrulayın

complete event’i akışın bittiğini bildirir. Doğrulama kararını tarayıcıdaki sonuca göre vermeyin: transactionId değerini sunucunuza gönderin ve sonucu GET /id/id-info-with-tid/{transactionId} ile Prove ID’den okuyun.

Akış boyunca çalışan kontroller controlResults içinde listelenir. Her birinde entryType, entryScore ve entryInterpretation (kontrol geçtiyse true) bulunur. Aşağıdaki örnekler 1. adımdaki accessToken() fonksiyonunu kullanır ve doğrulamayı yalnızca tüm kontroller geçtiyse kabul eder. Kuralı kendi risk politikanıza göre uyarlayın.

Node.js

export async function getVerification(transactionId) {
  const res = await fetch(`${API}/id/id-info-with-tid/${encodeURIComponent(transactionId)}`, {
    headers: { Authorization: `Bearer ${await accessToken()}` },
  });
  if (!res.ok) throw new Error(`Sonuç okunamadı: ${res.status}`);
  const info = await res.json();
  const controls = info.controlResults ?? [];
  const passed = controls.length > 0 && controls.every((c) => c.entryInterpretation === true);
  return { passed, info };
}

Python

from urllib.parse import quote


def get_verification(transaction_id):
    res = requests.get(
        f"{API}/id/id-info-with-tid/{quote(transaction_id, safe='')}",
        headers={"Authorization": f"Bearer {access_token()}"},
        timeout=30,
    )
    res.raise_for_status()
    info = res.json()
    controls = info.get("controlResults") or []
    passed = bool(controls) and all(c.get("entryInterpretation") is True for c in controls)
    return passed, info

C#

// 1. adımdaki ProveIdClient sınıfına ekleyin
public async Task<(bool Passed, JsonElement Info)> GetVerificationAsync(string transactionId)
{
    using var req = await AuthorizedAsync(HttpMethod.Get, $"id/id-info-with-tid/{Uri.EscapeDataString(transactionId)}");
    var res = await http.SendAsync(req);
    res.EnsureSuccessStatusCode();
    var info = await res.Content.ReadFromJsonAsync<JsonElement>();
    var controls = info.TryGetProperty("controlResults", out var list) ? list.EnumerateArray().ToList() : [];
    var passed = controls.Count > 0 && controls.All(c =>
        c.TryGetProperty("entryInterpretation", out var ok) && ok.ValueKind == JsonValueKind.True);
    return (passed, info);
}

curl

curl -s "$API/id/id-info-with-tid/$TRANSACTION_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq '.controlResults'

Sonucu kullanıcıya bağlayın

transactionId sunucunuza tarayıcıdan gelir. Bu değeri yalnızca token’ı kendisi için oluşturduğunuz, giriş yapmış kullanıcıdan kabul edin. Böylece kimse başkasının doğrulamasını kendi doğrulaması gibi gönderemez.

Yanıt modelinin tamamı ve diğer sonuç servisleri API Reference sekmesindedir.

Tek dosya (IIFE) kullanımı

type="module" kullanamayan sayfalar için:

<script src="/sdk/techsign-kyc.iife.js"></script>

<techsign-kyc token="TRANSACTION_TOKEN" lang="tr" enable-face="false"></techsign-kyc>

<script>
  const kyc = document.querySelector('techsign-kyc');
  kyc.addEventListener('complete', (e) => console.log(e.detail));
  kyc.addEventListener('error', (e) => console.error(e.detail));
</script>

Bundler ile

import '@techsign/kyc';
import { warmupAssets } from '@techsign/kyc';

// İsteğe bağlı: modelleri kullanıcı akışa gelmeden önce indir
void warmupAssets({ enableFace: true });

Ardından <techsign-kyc> etiketini şablonunuzda kullanın.