CoreApiPades (v4.0)

CoreApiPades V4, PDF üzerinde PAdES imzalama işlemlerinin en güncel versiyonudur. V2/V3'teki tüm özelliklere ek olarak imza profilleri (P3, P4), tüm PAdES Baseline seviyeleri (B-B, B-T, B-LT, B-LTA), hash algoritması seçimi ve akıllı upgrade önerileri sunar. İmzalama iki adımda gerçekleşir: SignStepOne (başlat) ve SignStepThree (bitir).

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.
Profiller: Türk Elektronik İmza Kullanım Profilleri. PAdES'te yalnızca P4 (ÇİSDuP/OCSP) desteklenir. P3 (SİL/CRL) PAdES'te desteklenmez — CAdES/XAdES için kullanılır.
B-LT kısıtı: B-LT seviyesine UpgradePadesCore ile ulaşılamaz. Update işlemi her zaman Document Timestamp ekler ve B-LTA üretir. B-LT yalnızca SignStepOne'da signatureLevel: 3 (BLT) ile doğrudan üretilebilir.
Auth: Tüm uç noktalar ApiKey gerektirir.
Zarf: Tüm yanıtlar ApiResult<T> tipindedir:
- result: T
- error: string (hata durumunda dolar)

Enum: SignatureLevelForPadesV4

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

Değer	Kod	Açıklama
`BB`	1	B-B — Baseline Basic
`BT`	2	B-T — Baseline Timestamp
`BLT`	3	B-LT — Baseline Long-Term (yalnızca Sign ile üretilebilir)
`BLTA`	4	B-LTA — Baseline Long-Term Archival

Not: PAdES'te CAdES'ten farklı olarak C/X/XL/A seviyeleri yoktur. DSS dictionary ile doğrudan B-LT/B-LTA'ya geçilir.

Enum: PadesProfileV4

Türk Elektronik İmza Kullanım Profilleri (Rehber v1.0). PAdES'te yalnızca P4 desteklenir.

Değer	Kod	Açıklama	Min. Seviye	Revocation
`None`	0	Profil yok	B-B	—
`P3`	3	~~SİL (CRL)~~ — PAdES'te desteklenmez	—	—
`P4`	4	EPES + B-LT/B-LTA, ÇİSDuP (OCSP)	B-LT	OCSP

Not: P3 profili gönderilirse API hata döner. PAdES'te CRL tabanlı revocation check desteklenmediğinden sadece P4 (OCSP) kullanılabilir.

Enum: CadesHashAlgorithmV4 (Paylaşımlı)

Hash algoritması seçimi. CAdES, PAdES ve XAdES V4 arasında ortak kullanılır.

Değer	Kod
`SHA256`	0
`SHA384`	1
`SHA512`	2

İmza bilgisi modeli (PadesSignatureInfoV4)

V4 imza listesinde dönen her imza aşağıdaki alanlardan oluşur. V3'e göre profil, hash algoritması, upgrade önerileri eklenmiştir.

Properties

Name
entityLabel
Type
string
Description
İmzanın hiyerarşik etiketi (ör. S0, S1).
Name
level
Type
string
Description
İmza seviyesi kısa kodu (ör. B-B, B-T, B-LT, B-LTA).
Name
levelString
Type
string
Description
İmza seviyesinin tam adı.
Name
subjectRDN
Type
string
Description
İmzalayanın sertifika subject bilgisi.
Name
citizenshipNo
Type
string?
Description
(Varsa) TCKN.
Name
timestamped
Type
boolean
Description
Zaman damgasına sahip olup olmadığı.
Name
claimedSigningTime
Type
string?
Description
Beyan edilen imza zamanı (string).
Name
claimedSigningTimeAsTime
Type
datetime?
Description
Beyan edilen imza zamanı (DateTime).
Name
profileName
Type
string?
Description
Profil adı (P4 veya null).
Name
policyOID
Type
string?
Description
İmzadaki Policy OID.
Name
hashAlgorithm
Type
string?
Description
Kullanılan hash algoritması.
Name
containsLongTermInfo
Type
boolean
Description
Uzun vadeli doğrulama bilgisi (DSS) içeriyor mu.
Name
timestamp
Type
TimestampInfoItemV4?
Description
Zaman damgası bilgisi.
Name
upgradeOptions
Type
string[]
Description
Mevcut seviyeden yapılabilecek tüm upgrade seçenekleri (ör. ["B-T","B-LTA"]). En üst seviyede boş döner. B-LT burada yer almaz (Update ile üretilemez).
Name
profileRecommendedUpgrades
Type
string[]?
Description
Profil uyumlu upgrade seçenekleri. Profil yoksa null.
Name
profileIncompatibleUpgrades
Type
string[]?
Description
Profil dışı (teknik olarak mümkün ama uyumsuz) upgrade seçenekleri. Profil yoksa null.

Örnek imza (B-LTA, P4 profilli)

{
  "entityLabel": "S0",
  "level": "B-LTA",
  "levelString": "Baseline-LTA",
  "subjectRDN": "CN=AHMET YILMAZ/SN=12345678901",
  "citizenshipNo": "12345678901",
  "timestamped": true,
  "claimedSigningTime": "2026-02-24 10:30:00.000",
  "claimedSigningTimeAsTime": "2026-02-24T10:30:00",
  "profileName": "P4",
  "policyOID": "2.16.792.1.61.0.1.5070.3.3.1",
  "hashAlgorithm": "SHA256",
  "containsLongTermInfo": true,
  "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": [],
  "profileRecommendedUpgrades": [],
  "profileIncompatibleUpgrades": []
}

TimestampInfoItemV4

Name
entityLabel
Type
string
Description
Zaman damgasının etiketi (ör. S0:T0).
Name
time
Type
string?
Description
Zaman damgası zamanı (string).
Name
timeAsTime
Type
datetime?
Description
Zaman damgası zamanı (DateTime).
Name
tsaName
Type
string?
Description
Zaman damgası otoritesi adı.
Name
hashAlgorithm
Type
string?
Description
Hash algoritması.
Name
timestampType
Type
integer
Description
Zaman damgası türü (sayısal).
Name
timestampTypeStr
Type
string?
Description
Zaman damgası türü (metinsel).

POST/v4/CoreApiPades/GetSignatureListCore

GetSignatureListCore

Verilen operationId ile ilişkili PDF dosyasındaki tüm imzaları döner. Her imzanın profilini, upgrade seçeneklerini ve zaman damgası detaylarını içerir.

Gerekli alanlar

Name
operationId
Type
uuid
Description
İmzaları listelenecek PDF dosyasının işlem kimliği.
Name
requestId
Type
string
Description
21 karakter uzunluğunda benzersiz bir string.
Name
displayLanguage
Type
string
Description
Dil tercihi.

Request

POST

/v4/CoreApiPades/GetSignatureListCore

curl -X POST "https://apitest.onaylarim.com/v4/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": "B-LTA",
        "levelString": "Baseline-LTA",
        "subjectRDN": "CN=AHMET YILMAZ/SN=12345678901",
        "citizenshipNo": "12345678901",
        "timestamped": true,
        "claimedSigningTime": "2026-02-24 10:30:00.000",
        "claimedSigningTimeAsTime": "2026-02-24T10:30:00",
        "profileName": "P4",
        "policyOID": "2.16.792.1.61.0.1.5070.3.3.1",
        "hashAlgorithm": "SHA256",
        "containsLongTermInfo": true,
        "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": [],
        "profileRecommendedUpgrades": [],
        "profileIncompatibleUpgrades": []
      }
    ],
    "operationId": "11111111-1111-1111-1111-111111111111"
  },
  "error": null
}

POST/v4/CoreApiPades/SignStepOnePadesCore

SignStepOnePadesCore — İmzayı başlat

PAdES imzalama sürecini başlatır. Hedef seviye, profil ve hash algoritması burada belirlenir. İstemci 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 (DER veya PEM).
Name
signatureLevel
Type
SignatureLevelForPadesV4
Description
Hedef imza seviyesi. StepThree'de bu seviyeye otomatik upgrade edilir.
Name
profile
Type
PadesProfileV4
Description
Türk imza profili. None: profilsiz imza. P4: EPES tabanlı (policy dahil, OCSP revocation).
Name
hashAlgorithm
Type
CadesHashAlgorithmV4
Description
Hash algoritması. Varsayılan: SHA256 (0).
Name
signatureWidgetInfo
Type
object?
Description
(Opsiyonel) Görünür imza için yerleşim/görsel ayarları. null ise görünmez imza atılır.

Not: V2'den farklı olarak PAdES V4'te coordinates alanı yoktur. Görsel imza yerleşimi yalnızca signatureWidgetInfo ile yapılır.

Request

POST

/v4/CoreApiPades/SignStepOnePadesCore

curl -X POST "https://apitest.onaylarim.com/v4/CoreApiPades/SignStepOnePadesCore" \
  -H "X-API-KEY: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
        "operationId": "11111111-1111-1111-1111-111111111111",
        "cerBytes": "MIIC...",
        "signatureLevel": 4,
        "profile": 4,
        "hashAlgorithm": 0,
        "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/v4/CoreApiPades/SignStepThreePadesCore

SignStepThreePadesCore — İmzayı bitir

İstemcide oluşturulan imzalı veriyi (signedData) göndererek PAdES imzalama sürecini tamamlar. StepOne'da belirtilen hedef seviye B-B'den yüksekse, imza otomatik olarak o seviyeye upgrade edilir.

Gerekli alanlar

Name
operationId
Type
uuid
Description
StepOne'dan dönen işlem kimliği.
Name
signedData
Type
string
Description
E-imza aracından dönen imzalı veri (Base64).
Name
keyId
Type
string
Description
StepOne yanıtındaki KeyId.
Name
keySecret
Type
string
Description
StepOne yanıtındaki KeySecret.

Not: V2'den farklı olarak V4'te signatureLevel bu adımda gönderilmez. Hedef seviye StepOne'da belirlenir ve StepThree'de otomatik uygulanır.

Otomatik upgrade akışı

StepThree'de imzalama sonrası hedef seviyeye göre otomatik upgrade yapılır:

B-B hedef: Upgrade yok. Profilsiz ise B-B, profilli ise EPES seviyesinde kalır.
B-T hedef: Timestamp eklenir → B-T.
B-LT hedef: DSS eklenir (Document Timestamp olmadan) → B-LT.
B-LTA hedef: DSS + Document Timestamp eklenir → B-LTA.

Request

POST

/v4/CoreApiPades/SignStepThreePadesCore

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

Response

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

POST/v4/CoreApiPades/UpgradePadesCore

UpgradePadesCore

Mevcut PAdES imzasını istenen seviyeye yükseltir. Desteklenen hedefler: B-T ve B-LTA.

Kısıt: B-LT'ye upgrade yapılamaz. Update işlemi her zaman Document Timestamp ekler ve B-LTA üretir. B-LT sadece SignStepOne'da doğrudan üretilebilir.

İpucu: Hangi seviyeye upgrade yapılabileceğini öğrenmek için önce GetSignatureListCore çağrısı yapın. Dönen upgradeOptions ve profileRecommendedUpgrades alanları yol gösterir.

Gerekli/opsiyonel alanlar

Name
operationId
Type
uuid
Description
Upgrade edilecek PDF'in işlem kimliği.
Name
targetLevel
Type
SignatureLevelForPadesV4
Description
Hedef seviye. BT (2) veya BLTA (4) olabilir. BB (1) ve BLT (3) kabul edilmez.
Name
signaturePath
Type
string?
Description
(Opsiyonel) Upgrade edilecek imzanın EntityLabel'ı (ör. S0). Boş bırakılırsa ilk imza upgrade edilir.

Upgrade validasyon kuralları

B-B hedefi: Reddedilir (zaten en düşük seviye).
B-LT hedefi: Reddedilir (Update ile B-LT üretilemez).
Aynı/düşük seviye: Reddedilir (sadece daha yüksek seviyeye upgrade yapılabilir).
B-LTA iken upgrade: Reddedilir (zaten en yüksek seviye).
Profilli imzada: Sadece B-LTA'ya upgrade yapılabilir.

Request

POST

/v4/CoreApiPades/UpgradePadesCore

curl -X POST "https://apitest.onaylarim.com/v4/CoreApiPades/UpgradePadesCore" \
  -H "X-API-KEY: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
        "operationId": "33333333-3333-3333-3333-333333333333",
        "targetLevel": 4,
        "signaturePath": "S0",
        "requestId": "aaaaaaaaaaaaaaaaaaaaa",
        "displayLanguage": "tr"
      }'

Response

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

Örnek akış (P4 profilli B-LTA imza)

Dosya yükleme: CoreApiFile/UploadFile veya parça/parça: ChunkInit → ChunkUpload → ChunkComplete → uploadOpId
SignStepOnePadesCore ile imzayı başlat:
- signatureLevel: 4 (B-LTA), profile: 4 (P4), hashAlgorithm: 0 (SHA256)
- → state, keyId, keySecret, yeni operationId
İstemci e-imza aracıyla state'i imzalar → signedData
SignStepThreePadesCore ile imzayı tamamla
- Profilli ise EPES olarak imzalanır, ardından otomatik B-LTA'ya upgrade edilir
- → isSuccess: true, final operationId
(Opsiyonel) GetSignatureListCore ile imzaları kontrol et
(Opsiyonel) Dosyayı indirmek için CoreApiFile/DownloadFile kullan

Örnek akış (Profilsiz B-B imza + sonradan B-LTA upgrade)

Dosya yükleme → uploadOpId
SignStepOnePadesCore:
- signatureLevel: 1 (B-B), profile: 0 (None)
- → state, keyId, keySecret, yeni operationId
İstemci imzalar → signedData
SignStepThreePadesCore → B-B seviyesinde imzalı PDF, final operationId
UpgradePadesCore ile targetLevel: 4 (B-LTA) → arşiv seviyesine yükseltilir

Örnek akış (Görünür imza ile B-T)

Dosya yükleme → uploadOpId
SignStepOnePadesCore:
- signatureLevel: 2 (B-T), profile: 0 (None)
- signatureWidgetInfo: { width: 240, height: 80, left: 0.1, top: 0.85, pagesToPlaceOn: [0] }
- → state, keyId, keySecret, yeni operationId
İstemci imzalar → signedData
SignStepThreePadesCore → B-T seviyesinde görünür imzalı PDF

V2/V3'ten V4'e geçiş

Endpoint değişiklik özeti

Amaç	V2/V3 endpoint	V4 endpoint	Önemli farklar
İmzayı başlat	`POST /v2/.../SignStepOnePadesCore`	`POST /v4/.../SignStepOnePadesCore`	Yeni: `signatureLevel`, `profile`, `hashAlgorithm`. Kaldırılan: `coordinates`.
İmzayı bitir	`POST /v2/.../signStepThreePadesCore`	`POST /v4/.../SignStepThreePadesCore`	`signatureLevel` artık StepOne'da verilir, StepThree'de yok. URL'de büyük 'S' harfi.
İmzayı yükselt	`POST /v2/.../UpgradePadesCore`	`POST /v4/.../UpgradePadesCore`	`signatureLevel` → `targetLevel`. Yeni seviye enum'u (B-B, B-T, B-LT, B-LTA). B-LT kısıtı.
İmza listesi	`POST /v3/.../GetSignatureListCore`	`POST /v4/.../GetSignatureListCore`	Yeni: `profileName`, `policyOID`, `hashAlgorithm`, `containsLongTermInfo`, `upgradeOptions`, `profileRecommendedUpgrades`, `profileIncompatibleUpgrades`.

V2 → V4 request alanı dönüşümleri

SignStepOnePadesCore

V4'te yeni
- signatureLevel: Hedef seviye (B-B, B-T, B-LT, B-LTA). V2'de seviye StepThree'de isteğe bağlı veriliyordu.
- profile: Türk imza profili enum'u (None, P4).
- hashAlgorithm: Hash algoritması seçimi (SHA256, SHA384, SHA512).
V2'de vardı, V4'te kaldırıldı
- coordinates: Kaldırıldı. Görsel imza yalnızca signatureWidgetInfo ile yapılır.
V2'de aynı/benzer
- operationId, cerBytes, signatureWidgetInfo, requestId, displayLanguage

signStepThreePadesCore → SignStepThreePadesCore

V2'de vardı, V4'te kaldırıldı
- signatureLevel: Artık StepOne'da verilir, StepThree'de otomatik uygulanır.
URL farkı: V2'de küçük 's' (signStepThreePadesCore), V4'te büyük 'S' (SignStepThreePadesCore).

UpgradePadesCore

V2'de signatureLevel (string: paslBES, paslLTV) → V4'te targetLevel (enum: BB=1, BT=2, BLT=3, BLTA=4).
V4'te kısıt: B-LT hedefi kabul edilmez (Update her zaman B-LTA üretir).

İmza seviyesi karşılaştırma tablosu

V2 Seviye	V4 Karşılığı	Açıklama
`paslBES`	`BB` (1)	Temel imza
`paslLTV`	`BLTA` (4)	Arşiv seviyesi (V2'de LTV, V4'te B-LTA)
—	`BT` (2)	V4'te yeni: Sadece timestamp ekli
—	`BLT` (3)	V4'te yeni: Long-Term (yalnızca Sign ile)

Profil-seviye uyumluluk tablosu

Profil	İzin verilen seviyeler	Önerilen minimum
None	B-B, B-T, B-LT, B-LTA	B-B
P4	B-B (standalone EPES), B-LT, B-LTA	B-LT

Not: Uyumsuz profil-seviye kombinasyonu (ör. P4 + B-T) API tarafından reddedilir. P3 profili PAdES'te desteklenmez.