CoreApiPadesMobile (v4.0)

CoreApiPadesMobile V4, mobil imza operatörleri (Turkcell/Vodafone/AVEA) üzerinden PAdES imzalama işlemini başlatır. V2'ye kıyasla Baseline seviyeler (B-B, B-T, B-LT, B-LTA) ve profil desteği (sadece P4) sunulur. Mobil imzada işlem tek adımda tamamlanır; ayrı bir "signStepThree" adımı yoktur.

Temel kavramlar

• OperationId: İmzalanacak PDF dosyasını temsil eden işlem kimliği. Önceki adımlardan (dosya yükleme) elde edilir.
• Profiller: PAdES'te yalnızca P4 (OCSP tabanlı) ve None (profilsiz) desteklenir.
• 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: SignatureLevelForPadesV4

Enum: PadesProfileV4

Not: PAdES'te P1, P2, P3 profilleri desteklenmez; yalnızca None ve P4 kullanılabilir.

SignStepOnePadesMobileCore — Mobil imzayı başlat

curl -X POST "https://apitest.onaylarim.com/v4/CoreApiPadesMobile/SignStepOnePadesMobileCore" \
  -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,
        "requestId": "aaaaaaaaaaaaaaaaaaaaa",
        "displayLanguage": "tr",
        "signatureWidgetInfo": null
      }'

{
  "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ış (PAdES Mobile V4)

1. PDF dosya yükleme: CoreApiFile/UploadFile veya ChunkInit → ChunkUpload → ChunkComplete. Dönen dosya işlem kimliğini saklayın.
2. v4/CoreApiPadesMobile/SignStepOnePadesMobileCore 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ı PDF 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.

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, P4=4).
  • signatureLevel: Yeni Baseline enum (BB=1, BT=2, BLT=3, BLTA=4).
  • signatureWidgetInfo: (Opsiyonel) Görsel imza desteği. null ise görünmez imza atılır.
• Aynı kalanlar
  • operationId, phoneNumber, operator, userPrompt, citizenshipNo, requestId, displayLanguage

Notlar

• URL prefix: /v2/ → /v4/ olarak güncelleyin.
• signatureLevel: V2'de string ("BES"), V4'te Baseline enum (BB=1, BT=2, BLT=3, BLTA=4). Her iki format da kabul edilir.
• Profil: V2'de signatureTurkishProfile (string), V4'te profile (enum). PAdES'te yalnızca None ve P4 geçerlidir.