CoreApiCades (v2.0 / v3.0)

CoreApiCades, PrimeAPI’de CAdES imzalama işlemlerini yönetir. İmzalama iki adımda gerçekleşir: SignStepOne (başlat) ve signStepThree (bitir). Ayrıca mevcut dosyadaki imzaları listeleme ve imzayı daha yüksek seviyeye yükseltme (upgrade) uç noktaları bulunur. Tüm işlemler bir OperationId etrafında yürür.

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/CoreApiCades/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/CoreApiCades/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
}

SignStepOneCadesCore — İmzayı başlat

curl -X POST "https://apitest.onaylarim.com/v2/CoreApiCades/SignStepOneCadesCore" \
  -H "X-API-KEY: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
        "operationId": "11111111-1111-1111-1111-111111111111",
        "cerBytes": "MIIC...",
        "serialOrParallel": "SERIAL",
        "signaturePath": "S0",
        "citizenshipNo": null,
        "signatureTurkishProfile": "P4",
        "requestId": "aaaaaaaaaaaaaaaaaaaaa",
        "displayLanguage": "tr"
      }'

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

signStepThreeCadesCore — İmzayı bitir

curl -X POST "https://apitest.onaylarim.com/v2/CoreApiCades/signStepThreeCadesCore" \
  -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",
        "requestId": "aaaaaaaaaaaaaaaaaaaaa",
        "displayLanguage": "tr"
      }'

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

UpgradeCadesCore

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

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

Örnek akış (CAdES)

1. Dosya yükleme: CoreApiFile/UploadFile veya parça/parça: ChunkInit → ChunkUpload → ChunkComplete
2. CoreApiCades/SignStepOneCadesCore → state, keyId, keySecret alınır (yeni operationId gelebilir).
3. İstemci e-imza aracıyla imzayı üretir ve signedData üretir.
4. CoreApiCades/signStepThreeCadesCore ile imzalama tamamlanır (final operationId).
5. (Opsiyonel) UpgradeCadesCore ile imzalar yükseltilebilir.
6. (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/CoreApiCades) 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 (CAdES)

SignStepOneCadesCore

• V1’de vardı, V2’de kaldırıldı
  • fileData: V2’de SignStepOneCadesCore içinde gönderilmez. Dosyayı önce CoreApiFile/UploadFile (veya chunk akışı) ile yükleyip dönen operationId ile devam edin.
  • signatureIndex: V2’de bunun yerine signaturePath (seri imza için) kullanılır.
• V2’de yeni
  • serialOrParallel: SERIAL | PARALLEL (boş ise PARALLEL kabul edilir)
  • signaturePath: Seri imzada hedef imzayı belirtir (S0, S0:S0 gibi). Parallel imzada yok sayılır.
  • citizenshipNo ve signatureTurkishProfile: opsiyonel ek kontroller/profil seçimi

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...",
  "serialOrParallel": "SERIAL",
  "signaturePath": "S0",
  "citizenshipNo": null,
  "signatureTurkishProfile": "P4",
  "requestId": "aaaaaaaaaaaaaaaaaaaaa",
  "displayLanguage": "tr"
}

UpgradeCadesCore

• 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).
• İmza doğrulama: V1'deki VerifySignaturesCoreCades (multipart) endpoint'i, V2'de CoreApiCades altında bulunmaz; doğrulama için Verification/ApiVerifySignaturesCades 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.