KPS Client

NVI (Nüfus ve Vatandaşlık İşleri Genel Müdürlüğü) Kimlik Paylaşım Sistemi (KPS) ile kimlik doğrulama işlemleri için TypeScript/JavaScript kütüphanesi.

Özellikler

• ✅ Framework-agnostic (Node.js, NestJS, Express vb. ile çalışır)
• ✅ TypeScript desteği
• ✅ Tam tip tanımları
• ✅ TC Kimlik No ile kişi doğrulama
• ✅ Opsiyonel TCKK Seri No kontrolü
• ✅ Detaylı hata yönetimi
• ✅ Modern async/await API

Kurulum

npm install kps-client

veya

yarn add kps-client

Hızlı Başlangıç

import { KpsClient } from 'kps-client';

// Client oluştur
const client = new KpsClient('kps_username', 'kps_password');

// Kimlik doğrulama yap
const result = await client.query({
  tcno: '12121212121',
  firstname: 'BARIŞ',
  lastname: 'DEMİR',
  birthyear: '1985',
  birthmonth: '5',
  birthday: '15'
});

if (result.status) {
  console.log('✓ Kimlik doğrulandı');
  console.log('Ad:', result.extra?.Ad);
  console.log('Soyad:', result.extra?.Soyad);
} else {
  console.log('✗ Doğrulama başarısız:', result.message);
}

API Dokümantasyonu

new KpsClient(username, password, options?)

KPS Client oluşturur.

Parametreler:

• username (string): KPS kullanıcı adı
• password (string): KPS şifresi
• options (KpsClientOptions, opsiyonel): Yapılandırma seçenekleri
  • timeout (number): HTTP timeout süresi (ms, varsayılan: 30000)

Örnek:

const client = new KpsClient('username', 'password', {
  timeout: 60000  // 60 saniye
});

client.query(request)

Kimlik doğrulama sorgusu yapar.

Parametreler:

request (KpsQueryRequest):

• tcno (string, zorunlu): TC Kimlik Numarası (11 haneli)
• firstname (string, zorunlu): Ad (büyük harflerle)
• lastname (string, zorunlu): Soyad (büyük harflerle)
• birthyear (string, zorunlu): Doğum yılı (4 haneli)
• birthmonth (string, zorunlu): Doğum ayı (1-12)
• birthday (string, zorunlu): Doğum günü (1-31)
• tckkSerino (string, opsiyonel): TCKK Seri No (örn: "A12B34567")

Dönüş Değeri:

KpsQueryResult:

• status (boolean): Sorgu başarılı mı?
• code (KpsStatusCode): Durum kodu
  • KpsStatusCode.ACIK (1): Açık (kayıt bulundu ve doğru)
  • KpsStatusCode.HATALI (2): Hatalı/Bulunamadı
  • KpsStatusCode.VEFAT (3): Ölüm (kişi vefat etmiş)
• message (string, opsiyonel): Durum mesajı
• identityType (IdentityType, opsiyonel): Kimlik türü
  • 'tckn': TC Kimlik No sahibi
  • 'yabanci': Yabancı Uyruklu
  • 'mavikart': Mavi Kart Sahibi
• extra (object, opsiyonel): Detay bilgiler
  • KimlikNo: TC Kimlik Numarası
  • Ad: Adı
  • Soyad: Soyadı
  • DogumTarih: Doğum Tarihi (YYYY-MM-DD)
  • OlumTarih: Ölüm Tarihi (varsa)
  • Uyruk: Uyruk (yabancılar için)
  • SeriNo: Seri numarası (varsa)

Kullanım Örnekleri

Temel Kullanım

import { KpsClient } from 'kps-client';

const client = new KpsClient('kps_username', 'kps_password');

const result = await client.query({
  tcno: '12121212121',
  firstname: 'BARIŞ',
  lastname: 'DEMİR',
  birthyear: '1984',
  birthmonth: '3',
  birthday: '18'
});

console.log(result.status);     // true veya false
console.log(result.code);       // KpsStatusCode.ACIK (1), HATALI (2), veya VEFAT (3)
console.log(result.message);    // "Açık", "Kayıt bulunamadı", vb.
console.log(result.identityType); // 'tckn', 'yabanci', veya 'mavikart'

TCKK Seri No ile Doğrulama

const result = await client.query({
  tcno: '12121212121',
  firstname: 'BARIŞ',
  lastname: 'DEMİR',
  birthyear: '1981',
  birthmonth: '11',
  birthday: '9',
  tckkSerino: 'A12B34567'  // Opsiyonel seri no
});

if (result.status) {
  console.log('✓ Kimlik ve seri no doğrulandı');
} else {
  console.log('✗ Doğrulama başarısız');
}

Detaylı Bilgilere Erişim

const result = await client.query({
  tcno: '12121212121',
  firstname: 'BARIŞ',
  lastname: 'DEMİR',
  birthyear: '1983',
  birthmonth: '6',
  birthday: '14'
});

if (result.status) {
  console.log('Kimlik Türü:', result.identityType); // 'tckn'
  console.log('Ad:', result.extra?.Ad);
  console.log('Soyad:', result.extra?.Soyad);
  console.log('Doğum Tarihi:', result.extra?.DogumTarih);
  console.log('Kimlik No:', result.extra?.KimlikNo);
}

NestJS Entegrasyonu

import { Injectable } from '@nestjs/common';
import { KpsClient, KpsStatusCode } from 'kps-client';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class IdentityService {
  private kpsClient: KpsClient;

  constructor(private configService: ConfigService) {
    const username = this.configService.get<string>('KPS_USERNAME');
    const password = this.configService.get<string>('KPS_PASSWORD');
    this.kpsClient = new KpsClient(username, password);
  }

  async verifyIdentity(
    tcno: string,
    firstname: string,
    lastname: string,
    birthyear: string,
    birthmonth: string,
    birthday: string,
    tckkSerino?: string
  ) {
    const result = await this.kpsClient.query({
      tcno,
      firstname,
      lastname,
      birthyear,
      birthmonth,
      birthday,
      tckkSerino
    });

    return {
      verified: result.status,
      code: result.code,
      message: result.message,
      identityType: result.identityType,
      details: result.extra
    };
  }
}

Express.js Entegrasyonu

import express from 'express';
import { KpsClient, KpsStatusCode } from 'kps-client';
import dotenv from 'dotenv';

dotenv.config();

const app = express();
app.use(express.json());

const kpsClient = new KpsClient(
  process.env.KPS_USERNAME!,
  process.env.KPS_PASSWORD!
);

app.post('/api/verify-identity', async (req, res) => {
  try {
    const { tcno, firstname, lastname, birthyear, birthmonth, birthday, tckkSerino } = req.body;

    const result = await kpsClient.query({
      tcno,
      firstname,
      lastname,
      birthyear,
      birthmonth,
      birthday,
      tckkSerino
    });

    res.json({
      verified: result.status,
      code: result.code,
      message: result.message,
      identityType: result.identityType,
      details: result.extra
    });
  } catch (error: any) {
    res.status(500).json({
      verified: false,
      code: KpsStatusCode.HATALI,
      message: error.message
    });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server ${PORT} portunda çalışıyor`);
});

Hata Yönetimi

const result = await client.query({
  tcno: '12121212121',
  firstname: 'BARIŞ',
  // lastname eksik - hata!
  birthyear: '1980',
  birthmonth: '2',
  birthday: '28'
} as any);

console.log(result.status);    // false
console.log(result.code);      // KpsStatusCode.HATALI (2)
console.log(result.message);   // "TC Kimlik No, Ad, Soyad ve Tam Doğum Tarihi (Yıl/Ay/Gün) zorunludur"

Farklı Senaryolar

// Senaryo 1: Geçerli TC Vatandaşı
const result1 = await client.query({
  tcno: '12121212121',
  firstname: 'BARIŞ',
  lastname: 'DEMİR',
  birthyear: '1985',
  birthmonth: '4',
  birthday: '12',
});

if (result1.status && result1.identityType === 'tckn') {
  console.log('✓ TC Vatandaşı doğrulandı');
}

// Senaryo 2: Kayıt bulunamadı
const result2 = await client.query({
  tcno: '99999999999',
  firstname: 'TEST',
  lastname: 'KULLANICI',
  birthyear: '1982',
  birthmonth: '9',
  birthday: '17',
});

if (!result2.status && result2.code === KpsStatusCode.HATALI) {
  console.log('✗ Kayıt bulunamadı:', result2.message);
}

Tip Tanımları

KpsStatusCode (Enum)

enum KpsStatusCode {
  ACIK = 1,      // Kayıt açık, doğrulama başarılı
  HATALI = 2,    // Hatalı veya kayıt bulunamadı
  VEFAT = 3      // Kişi vefat etmiş
}

IdentityType (Enum)

enum IdentityType {
  TCKN = 'tckn',           // TC Kimlik No sahibi
  YABANCI = 'yabanci',     // Yabancı uyruklu
  MAVIKART = 'mavikart'    // Mavi Kart sahibi
}

KpsQueryRequest

interface KpsQueryRequest {
  tcno: string;            // TC Kimlik Numarası
  firstname: string;       // Ad
  lastname: string;        // Soyad
  birthyear: string;       // Doğum yılı
  birthmonth: string;      // Doğum ayı
  birthday: string;        // Doğum günü
  tckkSerino?: string;     // TCKK Seri No (opsiyonel)
}

KpsQueryResult

interface KpsQueryResult {
  status: boolean;                 // Başarılı mı?
  code: KpsStatusCode;             // Durum kodu
  message?: string;                // Durum mesajı
  identityType?: IdentityType;     // Kimlik türü
  extra?: Record<string, string>;  // Ek bilgiler
}

Güvenlik Notları

⚠️ ÖNEMLİ GÜVENLİK UYARILARI:

• KPS kullanıcı adı ve şifrenizi asla doğrudan kod içine yazmayın.
• Ortam değişkenleri (.env dosyası) veya güvenli bir yapılandırma yönetimi kullanın.
• KPS servisinden dönen hassas verileri (örneğin extra alanı) uygulamanızın güvenlik politikalarına uygun şekilde işleyin ve saklayın.
• Kimlik bilgilerini loglamayın veya cache'lemeyin.
• Production ortamında HTTPS kullanın.

Örnek .env Dosyası

KPS_USERNAME=your_kps_username
KPS_PASSWORD=your_kps_password

Hata Mesajları

Kütüphane hataları KpsQueryResult içinde döndürür, exception fırlatmaz:

• "TC Kimlik No, Ad, Soyad ve Tam Doğum Tarihi (Yıl/Ay/Gün) zorunludur": Zorunlu alan eksik
• "STS hatası: ...": Güvenlik token servisi hatası (kullanıcı adı/şifre kontrolü)
• "Servis hatası: ...": KPS servisi hatası
• "Parse hatası: ...": Yanıt ayrıştırma hatası
• "Kayıt bulunamadı": KPS'de eşleşen kayıt yok

Sınırlamalar

• KPS servisi tam doğum tarihini (gün/ay/yıl) gerektirir.
• TC Kimlik No 11 haneli olmalıdır.
• Ad ve Soyad büyük harflerle girilmelidir.
• Servis timeout varsayılan olarak 30 saniyedir.

Bağımlılıklar

• axios: HTTP istekleri için
• uuid: Benzersiz ID oluşturma
• fast-xml-parser: XML ayrıştırma
• xml-crypto: XML imzalama ve doğrulama
• xmldom: XML DOM işlemleri

Geliştirici

Barış Demir

• 🐙 GitHub: @barisdemir49
• 📦 NPM: @barisdemir49
• 💼 LinkedIn: @barisdemir49
• 🎥 YouTube: @barisdemir49
• 📧 Email: [email protected]
• 🌐 Web: abelsis.com.tr | botcex.com | ozeldersveriyorum.com

Lisans

MIT

Destek ve İletişim

Sorularınız veya önerileriniz için GitHub Issues üzerinden iletişime geçebilirsiniz.

Katkıda Bulunma

Pull request'ler memnuniyetle karşılanır. Büyük değişiklikler için lütfen önce bir issue açın.

Changelog

1.0.0

• İlk sürüm
• TumKutukDogrulama servisi entegrasyonu
• TC Kimlik No, Ad, Soyad, Doğum Tarihi ile doğrulama
• TCKK Seri No desteği
• TypeScript tam tip desteği
• Framework-agnostic tasarım