CoreApiCades (v4.0)

CoreApiCades V4, CAdES imzalama işlemlerinin en güncel versiyonudur. V2/V3'teki tüm özelliklere ek olarak imza profilleri (P1–P4), detached imza, tüm CAdES seviyeleri (BES, EPES, T, C, X, XL, A) ve akıllı upgrade önerileri sunar. İmzalama iki adımda gerçekleşir: SignStepOne (başlat) ve SignStepThree (bitir).

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.
  • Attached vs Detached: Attached imzada orijinal dosya .p7s içine gömülür. Detached imzada .p7s yalnızca imza verisini içerir; orijinal dosya ayrı tutulur.
  • Profiller: Türk Elektronik İmza Kullanım Profilleri (P1–P4). Profil seçimi, imza seviyesi ve revocation check davranışını belirler.
  • Auth: Tüm uç noktalar ApiKey gerektirir.
  • Zarf: Tüm yanıtlar ApiResult<T> tipindedir:
    • result: T
    • error: string (hata durumunda dolar)

Enum: SignatureLevelForCadesV4

CAdES imza seviyeleri. StepOne'da hedef seviye belirtilir; StepThree sonunda otomatik upgrade edilir.

DeğerKodAçıklama
BES1Basic Electronic Signature
EPES2Electronic Signature with Explicit Policy
T3ES-T — Zaman damgalı
C4ES-C — T + revocation referansları
X5ES-X — C + zaman damgası
XL6ES-XL — X + revocation değerleri
A7ES-A — Arşiv zaman damgalı

Enum: CadesProfileV4

Türk Elektronik İmza Kullanım Profilleri (Rehber v1.0).

DeğerKodAçıklamaMin. SeviyeRevocation
None0Profil yokBES—
P11Profilsiz BESBES—
P22EPES + T, SİL (CRL)TCRL
P33EPES + XL/A, SİL (CRL)XLCRL
P44EPES + XL/A, ÇİSDuP (OCSP)XLOCSP

Enum: CadesHashAlgorithmV4

DeğerKod
SHA2560
SHA3841
SHA5122

İmza bilgisi modeli (CadesSignatureInfoV4)

V4 imza listesinde dönen her imza aşağıdaki alanlardan oluşur. V3'e göre profil, hash algoritması, upgrade önerileri ve detached bilgisi eklenmiştir.

Properties

  • Name
    entityLabel
    Type
    string
    Description

    İmzanın hiyerarşik etiketi (ör. S0, S0:S0, S1).

  • Name
    level
    Type
    string
    Description

    İmza seviyesi kısa kodu (ör. BES, T, XL, A).

  • Name
    levelString
    Type
    string
    Description

    İmza seviyesinin tam adı.

  • Name
    subjectRDN
    Type
    string
    Description

    İmzalayanın sertifika subject bilgisi.

  • Name
    citizenshipNo
    Type
    string?
    Description

    (Varsa) TCKN.

  • Name
    timestamped
    Type
    boolean
    Description

    Zaman damgasına sahip olup olmadığı.

  • Name
    claimedSigningTime
    Type
    string?
    Description

    Beyan edilen imza zamanı (string).

  • Name
    claimedSigningTimeAsTime
    Type
    datetime?
    Description

    Beyan edilen imza zamanı (DateTime).

  • Name
    scope
    Type
    integer
    Description

    İmzanın kapsamı (1: imza, 2: karşı imza, 3: zaman damgası).

  • Name
    parentEntity
    Type
    string?
    Description

    Üst imza (seri imzada).

  • Name
    profileName
    Type
    string?
    Description

    Profil adı (P2, P3, P4 veya null).

  • Name
    policyOID
    Type
    string?
    Description

    İmzadaki Policy OID.

  • Name
    hashAlgorithm
    Type
    string?
    Description

    Kullanılan hash algoritması.

  • Name
    containsLongTermInfo
    Type
    boolean
    Description

    Uzun vadeli doğrulama bilgisi içeriyor mu.

  • Name
    lastArchivalTime
    Type
    string?
    Description

    Son arşivleme zamanı (A seviyesinde).

  • Name
    timestamp
    Type
    TimestampInfoItemV4?
    Description

    Zaman damgası bilgisi.

  • Name
    upgradeOptions
    Type
    string[]
    Description

    Mevcut seviyeden yapılabilecek tüm upgrade seçenekleri (ör. ["T","C","X","XL","A"]). En üst seviyede boş döner.

  • Name
    profileRecommendedUpgrades
    Type
    string[]?
    Description

    Profil uyumlu upgrade seçenekleri. Profil yoksa null.

  • Name
    profileIncompatibleUpgrades
    Type
    string[]?
    Description

    Profil dışı (teknik olarak mümkün ama uyumsuz) upgrade seçenekleri. Profil yoksa null.

Örnek imza (XL, P4 profilli)

{
  "entityLabel": "S0",
  "level": "XL",
  "levelString": "Extended-XL-Type-2",
  "subjectRDN": "CN=AHMET YILMAZ/SN=12345678901",
  "citizenshipNo": "12345678901",
  "timestamped": true,
  "claimedSigningTime": "2026-02-24 10:30:00.000",
  "claimedSigningTimeAsTime": "2026-02-24T10:30:00",
  "scope": 1,
  "parentEntity": null,
  "profileName": "P4",
  "policyOID": "2.16.792.1.61.0.1.5070.3.3.1",
  "hashAlgorithm": "SHA256",
  "containsLongTermInfo": true,
  "lastArchivalTime": null,
  "timestamp": {
    "entityLabel": "S0:T0",
    "time": "2026-02-24 10:30:05.123",
    "timeAsTime": "2026-02-24T10:30:05.123",
    "tsaName": "CN=TUBITAK KAMU SM TSA",
    "hashAlgorithm": "SHA512",
    "timestampType": 1,
    "timestampTypeStr": "Signature"
  },
  "upgradeOptions": ["A"],
  "profileRecommendedUpgrades": ["A"],
  "profileIncompatibleUpgrades": []
}

TimestampInfoItemV4

  • Name
    entityLabel
    Type
    string
    Description

    Zaman damgasının etiketi (ör. S0:T0).

  • Name
    time
    Type
    string?
    Description

    Zaman damgası zamanı (string).

  • Name
    timeAsTime
    Type
    datetime?
    Description

    Zaman damgası zamanı (DateTime).

  • Name
    tsaName
    Type
    string?
    Description

    Zaman damgası otoritesi adı.

  • Name
    hashAlgorithm
    Type
    string?
    Description

    Hash algoritması.

  • Name
    timestampType
    Type
    integer
    Description

    Zaman damgası türü (sayısal).

  • Name
    timestampTypeStr
    Type
    string?
    Description

    Zaman damgası türü (metinsel).

POST/v4/CoreApiCades/GetSignatureListCore

GetSignatureListCore

Verilen operationId ile ilişkili dosyadaki tüm imzaları döner. Dosyanın detached olup olmadığını, her imzanın profilini, upgrade seçeneklerini ve zaman damgası detaylarını içerir.

Gerekli/opsiyonel alanlar

  • Name
    operationId
    Type
    uuid
    Description

    İmzaları listelenecek dosyanın işlem kimliği.

  • Name
    originalFileOperationId
    Type
    uuid?
    Description

    (Detached imzalarda) Orijinal dosyanın operasyon ID'si. Attached imzalarda null/boş bırakılır.

  • Name
    requestId
    Type
    string
    Description

    21 karakter uzunluğunda benzersiz bir string.

  • Name
    displayLanguage
    Type
    string
    Description

    Dil tercihi.

Request

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

Response

{
  "result": {
    "signatures": [
      {
        "entityLabel": "S0",
        "level": "XL",
        "levelString": "Extended-XL-Type-2",
        "subjectRDN": "CN=AHMET YILMAZ/SN=12345678901",
        "citizenshipNo": "12345678901",
        "timestamped": true,
        "claimedSigningTime": "2026-02-24 10:30:00.000",
        "claimedSigningTimeAsTime": "2026-02-24T10:30:00",
        "scope": 1,
        "parentEntity": null,
        "profileName": "P4",
        "policyOID": "2.16.792.1.61.0.1.5070.3.3.1",
        "hashAlgorithm": "SHA256",
        "containsLongTermInfo": true,
        "lastArchivalTime": null,
        "timestamp": {
          "entityLabel": "S0:T0",
          "time": "2026-02-24 10:30:05.123",
          "timeAsTime": "2026-02-24T10:30:05.123",
          "tsaName": "CN=TUBITAK KAMU SM TSA",
          "hashAlgorithm": "SHA512",
          "timestampType": 1,
          "timestampTypeStr": "Signature"
        },
        "upgradeOptions": ["A"],
        "profileRecommendedUpgrades": ["A"],
        "profileIncompatibleUpgrades": []
      }
    ],
    "isDetached": false,
    "operationId": "11111111-1111-1111-1111-111111111111"
  },
  "error": null
}
POST/v4/CoreApiCades/SignStepOneCadesCore

SignStepOneCadesCore — İmzayı başlat

CAdES imzalama sürecini başlatır. Hedef seviye, profil, hash algoritması ve detached mod burada belirlenir. İstemci tarafındaki e-imza aracına iletilecek state, keyId, keySecret değerlerini döner.

Gerekli/opsiyonel alanlar

  • Name
    operationId
    Type
    uuid
    Description

    İmzalanacak dosyanın işlem kimliği.

  • Name
    cerBytes
    Type
    string
    Description

    İmzalayan sertifikanın Base64 metni (DER veya PEM).

  • Name
    signatureLevel
    Type
    SignatureLevelForCadesV4
    Description

    Hedef imza seviyesi. StepThree'de bu seviyeye otomatik upgrade edilir.

  • Name
    profile
    Type
    CadesProfileV4
    Description

    Türk imza profili. None veya P1: profilsiz BES. P2/P3/P4: EPES tabanlı (policy dahil).

  • Name
    hashAlgorithm
    Type
    CadesHashAlgorithmV4
    Description

    Hash algoritması. Varsayılan: SHA256 (0).

  • Name
    detached
    Type
    boolean
    Description

    true ise detached imza oluşturulur (orijinal veri .p7s içine gömülmez).

  • Name
    serialOrParallel
    Type
    string?
    Description

    (Opsiyonel) SERIAL | PARALLEL. Boş geçilirse PARALLEL kabul edilir.

  • Name
    signaturePath
    Type
    string?
    Description

    (Opsiyonel) Seri imzada, üzerine imza atılacak imzanın EntityLabel'ı (ör. S0).

  • Name
    originalFileOperationId
    Type
    uuid?
    Description

    (Detached) Mevcut bir detached imza dosyasına yeni imza eklerken orijinal dosyanın operasyon ID'si. İlk detached imzada gerekli değildir.

Request

POST
/v4/CoreApiCades/SignStepOneCadesCore
curl -X POST "https://apitest.onaylarim.com/v4/CoreApiCades/SignStepOneCadesCore" \
  -H "X-API-KEY: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
        "operationId": "11111111-1111-1111-1111-111111111111",
        "cerBytes": "MIIC...",
        "signatureLevel": 6,
        "profile": 4,
        "hashAlgorithm": 0,
        "detached": false,
        "requestId": "aaaaaaaaaaaaaaaaaaaaa",
        "displayLanguage": "tr"
      }'

Response

{
  "result": {
    "state": "BASE64_STATE",
    "keyID": "abcd1234",
    "keySecret": "wxyz5678",
    "operationId": "22222222-2222-2222-2222-222222222222"
  },
  "error": null
}
POST/v4/CoreApiCades/SignStepThreeCadesCore

SignStepThreeCadesCore — İmzayı bitir

İstemcide oluşturulan imzalı veriyi (signedData) göndererek imzalama sürecini tamamlar. StepOne'da belirtilen hedef seviye BES/EPES'den yüksekse, imza otomatik olarak o seviyeye upgrade edilir.

Gerekli alanlar

  • Name
    operationId
    Type
    uuid
    Description

    StepOne'dan dönen işlem kimliği.

  • Name
    signedData
    Type
    string
    Description

    E-imza aracından dönen imzalı veri (Base64).

  • Name
    keyId
    Type
    string
    Description

    StepOne yanıtındaki KeyId.

  • Name
    keySecret
    Type
    string
    Description

    StepOne yanıtındaki KeySecret.

Not: V2'den farklı olarak V4'te signatureLevel bu adımda gönderilmez. Hedef seviye StepOne'da belirlenir ve StepThree'de otomatik uygulanır.

Request

POST
/v4/CoreApiCades/SignStepThreeCadesCore
curl -X POST "https://apitest.onaylarim.com/v4/CoreApiCades/SignStepThreeCadesCore" \
  -H "X-API-KEY: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
        "operationId": "22222222-2222-2222-2222-222222222222",
        "signedData": "BASE64_SIGNED_DATA",
        "keyId": "abcd1234",
        "keySecret": "wxyz5678",
        "requestId": "aaaaaaaaaaaaaaaaaaaaa",
        "displayLanguage": "tr"
      }'

Response

{
  "result": {
    "isSuccess": true,
    "operationId": "33333333-3333-3333-3333-333333333333"
  },
  "error": null
}
POST/v4/CoreApiCades/UpgradeCadesCore

UpgradeCadesCore

Mevcut CAdES imzasını istenen seviyeye yükseltir. Tüm seviyeler desteklenir: T, C, X, XL, A. Detached dosyalarda originalFileOperationId zorunludur.

İpucu: Hangi seviyeye upgrade yapılabileceğini öğrenmek için önce GetSignatureListCore çağrısı yapın. Dönen upgradeOptions ve profileRecommendedUpgrades alanları yol gösterir.

Gerekli/opsiyonel alanlar

  • Name
    operationId
    Type
    uuid
    Description

    Upgrade edilecek dosyanın işlem kimliği.

  • Name
    targetLevel
    Type
    SignatureLevelForCadesV4
    Description

    Hedef seviye (mevcut seviyeden yüksek olmalı).

  • Name
    signaturePath
    Type
    string?
    Description

    (Opsiyonel) Upgrade edilecek imzanın EntityLabel'ı (ör. S0). Boş bırakılırsa ilk imza upgrade edilir.

  • Name
    originalFileOperationId
    Type
    uuid?
    Description

    (Detached imzalarda zorunlu) Orijinal dosyanın operasyon ID'si.

Request

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

Response

{
  "result": {
    "isSuccess": true,
    "operationId": "44444444-4444-4444-4444-444444444444"
  },
  "error": null
}

Örnek akış (Attached, P4 profilli XL imza)

  1. Dosya yükleme: CoreApiFile/UploadFile veya parça/parça: ChunkInit → ChunkUpload → ChunkComplete → uploadOpId
  2. SignStepOneCadesCore ile imzayı başlat:
    • signatureLevel: 6 (XL), profile: 4 (P4), detached: false
    • → state, keyId, keySecret, yeni operationId
  3. İstemci e-imza aracıyla state'i imzalar → signedData
  4. SignStepThreeCadesCore ile imzayı tamamla
    • BES olarak imzalanır, ardından otomatik XL'e upgrade edilir
    • → isSuccess: true, final operationId
  5. (Opsiyonel) GetSignatureListCore ile imzaları kontrol et
  6. (Opsiyonel) UpgradeCadesCore ile A seviyesine yükselt

Örnek akış (Detached, ikinci imza ekleme)

  1. Orijinal dosya zaten yüklenmiş: uploadOpId
  2. İlk detached imza atılmış: baseOpId (detached .p7s)
  3. İkinci imza için SignStepOneCadesCore:
    • operationId: baseOpId, detached: true
    • originalFileOperationId: uploadOpId (orijinal dosya referansı)
    • serialOrParallel: "SERIAL", signaturePath: "S0"
  4. SignStepThreeCadesCore → final operationId
  5. Upgrade: UpgradeCadesCore ile originalFileOperationId: uploadOpId vererek upgrade

V2/V3'ten V4'e geçiş

Endpoint değişiklik özeti

AmaçV2/V3 endpointV4 endpointÖnemli farklar
İmzayı başlatPOST /v2/.../SignStepOneCadesCorePOST /v4/.../SignStepOneCadesCoreYeni: signatureLevel, profile, hashAlgorithm, detached, originalFileOperationId. Kaldırılan: citizenshipNo, signatureTurkishProfile (yerine profile enum).
İmzayı bitirPOST /v2/.../signStepThreeCadesCorePOST /v4/.../SignStepThreeCadesCoresignatureLevel artık StepOne'da verilir, StepThree'de yok. URL'de büyük 'S' harfi.
İmzayı yükseltPOST /v2/.../UpgradeCadesCorePOST /v4/.../UpgradeCadesCoresignatureLevel → targetLevel. Tüm seviyeler (T, C, X, XL, A). Detached desteği (originalFileOperationId).
İmza listesiPOST /v3/.../GetSignatureListCorePOST /v4/.../GetSignatureListCoreYeni: isDetached, profileName, policyOID, hashAlgorithm, upgradeOptions, profileRecommendedUpgrades, profileIncompatibleUpgrades, originalFileOperationId.

V2 → V4 request alanı dönüşümleri

SignStepOneCadesCore

  • V2'de vardı, V4'te değişti
    • signatureTurkishProfile (string) → profile (CadesProfileV4 enum: 0–4)
  • V4'te yeni
    • signatureLevel: Hedef seviye (BES–A). V2'de bu StepThree'de veriliyordu.
    • profile: Türk imza profili (enum).
    • hashAlgorithm: Hash algoritması seçimi.
    • detached: Detached imza modu.
    • originalFileOperationId: Detached dosyalarda orijinal dosya referansı.
  • V2'de vardı, V4'te kaldırıldı
    • citizenshipNo: V4'te bu alan StepOne'da yoktur.
    • coordinates: Kaldırıldı.

signStepThreeCadesCore → SignStepThreeCadesCore

  • V2'de vardı, V4'te kaldırıldı
    • signatureLevel: Artık StepOne'da verilir, StepThree'de otomatik uygulanır.
  • URL farkı: V2'de küçük 's' (signStepThreeCadesCore), V4'te büyük 'S' (SignStepThreeCadesCore).

UpgradeCadesCore

  • V2'de signatureLevel → V4'te targetLevel (farklı enum tipi, tüm seviyeler desteklenir).
  • V4'te yeni: originalFileOperationId (detached dosya desteği).

Profil-seviye uyumluluk tablosu

Profilİzin verilen seviyelerÖnerilen minimum
None / P1BES, T, C, X, XL, ABES
P2EPES, TT
P3EPES, XL, AXL
P4EPES, XL, AXL

Not: Uyumsuz profil-seviye kombinasyonu (ör. P3 + T) API tarafından reddedilir.

Was this page helpful?