Belge Doğrulama API

e-Devlet Barkodlu Belge Doğrulama Sistemi

Başlarken

Bu API, e-Devlet Kapısı üzerinden oluşturulan barkodlu belgeleri doğrulamak için kullanılır. Tüm endpoint'ler API Key ile korunmaktadır.

🔐
Güvenli
API Key ile korumalı endpoint'ler ve RLS aktif veritabanı
Hızlı
Puppeteer ile otomatik browser kontrolü
📊
Kayıt Tutuyor
Tüm doğrulamalar PostgreSQL veritabanında saklanır
🎯
Kolay Kullanım
RESTful API ile basit entegrasyon

Authentication

Tüm API istekleri X-API-Key header'ı ile doğrulanır. API Key'inizi her istekte göndermelisiniz.
Header
X-API-Key: your-api-key-here

Endpoints

POST /api/verify
Barkod numarası ve TC Kimlik Numarası ile belge doğrulama işlemi yapar. Sistem otomatik olarak e-Devlet sistemine bağlanır ve belgeyi doğrular.

Request Headers

X-API-Key string required
API erişim anahtarı
Content-Type string required
application/json

Request Body

barcodeNumber string required
Doğrulanacak belgeye ait barkod numarası (max 50 karakter)
tcNumber string required
T.C. Kimlik Numarası (11 haneli)

Örnek İstek

curl -X POST https://api.example.com/api/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: demo-api-key-12345" \
  -d '{
    "barcodeNumber": "UDH0325070902182717",
    "tcNumber": "12345678901"
  }'

Başarılı Yanıt (200)

{
  "success": true,
  "data": {
    "barcodeNumber": "UDH0325070902182717",
    "tcNumber": "123********",
    "verificationStatus": "success",
    "documentInfo": {
      "Belge Türü": "Adli Sicil Kaydı",
      "Belge Tarihi": "04.12.2025"
    },
    "hasDownloadButton": true,
    "verifiedAt": "2025-12-04T14:30:00.000Z"
  },
  "timestamp": "2025-12-04T14:30:00.000Z"
}

Hata Yanıtları

400 - Bad Request
{
  "success": false,
  "error": "Barkod numarası gerekli"
}
401 - Unauthorized
{
  "success": false,
  "error": "Unauthorized - Invalid API key"
}
500 - Server Error
{
  "success": false,
  "error": "Belge doğrulama hatası: TC Kimlik Numarası alanı bulunamadı"
}
GET /api/history
Son yapılan belge doğrulama işlemlerinin listesini döndürür. Son 50 kayıt gösterilir.

Request Headers

X-API-Key string required
API erişim anahtarı

Örnek İstek

curl -X GET https://api.example.com/api/history \
  -H "X-API-Key: demo-api-key-12345"

Başarılı Yanıt (200)

{
  "success": true,
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "barcode_number": "UDH0325070902182717",
      "verification_status": "success",
      "document_info": {
        "Belge Türü": "Adli Sicil Kaydı"
      },
      "verified_at": "2025-12-04T14:30:00.000Z",
      "ip_address": "192.168.1.1",
      "created_at": "2025-12-04T14:30:00.000Z"
    }
  ],
  "timestamp": "2025-12-04T14:35:00.000Z"
}
GET /health
API'nin çalışma durumunu kontrol eder.

Request Headers

X-API-Key string required
API erişim anahtarı

Örnek İstek

curl -X GET https://api.example.com/health \
  -H "X-API-Key: demo-api-key-12345"

Başarılı Yanıt (200)

{
  "status": "ok",
  "timestamp": "2025-12-04T14:30:00.000Z"
}

HTTP Durum Kodları

200 OK - İstek başarıyla tamamlandı
400 Bad Request - Geçersiz veya eksik parametre
401 Unauthorized - Geçersiz veya eksik API key
500 Internal Server Error - Sunucu hatası

Doğrulama Akışı

Sistem, aşağıdaki adımları otomatik olarak gerçekleştirir:

  1. Adım 1: e-Devlet belge doğrulama sayfasına bağlanır
  2. Adım 2: Barkod numarasını girer ve "Devam Et" butonuna basar
  3. Adım 3: TC Kimlik Numarasını girer ve "Devam Et" butonuna basar
  4. Adım 4: Onay checkbox'ını işaretler ve son "Devam Et" butonuna basar
  5. Adım 5: Sonuç sayfasında "Dosyayı İndir" butonunu kontrol eder
  6. Sonuç: Buton varsa belge doğrulandı, yoksa doğrulanamadı

Rate Limiting

Production ortamında rate limiting uygulamanız önerilir. Her IP adresi için dakika başına maksimum 10 istek önerilir.

Veritabanı Yapısı

Tüm doğrulama kayıtları PostgreSQL veritabanında document_verifications tablosunda saklanır:

id uuid
Benzersiz kayıt ID'si
barcode_number text
Barkod numarası
verification_status text
Doğrulama durumu (success, failed, error)
document_info jsonb
Belge bilgileri (JSON formatında)
verified_at timestamptz
Doğrulama zamanı
ip_address text
İstek yapan IP adresi