REST API

QuickSign argümansız çalıştırıldığında REST API açılır (varsayılan http://localhost:5000). Tüm uçların makine tarafından okunabilir şeması GET /openapi/v1.json adresindedir; bu şemayı Postman, Insomnia veya kod üreticilerine verebilirsiniz.

#Uçlar

#Yanıt biçimi

Uçların çoğu aynı zarfı döner:

{
  "Success": true,
  "Data": { "...": "..." },
  "Error": null,
  "StatusCode": 200
}

Hata durumunda Success false, Error açıklayıcı bir mesaj olur ve HTTP durum kodu StatusCode ile aynıdır. İstek gövdelerinde alan adları büyük/küçük harfe duyarlı değildir; örneklerde camelCase kullanılmıştır.

#İmzacı ve PIN

Her imzacı tckn veya kayıtlı bir alias ile belirtilir. PIN şu sırayla çözülür:

1. Token kaydında saklanan PIN (Token yönetimi)
2. İstekteki pin alanı
3. İkisi de yoksa istek reddedilir

İmza sertifikası, takılı token'lar arasında konu (subject) bilgisinde bu TCKN'yi taşıyan sertifika aranarak bulunur.

#Tek dosya imzalama

POST /api/sign/file — en basit kullanım. Dosyayı doğrudan yükleyin:

curl -F "[email protected]" -F "tckn=12345678901" -F "pin=1234" \
  http://localhost:5000/api/sign/file

Form alanları: file (zorunlu), tckn veya alias, pin, detached (true varsayılan), algorithm (SHA256 varsayılan).

Aynı uç JSON (base64) da kabul eder:

curl -X POST http://localhost:5000/api/sign/file \
  -H "Content-Type: application/json" \
  -d '{"file":"<BASE64>","tckn":"12345678901","pin":"1234"}'

Yanıt:

{
  "Success": true,
  "Data": {
    "JobId": "a1b2c3d4...",
    "Signature": "MIIHRgYJKoZIhvcNAQcC...",
    "SignerCount": 1,
    "Detached": true,
    "SignerDetails": [
      {
        "Tckn": "12345678901",
        "FullName": "ALİ YILMAZ",
        "TemplateName": "sol-alt",
        "Position": "bottom-left",
        "RenderedText": "Bu belge 01.01.2026 tarihinde\nALİ YILMAZ tarafından\nimzalanmıştır."
      }
    ]
  }
}

Signature Base64 kodlu DER CMS imzadır; ayrık imzada (detached: true) .p7s olarak orijinal dosyanın yanında saklanır. SignerDetails içindeki metin ve konum, imzacıya atanmış şablondan üretilir ve kendi belge görünümünüzde kullanılabilir.

#Senkron imza (çoklu imzacı)

POST /api/sign/sync — imza tamamlanana kadar bekler. Birden çok imzacı sırayla imzalar.

curl -X POST http://localhost:5000/api/sign/sync \
  -H "Content-Type: application/json" \
  -d '{
    "data": "<BASE64>",
    "isBase64": true,
    "signers": [
      { "alias": "muhasebe" },
      { "tckn": "09876543210", "pin": "5678", "templateId": 6 }
    ],
    "detached": true,
    "algorithm": "SHA256"
  }'

#Asenkron imza

Uzun süren veya çok imzacılı işler için POST /api/sign/async aynı gövdeyi alır ve hemen bir iş numarası döner:

{ "Success": true, "Data": { "JobId": "a1b2c3d4...", "Status": "pending", "SignerCount": 2, "Detached": true, "CreatedAt": 1792494498329 } }

Sonucu GET /api/sign/jobs/{jobId} ile sorgulayın. Status değerleri: pending, processing, done, failed. done olduğunda Signature ve SignerDetails, failed olduğunda Error doludur.

curl http://localhost:5000/api/sign/jobs/a1b2c3d4...

#PDF imzası (PAdES)

POST /sign/pdf/base64 PDF'in kendisini imzalar: imza PDF'in içine gömülür (PAdES), Adobe Acrobat'ta doğrulanır ve her imzacı için sayfaya görünür bir imza metni basılır.

curl -X POST http://localhost:5000/sign/pdf/base64 \
  -H "Content-Type: application/json" \
  -d '{
    "base64": "<PDF_BASE64>",
    "credentials": [
      { "tckn": "12345678901", "pin": "1234" },
      { "tckn": "09876543210", "pin": "5678" }
    ]
  }'

Bu uç eski istemcilerle uyum için zarfsız yanıt döner:

{ "SignedBase64": "<imzalı PDF, base64>", "SignerCount": 2 }

İmza metni “{adSoyad} tarafından, {tarih} tarihinde e-imza ile imzalanmıştır.” biçimindedir; imzacılar sırasıyla sol alt, sağ alt, sol üst, sağ üst köşelere, beşinci ve sonrakiler alt ortaya yerleşir.

Hatalar HTTP 422 ile ve makine tarafından ayırt edilebilir kodlarla döner:

{ "errorId": 1001, "code": "WRONG_PIN", "message": "PIN hatalı. 1 deneme hakkınız kaldı." }

POST /base64pdfimzala eski Java esigner servisinin aynı adlı ucuyla birebir uyumludur ({"Base64Pdf": "...", "cred": [{"TcKimlikNo": "...", "Password": "..."}]}) ve düz metin yanıt döner. Yeni entegrasyonlarda /sign/pdf/base64 kullanın.

#Zaman damgası

Token gerekmez. Dosyayı yükleyin; yanıt .tst dosyası olarak iner:

curl -OJ -F "[email protected]" http://localhost:5000/api/timestamp/file

İçeriği göndermeden yalnız hash'i damgalamak için:

curl -X POST http://localhost:5000/api/timestamp/hash \
  -H "Content-Type: application/json" \
  -d '{"hash":"<hex veya base64>","algorithm":"SHA256"}'

{
  "Success": true,
  "Data": {
    "Token": "<base64 RFC 3161 token>",
    "TokenSize": 2693,
    "Hash": "F80B17ED...",
    "HashAlgorithm": "SHA256",
    "Timestamp": "2026-06-27T11:19:42.0000000+00:00",
    "SerialNumber": "00FA553425799E448E8F",
    "Tsa": "http://zd.turktrust.com.tr"
  }
}

Sağlayıcı seçimi ve .asics paketleri için Zaman damgası kılavuzuna bakın.

#Token yönetimi

Token'ları kaydetmek isteğe bağlıdır ama iki kolaylık sağlar: kısa ad (alias) ile imzacı seçmek ve PIN'i şifreli saklayıp her istekte göndermemek.

# kaydet
curl -X POST http://localhost:5000/api/sign/tokens \
  -H "Content-Type: application/json" \
  -d '{"tckn":"12345678901","alias":"muhasebe","pin":"1234","templateId":1}'

# listele (IsBusy: token o an imza atıyor mu)
curl http://localhost:5000/api/sign/tokens

# PIN'i sil, bundan sonra PIN istekten alınsın
curl -X PATCH http://localhost:5000/api/sign/tokens/1 \
  -H "Content-Type: application/json" -d '{"clearPin":true}'

# kaydı sil
curl -X DELETE http://localhost:5000/api/sign/tokens/1

PATCH alanları: alias, pin, templateId, clearPin, clearAlias, clearTemplate. Yanıtlarda PIN hiçbir zaman dönmez; yalnızca HasPin bilgisi yer alır.

#Tanılama uçları

GET /api/sign/check sistemde kurulu PKCS#11 kütüphanelerini, takılı token'ları ve sertifikaları listeler — kurulum sorunlarında ilk bakılacak yerdir.

POST /api/sign/test verilen TCKN ve PIN ile 350 bayttan 5 MB'a kadar dört farklı boyutta deneme imzası atar ve her biri için süreyi ve sonucu döner:

curl -X POST http://localhost:5000/api/sign/test \
  -H "Content-Type: application/json" -d '{"tckn":"12345678901","pin":"1234"}'

Sorunuzun cevabını bulamadınız mı? [email protected]