CoreApiXadesMobile (v4.0)

CoreApiXadesMobile V4, mobil imza operatörleri (Turkcell/Vodafone/AVEA) üzerinden XAdES imzalama işlemini başlatır. V2'ye kıyasla imza profilleri (P1–P4), genişletilmiş seviyeler (BES, EPES, T, XL, A) ve imza modu seçimi (Enveloped/Enveloping) desteklenir. Mobil imzada işlem tek adımda tamamlanır; ayrı bir "signStepThree" adımı yoktur.

Temel kavramlar

  • OperationId: İmzalanacak XML dosyasını temsil eden işlem kimliği. Önceki adımlardan (dosya yükleme) elde edilir.
  • Enveloped vs Enveloping: Enveloped imzada imza XML'in içine gömülür. Enveloping imzada XML dosyası imza zarfının içine yerleştirilir.
  • Profiller: Türk Elektronik İmza Kullanım Profilleri (P1–P4). Profil seçimi, imza seviyesi ve revocation check davranışını belirler.
  • Auth: Tüm uç noktalar ApiKey gerektirir.
  • Zarf: Tüm yanıtlar ApiResult<T> tipindedir:
    • result: T
    • error: string (hata durumunda dolar)

Enum: SignatureLevelForXadesV4

DeğerKodAçıklama
BES1Basic Electronic Signature
EPES2Electronic Signature with Explicit Policy
T3XAdES-T — Zaman damgalı
XL6XAdES-XL — Revocation değerleri dahil
A7XAdES-A — Arşiv zaman damgalı

Not: XAdES'te C (4) ve X (5) seviyeleri desteklenmez.

Enum: XadesProfileV4

DeğerKodAçıklamaGeçerli SeviyelerRevocation
None0Profil yokBES—
P11Profilsiz BESBES—
P22EPES + T, SİL (CRL)TCRL
P33EPES + XL/A, SİL (CRL)EPES, XL, ACRL
P44EPES + XL/A, ÇİSDuP (OCSP)EPES, XL, AOCSP
POST/v4/CoreApiXadesMobile/SignStepOneXadesMobileCore

SignStepOneXadesMobileCore — Mobil imzayı başlat

Mobil imza işlemini başlatır. İşlem sırasında operatör ile iletişim kurulur ve parmak izi (fingerprint) üretilir. İstemci bu fingerprint'i CoreApiFingerPrint ile sorgulayabilir.

Gerekli/opsiyonel alanlar

  • Name
    operationId
    Type
    uuid
    Description

    İmzalanacak XML dosyasının işlem kimliği (önceki adımdan elde edilir).

  • Name
    phoneNumber
    Type
    string
    Description

    Mobil imza telefon numarası (örn. 5XXXXXXXXX).

  • Name
    operator
    Type
    string
    Description

    Operatör adı (TURKCELL | VODAFONE | AVEA).

  • Name
    userPrompt
    Type
    string
    Description

    Kullanıcıya gösterilecek mesaj.

  • Name
    citizenshipNo
    Type
    string?
    Description

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

  • Name
    signatureLevel
    Type
    SignatureLevelForXadesV4
    Description

    XAdES imza seviyesi. Olası değerler: BES, EPES, T, XL, A.

  • Name
    profile
    Type
    XadesProfileV4
    Description

    İmza profili. Olası değerler: None, P1, P2, P3, P4.

  • 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:S0). Parallel imzada yok sayılır.

  • Name
    envelopingOrEnveloped
    Type
    string
    Description

    İmza modu: ENVELOPING veya ENVELOPED. Dosya üzerinde zaten imza varsa bu alan yok sayılır.

  • Name
    requestId
    Type
    string
    Description

    21 karakter uzunluğunda benzersiz bir string. Her istek için farklı olmalıdır.

  • Name
    displayLanguage
    Type
    string
    Description

    Dil tercihi (ör. "tr").

Request

POST
/v4/CoreApiXadesMobile/SignStepOneXadesMobileCore
curl -X POST "https://apitest.onaylarim.com/v4/CoreApiXadesMobile/SignStepOneXadesMobileCore" \
  -H "X-API-KEY: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
        "operationId": "11111111-1111-1111-1111-111111111111",
        "phoneNumber": "5XXXXXXXXX",
        "operator": "TURKCELL",
        "userPrompt": "İmzalamayı onaylıyor musunuz?",
        "citizenshipNo": null,
        "signatureLevel": 1,
        "profile": 0,
        "serialOrParallel": null,
        "signaturePath": null,
        "envelopingOrEnveloped": "ENVELOPED",
        "requestId": "aaaaaaaaaaaaaaaaaaaaa",
        "displayLanguage": "tr"
      }'

Response

{
  "result": {
    "isSuccess": true,
    "operationId": "22222222-2222-2222-2222-222222222222"
  },
  "error": null
}

Örnek akış (XAdES Mobile V4)

  1. XML dosya yükleme: CoreApiFile/UploadFile veya parça/parça: ChunkInit → ChunkUpload → ChunkComplete
  2. v4/CoreApiXadesMobile/SignStepOneXadesMobileCore → mobil operatör akışı başlatılır, fingerprint üretilir (yeni operationId gelebilir).
  3. (Opsiyonel) CoreApiFingerPrint/GetFingerPrintCore ile operationId üzerinden fingerprint alınır ve kullanıcıya gösterilir.
  4. Operatör onayı sonrası imzalama tamamlanır; ek bir adım gerekmez.
  5. CoreApiFile/DownloadCore ile imzalı dosya indirilir.

V2'den V4'e geçiş

Endpoint değişiklik özeti

AmaçV2 endpointV4 endpoint
Mobil imzayı başlatPOST /v2/CoreApiXadesMobile/SignStepOneXadesMobileCorePOST /v4/CoreApiXadesMobile/SignStepOneXadesMobileCore

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

  • V2'de vardı, V4'te kaldırıldı
    • coordinates: V4'te bu alan kaldırılmıştır.
    • signatureTurkishProfile: Yerine profile (enum) kullanılır.
    • signatureLevel (string): V4'te sayısal enum'a dönüştürüldü.
  • V4'te yeni
    • profile: Enum tabanlı profil seçimi (None=0, P1=1, P2=2, P3=3, P4=4).
    • signatureLevel: Genişletilmiş enum (BES=1, EPES=2, T=3, XL=6, A=7). C ve X XAdES'te desteklenmez.
    • envelopingOrEnveloped: İmza modu seçimi (ENVELOPING veya ENVELOPED).
  • Aynı kalanlar
    • operationId, phoneNumber, operator, userPrompt, citizenshipNo, serialOrParallel, signaturePath, requestId, displayLanguage

Notlar

  • URL prefix: /v2/ → /v4/ olarak güncelleyin.
  • signatureLevel: V2'de string ("BES"), V4'te integer (1). Her iki format da kabul edilir.
  • Profil: V2'de signatureTurkishProfile (string), V4'te profile (enum).
  • İmza modu: V4'te envelopingOrEnveloped alanı eklendi. V2'de bu alan yoktu.

Was this page helpful?