GİB Mükellef Sorgulama Servisi

Türkiye'de e-Fatura ve e-İrsaliye sistemlerinde mükellef sorgulama ihtiyacı hemen her uygulamada tekrar eden bir problemdir. GİB'in yayınladığı PK/GB XML listeleri milyonlarca kaydı barındırır ve bu verileri her uygulamanın kendi bünyesinde yönetmesi ciddi bir teknik yük oluşturur.

gib-user-list bu sorunu bir kez çözüp tüm iç uygulamalarınıza sunma felsefesiyle tasarlanmıştır.

Temel Avantajlar

Tipik Kullanım Senaryosu

Bu servis, doğrudan dış dünyaya açılmak yerine internal mikroservis olarak tasarlanmıştır:

Kendi uygulamanızda mükellef tablosu tutmanıza, GİB XML'lerini parse etmenize gerek kalmaz. Backend servisiniz bu internal mikroservise bir HTTP çağrısı yapar, sonucu alır ve kendi iş mantığında kullanır.

Mimari

Proje Clean Architecture prensiplerine uygun olarak katmanlı bir yapıdadır:

Hızlı Başlangıç

Docker Compose ile

cd docker
docker compose up -d

Monitoring Stack ile

cd monitoring
export POSTGRES_PASSWORD=gizli-sifre
export GRAFANA_ADMIN_PASSWORD=grafana-sifre
docker compose up -d

Senkronizasyon Mekanizması

Worker'ın senkronizasyon akışı 12 adımdan oluşur:

1. GİB'den PK + GB ZIP dosyalarını paralel indir (retry destekli)
2. ZIP'ten XML dosyalarını çıkar
3. XmlReader ile akış tabanlı parse — tüm listeyi belleğe yüklemez
4. PostgreSQL COPY protokolü ile geçici tablolara toplu yaz (25K batch)
5. Advisory Lock — eş zamanlı sync çalışmasını engeller
6. Diff Engine — content_hash ile değişiklik tespiti (added/modified/removed)
7. Safe removal guard — toplam silme yüzdesi eşik aşarsa silme atlanır
8. REFRESH MATERIALIZED VIEW CONCURRENTLY (retry destekli, maks 3 deneme)
9. Belge türüne göre XML.GZ arşiv üret (PK+GB birleşik)
10. Eski arşiv dosyalarını retention'a göre temizle
11. sync_metadata güncelle
12. Webhook bildirimi gönder, çık — ~200 MB RAM tamamen serbest kalır

Materialized View ile Sıfır Kesinti

REFRESH MATERIALIZED VIEW CONCURRENTLY PostgreSQL'e özgü güçlü bir yetenektir: eski veri okunmaya devam ederken arka planda yeni veri hazırlanır, tamamlandığında atomik olarak değiştirilir.

API Endpoint'leri

Sorgulama

Değişiklik Takibi (Delta Sync)

Her kayıt changeType alanı içerir: added, modified veya removed. Retention süresi dışındaki istekler 410 Gone döner — bu durumda tüketici tam listeyi yeniden indirmelidir.

Arşiv (Tam Liste)

Durum ve Sağlık

Kullanım Örnekleri

# VKN ile e-Fatura mükellefi sorgula
curl http://localhost:8080/api/v1/einvoice/1234567890

# Ünvana göre arama
curl "http://localhost:8080/api/v1/einvoice?search=MERSEL&page=1&pageSize=20"

# Delta sync — son 1 saatteki değişiklikler
curl "http://localhost:8080/api/v1/einvoice/changes?since=2026-02-27T00:00:00Z"

# Senkronizasyon durumunu kontrol et
curl http://localhost:8080/api/v1/status

Tüm sorgu ve arşiv endpoint'leri yanıtta X-Last-Sync-At başlığını döner:

X-Last-Sync-At: 2026-02-19T03:05:12.0000000+03:00

Tüketici Senkronizasyon Protokolü

Tüketicilerin mükellef listesini verimli şekilde güncel tutması için bir protokol sunulur:

1. Bootstrap: /api/v1/einvoice/archives/latest ile tam listeyi XML.GZ olarak indir
2. Delta Takibi: Periyodik olarak /changes?since=... ile değişiklikleri sorgula
3. Re-bootstrap: 410 Gone dönerse retention süresi dışına düşülmüş demektir — tam listeyi yeniden indir

HMAC-SHA256 Kimlik Doğrulama

İki mod desteklenir:

Devre dışı (varsayılan): Tüm istekler anonim geçer.

Authentication__Enabled=false

HMAC aktif: Her istemci AccessKey + SecretKey çifti ile tanımlanır.

Authentication__Enabled=true
Authentication__TimestampToleranceSeconds=300
Authentication__Clients__0__AccessKey=belgehub-prod
Authentication__Clients__0__SecretKey=gizli-anahtar-buraya
Authentication__Clients__0__Name=BelgeHub

Sunucu tarafında timestamp toleransı (varsayılan 5 dk) ve sabit-zaman imza karşılaştırması uygulanır.

Webhook Bildirimleri

Kritik olaylar için Slack ve/veya HTTP webhook desteği:

Webhooks__Enabled=true
Webhooks__Slack__Enabled=true
Webhooks__Slack__WebhookUrl=https://hooks.slack.com/services/T.../B.../xxx
Webhooks__Slack__Channel=#gib-sync-alerts

HTTP webhook'ta Secret tanımlıysa gövdenin HMAC-SHA256 imzası X-Webhook-Signature: sha256=... başlığında gönderilir. Her kanal hangi olayları alacağını NotifyOn ile bağımsız olarak seçebilir.

Güvenli Silme Koruyucusu

Senkronizasyon sırasında silinecek mükellef oranı MaxAllowedRemovalPercent eşiğini aşarsa (örn. GİB'den hatalı/boş liste gelmesi durumunda) silme işlemi otomatik olarak atlanır ve webhook bildirimi gönderilir.

GibEndpoints__MaxAllowedRemovalPercent=10    # Güvenli silme eşiği (%)

Önbellekleme

Caching__Provider=Memory       # "Memory" (varsayılan) veya "Redis"
Caching__DefaultTtlMinutes=60
Caching__RedisConnectionString=localhost:6379

Yalnızca VKN/TCKN ile yapılan doğrudan sorgular (/api/v1/einvoice/{identifier}) önbelleğe alınır. Arama sorguları her zaman veritabanından gelir.

Arşiv Depolama

İki depolama seçeneği:

.NET İstemci SDK

Kurulum

dotnet add package MERSEL.Services.GibUserList.Client

DI Kaydı

// Auth devre dışı
builder.Services.AddGibUserListClient(options =>
{
    options.BaseUrl = "https://gib-userlist.example.com";
});

// HMAC kimlik doğrulamalı
builder.Services.AddGibUserListClient(options =>
{
    options.BaseUrl = "https://gib-userlist.example.com";
    options.AccessKey = "belgehub-prod";
    options.SecretKey = "gizli-anahtar-buraya";
});

AccessKey ve SecretKey verildiğinde tüm çıkan istekler otomatik olarak HMAC-SHA256 ile imzalanır.

Kullanım

public class MyService(IGibUserListClient gibuserClient)
{
    public async Task Example(CancellationToken ct)
    {
        // VKN/TCKN ile sorgula
        var user = await gibuserClient
            .GetEInvoiceGibUserAsync("1234567890", ct: ct);

        // Ünvana göre ara
        var results = await gibuserClient
            .SearchEInvoiceGibUsersAsync("MERSEL", ct: ct);

        // Toplu sorgulama (maks 100)
        var batch = await gibuserClient
            .BatchGetEInvoiceGibUsersAsync(
                ["1234567890", "9876543210"], ct);

        // e-İrsaliye mükellefi sorgula
        var despatch = await gibuserClient
            .GetEDespatchGibUserAsync("1234567890", ct: ct);

        // Delta sync
        var changes = await gibuserClient
            .GetEInvoiceChangesAsync(
                since: DateTime.Now.AddHours(-1), ct: ct);

        // Tam mükellef listesi arşivi (bootstrap)
        var archive = await gibuserClient
            .GetLatestEInvoiceArchiveAsync(ct);

        // Senkronizasyon durumu
        var status = await gibuserClient
            .GetSyncStatusAsync(ct);
    }
}

Tüketici Sync Örneği

public async Task SyncLocalDatabase(
    IGibUserListClient client, CancellationToken ct)
{
    try
    {
        var changes = await client.GetEInvoiceChangesAsync(
            since: _lastSyncTime, ct: ct);

        foreach (var change in changes.Data.Changes)
        {
            switch (change.ChangeType)
            {
                case "added":
                case "modified":
                    await UpsertLocalUser(change);
                    break;
                case "removed":
                    await DeleteLocalUser(change.Identifier);
                    break;
            }
        }
        _lastSyncTime = changes.LastSyncAt ?? DateTime.Now;
    }
    catch (GibUserListSyncExpiredException)
    {
        // 410 Gone — tam listeyi tekrar indir
        var archive = await client
            .GetLatestEInvoiceArchiveAsync(ct);
        if (archive.Data is not null)
            await RebuildLocalDatabase(archive.Data);
    }
}

Dağıtım

Kubernetes

kubectl apply -f k8s/api-deployment.yaml
kubectl apply -f k8s/updater-cronjob.yaml

• API: Deployment + HPA ile yatay ölçeklendirme, sürekli çalışır
• Worker: CronJob, günde 4 kez çalışır (03:00, 09:00, 15:00, 21:00), bitince kapanır. concurrencyPolicy: Forbid ile aynı anda birden fazla çalışması engellenir.

Linux (systemd + cron)

# API: systemd servisi
sudo systemctl enable --now gibuserlist-api

# Worker: crontab ile periyodik tetikleme
echo "0 3 * * * /opt/gib-userlist/Worker.Updater" | sudo crontab -

Docker Compose

cd docker
docker compose up -d

PostgreSQL, API ve Worker tek komutla ayağa kalkar.

Observability

Prometheus Metrikleri (/metrics)

Grafana Dashboard

monitoring/ klasöründe hazır dashboard, 7 bölüm, 25+ panel:

• Genel Bakış — Toplam sorgu, hata oranı, ortalama süre, cache hit oranı
• Sorgu Performansı — Rate, p50/p95/p99, belge türü dağılımı
• Sync Job — İşlem sayısı, süre, kullanıcı sayısı
• Cache — Hit/miss rate, hit oranı
• Kimlik Doğrulama — İstemci bazında sorgu rate, başarısızlık nedenleri
• HTTP İstekleri — Status code dağılımı, response time
• .NET Runtime — GC heap, thread pool, bellek

Sonuç

gib-user-list, e-Dönüşüm uygulamalarının en yaygın ihtiyaçlarından biri olan mükellef sorgulama problemini bir kez çözüp tüm altyapınıza sunar. Stream tabanlı parsing ile düşük bellek kullanımı, Materialized View ile sıfır kesinti güncelleme, delta sync ile verimli tüketici protokolü ve kapsamlı observability ile production-grade bir çözümdür.

Kendi uygulamanızda mükellef tablosu tutmanıza, GİB XML'lerini parse etmenize, güncelleme job'ları yazmanıza gerek kalmaz.

• GitHub: github.com/mersel-os/gib-user-list
• Detay Sayfası: Proje Detayları
• NuGet: MERSEL.Services.GibUserList.Client
• Lisans: MIT