CoreApiFingerPrint (v2.0)

CoreApiFingerPrint, mobil imza başlatma adımında (CoreApiPadesMobile / CoreApiCadesMobile / CoreApiXadesMobile) üretilen parmak izi (fingerprint) değerini okumanız için kısa beklemeli bir uç nokta sağlar. İstemci bu endpoint’i çağırarak kullanıcıya gösterilecek fingerprint’i elde eder.

Temel kavramlar

  • OperationId: V4 mobil imza isteğinin girişinde kullanılan dosya işlem kimliği (yükleme/önceki adımdan gelen ID). İmza yanıtında dönen yeni imzalama işlem kimliği değildir.
  • Auth: Uç nokta ApiKey gerektirir.
  • Zarf: Yanıt ApiResult<T> tipindedir:
    • result: T
    • error: string (hata durumunda dolar)
    • errorCode: string (opsiyonel; bekleme bütçesi dolduğunda FINGERPRINT_TIMEOUT)
POST/v2/CoreApiFingerPrint/GetFingerPrintCore

GetFingerPrintCore

Verilen operationId için bu sunucu sürecinin cache'inde bulunan fingerprint değerini döner. Hazırsa beklemeden yanıtlanır. Hazır değilse yaklaşık 200 ms aralıklarla asenkron kontrol edilir; 20 saniyelik bekleme bütçesi dolduğunda FINGERPRINT_TIMEOUT döner. Ağ ve zamanlama gecikmeleri nedeniyle istemcide ölçülen süre biraz daha uzun olabilir. İstemci bağlantısı kesildiğinde bekleme sonlandırılır.

Gerekli alanlar

  • Name
    operationId
    Type
    uuid
    Description

    V4 mobil imza isteğine gönderilen dosya işlem kimliği; imza sonucundaki yeni işlem kimliği değil.

  • 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/CoreApiFingerPrint/GetFingerPrintCore
curl -X POST "https://apitest.onaylarim.com/v2/CoreApiFingerPrint/GetFingerPrintCore" \
  -H "X-API-KEY: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "11111111-1111-1111-1111-111111111111", "requestId": "aaaaaaaaaaaaaaaaaaaaa", "displayLanguage": "tr" }'

Response

{
  "result": {
    "fingerPrint": "CAFEBABE1234..."
  },
  "error": null
}

Örnek akış (Mobil İmza + Fingerprint)

  1. Dosya yükleme/önceki adımdan gelen operationId ile PAdES, CAdES veya XAdES V4 mobil imza isteğini başlatın.
  2. İmza isteği sürerken ayrı bir istekle fingerprint sorgulayın. İmza isteğinin girişindeki aynı operationId değerini kullanın. Nihai imza yanıtını bekleyip yeni işlem kimliğiyle sorgulamayın.
  3. Fingerprint bulunursa kullanıcıya gösterin; bu, imzanın başarıyla tamamlandığı anlamına gelmez. Nihai imza isteğinin yanıtını da takip edin.
  4. İmza yanıtında USER_CANCEL, UNKNOWN_CLIENT veya başka bir hata varsa takibi sonlandırın; bekleyen fingerprint isteğini mümkünse iptal edin. Geç gelen yanıtın sonlandırılmış işlemi tekrar aktif hale getirmesine izin vermeyin.

Bekleme süresi dolduğunda

Bu davranış 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. Ortak V2 fingerprint endpoint'ini kullanan PAdES/CAdES/XAdES akışları aynı bekleme sınırına tabidir.

FINGERPRINT_TIMEOUT — displayLanguage: tr

{
  "result": { "fingerPrint": null },
  "error": "Bekleme süresi içinde parmak izi bulunamadı.",
  "errorCode": "FINGERPRINT_TIMEOUT"
}

İngilizce mesaj: Fingerprint could not be found within the waiting period. Başarı yanıtında errorCode alanı bulunmaz. HTTP 200 içinde hata dönebileceğinden yalnızca HTTP durum koduna bakmayın.

  • FINGERPRINT_TIMEOUT kullanıcı iptali değildir; imzanın kesin olarak başarısız olduğunu da göstermez. Devam eden imza isteğinin nihai sonucunu esas alın.
  • Sınırsız polling veya otomatik yeni mobil imza isteği başlatmayın. İstemcinin HTTP zaman aşımını 20 saniyelik sunucu beklemesi ve ağ payını dikkate alarak belirleyin.
  • Cache süreç içidir. Farklı sunucuya yönlendirme veya süreç yeniden başlatılması fingerprint'in bulunamamasına yol açabilir.
  • Mevcut XAdES enveloping üzerine paralel imza yolu fingerprint callback'ini çağırmaz; imza başarılı olsa bile bu sorgu zaman aşımına uğrayabilir.
  • Bu iyileştirme bütün HTTP 524 nedenlerinin çözüldüğü anlamına gelmez. Kullanıcı iptali tek başına 524'ün kanıtlanmış nedeni değildir.

İlgili sayfalar: PAdES Mobile V4, CAdES Mobile V4, XAdES Mobile V4 ve hata kodları.

Was this page helpful?