CoreApiPades (v2.0 / v3.0)

CoreApiPades, PrimeAPI’de PDF üstünde PAdES imzalama işlemlerini yönetir. İmzalama iki adımda gerçekleşir: SignStepOne (başlat) ve signStepThree (bitir). Ayrıca mevcut dosyadaki imzaları listeleme, imzayı daha yüksek seviyeye yükseltme (upgrade), PDF’e dönüştürme ve PDF’e doğrulama yazısı/QR code gibi katmanlar ekleme uç noktaları bulunur. Tüm işlemler bir OperationId etrafında yürür.

Not: PDF’e dönüştürme ve PDF’e katman ekleme uç noktaları CoreApiPdf (v2.0) altında yer alır. Bu sayfada yalnızca CoreApiPades uç noktaları dokümante edilir.

Temel kavramlar

• OperationId: İşlem kimliği. Bir adım yeni çıktı üretiyorsa yanıt içinde yeni OperationId döner ve takip eden adımlarda bu yeni değer kullanılmalıdır.
• Auth: Tüm uç noktalar ApiKey gerektirir.
• Zarf: Tüm yanıtlar ApiResult<T> tipindedir:
  • result: T
  • error: string (hata durumunda dolar)

İmza listesi modeli (V2)

Bir dosyadaki imzaları listeleyen V2 uç noktası, aşağıdaki alanlardan oluşan öğeler döndürür.

Properties

İmza listesi modeli (V3)

V3 uç noktası, V2'deki tüm alanların yanı sıra zaman damgası detaylarını da döndürür. Belge zaman damgaları (document timestamp) filtrelenir ve sadece gerçek e-imzalar listelenir.

Properties

TimestampInfoItem

GetSignatureListCore

curl -X POST "https://apitest.onaylarim.com/v2/CoreApiPades/GetSignatureListCore" \
  -H "X-API-KEY: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "11111111-1111-1111-1111-111111111111", "requestId": "aaaaaaaaaaaaaaaaaaaaa", "displayLanguage": "tr" }'

{
  "result": {
    "signatures": [
      {
        "entityLabel": "S0",
        "level": 1,
        "levelString": "BES",
        "subjectRDN": "CN=Example",
        "timestamped": false,
        "citizenshipNo": null
      }
    ],
    "operationId": "11111111-1111-1111-1111-111111111111"
  },
  "error": null
}

GetSignatureListCore (V3)

curl -X POST "https://apitest.onaylarim.com/v3/CoreApiPades/GetSignatureListCore" \
  -H "X-API-KEY: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "11111111-1111-1111-1111-111111111111", "requestId": "aaaaaaaaaaaaaaaaaaaaa", "displayLanguage": "tr" }'

{
  "result": {
    "signatures": [
      {
        "entityLabel": "S0",
        "level": 1,
        "levelString": "BES",
        "subjectRDN": "CN=Example",
        "timestamped": true,
        "claimedSigningTime": "2026-01-08 12:50:26.819",
        "claimedSigningTimeAsTime": "2026-01-08T12:50:26.819",
        "citizenshipNo": "12345678901",
        "timestamp": {
          "entityLabel": "S0:T0",
          "time": "2026-01-08 12:50:30.123",
          "timeAsTime": "2026-01-08T12:50:30.123"
        }
      },
      {
        "entityLabel": "S1",
        "level": 1,
        "levelString": "BES",
        "subjectRDN": "CN=Example2",
        "timestamped": false,
        "claimedSigningTime": "2026-01-08 13:15:00.000",
        "claimedSigningTimeAsTime": "2026-01-08T13:15:00",
        "citizenshipNo": "98765432100",
        "timestamp": null
      }
    ],
    "operationId": "11111111-1111-1111-1111-111111111111"
  },
  "error": null
}

SignStepOnePadesCore — İmzayı başlat

curl -X POST "https://apitest.onaylarim.com/v2/CoreApiPades/SignStepOnePadesCore" \
  -H "X-API-KEY: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
        "operationId": "11111111-1111-1111-1111-111111111111",
        "cerBytes": "MIIC...",
        "signatureWidgetInfo": {
          "width": 240,
          "height": 80,
          "left": 0.1,
          "top": 0.1,
          "pagesToPlaceOn": [0]
        },
        "requestId": "aaaaaaaaaaaaaaaaaaaaa",
        "displayLanguage": "tr"
      }'

{
  "result": {
    "state": "BASE64_STATE",
    "keyID": "abcd1234",
    "keySecret": "wxyz5678",
    "operationId": "22222222-2222-2222-2222-222222222222"
  },
  "error": null
}

signStepThreePadesCore — İmzayı bitir

curl -X POST "https://apitest.onaylarim.com/v2/CoreApiPades/signStepThreePadesCore" \
  -H "X-API-KEY: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
        "operationId": "22222222-2222-2222-2222-222222222222",
        "signedData": "HEX_OR_BASE64",
        "keyId": "abcd1234",
        "keySecret": "wxyz5678",
        "signatureLevel": "BES",
        "requestId": "aaaaaaaaaaaaaaaaaaaaa",
        "displayLanguage": "tr"
      }'

{
  "result": {
    "isSuccess": true,
    "operationId": "33333333-3333-3333-3333-333333333333"
  },
  "error": null
}

UpgradePadesCore

curl -X POST "https://apitest.onaylarim.com/v2/CoreApiPades/UpgradePadesCore" \
  -H "X-API-KEY: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
        "operationId": "33333333-3333-3333-3333-333333333333",
        "signatureLevel": "LTV",
        "signaturePath": null,
        "requestId": "aaaaaaaaaaaaaaaaaaaaa",
        "displayLanguage": "tr"
      }'

{
  "result": {
    "isSuccess": true
  },
  "error": null
}

Örnek akış (PAdES)

1. Dosya yükleme: CoreApiFile/UploadFile veya parça/parça: ChunkInit → ChunkUpload → ChunkComplete
2. (Gerekirse) PDF'e dönüşüm ve katman ekleme işlemleri CoreApiPdf (v2.0) sayfasındaki uç noktalarla yapılır; dönen operationId ile devam edilir.
3. CoreApiPades/SignStepOnePadesCore → state, keyId, keySecret alınır (yeni operationId gelebilir).
4. İstemci e-imza aracına göre signedData üretilir.
5. CoreApiPades/signStepThreePadesCore ile imzalama tamamlanır (final operationId).
6. (Opsiyonel) UpgradePadesCore ile PAdES imzalar yükseltilebilir.
7. (Opsiyonel) GetSignatureListCore ile imzalar listelenir:
   • V2 (/v2/...): Temel imza bilgileri
   • V3 (/v3/...): Zaman damgası detayları dahil (en son imzayı bulmak için önerilir)

V1’den V2’ye geçiş

Bu sayfa V2.0 uç noktalarını anlatır. Eğer mevcut entegrasyonunuz V1 (/v1/CoreApiPades) ile çalışıyorsa, aşağıdaki maddelerle hızlıca V2’ye geçebilirsiniz.

Endpoint değişiklik özeti

V1 → V2 request alanı dönüşümleri (PAdES)

SignStepOnePadesCore

• V1’de vardı, V2’de kaldırıldı
  • fileData: V2’de SignStepOnePadesCore içinde gönderilmez. Dosyayı önce CoreApiFile/UploadFile (veya chunk akışı) ile yükleyip dönen operationId ile devam edin.
  • signatureIndex: V2 SignStepOnePadesCoreRequestV2 modelinde yoktur (PAdES’te seri imza için signaturePath yaklaşımı ayrı UpgradePadesCore çağrısında bulunur).
• V2’de aynı/benzer
  • cerBytes, signatureWidgetInfo (görünür imza), operationId, requestId, displayLanguage

V1 örnek istek (özet):

{
  "operationId": "11111111-1111-1111-1111-111111111111",
  "cerBytes": "MIIC...",
  "fileData": "BASE64_FILE_BYTES",
  "signatureIndex": 0,
  "requestId": "aaaaaaaaaaaaaaaaaaaaa",
  "displayLanguage": "tr"
}

V2 örnek istek (özet):

{
  "operationId": "11111111-1111-1111-1111-111111111111",
  "cerBytes": "MIIC...",
  "signatureWidgetInfo": {
    "width": 240,
    "height": 80,
    "left": 0.1,
    "top": 0.1,
    "pagesToPlaceOn": [0]
  },
  "requestId": "aaaaaaaaaaaaaaaaaaaaa",
  "displayLanguage": "tr"
}

signStepThreePadesCore

• V1’de vardı, V2’de kaldırıldı
  • dontUpgradeToLtv: V1’de imza sonrası otomatik LTV yükseltmeyi kontrol ediyordu.
• V2’de yaklaşım
  • İmza seviyesi istiyorsanız signatureLevel ile (örn. LTV) belirtebilir veya imza bittikten sonra UpgradePadesCore çağrısı yapabilirsiniz.

UpgradePadesCore

• V1’de istek gövdesi pratikte sadece operationId ile çalışıyordu.
• V2’de istek gövdesi:
  • signatureLevel: zorunlu
  • signaturePath: opsiyonel (null ise dosyadaki tüm imzalar hedef seviyeye yükseltilebilir)

Notlar / breaking changes

• URL prefix: V1'den V2'ye geçerken /v1/ → /v2/ olarak güncelleyin (bu sayfadaki örnekler V2.0 içindir).
• Dosya yükleme: V2'de SignStepOnePadesCore içine fileData gönderilmez; dosya yükleme CoreApiFile akışı ile yapılır.
• İmza doğrulama: V1'deki VerifySignaturesCore (multipart) endpoint'i, V2'de CoreApiPades altında bulunmaz; doğrulama için Verification/ApiVerifySignaturesPades kullanılmalıdır.

V2'den V3'e geçiş

V3, şu an sadece GetSignatureListCore endpoint'ini içerir. Diğer endpoint'ler V2'de kalmaya devam eder.

GetSignatureListCore değişiklikleri

V3'te yeni alanlar

• claimedSigningTime: İmzalayanın beyan ettiği zaman (string)
• claimedSigningTimeAsTime: İmzalayanın beyan ettiği zaman (DateTime)
• timestamp: Zaman damgası bilgisi (varsa)
  • entityLabel: Zaman damgası etiketi (ör. S0:T0)
  • time: Zaman damgası zamanı (string)
  • timeAsTime: Zaman damgası zamanı (DateTime)

En son imzayı bulma

V3 ile en son atılan imzayı doğru şekilde bulabilirsiniz:

// V3 ile en son imzayı bul (zaman damgası varsa onu, yoksa beyan edilen zamanı kullan)
var latestSignature = signatures
    .OrderByDescending(x => x.Timestamp?.TimeAsTime ?? x.ClaimedSigningTimeAsTime)
    .FirstOrDefault();

Not: V2'deki EntityLabel sıralaması (S0, S1, S2...) imzaların atılma sırasını garanti etmez. V3'teki zaman damgası bilgileri ile doğru sıralama yapılabilir.