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

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.
Name
xadesSignatureType
Type
string
Description
(Varsa) XAdES imza türü.

POST/v2.0/CoreApiXades/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/CoreApiXades/GetSignatureListCore

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

POST/v2.0/CoreApiXades/SignStepOneXadesCore

SignStepOneXadesCore — İmzayı başlat

XAdES 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.
Name
envelopingOrEnveloped
Type
string
Description
(Opsiyonel) ENVELOPING | ENVELOPED. Boş geçilirse ENVELOPED kabul edilir.
Name
envelopingObjectMimeType
Type
string
Description
(Opsiyonel, ENVELOPING için) Zarf içindeki nesnenin MIME türü (örn. application/pdf). Boşsa application/pdf.
Name
envelopingObjectEncoding
Type
string
Description
(Opsiyonel, ENVELOPING için) Encoding değeri (örn. http://www.w3.org/2000/09/xmldsig#base64). Boşsa base64 URL’si.
Name
requestId
Type
string
Description
İsteğin tekil kimliği (BaseRequest).
Name
displayLanguage
Type
string
Description
Dil tercihi (BaseRequest).

Request

POST

/v2.0/CoreApiXades/SignStepOneXadesCore

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

Response

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

POST/v2.0/CoreApiXades/signStepThreeXadesCore

signStepThreeXadesCore — İmzayı bitir

İstemcide oluşturulan imzalı veriyi (signedData) göndererek XAdES 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) XAdES imza seviyesi (boşsa BES).

Request

POST

/v2.0/CoreApiXades/signStepThreeXadesCore

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

Response

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

POST/v2.0/CoreApiXades/UpgradeXadesCore

UpgradeXadesCore

Mevcut XAdES imzasını istenen seviyeye yükseltir. 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 (SignatureLevelForXades).
Name
signaturePath
Type
string
Description
(Opsiyonel) Yükseltilecek imzanın yolu.

Request

POST

/v2.0/CoreApiXades/UpgradeXadesCore

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

Response

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

Örnek akış (XAdES)

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