e-İmza Entegrasyonu Nedir, API ile Nasıl Kurulur? (2026)

İçindekiler:
Bu içeriği Yapay Zeka (AI) ile özetleyin:
İçeriği paylaşın:

BTK’nın elektronik imza açıklamasında yer alan kanuni tanıma göre elektronik imza geniş bir kavramdır: Başka bir elektronik veriye eklenen veya onunla mantıksal bağı bulunan ve kimlik doğrulama amacıyla kullanılan elektronik veri. Güvenli elektronik imza ise bu genel kavramın kanunda belirlenen koşulları taşıyan türüdür. Münhasıran imza sahibine bağlıdır; yalnızca onun tasarrufundaki güvenli imza oluşturma aracıyla oluşturulur; nitelikli elektronik sertifikaya dayanarak imza sahibinin kimliğini tespit etmeyi ve imzalanmış veride sonradan değişiklik olup olmadığını belirlemeyi sağlar.

e-İmza entegrasyonu nedir?

e-İmza entegrasyonu, bir kurumun uygulamasında üretilen veya işlenen belgelerin elektronik olarak imzalanabilmesi için imza altyapısının mevcut iş akışına bağlanmasıdır. ERP, CRM, insan kaynakları sistemi, elektronik belge yönetim sistemi veya müşteri portalı bu akışın başlangıç noktası olabilir. Entegrasyon; imza isteğinin oluşturulmasını, imzacının sürece katılmasını, imzalı belgenin alınmasını ve sonrasında doğrulanıp saklanmasını kapsayabilir.

Bu nedenle entegrasyon, uygulamaya yalnızca bir “imzala” düğmesi eklemekten ibaret değildir. Belge türü, imza sırası, sertifika, doğrulama, zaman damgası ve arşiv kuralları birlikte ele alınır. Elektronik imzanın teknik ve hukuki kapsamını ayrıca incelemek isterseniz dijital imza ile e-İmza arasındaki farkları anlattığımız yazıya bakabilirsiniz.

PTT KEP e-İmza API uygulamasıyla aynı şey mi?

“PTTKEP E-İmza API” adı, PTT KEP kullanıcılarının web arayüzündeki belirli imzalama işlemleri için kurduğu uygulamanın adında da geçer. Bu yazıda ele aldığımız e-imza API entegrasyonu ise bir kurumun kendi yazılımı ile imzalama altyapısı arasında bağlantı kurmasıdır. PTT KEP uygulamasını kurmaya veya çalıştırmaya ilişkin bir sorun yaşıyorsanız PTT KEP’in kendi kullanıcı kılavuzuna başvurmanız gerekir.

PTT KEP hesabınızda kullanılan uygulama, erişim veya kurulum hakkında bilgi arıyorsanız PTT KEP’in resmi hizmet ve destek sayfalarına başvurun. PTT’nin sunduğu KEP entegrasyonu da ayrıca KEP sistemine bağlantı kurmaya yöneliktir; bu yazının odağı olan kurumsal belge imzalama akışıyla aynı kapsamda değildir.

Kimler e-İmza entegrasyonuna ihtiyaç duyar?

Ayda birkaç belge imzalayan bir ekip, mevcut masaüstü araçlarıyla rahatça çalışabilir. Belge sayısı arttığında veya imza işlemi başka bir uygulamadaki sürecin parçası haline geldiğinde entegrasyon ihtiyacı belirginleşir. Örneğin:

  • İK sistemi işe giriş belgelerini üretir ve yetkili kişilerin imzasını bekler.
  • Satış ekibi CRM’de oluşturduğu sözleşmenin imza durumunu aynı kayıt üzerinden izlemek ister.
  • Satın alma sürecinde birden fazla onay ve imza belirli bir sırayla tamamlanır.
  • Bir EBYS’de hazırlanan yazının imzalı sürümü ilgili kayıtla birlikte saklanır.

Ortak ihtiyaç, belge ve durum bilgisinin farklı araçlar arasında elle taşınmasını azaltmaktır. Sözleşmeler özelinde belge hazırlama, imzacı atama ve saklama adımlarının nasıl birlikte planlanacağını dijital sözleşme imzalama rehberimizde daha ayrıntılı ele alıyoruz.

Entegrasyon yöntemleri: Kütüphane, API ve SDK

Elektronik imzayı bir uygulamaya eklemenin tek yolu yoktur. Yöntem seçimi, kurumun geliştirme kaynakları ve imzacının sertifikasına nereden erişileceğiyle birlikte değerlendirilmelidir.

YöntemNasıl çalışır?Hangi durumda değerlendirilebilir?Tasarımda dikkat edilmesi gerekenler
İmza kütüphanesiİmzalama işlevleri uygulamanın geliştirme ortamına eklenir. Kamu SM’nin MA3 API kütüphaneleri buna örnektir.İmza işlemleri üzerinde ayrıntılı teknik kontrol isteniyorsa.Geliştirme, bakım, sertifika erişimi ve doğrulama sorumluluklarının kapsamı belirlenmelidir.
API tabanlı platformKurum uygulaması, hizmetin sunduğu arayüzler üzerinden imza sürecini başlatır ve durumunu takip eder.İmza akışının mevcut uygulama ve süreçlerle bağlantısı kurulacaksa.Veri akışı, kimlik doğrulama, hata yönetimi ve sağlayıcının sunduğu işlevler incelenmelidir.
SDK veya gömülü bileşenİmzalamayla ilgili yazılım bileşeni istemciye ya da uygulamaya dahil edilir.Kullanıcının cihazındaki sertifika veya imza aracına yerel erişim gerekiyorsa.İşletim sistemi uyumu, dağıtım, sürüm güncellemeleri ve kullanıcı deneyimi planlanmalıdır.

Bu seçenekler birbirini her zaman dışlamaz. Bir çözüm, iş akışını API üzerinden yönetirken kullanıcının imza aracına erişmek için yerel bir bileşenden yararlanabilir.

SDK mı, API mi?

API, uygulamalar arasındaki iletişim ve sürecin yönetimi için bir arayüz sağlar. SDK ise geliştiricinin uygulamasına eklediği araçları ve bileşenleri sunar. İmzacının bilgisayarındaki kart veya token ile etkileşim gerekiyorsa istemci tarafındaki bileşenler önem kazanır. İmza isteğinin açılması, durumunun izlenmesi ve sonucun kurumsal sisteme aktarılması gerekiyorsa API katmanı öne çıkar. Seçim, ürünün teknik dokümantasyonu ve hedeflenen kullanım senaryosu üzerinden yapılmalıdır.

Sertifika nereden gelir?

Entegrasyon kendi başına nitelikli elektronik sertifika üretmez. Türkiye’de güvenli elektronik imza için gereken sertifika, BTK’nın yayımladığı elektronik sertifika hizmet sağlayıcılarından (ESHS) temin edilir. İmzalama çözümü ise uygun sertifikayla yürütülen işlemi kurumun yazılım sürecine bağlar. www.btk.gov.tr

Bu ayrım satın alma ve proje planı için önemlidir: İmzacıların sertifikalarının bulunması, kullanılacak araçların desteklenmesi ve sertifikaların geçerliliğinin kontrolü ayrı başlıklardır. Kurum adına işlem yapılacaksa imzacının temsil yetkisi de değerlendirilmelidir. Başvuru sürecini kurumlar için e-İmza rehberimizde, sertifika sağlayıcısının rolünü ise ESHS nedir? yazımızda açıklıyoruz.

API ile e-İmza entegrasyonu nasıl kurulur?

1. Belge ve imzacı kapsamını çıkarın

Hangi sistem hangi belgeyi üretiyor? Belgeler PDF mi, XML mi, başka bir veri türü mü? Bir belgede kaç imzacı var ve imza sırası önemli mi? İmza tamamlandığında hangi sistemin haberdar olması gerektiğini de belirleyin.

2. Sertifika ve imza araçlarını belirleyin

İmzacıların sertifikalarını ve kullandıkları araçları envantere alın. Kart, token ve mobil imza için kullanıcı akışı ve teknik erişim koşulları farklı olabilir. Kullanıcının hangi cihazda ve hangi aşamada imza vereceği, API veya yerel bileşen ihtiyacını etkiler.

3. Belgeye uygun imza formatını seçin

PDF belgeler için PAdES, diğer veri yapıları için CAdES ve XML tabanlı işlemler için XAdES gündeme gelebilir. Ancak seçimi yalnızca dosya uzantısına göre yapmayın. Alıcı kurumun kabul koşullarını, doğrulama yöntemini ve uzun süreli saklama ihtiyacını da inceleyin. Formatların kullanım alanlarını PAdES, CAdES ve XAdES rehberimizde karşılaştırıyoruz. imzago

4. Yöntemi ve çözümü değerlendirin

Kütüphane, API ve SDK seçeneklerini kurumun geliştirme kapasitesiyle karşılaştırın. Dokümantasyon, test ortamı, hata kodları, kimlik doğrulama yöntemi, desteklenen sertifika araçları, lisans ve bakım koşulları değerlendirme ölçütleri arasında olmalıdır. İmza öncesinde ve sonrasında hangi verinin hangi sisteme geçtiğini gösteren bir akış şeması hazırlayın.

5. İmza akışını tasarlayın

Tipik akışta belge hazırlanır, imza isteği oluşturulur, ilgili imzacıya görev iletilir, imzalama tamamlanır ve sonuç kurumsal sisteme döner. Ardından imza doğrulanır ve belge doğru kayıtla ilişkilendirilerek saklanır. Zaman damgası, hatırlatma, yeniden deneme ve çok imzacılı sıralama gibi adımlar ihtiyaca ve seçilen çözümün özelliklerine göre eklenir.

6. Olumlu ve olumsuz senaryoları test edin

Başarılı bir imza tek başına yeterli test değildir. Süresi dolmuş veya iptal edilmiş sertifika, imzadan sonra değiştirilmiş belge, erişilemeyen imza aracı, yarım kalan işlem ve ikinci imzacının süreci tamamlamaması gibi durumları deneyin. İmzanın sonradan doğrulanabildiğini ve hata halinde işlem durumunun uygulamada doğru göründüğünü kontrol edin.

7. Canlı kullanımı izleyin

Canlıya geçişten sonra başarısız işlemlerin nedenleri, tamamlanma durumları ve denetim kayıtları izlenmelidir. Kayıtlar sorun çözmeye yetecek bilgiyi sağlamalı; belge ve kullanıcı verilerine erişim kurallarına da uymalıdır.

Güvenlik: Özel anahtar nerede durur?

Bir imzalama akışındaki kritik sorulardan biri, imza oluşturma verisinin hangi güvenli ortamda korunduğu ve imza işleminin nerede gerçekleştiğidir. Kart veya token kullanılan modelde anahtar güvenli imza oluşturma aracında korunur; kurumsal uygulamanın bu anahtarı alıp kendi sunucusunda saklaması beklenmez. BTK, güvenli imza oluşturma aracındaki imza oluşturma verisinin araç dışına çıkarılamamasını ilgili güvenlik koşulları arasında sayar. www.btk.gov.tr

Bununla birlikte bir API’nin belgeyi, belgenin özetini veya işlemle ilgili başka verileri taşıyıp taşımadığı ürüne ve senaryoya bağlıdır. Bu nedenle seçilen çözüm için şu soruları yanıtlayın: Belgenin tamamı hizmete iletiliyor mu? Hangi veri ne kadar süre tutuluyor? İmzacı nasıl doğrulanıyor? İmza oluşturma verisi hangi ortamda kullanılıyor? İmzalı sonuç ve işlem kayıtları nerede saklanıyor?

İmza sonrasında belgenin değiştirilip değiştirilmediği, sertifikanın durumu ve gerektiğinde zaman damgası ile uzun dönem doğrulama koşulları da kontrol edilmelidir. Saklama politikası, bu kontrollerin ileride yapılabilmesi düşünülerek kurulmalıdır.

ERP, CRM ve İK sistemleriyle bağlantı nasıl kurulur?

Entegrasyonun başlangıç noktası çoğu zaman belgenin üretildiği sistemdir. Bir ERP’de hazırlanan satın alma belgesi, CRM’deki sözleşme veya İK uygulamasındaki işe giriş evrakı imzaya gönderilebilir. İmza tamamlandığında sonuç ilgili kayda döner; kullanıcı da sürecin durumunu kendi uygulamasından izleyebilir.

Bu örnekler belirli bir yazılımla hazır bağlantı bulunduğu anlamına gelmez. Hazır bir entegrasyon olup olmadığı, API ile özel geliştirme gerekip gerekmediği ve hangi verilerin eşleştirileceği seçilen çözüm için ayrıca doğrulanmalıdır. İmza altyapısı belgeyi imzalama işlevini sağlar; bildirim, yetki, sıralama ve arşiv kuralları kurumun uçtan uca süreç tasarımında tanımlanır.

KEP ve UETS entegrasyonundan farkı nedir?

e-İmza, elektronik verinin imzalanmasıyla ilgilidir. Kayıtlı elektronik posta (KEP) elektronik ileti gönderimi ve buna ilişkin delillerle; UETS ise elektronik tebligatın ilgili sistem üzerinden iletilmesiyle ilgilidir. Bir iş akışında belge önce imzalanıp ardından uygun kanalla gönderilebilir. İmzalama, gönderim ve tebligat adımlarının gereksinimleri ayrı ayrı ele alınmalıdır.

Entegrasyon kurulduktan sonra neye bakılmalı?

Teknik bağlantının çalışması projenin yalnızca ilk ölçütüdür. İmza isteklerinin kime ve ne zaman gittiği, bekleyen işlemlerin nasıl takip edildiği, çok taraflı akışın nasıl tamamlandığı ve imzalı belgenin hangi kayda döndüğü kullanıcı deneyimini belirler. Doğrulama ve arşiv düzeni de aynı planın içinde olmalıdır.

İmzago’nun API ve e-İmza Kütüphanesi seçeneklerini değerlendirirken ihtiyaç duyduğunuz belge, sertifika aracı ve uygulama mimarisini teknik ekiple birlikte eşleştirin. İmzago bir elektronik sertifika hizmet sağlayıcısı değildir; nitelikli elektronik sertifika edinme adımı ayrıca yürütülür. Ürün kapsamı ve uygulamanıza uygun entegrasyon yöntemi için İmzago ekibiyle görüşebilirsiniz.

e-İmza entegrasyonu hakkında sık sorulan sorular

e-İmza API’si nedir?

Bir yazılımın elektronik imza sürecini başka bir sistemle ilişkilendirmesini sağlayan programlama arayüzüdür. Sunulan işlemler, veri akışı ve imzanın oluşturulma yöntemi kullanılan çözüme göre değişir.

e-İmza entegrasyonu için sertifika gerekir mi?

Güvenli elektronik imza atılacaksa imzacı için uygun nitelikli elektronik sertifika gerekir. Entegrasyon bu sertifikayı vermez; mevcut sertifikayla yürütülen imzalama sürecini kurumsal uygulamaya bağlar.

SDK ile API arasındaki fark nedir?

API, sistemlerin belirlenmiş arayüzler üzerinden haberleşmesini sağlar. SDK, geliştiricinin uygulamasında kullanacağı yazılım bileşenlerini sunar. Mimariye göre iki yaklaşım birlikte de kullanılabilir.

API ile imza atılırken özel anahtar sunucuya gider mi?

Bunun yanıtı imzalama modeline bağlıdır; “API” sözcüğü tek başına anahtarın yerini tarif etmez. Kart veya token modelinde anahtar güvenli araçta korunur. Seçilen çözümün özel anahtarı nerede kullandığı ve API’nin hangi verileri taşıdığı teknik dokümantasyondan teyit edilmelidir.

Mobil imza API ile kullanılabilir mi?

Bazı imzalama çözümleri mobil imza akışlarını destekleyebilir. Bunun seçilen hizmette ve kullanılacak operatör senaryosunda mümkün olup olmadığı, kullanıcı doğrulaması ve entegrasyon koşullarıyla birlikte kontrol edilmelidir.

ERP veya İK yazılımına e-imza nasıl eklenir?

Önce imzalanacak belge, imzacılar ve imza sonrasındaki kayıt akışı belirlenir. Ardından uygun kütüphane, API veya SDK ile bağlantı kurulur; imzalama ve doğrulama senaryoları test edilir. Hazır bağlantı bulunup bulunmadığı kullanılan iki ürüne göre değişir.

e-İmza entegrasyonu ne kadar sürer?

Tek bir süre vermek doğru olmaz. Mevcut sistemin yapısı, imzacı sayısı, sertifika araçları, belge formatları, onay akışı ve güvenlik testleri süreyi etkiler. Sağlıklı tahmin için önce kapsam ve teknik bağımlılıklar çıkarılmalıdır.

İmza sürecini uygulamanızın içine taşımak mı istiyorsunuz? İmzago API ve e-İmza Kütüphanesi seçeneklerinin projenize uygunluğunu değerlendirmek için ekibimizle iletişime geçin.

Kaynakça