CoreApiCadesMobile (v2.0)

CoreApiCadesMobile, mobil imza operatörleri (Turkcell/Vodafone/AVEA) üzerinden CAdES 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 veya önimzalama) 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/CoreApiCadesMobile/SignStepOneCadesMobileCore

SignStepOneCadesMobileCore — 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 ayrı bir uç nokta olan CoreApiFingerPrint 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
SignatureLevelForCades?
Description
(Opsiyonel) CAdES imza seviyesi. Olası değerler: aslBES, aslT, aslXLType2, aslA. Boş geçilirse aslBES kabul edilir.
Name
signaturePath
Type
string
Description
(Opsiyonel) Seri imzada, ü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
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/CoreApiCadesMobile/SignStepOneCadesMobileCore

curl -X POST "https://apitest.onaylarim.com/v2/CoreApiCadesMobile/SignStepOneCadesMobileCore" \
  -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",
        "requestId": "aaaaaaaaaaaaaaaaaaaaa",
        "displayLanguage": "tr"
      }'

Response

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

Örnek akış (CAdES Mobile)

Dosya yükleme: CoreApiFile/UploadFile veya parça/parça: ChunkInit → ChunkUpload → ChunkComplete
CoreApiCadesMobile/SignStepOneCadesMobileCore → 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 (/v1.0/CoreApiCadesMobile) 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 /v1.0/CoreApiCadesMobile/SignStepOneCadesMobileCore`	`POST /v2/CoreApiCadesMobile/SignStepOneCadesMobileCore`	V2’de dosya yükleme akışı değişti (bkz. aşağı).
Fingerprint sorgula	`POST /v1.0/CoreApiCadesMobile/GetFingerPrintCore`	`POST /v2/CoreApiFingerPrint/GetFingerPrintCore`	V2’de fingerprint endpoint’i CoreApiFingerPrint altına taşındı.

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

SignStepOneCadesMobileCore

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 CAdES V2 request’inde bulunmaz.
V2’de yeni (seri/paralel imza)
- serialOrParallel: SERIAL | PARALLEL (boş ise PARALLEL kabul edilir)
- signaturePath: Seri imzada hedef imzayı belirtir (S0, S0:S0 gibi). Parallel imzada yok sayılır.
- signatureTurkishProfile: P1 | P2 | P3 | P4 (opsiyonel; pratikte P4)
Aynı kalanlar
- operationId, phoneNumber, operator, userPrompt, citizenshipNo, signatureLevel, 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,
  "signatureLevel": "BES",
  "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": "S0",
  "serialOrParallel": "SERIAL",
  "signatureTurkishProfile": "P4",
  "requestId": "aaaaaaaaaaaaaaaaaaaaa",
  "displayLanguage": "tr"
}

Notlar / breaking changes

URL prefix: V1’den V2’ye geçerken /v1.0/ → /v2/ olarak güncelleyin.
Fingerprint: V1’de fingerprint CoreApiCadesMobile/GetFingerPrintCore ile alınırdı; V2’de bu uç nokta CoreApiFingerPrint/GetFingerPrintCore altına taşındı.