CoreApiXadesMobile (v2.0)

CoreApiXadesMobile, mobil imza operatörleri (Turkcell/Vodafone/AVEA) üzerinden XAdES imzalama başlatmayı sağlar. Bu adımda son kullanıcıya SMS/onay akışı gösterilir, parmak izi (fingerprint) üretilir ve işlem bir OperationId üzerinde sürdürülür.

Not: Mobil imzada işlem, operatör onayı sonrası SignStepOne çağrısından sonra tamamlanır; ayrı bir “signStepThree” adımı yoktur.

Temel kavramlar

OperationId: İmzalanacak dosyayı temsil eden işlem kimliği. Önceki adımlardan (ör. yükleme) alınır.
Auth: Tüm uç noktalar ApiKey gerektirir.
Zarf: Tüm yanıtlar ApiResult<T> tipindedir:
- result: T
- error: string (hata durumunda dolar)

POST/v2/CoreApiXadesMobile/SignStepOneXadesMobileCore

SignStepOneXadesMobileCore — Mobil imzayı başlat

Mobil XAdES 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 (v2.0) altındaki uç nokta ile sorgulayabilir.

Gerekli/opsiyonel alanlar

Name
operationId
Type
uuid
Description
İmzalanacak dosyanın işlem kimliği (önceki adımdan elde edilir).
Name
coordinates
Type
object
Description
(Opsiyonel) Konum bilgileri (şu an kullanılmıyor).
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
SignatureLevelForXades?
Description
(Opsiyonel) XAdES imza seviyesi. Olası değerler: aslBES, aslT, aslXL, aslA. Boş geçilirse aslBES kabul edilir.
Name
signaturePath
Type
string
Description
(Opsiyonel, SERIAL için) Üzerine imza atılacak imza yolu (ör. S0:S0).
Name
signatureTurkishProfile
Type
string
Description
(Opsiyonel) P1 | P2 | P3 | P4 (profil istenmiyorsa boş geçilir).
Name
serialOrParallel
Type
string
Description
(Opsiyonel) SERIAL | PARALLEL. Boş geçilirse PARALLEL kabul edilir.
Name
envelopingOrEnveloped
Type
string
Description
(Opsiyonel) ENVELOPING | ENVELOPED. Boş geçilirse ENVELOPED kabul edilir.
Name
requestId
Type
string
Description
21 karakter uzunluğunda benzersiz bir string. Her istek için farklı olmalıdır. Örnek: Guid.NewGuid().ToString("N").Substring(0,21)
Name
displayLanguage
Type
string
Description
Dil tercihi (BaseRequest).

Request

POST

/v2/CoreApiXadesMobile/SignStepOneXadesMobileCore

curl -X POST "https://apitest.onaylarim.com/v2/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": "BES",
        "signaturePath": null,
        "serialOrParallel": "SERIAL",
        "signatureTurkishProfile": "P4",
        "envelopingOrEnveloped": "ENVELOPED",
        "requestId": "aaaaaaaaaaaaaaaaaaaaa",
        "displayLanguage": "tr"
      }'

Response

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

Örnek akış (XAdES Mobile)

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

V1’den V2’ye geçiş

Bu sayfa V2.0 uç noktalarını anlatır. Eğer mevcut entegrasyonunuz V1 ile çalışıyorsa, aşağıdaki maddelerle V2’ye geçebilirsiniz.

Endpoint değişiklik özeti

Amaç	V1 endpoint	V2 endpoint	Not
Mobil imzayı başlat	`POST /CoreApiXadesMobile/SignStepOneXadesMobileCore`	`POST /v2/CoreApiXadesMobile/SignStepOneXadesMobileCore`	V1’de route version prefix’i yoktur; V2’de `/v2/` vardır.
Fingerprint sorgula	`POST /CoreApiXadesMobile/GetFingerPrintCore`	`POST /v2/CoreApiFingerPrint/GetFingerPrintCore`	V2’de fingerprint endpoint’i CoreApiFingerPrint altına taşındı.

V1 → V2 request alanı dönüşümleri (XAdES Mobile)

SignStepOneXadesMobileCore

V1’de vardı, V2’de kaldırıldı
- fileData: V1’de dosya bu çağrıda gönderiliyordu. V2’de dosya CoreApiFile/UploadFile (veya chunk akışı) ile yüklenir; burada sadece operationId referanslanır.
- signatureIndex: V2’de bunun yerine (seri imza için) signaturePath kullanılır.
- cerBytes: Mobil XAdES V2 request’inde bulunmaz.
V2’de yeni
- serialOrParallel: SERIAL | PARALLEL (boş ise PARALLEL kabul edilir)
- signaturePath: (Opsiyonel, SERIAL için) üzerine imza atılacak imza yolu
- signatureLevel ve signatureTurkishProfile: opsiyonel
- envelopingOrEnveloped: ENVELOPING | ENVELOPED (boş ise ENVELOPED)
Aynı kalanlar
- operationId, phoneNumber, operator, userPrompt, citizenshipNo, requestId, displayLanguage

V1 örnek istek (özet):

{
  "operationId": "11111111-1111-1111-1111-111111111111",
  "fileData": "BASE64_FILE_BYTES",
  "signatureIndex": 0,
  "phoneNumber": "5XXXXXXXXX",
  "operator": "TURKCELL",
  "userPrompt": "İmzalamayı onaylıyor musunuz?",
  "citizenshipNo": null,
  "requestId": "aaaaaaaaaaaaaaaaaaaaa",
  "displayLanguage": "tr"
}

V2 örnek istek (özet):

{
  "operationId": "11111111-1111-1111-1111-111111111111",
  "phoneNumber": "5XXXXXXXXX",
  "operator": "TURKCELL",
  "userPrompt": "İmzalamayı onaylıyor musunuz?",
  "citizenshipNo": null,
  "signatureLevel": "BES",
  "signaturePath": null,
  "serialOrParallel": "SERIAL",
  "signatureTurkishProfile": "P4",
  "envelopingOrEnveloped": "ENVELOPED",
  "requestId": "aaaaaaaaaaaaaaaaaaaaa",
  "displayLanguage": "tr"
}

Notlar / breaking changes

URL prefix: V1’de CoreApiXadesMobile route’u version prefix’sizdir; V2’de /v2/ ile çağrılır.
Fingerprint: V1’de fingerprint CoreApiXadesMobile/GetFingerPrintCore ile alınırdı; V2’de CoreApiFingerPrint/GetFingerPrintCore altına taşındı.