CoreApiPades (v2.0)

CoreApiPades, PrimeAPI’de PDF üstünde PAdES imzalama işlemlerini yönetir. İmzalama iki adımda gerçekleşir: SignStepOne (başlat) ve signStepThree (bitir). Ayrıca mevcut dosyadaki imzaları listeleme, imzayı daha yüksek seviyeye yükseltme (upgrade), PDF’e dönüştürme ve PDF’e doğrulama yazısı/QR code gibi katmanlar ekleme uç noktaları bulunur. Tüm işlemler bir OperationId etrafında yürür.

Not: PDF’e dönüştürme ve PDF’e katman ekleme uç noktaları CoreApiPdf (v2.0) altında yer alır. Bu sayfada yalnızca CoreApiPades uç noktaları dokümante edilir.

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/CoreApiPades/GetSignatureListCore

GetSignatureListCore

Verilen operationId ile ilişkili PDF dosyasındaki 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/CoreApiPades/GetSignatureListCore

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

SignStepOnePadesCore — İmzayı başlat

PAdES imzalama sürecini başlatır ve istemci tarafındaki e-imza aracına iletilecek state, keyId, keySecret değerlerini döner. PDF üzerinde görünür imza istenirse SignatureWidgetInfo ile görsel/yerleşim bilgileri verilir.

Gerekli/opsiyonel alanlar

Name
operationId
Type
uuid
Description
İmzalanacak PDF’in 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
signatureWidgetInfo
Type
object
Description
(Opsiyonel) Görünür imza için yerleşim/görsel ayarları.
Name
requestId
Type
string
Description
İsteğin tekil kimliği (BaseRequest).
Name
displayLanguage
Type
string
Description
Dil tercihi (BaseRequest).

Request

POST

/v2.0/CoreApiPades/SignStepOnePadesCore

curl -X POST "https://apitest.onaylarim.com/v2.0/CoreApiPades/SignStepOnePadesCore" \
  -H "X-API-KEY: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
        "operationId": "11111111-1111-1111-1111-111111111111",
        "cerBytes": "MIIC...",
        "signatureWidgetInfo": {
          "width": 240,
          "height": 80,
          "left": 0.1,
          "top": 0.1,
          "pagesToPlaceOn": [0]
        },
        "requestId": "aaaaaaaaaaaaaaaaaaaaa",
        "displayLanguage": "tr"
      }'

Response

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

POST/v2.0/CoreApiPades/signStepThreePadesCore

signStepThreePadesCore — İmzayı bitir

İstemcide oluşturulan imzalı veriyi (signedData) göndererek PAdES imzalama sürecini tamamlar. (İstenirse) daha yüksek seviyeye yükseltme işlemi ayrı bir çağrı ile yapılır.

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) PAdES imza seviyesi (boşsa BES).

Request

POST

/v2.0/CoreApiPades/signStepThreePadesCore

curl -X POST "https://apitest.onaylarim.com/v2.0/CoreApiPades/signStepThreePadesCore" \
  -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/CoreApiPades/UpgradePadesCore

UpgradePadesCore

Mevcut PAdES 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 PDF’in işlem kimliği.
Name
signatureLevel
Type
string
Description
Hedef imza seviyesi (SignatureLevelForPades).
Name
signaturePath
Type
string
Description
(Opsiyonel) Yükseltilecek imzanın yolu.

Request

POST

/v2.0/CoreApiPades/UpgradePadesCore

curl -X POST "https://apitest.onaylarim.com/v2.0/CoreApiPades/UpgradePadesCore" \
  -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ış (PAdES)

Dosya yükleme: CoreApiFile/UploadFile veya parça/parça: ChunkInit → ChunkUpload → ChunkComplete
(Gerekirse) PDF’e dönüşüm ve katman ekleme işlemleri CoreApiPdf (v2.0) sayfasındaki uç noktalarla yapılır; dönen operationId ile devam edilir.
CoreApiPades/SignStepOnePadesCore → state, keyId, keySecret alınır (yeni operationId gelebilir).
İstemci e-imza aracına göre signedData üretilir.
CoreApiPades/signStepThreePadesCore ile imzalama tamamlanır (final operationId).
(Opsiyonel) UpgradePadesCore ile PAdES imzalar yükseltilebilir.
*** End Patch !*** } #-} *** End Patch } !*** ! *** End Patch } !*** !*** !*** ***! *** End Patch } ! !*** !*** !*** ! *** End Patch } !*** !*** !*** !*** !*** ***! *** End Patch } ! !*** !*** !*** !*** !*** ! *** End Patch } !*** !*** !*** !*** !*** !*** !*** ***! *** End Patch } ! !*** !*** !*** !*** !*** !*** !*** ! *** End Patch } !*** !*** !*** !*** !*** !*** !*** !*** !*** ***! *** End Patch } ! !*** !*** !*** !*** !*** !*** !*** !*** !*** ! *** End Patch } !*** !*** !*** !*** !*** !*** !*** !*** !*** !*** !*** ***! *** End Patch } ! !*** !*** !*** !*** !*** !*** !*** !*** !*** !*** !*** ***! *** End Patch }``` ***!