docufykit.com, imzalı Türkiye belge doğrulama akışlarına odaklanır. Yüklenen belgeleri yapılandırılmış authority adapter üzerinden doğrular, desteklenen belge tiplerinden yapılandırılmış alanları çıkarır ve nihai sonucu imzalı webhook’lar ile REST sorguları üzerinden döner.

Bu ürün genel dosya işleme için değil, Türkiye’deki imzalı belgelerin doğrulanması ve veri çıkarımı için tasarlanmıştır.

Temel URL ve kimlik bilgileri

• Ortamınıza atanmış temel URL’yi kullanın. Production için https://api.docufykit.com kullanın.
• Her istemci uygulamasının kendine ait bir API anahtarı vardır.
• Tekrarlanan isteklerin aynı doğrulamayı yeniden oluşturmaması için her create isteğinde Idempotency-Key gönderin.

İlk API isteği

Önce bir doğrulama oluşturun. API size belge baytları için imzalı bir yükleme hedefi döner.

curl -X POST "https://api.docufykit.com/v1/verifications" \
  -H "X-API-Key: <api-anahtarınız>" \
  -H "Idempotency-Key: 4dd2b36b-8f7c-4f8a-8fb5-1f2d27c3c0f1" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "YOK_STUDENT",
    "process_type": "async",
    "external_reference_id": "student-12345",
    "original_filename": "belge.pdf",
    "file_size_bytes": 160585,
    "metadata": {
      "customer_user_id": "usr_12345"
    }
  }'

Önemli alanlar:

• document_type: bugün opsiyoneldir, ancak beklenen şemayı biliyorsanız önerilir
• process_type: sync veya async, varsayılan sync
• external_reference_id: sizin mutabakat kimliğiniz
• original_filename: yalnızca izlenebilirlik için
• file_size_bytes: beklenen dosya boyutu
• metadata: sonuçlarda ve webhook’larda size geri dönen serbest JSON alanı

İmzalı yükleme akışı

1. Doğrulamayı oluşturun ve verification_id ile imzalı yükleme hedefini alın.
2. Ham dosyayı doğrudan imzalı URL’ye yükleyin.
3. Yüklemenin tamamlandığını onaylayın.
4. Nihai sonucu webhook ile alın veya REST üzerinden sorgulayın.

Dosyayı yükleyin

curl -X PUT "<imzali-yukleme-urlsi>" \
  --upload-file "/absolute/path/to/belge.pdf"

Yükleme tamamlandı onayı

curl -X POST "https://api.docufykit.com/v1/verifications/<verification_id>/upload-complete" \
  -H "X-API-Key: <api-anahtarınız>"

Doğrulamayı sorgulama

curl "https://api.docufykit.com/v1/verifications/<verification_id>" \
  -H "X-API-Key: <api-anahtarınız>"

Yüklemeden sonra ne olur

Yükleme onayı geldikten sonra docufykit:

1. yüklenen nesneyi storage’dan okur
2. dosyayı doğrular
3. belge gerçekliğini yapılandırılmış authority adapter üzerinden kontrol eder
4. analiz ve yapılandırılmış veri çıkarımı yapar
5. deterministik karar kurallarını uygular
6. nihai sonucu kaydeder
7. uygulamada etkin bir uç nokta varsa webhook gönderir

Yüklenen belge authenticity kontrollerinden geçmiyorsa geçerli bir sonuç olarak kabul edilmez.

Webhook kurulumu

Webhook yapılandırması her istemci uygulaması için tutulur. Müşteriler uç nokta ve imza gizli anahtarını portaldan ayarlar.

Mevcut terminal event’ler:

• verification.completed
• verification.review_required
• verification.failed

Webhook başlıkları

Her giden istekte şunlar bulunur:

• Content-Type: application/json
• User-Agent: docufykit-webhooks/1.0
• X-Webhook-Event
• X-Webhook-Id
• X-Webhook-Timestamp
• X-Webhook-Signature

Webhook imza doğrulama örneği

İmza formatı:

sha256=HMAC_SHA256(secret, timestamp + "." + delivery_id + "." + raw_body)

Doğrulamayı yeniden serialize edilmiş JSON ile değil, ham request body baytlarıyla yapın.

import crypto from "node:crypto";

function verifyDocufykitWebhook({
  secret,
  timestamp,
  deliveryId,
  rawBody,
  signature,
}: {
  secret: string;
  timestamp: string;
  deliveryId: string;
  rawBody: Buffer;
  signature: string;
}) {
  const payload = Buffer.concat([
    Buffer.from(timestamp, "utf8"),
    Buffer.from(".", "utf8"),
    Buffer.from(deliveryId, "utf8"),
    Buffer.from(".", "utf8"),
    rawBody,
  ]);

  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(payload).digest("hex");

  const actual = Buffer.from(signature, "utf8");
  const wanted = Buffer.from(expected, "utf8");

  return (
    actual.length === wanted.length &&
    crypto.timingSafeEqual(actual, wanted)
  );
}

Retry davranışı ve yeniden gönderim

Webhook teslimatı uygulama ortamına göre değişir.

Sandbox

• Başarısız webhook yalnızca bir kez gönderilir.
• Otomatik retry yoktur.
• dead_letter durumu yoktur.
• Başarısız teslimatlar manuel replay yapılana kadar failed olarak kalır.

Production

Uç noktanız 2xx dönmezse platform otomatik retry yapar:

• 30 saniye
• 2 dakika
• 10 dakika
• 1 saat
• 6 saat
• 24 saat

Son denemeden sonra teslimat dead_letter durumuna geçer.

Müşteriler şunları yapabilir:

• portal üzerinden son webhook request/response çiftini incelemek
• failed ve dead-letter teslimatları görmek
• deliveries sayfasından manuel replay başlatmak

Reason code referansı

Reason code’lar son durumun makine tarafından okunabilir açıklamalarıdır.

• awaiting_upload: doğrulama oluşturuldu ve yükleme bekleniyor
• processing: yükleme onayı alındı ve arka plan işleme başladı
• source_verifier_not_configured: gerçeklik doğrulaması gerekliydi ama yapılandırılmamıştı
• source_verification_failed: extraction başlamadan gerçeklik doğrulaması başarısız oldu
• authenticity_missing_qrcode: belge QR kodu yoktu veya okunamadı
• authenticity_source_missing: yukarı akıştaki kaynak belge bulunamadı
• authenticity_hash_mismatch: yüklenen dosya kaynak belgeyle eşleşmedi
• authenticity_lookup_failed: yukarı akış doğrulama sorgusu operasyonel olarak başarısız oldu
• local_analysis_failed: karar aşamasından önce yerel analiz başarısız oldu
• document_type_unknown: platform belge tipini sınıflandıramadı
• manual_review_required: nihai sonuç için manuel inceleme gerekiyor
• verified_yok_student: YOK_STUDENT belgesi gerçeklik, extraction ve karar kurallarını geçti
• yok_student_structured_data_missing: YOK_STUDENT için yapılandırılmış veri eksik
• yok_student_payload_invalid: yapılandırılmış veri var ama geçersiz
• yok_student_schema_invalid: YOK_STUDENT şema doğrulaması başarısız

Sandbox ve production farkı

sandbox ve production aynı belge doğrulama ve extraction motorunu kullanır, ancak operasyonel davranışları aynı değildir.

• sandbox
  • entegrasyon testi ve müşteri QA için
  • yalnızca tek webhook denemesi
  • otomatik webhook retry yok
  • dead-letter kuyruğu yok
  • düşük kota
  • tüm planlarda ortak ve daha sıkı sandbox rate limitleri
• production
  • canlı trafik için
  • otomatik webhook retry planı
  • dead-letter desteği
  • plan bazlı daha yüksek kota
  • plan bazlı standart rate limitleri

Her ortam için ayrı uygulama, ortam önekli API anahtarı ve ayrı webhook URL’si kullanın.