CoreApiXades (v2.0)

CoreApiXades, PrimeAPI’de XML tabanlı XAdES 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

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

Properties

GetSignatureListCore

curl -X POST "https://apitest.onaylarim.com/v2/CoreApiXades/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,
        "xadesSignatureType": "ENVELOPED"
      }
    ],
    "operationId": "11111111-1111-1111-1111-111111111111"
  },
  "error": null
}

SignStepOneXadesCore — İmzayı başlat

curl -X POST "https://apitest.onaylarim.com/v2/CoreApiXades/SignStepOneXadesCore" \
  -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",
        "envelopingOrEnveloped": "ENVELOPED",
        "envelopingObjectMimeType": "application/pdf",
        "envelopingObjectEncoding": "http://www.w3.org/2000/09/xmldsig#base64",
        "requestId": "aaaaaaaaaaaaaaaaaaaaa",
        "displayLanguage": "tr"
      }'

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

signStepThreeXadesCore — İmzayı bitir

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

UpgradeXadesCore

curl -X POST "https://apitest.onaylarim.com/v2/CoreApiXades/UpgradeXadesCore" \
  -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ış (XAdES)

1. Dosya yükleme: CoreApiFile/UploadFile veya parça/parça: ChunkInit → ChunkUpload → ChunkComplete
2. CoreApiXades/SignStepOneXadesCore → state, keyId, keySecret alınır (yeni operationId gelebilir).
3. İstemci e-imza aracına göre signedData üretilir.
4. CoreApiXades/signStepThreeXadesCore ile imzalama tamamlanır (final operationId).
5. (Opsiyonel) UpgradeXadesCore ile imzalar yükseltilebilir.

V1’den V2’ye geçiş

Bu sayfa V2.0 uç noktalarını anlatır. Eğer mevcut entegrasyonunuz V1 (/v1/CoreApiXades) 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 (XAdES)

SignStepOneXadesCore

• V1’de vardı, V2’de kaldırıldı
  • fileData: V2’de SignStepOneXadesCore içinde gönderilmez. Dosyayı önce CoreApiFile/UploadFile (veya chunk akışı) ile yükleyip dönen operationId ile devam edin.
  • signatureIndex: V1’de “kaçıncı imza” mantığı için kullanılıyordu. V2’de bunun yerine:
    • serialOrParallel (SERIAL | PARALLEL)
    • Seri imzada hedef imzayı belirtmek için signaturePath (S0, S0:S0 gibi)
  • xmlSignatureType (int): V1’de ENVELOPING=2, ENVELOPED=4 idi. V2’de bunun yerine envelopingOrEnveloped (ENVELOPING | ENVELOPED) kullanılır.
• V2’de yeni
  • citizenshipNo, signatureTurkishProfile (opsiyonel)
  • envelopingObjectMimeType, envelopingObjectEncoding: ENVELOPING için opsiyonel (V1’e benzer, fakat V2’de tipler string ile kontrol edilir)

V1 örnek istek (özet):

{
  "operationId": "11111111-1111-1111-1111-111111111111",
  "cerBytes": "MIIC...",
  "fileData": "BASE64_FILE_BYTES",
  "signatureIndex": 0,
  "xmlSignatureType": 4,
  "envelopingObjectMimeType": "application/pdf",
  "envelopingObjectEncoding": "http://www.w3.org/2000/09/xmldsig#base64",
  "requestId": "aaaaaaaaaaaaaaaaaaaaa",
  "displayLanguage": "tr"
}

V2 örnek istek (özet):

{
  "operationId": "11111111-1111-1111-1111-111111111111",
  "cerBytes": "MIIC...",
  "serialOrParallel": "SERIAL",
  "signaturePath": "S0",
  "citizenshipNo": null,
  "signatureTurkishProfile": "P4",
  "envelopingOrEnveloped": "ENVELOPED",
  "envelopingObjectMimeType": "application/pdf",
  "envelopingObjectEncoding": "http://www.w3.org/2000/09/xmldsig#base64",
  "requestId": "aaaaaaaaaaaaaaaaaaaaa",
  "displayLanguage": "tr"
}

signStepThreeXadesCore

• V1’de istek gövdesi signedData, keyId, keySecret, operationId içeriyordu.
• V2’de aynı alanlara ek olarak:
  • signatureLevel: opsiyonel (boşsa BES)

UpgradeXadesCore

• 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 SignStepOneXadesCore içine fileData gönderilmez; dosya yükleme CoreApiFile akışı ile yapılır.