Tanıtım

API Entegrasyonu kurumunuza nasıl katkı sağlar?

V-İmza API entegrasyonu; ERP, CRM, müşteri portalı veya belge kabul ekranından PDF doğrulama, kalıcı doğrulama linki üretme ve imza süreç durumlarını izleme işini V-İmza API v1 uçlarına bağlar.

OpenAPI JSON, scope bazlı API anahtarı, multipart PDF doğrulama, kalıcı doğrulama linki ve süreç durum çıktılarıyla kurum yazılımınıza bağlanır.

API cevabındaki classification veya result_label alanları teknik doğrulama çıktısıdır. “qualified_candidate” gibi sınıflandırmalar hukuki kesin karar yerine sertifika, imza ve politika kontrollerinin teknik yorumu olarak ele alınmalıdır.

Base URL: https://v-imza.com/api/v1 ve OpenAPI JSON
verification.temporary / verification.link scope ayrımı
120 istek/dakika, 50 MB PDF limiti, IP ve origin kısıtı

Öne Çıkanlar

Süreç sadece teknik değil, takip edilebilir olmalı.

Backend tarafında çağrı

API anahtarı tarayıcıya verilmez; kurum backend’i Bearer token veya X-Vimza-Api-Key header’ı ile PDF’i gönderir. Tarayıcıdan çağrı gerekiyorsa origin kısıtı ayrıca tanımlanır.

Seçilebilir doğrulama kontrolleri

İstek içinde signature, certificate, timestamp, ltv, integrity veya etsi gibi kontrol başlıkları seçilebilir. Cevapta summary, checks, timestamps ve ltv gibi alanlar ayrı ayrı istenebilir.

Süreç durumunu dış sisteme taşıma

Belge süreci oluşturma, PDF yükleme, imzacı ekleme ve durum sorgulama uçlarıyla ERP veya portal tarafında “beklemede, imzalanıyor, tamamlandı, reddedildi” gibi durumlar gösterilebilir.

Operasyon İzleri

Belge akışında hangi kayıtlar görünür?

Dosya izi ve imha kaydı

Geçici doğrulamada PDF işlem sonunda silinir; deleted bloğu tracking_uuid, file_sha256 ve deleted_at gibi alanlarla imha izini döndürür.

Doğrulama linki çıktısı

Kalıcı link endpoint’i tokenlı doğrulama URL’si, dosya SHA-256 izi, dosya boyutu, sınıflandırma ve sonuç etiketini tek cevapta verir.

Audit ve hata görünürlüğü

Belge süreçlerinde PDF yükleme, imzacı ekleme, imza hatası, red ve tamamlanma adımları log/audit kayıtlarına bağlanır; status cevabında progress ve signature_failures alanları izlenebilir.

Geliştirici Örnekleri

API gerçekten nasıl çalışır?

Bu bölüm pazarlama vaadi yerine entegrasyon sırasında yazılımcının gördüğü parçalara odaklanır: endpoint, header, scope, status cevabı, hata davranışı ve örnek JSON.

Base URL https://v-imza.com/api/v1 Yetki Authorization: Bearer YOUR_API_KEY Limit 120 istek/dakika, 50 MB PDF Doküman GET /openapi.json

cURL

Geçici PDF doğrulama isteği

PDF doğrulanır, JSON cevap döner ve geçici dosya işlem sonunda imha kaydıyla silinir.

curl -X POST "https://v-imza.com/api/v1/pdf-verification/temporary" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -F "pdf=@/path/to/signed.pdf" \
  -F "checks[]=signature" \
  -F "checks[]=certificate" \
  -F "checks[]=timestamp" \
  -F "checks[]=ltv" \
  -F "fields[]=summary" \
  -F "fields[]=checks"

JSON

Kalıcı doğrulama linki cevap özeti

Dış sisteme saklanabilir link, dosya izi ve doğrulama sonucu birlikte döner.

{
  "success": true,
  "mode": "persistent_link",
  "persisted": true,
  "link": {
    "id": 125,
    "url": "https://v-imza.com/pdf-dogrula/link/TOKEN_VALUE",
    "expires_at": "2026-06-13T15:30:00+03:00",
    "file_sha256": "0d7a0efec18c8f24984bdf31768a41c7208e1edfb9020ad486172309bafca00d",
    "classification": "qualified_candidate",
    "result_label": "Nitelikli imza"
  }
}

Laravel

Laravel backend örneği

API anahtarı config veya env üzerinden okunur; gerçek değer kod içine yazılmaz.

$response = Http::withToken(config('services.vimza.api_key'))
    ->acceptJson()
    ->attach('pdf', fopen(storage_path('app/signed.pdf'), 'r'), 'signed.pdf')
    ->post('https://v-imza.com/api/v1/pdf-verification/temporary', [
        'checks' => ['signature', 'timestamp', 'ltv'],
        'fields' => ['summary', 'checks', 'timestamps'],
    ]);

$payload = $response->json();

Status

Süreç durumu ve callback tasarımı

İmza sürecinde dış sistem genelde GET /sign-process/{id}/status çıktısını izler. Webhook gerekiyorsa aynı alanlar callback payload tasarımının temelini oluşturur.

{
  "success": true,
  "data": {
    "id": 98231,
    "status": "imzalandi",
    "signature_type": "sequential",
    "total_signers": 2,
    "completed_signers": 2,
    "progress": 100,
    "next_signer": null,
    "signature_failures": []
  }
}

taslak Süreç açıldı, PDF veya imzacı seti tamamlanıyor.

beklemede PDF yüklendi; imzacı veya onay adımı başlamayı bekliyor.

imzalaniyor Süreç aktif; sıradaki imzacı, token, SMS/e-posta veya local ajan adımı izleniyor.

imzalandi Tüm imza/onay adımları tamamlandı; dış sistem arşiv, doğrulama linki veya indirme akışına geçebilir.

reddedildi / hata Red nedeni, imza hatası veya signature_failures alanı operasyon ekranına ayrı uyarı olarak düşmelidir.

API anahtarı frontend koduna gömülmemelidir; sunucu tarafında saklanmalı ve gerektiğinde IP/origin kısıtıyla sınırlandırılmalıdır.
include_raw=true yalnızca güvenilir backend debug akışlarında kullanılmalıdır; ham doğrulama çıktısı gereksiz yere dış ekrana basılmamalıdır.
Webhook ihtiyacı varsa callback URL, imza, tekrar deneme, timeout ve başarısız gönderim politikası entegrasyon projesinde ayrıca netleştirilmelidir.

Akış

Üç adımda konumlandırılır.

01

Scope ve anahtar tanımlanır

Geçici doğrulama, kalıcı link veya belge süreci için gerekli scope seçilir; API anahtarı, IP/origin kısıtı ve erişim süresi belirlenir.

02

Endpoint gerçek akışa bağlanır

ERP, CRM veya portal backend’i PDF’i multipart/form-data ile gönderir; checks ve fields parametreleriyle sadece ihtiyaç duyulan doğrulama çıktısını alır.

03

Durum ve hata senaryosu izlenir

HTTP 401/403/422/500 cevapları, imza süreci status alanı, progress değeri ve başarısız imza detayları dış sistemde ayrı davranışlara bağlanır.

Müşteri portalında imzalı PDF kontrolü ERP/CRM belge kabul akışları Satın alma ve teklif onayında doğrulama linki Audit ekranına SHA-256 ve sonuç etiketi basma

Diğer Çözümler