Kolay İmza Doğrulama Servisi Dokümantasyonu

Kolay İmza Doğrulama Servisi Nasıl Çalışır ?

Kolay İmza Doğrulama servisi elektronik imzalı belgelerin ilgili kişilerle güvenli olarak paylaşılması ve üzerindeki imzaların doğrulanması amacıyla kullanılır.

Sisteme elektronik imzalı belgenin ulaşılacağı adres rest API ile kaydedilir ve kolay imza her belge için tekil olmak üzere bir belge kodu üretir. Üretilen belge kodu ilgili kişiye SMS veya e-Posta gibi herhangi bir ortamda iletilir.

Belgeyi kontrol etmek isteyen kişi belge numarasını belirterek, belge üzerindeki elektronik imzaların doğru olduğunu görebilir ve gerekiyor ise belgeyi saklama amacıyla indirebilir.

Nasıl Çalışır ?

Doğrulama servisi Belge Kaydı ve Doğrulama olarak 2 senaryo ile çalışır.

Belge Kaydı

Belge Doğrulama

Belge Kaydı nasıl yapılır ?

Belge kaydı için doğrulama servisindeki “/api/code” sayfasına aşağıdaki örnekteki gibi bir post çağrısı yapılır.

İstek üzerinde kimlik doğrulama amacıyla Bearer token içerisinde lisans kontrolü için API anahtarı belirtilmesi zorunludur.

POST https://belge.kolayimza.com/api/code  
Authorization: Bearer fbaa.......897  
  
{  
"url":"https://myserver/file?id=e65ac6cb-0b56-451f-a98c-9915f96eb861"  
}

Belge kaydı için yapılan rest çağrısına aşağıdaki örnekteki gibi içerisinde “code” alanı bulunan bir cevapla dönüş yapar.

{  
  "code": "1GR8P2P6O9"
}

Belge kodu dışında 2. faktör doğrulama gerektiğinde belge kaydında ayrıca PIN isteği de aşağıdaki örnekteki gibi belirtilebilir.

POST https://belge.kolayimza.com/api/code  
Authorization: Bearer fbaa.......897  
  
{  
"requestPIN":true,
"url":"https://myserver/file?id=e65ac6cb-0b56-451f-a98c-9915f96eb861"
}

PIN kodu istenmesi durumunda doğrulama servisi aşağıdaki gibi PIN kodu da içeren 2 ayrı kod bilgisi ile cevap verir.

{  
  "code": "1GR2P2P649",  
  "pin": "O4THK0AH9G"  
}

Belge Doğrulama nasıl yapılır ?

Belge Doğrulama Sayfası

Doğrulama sayfasına “https://belge.kolayimza.com” adresi üzerinden ulaşılabilmektedir. Sayfa açıldığında belge kodu girilmesini bekleyecektir.

Belge kodu belirtildiğinde doğrulama sonucu sayfa üzerinde görüntülenir.

Belge kodunun elle girilmesine alternatif olarak belge kodu sayfaya parametre olarak geçilebilir. Bu durumda doğrulama sonucu ek bir işleme gerek kalmadan görüntülenir.

https://belge.kolayimza.com/?1GR2P2A619

Belge kaydı yapılırken PIN gereksinimi belirtilmiş ise doğrulama sayfası doğrulama sonuçlarını görüntülemeden önce PIN kodu girilmesi şeklinde kullanıcıyı yönlendirir.

API ile doğrulama

Kayıt işlemi ile üretilen kod bilgisi aşağıdaki örnekteki gibi rest çağrısı ile doğrulama sonuçları alınabilir. Doğrulama işlemi için herhangi bir API key gerekmemektedir.

GET https://belge.kolayimza.com/api/verify/8AEYE6HFCH

Yapılan bu istekle belge üzerindeki elektronik imzalar doğrulanır ve sonuçlar aşağıdaki gibi bir örnek JSON içerisinde cevaplanır.

{
  "format": "Pades",
  "level": "T",
  "allValid": true,
  "validity": "Valid",
  "timestamp": "2020-01-01T15:00:00",
  "signatures": [
    {
      "dateTime": "2020-02-14T11:45:41",
      "isValid": true,
      "certificateName": "AD SOYAD",
      "certificateSerialNumber": "TCKIMLIKNO"
    }
  ],
  "token": "B56C....E7B",
  "invalidPIN": false
}

Belge kaydı sırasında 2. faktör doğrulama belirtilmiş ise doğrulama çağrısı aşağıdaki örnekteki gibi POST methodu ile yapılmalı ve PIN kodu belirtilmelidir.

POST https://belge.kolayimza.com/api/verify/1GR2P2P649

{
  "PIN": "1234"
}

Belge İçeriğine Ulaşım

İmzalı belge içeriğine ancak doğrulama işlemi sonrasında üretilen token bilgisi ile ulaşılabilir.

İmzalı belgeyi indirmek için aşağıdaki örnekteki gibi api/download adresine token bilgisi eklenerek imzalı belge indirilebilir.

https://belge.kolayimza.com/api/download/4712C585....E507C228DC

JSON Modelleri

/api/code

CodeRequest

Belge için kod üretilmesi isteğini belirtir.

Url: string: Belgenin indirileceği adres. Doğrulama servisi tarafından ulaşılabilir bir adres olmalıdır.
RequestPIN: bool: PIN kodu gerekli olup olmadığını belirtir. Varsayılan False.
ExpiresAt: DateTime: Belgenin erişime kapatılacağı tarih. Belirtilmez ise süresiz olarak kaydedilir.

CodeResponse

Kod isteği sonucunda verilen cevabı belirtir.

Code:string: Belgeye verilen tekil kod bilgisidir.
PIN:string: Talep edildi ise doğrulama sırasında beklenen PIN değeridir. PIN talep edilmedi ise bu bilgi gönderilmez.

/api/verify/{code}

VerifyRequest

PIN:string: Belgeye erişim için kullanılacak 2. faktör PIN kodu.

VerifyResult

format:string ∈ { None, Cades, Pades, Xades, SMime }: Otomatik tanınmış imza formatını belirtir.
level: string ∈ { BES, T, X, A }: Belge üzerinde imzaların seviyesini belirtir. BES basit imza, T zaman damgalı imza, X uzun dönem imza, A arşiv imza değerlerinden birini alabilir.
allValid:boolean: Belge üzerindeki tüm imzaların geçerli olması durumunda true değeri taşır.
validity: string: İmzanın geçerli olması durumunda Valid değerini taşır.
timestamp: string: İmza üzerinde zaman damgası bulunuyor ise zaman damgası tarihini taşır.
signature: Signature[]: Belge üzerindeki imzaların listesini belirtir.
token: string: Belgeye erişim için kullanılacak token değerini belirtir.
invalidPIN: boolean: Hatalı PIN girilmesi durumunda true değerini taşır.

Signature

dateTime: string: Var ise zaman damgası tarihini, zaman damgası yok ise imzalanan cihazdaki tarih değerini belirtir.
isValid: boolean: İmza geçerli ise true değerini taşır.
certificateName: İmzayı oluşturan sertifika sahibini belirtir.
certificateSerialNumber: İmzayı oluşturan sertifika sahibinin TC Kimlik numarasını belirtir.