Chaindoc REST API referansı

Chaindoc REST API için eksiksiz endpoint referansı. İşin aslı, authentication'dan document'lere, signature'lardan media upload'lara ve blockchain doğrulamaya kadar her şeyi burada bulacaksınız.

Genel Bakış

Bu API, Chaindoc'teki her şeye programatik erişim sağlar: document'ler, signature'lar, blockchain doğrulama ve takım yönetimi. Sunucu-sunucu kullanımı için tasarlanmıştır, public ve secret API key'leri destekler.

• Documents — oluşturun, güncelleyin ve blockchain'de doğrulayın
• Signatures — imza istekleri gönderin ve tamamlanmayı takip edin
• Media — PDF, image ve video yükleyin (request başına max 10)
• Embedded sessions — frontend'iniz için imza oturumları oluşturun (Embed SDK kullanır)
• KYC — Sumsub entegrasyonu ile kimlik verilerini paylaşın ve doğrulayın

Authentication

Her request Authorization header'ında bir API key gerektirir. İki tip vardır:

Key Tipleri

• Public key (`pk_`) — salt okunur, frontend kodu için güvenlidir
• Secret key (`sk_`) — tam okuma/yazma, sadece backend. Asla client-side kodda açıklamayın.

Key'lerinizi Alma

API Key Kullanımı

API key'inizi Bearer authentication ile Authorization header'ında ekleyin:

curl -X GET https://api.chaindoc.io/api/v1/me \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Rate Limiting

API endpoint'leri kötüye kullanımı önlemek için rate-limited'tir. Limitler endpoint tipine göre değişir.

• Genel endpoint'ler: 10 saniyede 3 request
• Media upload: 10 saniyede 3 request
• OTP doğrulama: 60 saniyede 5 request
• Okuma işlemleri: 60 saniyede 10 request
• İmza oluşturma: 3 saniyede 20 request

Rate limit aşıldığında 429 Too Many Requests response alırsınız. Rate limit header'ları response'larda bulunur:

X-RateLimit-Limit: 3
X-RateLimit-Remaining: 2
X-RateLimit-Reset: 1640000000

Hata İşleme

HTTP Status Kodları

• 200 - Başarılı
• 201 - Kaynak başarıyla oluşturuldu
• 400 - Bad request (doğrulama hatası)
• 401 - Unauthorized (geçersiz veya eksik API key)
• 403 - Forbidden (yetersiz izinler)
• 404 - Kaynak bulunamadı
• 429 - Too many requests (rate limit aşıldı)
• 500 - Internal server error

Hata Response Formatı

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "details": [
    {
      "field": "name",
      "message": "name must be a string"
    }
  ]
}

Genel API

API Key Bilgisi Al

Mevcut API key hakkında bilgi alın.

GET /me

Authorization: Bearer sk_live_xxxxx

Health Check

API bağlantısını ve key geçerliliğini doğrulayın.

GET /health

Authorization: Bearer sk_live_xxxxx

Documents API

Document Oluştur

Blockchain doğrulama ile yeni document oluşturun. Status 'published' olarak ayarlandığında document otomatik olarak blockchain'de doğrulanır.

POST /documents

Headers:
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Document Güncelle

Yeni version oluşturarak document'i güncelleyin. Önceki version'lar audit trail için korunur.

PUT /documents/:documentId

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Document Erişim Haklarını Güncelle

Document erişim kontrol ayarlarını güncelleyin.

PUT /documents/:documentId/rights

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Document Doğrula

Blockchain kullanarak document orijinalliğini doğrulayın. Transaction hash ve chain ID ile doğrulama status'ü döndürür.

POST /documents/verify

{
  "versionHash": "0x123abc...",
  "certificateHash": "0x456def..."
}

Doğrulama Status'ünü Al

Bir document version'ı için blockchain doğrulama status'ünü alın.

GET /documents/versions/:versionId/verification

Authorization: Bearer sk_live_xxxxx

Signatures API

İmza Request'i Oluştur

Bir veya daha fazla alıcı için imza request'i oluşturun. Frontend entegrasyonu için embedded flow'u etkinleştirin.

curl -X POST https://api.chaindoc.io/api/v1/signatures/requests \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": "f0b7721f-0399-4035-9b69-7b95d3a367f0",
    "recipients": [{"email": "signer@example.com"}],
    "deadline": "2024-12-31T23:59:59Z",
    "embeddedFlow": true
  }'

İmza Request Status'ünü Al

Bir imza request'inin status'ünü kontrol edin ve hangi imzacıların imzalamayı tamamladığını görün.

GET /signatures/requests/:requestId/status

Authorization: Bearer sk_live_xxxxx

Document İmzala

Document'i imzalayın (eğer API key sahibi bir imzacıysa).

POST /signatures/sign

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Kullanıcı İmzalarını Al

Authenticated kullanıcı için tüm imzaları alın.

GET /signatures

Authorization: Bearer sk_live_xxxxx

İmza Request'lerini Al

Authenticated kullanıcı için pagination desteğiyle tüm imza request'lerini alın.

GET /signatures/requests?pageNumber=1&pageSize=10

Authorization: Bearer sk_live_xxxxx

Media Upload API

Document oluşturmada kullanılmak üzere dosya yükleyin. PDF, image ve video destekler. Request başına maximum 10 dosya.

curl -X POST https://api.chaindoc.io/api/v1/media/upload \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -F "media=@contract.pdf"

KYC API

KYC Verisi Paylaş

Kimlik doğrulama için recipient'larla KYC (Know Your Customer) verisi paylaşın.

POST /kyc/share

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Embedded Sessions API

Frontend uygulamanızda document imzalama için embedded session'lar oluşturun. Session'lar 10 dakika geçerlidir.

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Sırada Ne Var?

• API entegrasyonu — yaygın pattern'ler, best practice'ler ve tam workflow örnekleri
• SDK'lar — framework-spesifik rehberlerle Server SDK ve Embed SDK
• Webhooks — gerçek zamanlı event bildirimleri ayarlayın
• Kurulum — tüm desteklenen framework'ler için npm kurulumu
• Güvenlik — API key yönetimi ve uyumluluk