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.
Doğrulama servisi Belge Kaydı ve Doğrulama olarak 2 senaryo ile çalışı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"
}
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.
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"
}
İ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
Belge için kod üretilmesi isteğini belirtir.
Kod isteği sonucunda verilen cevabı belirtir.