ESYA'dan PrimeAPI'ye Geçiş: Adım Adım Teknik Migrasyon Rehberi

ESYA'nın ücretsiz sürümünün kapanmasına 2 hafta kaldı. Önceki yazımızda ne olduğunu ve seçeneklerinizi anlattık. Bu yazıda ise nasıl geçiş yapacağınızı anlatıyoruz: ESYA MA3 API'den PrimeAPI'ye teknik migrasyon adımları, mimari farklar ve endpoint eşleştirmeleri.

Mimari Fark: Kütüphane vs REST API

ESYA ve PrimeAPI temelden farklı bir mimaride çalışır. Bu farkı anlamak, geçiş stratejinizi şekillendirecek en önemli nokta.

ESYA (MA3 API):

Yerel kütüphane. Java JAR veya .NET DLL olarak projenize eklenir.
Tüm imza işlemleri (hash oluşturma, imzalama, birleştirme) uygulamanızın process'inde çalışır.
Sertifika erişimi, PKCS#11 driver'ları, TSP sunucu iletişimi — hepsi sizin yönetiminizde.
Platform bağımlı: Java veya .NET zorunlu.

PrimeAPI:

REST API. HTTP istekleri atabilen her dil ve platformda çalışır.
Hash oluşturma ve imza birleştirme sunucu tarafında (Onaylarım CoreAPI) gerçekleşir.
Yerel imzalama, kullanıcının bilgisayarındaki e-İmza Aracı üzerinden yapılır.
Sertifika yönetimi, zaman damgası, CRL/OCSP kontrolleri API tarafında halledilir.

Pratik sonuç: ESYA'da doğrudan yönettiğiniz birçok alt sistemi (TSP, CRL, sertifika deposu) PrimeAPI'de yönetmeniz gerekmez. Ancak mimari olarak bir backend proxy katmanı eklemeniz gerekir.

Geçiş Stratejisi: 3 Senaryo

Projenizin yapısına göre geçiş scope'u değişir:

Senaryo 1: ESYA Doğrudan Çağrılıyor

Uygulamanız ESYA sınıflarını doğrudan kullanıyorsa (EsyaSmartCardManager, BaseSignedData, PadesSigner vb.), tüm imza katmanını yeniden yazmanız gerekir. Bu en kapsamlı senaryo.

Geçiş adımı: ESYA çağrılarını bir servis arayüzü (interface) arkasına alın, ardından bu arayüzün PrimeAPI implementasyonunu yazın.

Senaryo 2: Abstraction Layer Var

Uygulamanızda zaten bir ISigningService veya benzeri bir soyutlama varsa, sadece yeni bir implementasyon yazmanız yeterli. Mevcut iş mantığınız değişmez.

Geçiş adımı: PrimeApiSigningService implementasyonunu yazın, DI container'da swap edin.

Senaryo 3: Web Uygulaması + Tarayıcı Tabanlı İmza

Eğer ESYA'yı tarayıcı eklentisi veya Java Applet üzerinden kullanıyorsanız, zaten eski bir mimaridesiniz. PrimeAPI'nin e-İmza Aracı + REST API yaklaşımı daha modern ve sürdürülebilir.

Geçiş adımı: Frontend'de e-İmza Aracı entegrasyonu, backend'de proxy endpoint'leri yazın. PrimeAPI Quickstart yazımız tam olarak bunu gösteriyor.

İmza İşlem Akışı Karşılaştırması

ESYA ile PAdES İmzalama (Java)

ESYA'da tipik bir PAdES imzalama akışı şu adımlardan oluşur:

SmartCardManager ile akıllı karta bağlan
Sertifikayı oku (ECertificate)
PadesSigner nesnesi oluştur
İmza parametrelerini ayarla (profil, hash algoritması, zaman damgası)
sign() metodu ile imzala
İmzalı dosyayı kaydet

Tüm bu işlemler tek bir process içinde, senkron olarak gerçekleşir.

PrimeAPI ile PAdES İmzalama

PrimeAPI'de aynı işlem 4 HTTP çağrısına dönüşür:

Dosya yükle → POST /CoreApiFile/UploadFile → operationId al
Hash oluştur → POST /V4/CoreApiPades/SignStepOnePadesCore → state, keyId, keySecret al
Yerel imzala → POST localhost:8099/signStepTwo (e-İmza Aracı) → signedData al
Birleştir → POST /V4/CoreApiPades/SignStepThreePadesCore → imzalı dosya hazır

Adım 1-2 ve 4 backend proxy'niz üzerinden CoreAPI'ye gider. Adım 3, kullanıcının tarayıcısından doğrudan e-İmza Aracı'na gider.

Endpoint Eşleştirme Tablosu

ESYA'daki sınıf/metot kullanımlarınızı PrimeAPI endpoint'lerine şöyle eşleyebilirsiniz:

ESYA İşlemi	PrimeAPI Endpoint	Not
`PadesSigner.sign()`	StepOne → signStepTwo → StepThree	3 adımlı akış
`CadesSigner.sign()`	`/V4/CoreApiCades/SignStepOneCadesCore` + StepTwo + StepThree	Aynı 3 adım
`XadesSigner.sign()`	`/V4/CoreApiXades/SignStepOneXadesCore` + StepTwo + StepThree	Aynı 3 adım
`SignedDataValidation.verify()`	`/CoreApiCades/Verify` veya `/CoreApiPades/Verify`	Format bazlı
`CertificateValidation.validate()`	Sertifika bilgisi `/reset` ile e-İmza Aracı'ndan okunur	Doğrulama API tarafında
`TimeStampClient`	Otomatik — SignatureLevel BLTA seçildiğinde	Ayrı yönetim yok
`SmartCardManager`	e-İmza Aracı (`localhost:8099/reset`)	Kart erişimi aracı üzerinden
`CertificateStore` / CRL-OCSP	Otomatik — API tarafında yönetilir	Ayrı yapılandırma yok

Parametre Eşleştirmeleri

İmza Profilleri

ESYA	PrimeAPI	Açıklama
`SignaturePolicy.P1`	`profile: 1`	Temel profil
`SignaturePolicy.P2`	`profile: 2`	Genişletilmiş profil
`SignaturePolicy.P3`	`profile: 3`	Arşiv profili
`SignaturePolicy.P4`	`profile: 4`	Tam profil

İmza Seviyeleri (PAdES)

ESYA	PrimeAPI	Açıklama
`PAdES_B_B`	`signatureLevel: 1`	Temel imza
`PAdES_B_T`	`signatureLevel: 2`	Zaman damgalı
`PAdES_B_LT`	`signatureLevel: 3`	Uzun vadeli
`PAdES_B_LTA`	`signatureLevel: 4`	Arşiv (önerilen)

Hash Algoritmaları

ESYA	PrimeAPI	Açıklama
`DigestAlg.SHA256`	`hashAlgorithm: 0`	Standart
`DigestAlg.SHA384`	`hashAlgorithm: 1`	Yüksek güvenlik
`DigestAlg.SHA512`	`hashAlgorithm: 2`	Maksimum güvenlik

Kod Örneği: Abstraction Layer ile Geçiş

Aşağıda, mevcut ESYA kodunuzu PrimeAPI'ye taşırken kullanabileceğiniz bir soyutlama yaklaşımı var. Bu pattern, iki sistemi paralel çalıştırmanıza da olanak tanır.

Interface Tanımı

public interface ISigningService
{
    Task<string> UploadFileAsync(Stream fileStream, string fileName);
    Task<CreateStateResult> CreateStateAsync(string operationId, string certificate, 
        SignatureFormat format, int profile, int level);
    Task<string> FinishSignAsync(string operationId, string signedData, 
        string keyId, string keySecret, SignatureFormat format);
}

public enum SignatureFormat { PAdES, CAdES, XAdES }

public class CreateStateResult
{
    public string State { get; set; }
    public string KeyId { get; set; }
    public string KeySecret { get; set; }
    public string OperationId { get; set; }
}

PrimeAPI Implementasyonu

public class PrimeApiSigningService : ISigningService
{
    private readonly string _baseUrl;
    private readonly string _apiKey;

    public PrimeApiSigningService(IOptions<OnaylarimApiOptions> options)
    {
        _baseUrl = options.Value.BaseUrl;
        _apiKey = options.Value.ApiKey;
    }

    public async Task<string> UploadFileAsync(Stream fileStream, string fileName)
    {
        var response = await $"{_baseUrl}/CoreApiFile/UploadFile"
            .WithHeader("X-API-KEY", _apiKey)
            .PostMultipartAsync(mp => mp.AddFile("file", fileStream, fileName))
            .ReceiveJson<OnaylarimApiResponse>();

        return response.OperationId;
    }

    public async Task<CreateStateResult> CreateStateAsync(
        string operationId, string certificate,
        SignatureFormat format, int profile, int level)
    {
        var endpoint = format switch
        {
            SignatureFormat.PAdES => "/V4/CoreApiPades/SignStepOnePadesCore",
            SignatureFormat.CAdES => "/V4/CoreApiCades/SignStepOneCadesCore",
            SignatureFormat.XAdES => "/V4/CoreApiXades/SignStepOneXadesCore",
            _ => throw new ArgumentException("Geçersiz format")
        };

        var response = await $"{_baseUrl}{endpoint}"
            .WithHeader("X-API-KEY", _apiKey)
            .PostJsonAsync(new
            {
                certificate,
                operationId,
                signatureLevel = level,
                profile,
                hashAlgorithm = 0 // SHA256
            })
            .ReceiveJson<OnaylarimApiResponse>();

        return new CreateStateResult
        {
            State = response.State,
            KeyId = response.KeyID,
            KeySecret = response.KeySecret,
            OperationId = response.OperationId
        };
    }

    public async Task<string> FinishSignAsync(
        string operationId, string signedData,
        string keyId, string keySecret, SignatureFormat format)
    {
        var endpoint = format switch
        {
            SignatureFormat.PAdES => "/V4/CoreApiPades/SignStepThreePadesCore",
            SignatureFormat.CAdES => "/V4/CoreApiCades/SignStepThreeCadesCore",
            SignatureFormat.XAdES => "/V4/CoreApiXades/SignStepThreeXadesCore",
            _ => throw new ArgumentException("Geçersiz format")
        };

        var response = await $"{_baseUrl}{endpoint}"
            .WithHeader("X-API-KEY", _apiKey)
            .PostJsonAsync(new { signedData, keyId, keySecret, operationId })
            .ReceiveJson<OnaylarimApiResponse>();

        return response.OperationId;
    }
}

DI Kaydı

// ESYA'dan PrimeAPI'ye geçiş — tek satır değişiklik
// builder.Services.AddScoped<ISigningService, EsyaSigningService>();
builder.Services.AddScoped<ISigningService, PrimeApiSigningService>();

Mevcut ESYA implementasyonunuzu silmeyin. Paralel çalışma döneminde her iki servisi de test edebilir, sorun çıkarsa geri dönebilirsiniz.

Mobil İmza Geçişi

ESYA'da mobil imza ayrı bir kütüphane ve farklı bir akış gerektiriyordu. PrimeAPI'de mobil imza aynı API yapısı içinde, format bazlı mobil imza endpoint'leri ile çalışır:

Format	Mobil İmza Endpoint
PAdES	`/V4/CoreApiMobilePades/...`
CAdES	`/V4/CoreApiMobileCades/...`
XAdES	`/V4/CoreApiMobileXades/...`

Akış, e-imza ile aynıdır — tek fark, StepTwo'da e-İmza Aracı yerine kullanıcının cep telefonuna SMS onay gitmesidir. Bu sayede akıllı kart veya token olmadan imza atılabilir.

Eliptik Eğri (EC) Uyumu

KamuSM'nin yeni NES sertifikaları RSA yerine Eliptik Eğri (EC) algoritmasını kullanıyor. ESYA'nın eski sürümlerinde EC desteği sorunlu olabiliyordu.

PrimeAPI V4, EC anahtarlı sertifikalarla sorunsuz çalışır. RSA'dan EC'ye geçişte uygulamanızda ek bir değişiklik gerekmez — API, sertifika türünü otomatik algılar ve uygun algoritmayı kullanır.

Geçiş Kontrol Listesi

Haziran'a kalan 2 haftada şu adımları takip edin:

Hafta 1 — Hazırlık ve Test:

ESYA kullanım envanterinizi çıkarın: hangi formatlar, hangi profiller, hangi seviyeler.
PrimeAPI sandbox API anahtarını alın (ücretsiz).
Backend proxy'yi kurun. Quickstart yazımızdaki .NET örneğini temel alabilirsiniz.
ISigningService abstraction layer'ını oluşturun, PrimeAPI implementasyonunu yazın.
Test ortamında tüm imza senaryolarınızı çalıştırın.

Hafta 2 — Production Geçişi:

Production API anahtarınızı alın.
Backend proxy'yi production ortamına deploy edin.
DI container'da ESYA → PrimeAPI swap'ını yapın.
Paralel çalışma döneminde her iki sistemi de izleyin.
1 Haziran öncesi ESYA bağımlılığını tamamen kaldırın.

Yönetmeniz Gerekmeyen Şeyler

ESYA'dan PrimeAPI'ye geçişte işiniz azalan alanlar:

Zaman damgası sunucu yapılandırması — PrimeAPI, SignatureLevel BLTA seçildiğinde zaman damgasını otomatik ekler.
CRL/OCSP kontrolleri — Sertifika geçerlilik kontrolleri API tarafında yapılır.
PKCS#11 driver yönetimi — e-İmza Aracı, farklı kart okuyucu ve token'larla uyumluluğu kendi yönetir.
Kütüphane sürüm güncellemeleri — REST API olduğu için istemci tarafında güncelleme gerekmez.

PrimeAPI sandbox ortamını test etmek için PrimeAPI sayfasını ziyaret edin. Geçiş sürecinizde teknik destek için bizimle iletişime geçin.

Detaylı API dokümantasyonu: primeapidocs.onaylarim.com