CoreApiXades (v4.0)

CoreApiXades V4, XML tabanli XAdES imzalama islemlerinin en guncel versiyonudur. V2/V3'teki tum ozelliklere ek olarak imza profilleri (P1-P4), uc farkli imza modu (Enveloped, Enveloping, Detached), tum XAdES seviyeleri (BES, EPES, T, XL, A) ve akilli upgrade onerileri sunar. Imzalama iki adimda gerceklesir: SignStepOne (baslat) ve SignStepThree (bitir).

Temel kavramlar

• OperationId: Islem kimligi. Bir adim yeni cikti uretiyorsa yanit icinde yeni OperationId doner ve takip eden adimlarda bu yeni deger kullanilmalidir.
• Imza Modlari: Enveloped (imza XML icine gomulur), Enveloping (veri imza icine gomulur), Detached (imza ayri dosyada, veri referans edilir).
• Profiller: Turk Elektronik Imza Kullanim Profilleri (P1-P4). Profil secimi, imza seviyesi ve revocation check davranisini belirler.
• Auth: Tum uc noktalar ApiKey gerektirir.
• Zarf: Tum yanitlar ApiResult<T> tipindedir:
  • result: T
  • error: string (hata durumunda dolar)

Enum: SignatureLevelForXadesV4

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

Not: CAdES'ten farkli olarak XAdES V4'te C (4) ve X (5) seviyeleri desteklenmez. Numara siralamasi CAdES ile uyumlu tutulmustur.

Enum: XadesProfileV4

Turk Elektronik Imza Kullanim Profilleri (Rehber v1.0).

Enum: XadesSignatureModeV4

XAdES imza modlari. StepOne'da imza modu belirtilir.

Enum: CadesHashAlgorithmV4

CAdES ile paylasilan hash algoritmasi enum'u.

Imza bilgisi modeli (XadesSignatureInfoV4)

{
  "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",
  "parentEntity": null,
  "signatureMode": "Enveloped",
  "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

GetSignatureListCore

curl -X POST "https://apitest.onaylarim.com/v4/CoreApiXades/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"
      }'

{
  "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",
        "parentEntity": null,
        "signatureMode": "Enveloped",
        "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,
    "signatureMode": "Enveloped",
    "operationId": "11111111-1111-1111-1111-111111111111"
  },
  "error": null
}

SignStepOneXadesCore -- Imzayi baslat

curl -X POST "https://apitest.onaylarim.com/v4/CoreApiXades/SignStepOneXadesCore" \
  -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,
        "signatureMode": 0,
        "requestId": "aaaaaaaaaaaaaaaaaaaaa",
        "displayLanguage": "tr"
      }'

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

SignStepThreeXadesCore -- Imzayi bitir

curl -X POST "https://apitest.onaylarim.com/v4/CoreApiXades/SignStepThreeXadesCore" \
  -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"
      }'

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

UpgradeXadesCore

curl -X POST "https://apitest.onaylarim.com/v4/CoreApiXades/UpgradeXadesCore" \
  -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"
      }'

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

Ornek akis (Enveloped, P4 profilli XL imza)

1. XML dosya yukleme: CoreApiFile/UploadFile veya parca/parca: ChunkInit -> ChunkUpload -> ChunkComplete -> uploadOpId
2. SignStepOneXadesCore ile imzayi baslat:
   • signatureLevel: 6 (XL), profile: 4 (P4), signatureMode: 0 (Enveloped)
   • -> state, keyId, keySecret, yeni operationId
3. Istemci e-imza araciyla state'i imzalar -> signedData
4. SignStepThreeXadesCore ile imzayi tamamla
   • BES olarak imzalanir, ardindan otomatik XL'e upgrade edilir
   • -> isSuccess: true, final operationId
5. (Opsiyonel) GetSignatureListCore ile imzalari kontrol et
6. (Opsiyonel) UpgradeXadesCore ile A seviyesine yukselt

Ornek akis (Enveloping, profilsiz BES + sonradan upgrade)

1. Dosya yukleme -> uploadOpId
2. SignStepOneXadesCore:
   • signatureLevel: 1 (BES), profile: 0 (None), signatureMode: 1 (Enveloping)
   • envelopingObjectMimeType: "application/pdf", envelopingObjectEncoding: "http://www.w3.org/2000/09/xmldsig#base64"
   • -> state, keyId, keySecret
3. Istemci signedData uretir
4. SignStepThreeXadesCore -> BES seviyesinde kalir -> final operationId
5. UpgradeXadesCore ile targetLevel: 3 (T) veya targetLevel: 6 (XL) olarak yukselt

Ornek akis (Detached, ikinci imza ekleme)

1. Orijinal dosya zaten yuklenmis: uploadOpId
2. Ilk detached imza atilmis: baseOpId (detached XML imza dosyasi)
3. Ikinci imza icin SignStepOneXadesCore:
   • operationId: baseOpId, signatureMode: 2 (Detached)
   • originalFileOperationId: uploadOpId (orijinal dosya referansi)
   • serialOrParallel: "SERIAL", signaturePath: "S0"
4. SignStepThreeXadesCore -> final operationId
5. Upgrade: UpgradeXadesCore ile originalFileOperationId: uploadOpId vererek upgrade

Ornek akis (Seri imza -- Enveloped)

1. XML dosya yukleme -> uploadOpId
2. Ilk imza: SignStepOneXadesCore + SignStepThreeXadesCore -> firstSignOpId
3. Ikinci imza (seri): SignStepOneXadesCore:
   • operationId: firstSignOpId
   • serialOrParallel: "SERIAL", signaturePath: "S0" (ilk imzanin uzerine)
   • -> state, keyId, keySecret
4. SignStepThreeXadesCore -> final operationId
5. GetSignatureListCore ile kontrol: S0 ve S0:S0 gorunur

V2/V3'ten V4'e gecis

Endpoint degisiklik ozeti

V2 -> V4 request alani donusumleri

SignStepOneXadesCore

• V2'de vardi, V4'te degisti
  • signatureTurkishProfile (string) -> profile (XadesProfileV4 enum: 0-4)
  • envelopingOrEnveloped (string) -> signatureMode (XadesSignatureModeV4 enum: 0-2). V4'te Detached mod da eklenmistir.
• V4'te yeni
  • signatureLevel: Hedef seviye (BES-A). V2'de bu StepThree'de veriliyordu.
  • profile: Turk imza profili (enum).
  • hashAlgorithm: Hash algoritmasi secimi.
  • signatureMode: Enveloped/Enveloping/Detached (enum).
  • originalFileOperationId: Detached dosyalarda orijinal dosya referansi.
  • detachedResourceUri: Detached imzadaki Reference URI.
  • envelopedContentElementId: Enveloped modda hedef eleman ID'si.
• V2'de vardi, V4'te kaldirildi
  • citizenshipNo: V4'te bu alan StepOne'da yoktur.
  • coordinates: Kaldirildi.

signStepThreeXadesCore -> SignStepThreeXadesCore

• V2'de vardi, V4'te kaldirildi
  • signatureLevel: Artik StepOne'da verilir, StepThree'de otomatik uygulanir.
• URL farki: V2'de kucuk 's' (signStepThreeXadesCore), V4'te buyuk 'S' (SignStepThreeXadesCore).

UpgradeXadesCore

• V2'de signatureLevel -> V4'te targetLevel (farkli enum tipi, BES/EPES hedef olamaz).
• V4'te yeni: originalFileOperationId (detached dosya destegi).

Profil-seviye uyumluluk tablosu

Not: Uyumsuz profil-seviye kombinasyonu (or. P3 + T) API tarafindan reddedilir.

Imza modu -- V2 vs V4 karsilastirmasi

Not: V2'de Detached mod yoktu. V4 ile Detached imza destegi eklenmistir.