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)
  • errorCode: string (opsiyonel, dilden bağımsız hata kodu; null ise JSON'a yazılmaz)

Enum: SignatureLevelForXadesV4

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

Enum: XadesProfileV4

SignStepOneXadesMobileCore — Mobil imzayı başlat

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"
      }'

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

Mobil imza hata yanıtları

HTTP 200 tek başına başarı anlamına gelmez. error, varsa errorCode ve result.isSuccess birlikte değerlendirilmelidir. Aşağıdaki kodlar bu güncellemeyi içeren API sürümü dağıtıldıktan sonra geçerlidir; kullandığınız ortamda sürümü doğrulayın.

errorCode dilden bağımsızdır; error, displayLanguage ile Türkçe/İngilizce döner. Başarıda veya kod üretilmeyen eski/validasyon hatalarında errorCode JSON'da bulunmayabilir. Tanınmayan kodları genel hata akışıyla ele alın; kodun olmamasını başarı saymayın.

{
  "result": {
    "isSuccess": false,
    "operationId": "22222222-2222-2222-2222-222222222222"
  },
  "error": "Mobil imza işlemi iptal edildi.",
  "errorCode": "USER_CANCEL"
}

UNKNOWN_CLIENT için Türkçe mesaj: "Bu telefon numarası için operatörde mobil imza kaydı bulunamadı. Numaranızı ve seçilen operatörü kontrol edin." Bu durum servis hesabı/parola hatası veya kullanıcı iptali anlamına gelmez.

Yeni hata kodları bu iyileştirmeyi içeren V4 API sürümünün dağıtılmasını gerektirir. EXPIRED_TRANSACTION: "Mobil imza işleminin süresi doldu."; OPERATOR_TIMEOUT: "Mobil imza operatöründen zamanında yanıt alınamadı."; OPERATOR_UNAVAILABLE: "Mobil imza operatörüyle iletişim kurulamadı." displayLanguage: "en" için İngilizce mesaj döner; kararları mesaj yerine errorCode ile verin.

Operatöre gönderilen süre 120 saniye, V4 HTTP istemcisinin zaman aşımı 150 saniyedir. Bu, toplam API süresi için üst sınır veya tüm proxy/HTTP 524 sorunlarının çözüldüğü garantisi değildir. İstemci ve reverse proxy süreleri ayrıca değerlendirilmelidir. HTTP zaman aşımı telefondan iptal kanıtı değildir; 208 de USER_CANCEL olarak eşlenmez.

Ortak hata modeli ve örnekler ile fingerprint bekleme davranışını inceleyin. Fingerprint'in alınması imzanın tamamlandığını göstermez; FINGERPRINT_TIMEOUT da kullanıcı iptali anlamına gelmez.

Örnek akış (XAdES Mobile V4)

1. XML dosya yükleme: CoreApiFile/UploadFile veya ChunkInit → ChunkUpload → ChunkComplete. Dönen dosya işlem kimliğini saklayın.
2. v4/CoreApiXadesMobile/SignStepOneXadesMobileCore isteğini bu operationId ile başlatın. İstek, imzalama sonucu oluşana kadar devam edebilir.
3. İmza isteği sürerken, gerekiyorsa ayrı bir istekle v2/CoreApiFingerPrint/GetFingerPrintCore çağırın. İmza isteğinin girişindeki dosya operationId değerini kullanın; sonuçta dönen yeni imzalama işlem kimliğini değil.
4. İmza isteğinin nihai yanıtını takip edin. USER_CANCEL, UNKNOWN_CLIENT veya diğer imza hatalarında fingerprint takibini durdurun; bekleyen sorguyu mümkünse iptal edin. Geç gelen fingerprint yanıtı tamamlanmış işlemi tekrar aktif hale getirmemelidir.
5. Yalnızca hata yoksa ve result.isSuccess = true ise, imza yanıtındaki result.operationId ile CoreApiFile/DownloadCore üzerinden imzalı dosya indirin. Ek bir imzalama adımı gerekmez.

Yukarıdaki C# örneği yalnızca nihai imza yanıtını bekler. Kullanıcıya işlem sırasında fingerprint göstermek istiyorsanız, fingerprint sorgusunu bu isteğin tamamlanmasını beklemeden ayrı yürütün.

Mevcut sınırlama: Enveloping biçimindeki mevcut XML imzasına paralel imza ekleyen yol fingerprint callback’ini çağırmaz. İmza başarılı olsa bile fingerprint sorgusu FINGERPRINT_TIMEOUT dönebilir; nihai imza yanıtını esas alın.

V2'den V4'e geçiş

Endpoint değişiklik özeti

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.