CoreApiCades (v2.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

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

Properties

  • Name
    entityLabel
    Type
    string
    Description

    İmzanın hiyerarşik etiket değeri (ör. S0, S0:S0).

  • Name
    level
    Type
    integer
    Description

    İmzanın seviye değeri (sayısal).

  • Name
    levelString
    Type
    string
    Description

    İmza seviyesinin metinsel karşılığı.

  • Name
    subjectRDN
    Type
    string
    Description

    İmzalayanın subject bilgisi.

  • Name
    timestamped
    Type
    boolean
    Description

    İmzanın zaman damgasına sahip olup olmadığı.

  • Name
    citizenshipNo
    Type
    string
    Description

    (Varsa) TCKN.

POST/v2.0/CoreApiCades/GetSignatureListCore

GetSignatureListCore

Verilen operationId ile ilişkili dosyadaki tüm imzaları döner.

Gerekli alanlar

  • Name
    operationId
    Type
    uuid
    Description

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

  • Name
    requestId
    Type
    string
    Description

    İsteğin tekil kimliği (BaseRequest).

  • Name
    displayLanguage
    Type
    string
    Description

    Dil tercihi (BaseRequest).

Request

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

Response

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

SignStepOneCadesCore — İmzayı başlat

CAdES imzalama sürecini başlatır ve istemci 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.

  • Name
    coordinates
    Type
    object
    Description

    (Opsiyonel) Konum bilgileri (şu an kullanılmıyor).

  • 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 imza yolu (ör. S0:S0).

  • Name
    citizenshipNo
    Type
    string
    Description

    (Opsiyonel) İmza sahibi TCKN doğrulaması için.

  • Name
    signatureTurkishProfile
    Type
    string
    Description

    (Opsiyonel) P1 | P2 | P3 | P4. Profil istenmiyorsa boş geçilir.

Request

POST
/v2.0/CoreApiCades/SignStepOneCadesCore
curl -X POST "https://apitest.onaylarim.com/v2.0/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"
      }'

Response

{
  "result": {
    "state": "BASE64_STATE",
    "keyID": "abcd1234",
    "keySecret": "wxyz5678",
    "operationId": "22222222-2222-2222-2222-222222222222"
  },
  "error": null
}
POST/v2.0/CoreApiCades/signStepThreeCadesCore

signStepThreeCadesCore — İmzayı bitir

İstemcide oluşturulan imzalı veriyi (signedData) göndererek imzalama sürecini tamamlar.

Gerekli/opsiyonel alanlar

  • Name
    operationId
    Type
    uuid
    Description

    İmza tamamlanacak işlem kimliği.

  • Name
    signedData
    Type
    string
    Description

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

  • Name
    keyId
    Type
    string
    Description

    SignStepOne yanıtındaki KeyId.

  • Name
    keySecret
    Type
    string
    Description

    SignStepOne yanıtındaki KeySecret.

  • Name
    signatureLevel
    Type
    string
    Description

    (Opsiyonel) CAdES imza seviyesi (örn. BES, vb.).

Request

POST
/v2.0/CoreApiCades/signStepThreeCadesCore
curl -X POST "https://apitest.onaylarim.com/v2.0/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"
      }'

Response

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

UpgradeCadesCore

Mevcut CAdES imzasını istenen seviyeye yükseltir (örn. LTV’ye hazırlık niteliğindeki seviye seçenekleri). Belirli bir imzanın yükseltilmesi istenirse signaturePath sağlanabilir; boş bırakılırsa tüm imzalar yükseltilebilir.

Gerekli/opsiyonel alanlar

  • Name
    operationId
    Type
    uuid
    Description

    Yükseltme yapılacak dosyanın işlem kimliği.

  • Name
    signatureLevel
    Type
    string
    Description

    Hedef imza seviyesi (SignatureLevelForCades).

  • Name
    signaturePath
    Type
    string
    Description

    (Opsiyonel) Yükseltilecek imzanın yolu.

Request

POST
/v2.0/CoreApiCades/UpgradeCadesCore
curl -X POST "https://apitest.onaylarim.com/v2.0/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"
      }'

Response

{
  "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 doğrulanır/listelenir.

Was this page helpful?