e-Belge Doğrulama & Dönüşüm Servisi

Türkiye'nin e-Dönüşüm ekosisteminde her gün milyonlarca e-Fatura, e-İrsaliye, e-Arşiv ve e-Defter belgesi üretiliyor. Bu belgelerin GİB standartlarına uygunluğunu doğrulamak ve XML'den okunabilir HTML'e dönüştürmek kritik ihtiyaçlar. İşte tam da bu ihtiyaç için ebelge-xslt-service'i açık kaynak olarak yayınladık.

Ne İşe Yarar?

Bu servis üç temel fonksiyon sunar:

Belge türü, XML root element'inden SAX parser ile otomatik algılanır — tek zorunlu parametre dosyanın kendisidir.

Desteklenen Belge Tipleri

Schema (XSD) Doğrulama

Schematron Doğrulama

XSLT Dönüşüm

Mimari

Servis, temiz katmanlı bir mimariye sahiptir:

Hızlı Başlangıç

Yerel Geliştirme

git clone https://github.com/mersel-os/ebelge-xslt-service.git
cd ebelge-xslt-service

# Derle ve test et
./gradlew build

# Çalıştır — Schematron otomatik derlenir, hazır!
./gradlew :xslt-web-api:bootRun

Servis adresleri:

Docker ile Çalıştırma

# Build ve çalıştır
docker compose up --build

# Veya sadece image oluştur
docker build -t mersel-xslt-service .
docker run -p 8080:8080 mersel-xslt-service

API Kullanımı

XML Doğrulama

Belge türü XML root element'inden otomatik tespit edilir. Tek zorunlu parametre source'dir.

# Temel doğrulama (belge türü otomatik tespit edilir)
curl -X POST http://localhost:8080/v1/validate \
  -F "source=@fatura.xml"

# Schematron parametreleri ile
curl -X POST http://localhost:8080/v1/validate \
  -F "source=@fatura.xml" \
  -F 'parameters=[{"key":"type","value":"efatura"},{"key":"sessionSupplierIdentification","value":"1234567890"}]'

Yanıt örneği:

{
  "result": {
    "validSchema": true,
    "validSchematron": false,
    "schemaValidationErrors": [],
    "schematronValidationErrors": [
      {
        "ruleId": "XadesSignatureCheck",
        "test": "ds:KeyInfo",
        "message": "ds:KeyInfo elemani zorunlu bir elemandir."
      }
    ]
  }
}

XSLT Dönüşüm

Başarılı dönüşümde ham HTML döner (text/html). Metadata, response header'larından okunur.

# Varsayılan XSLT ile
curl -v -X POST http://localhost:8080/v1/transform \
  -F "document=@fatura.xml" \
  -F "transformType=INVOICE"

# Belgenin kendi gömülü XSLT'si ile
curl -v -X POST http://localhost:8080/v1/transform \
  -F "document=@fatura.xml" \
  -F "transformType=INVOICE" \
  -F "useEmbeddedXslt=true"

# Özel XSLT + filigran ile
curl -v -X POST http://localhost:8080/v1/transform \
  -F "document=@fatura.xml" \
  -F "transformType=INVOICE" \
  -F "transformer=@ozel-sablon.xslt" \
  -F "watermarkText=TASLAK"

XSLT seçim önceliği: (1) transformer dosyası yüklendiyse onu kullan → (2) useEmbeddedXslt=true ve belgede gömülü XSLT varsa belgeden çıkar → (3) varsayılan XSLT şablonu.

Doğrulama Profilleri

Doğrulama profilleri, belirli Schematron/XSD hatalarının bastırılmasını sağlar. En yaygın kullanım: imzasız belgelerin doğrulanması.

Bastırma Modları

Profil YAML Yapısı

profiles:
  unsigned:
    description: "Imzasiz belge dogrulama"
    suppressions:
      - match: ruleId
        pattern: "XadesSignatureCheck"
        description: "XAdES imza kontrolu"
      - match: ruleId
        pattern: "SignatureCheck"
      - match: text
        pattern: ".*[Ii]mza.*"

  my-company:
    extends: unsigned          # unsigned'ın tüm kurallarını miras al
    description: "Firma ozel profili"
    suppressions:
      - match: ruleId
        pattern: "InvoiceIDCheck"

# Profil ile doğrulama
curl -X POST http://localhost:8080/v1/validate \
  -F "source=@fatura.xml" \
  -F "profile=unsigned"

# Profil + ad-hoc bastırma kuralları ile
curl -X POST http://localhost:8080/v1/validate \
  -F "source=@fatura.xml" \
  -F "profile=unsigned" \
  -F "suppressions=InvoiceIDCheck,text:.*organizationDescription.*"

Özel Schematron Kuralları

Kod değişikliği yapmadan, admin panelinden veya API ile özel iş kuralları tanımlayabilirsiniz.

Her kural şu alanları içerir:

Dinamik Parametreler

Kural test ifadelerinde $parametre_adi şeklinde değişkenler kullanılabilir. Bu değişkenler otomatik tanınır ve doğrulama isteğinde parameters alanı ile değerleri geçirilir.

Mesajlarda {{xpath}} Placeholder Desteği

Hata mesajlarında {{xpath_ifadesi}} syntax'i ile XML'deki değerleri doğrudan hata çıktısına yerleştirebilirsiniz:

Satıcı VKN ({{cac:AccountingSupplierParty/.../cbc:ID}}) oturumdaki firma
({{$sessionSupplierIdentification}}) ile eşleşmiyor.

Runtime'da {{...}} bloklarının yerine XML'den okunan gerçek değerler yerleştirilir:

Satıcı VKN (9876543210) oturumdaki firma (1234567890) ile eşleşmiyor.

GİB Paket Otomatik Sync

GİB resmi web sitesinden e-Fatura, UBL-TR XSD, e-Arşiv ve e-Defter paketlerini API ile otomatik indirir ve günceller.

# Tüm paketleri sync et
curl -X POST http://localhost:8080/v1/admin/packages/sync

# Belirli bir paketi sync et
curl -X POST http://localhost:8080/v1/admin/packages/sync?package=efatura

# Paket listesini gör
curl http://localhost:8080/v1/admin/packages

Hot-Reload ve External Asset Override

Hot-Reload

Dosya değişikliğinde veya API ile restart gerektirmeden yeniden yükleme:

curl -X POST http://localhost:8080/v1/admin/assets/reload

External Asset Override

Servisin kullandığı XSD, XSLT ve Schematron dosyaları Docker volume mount ile dışarıdan beslenebilir:

docker run -p 8080:8080 \
  -v $(pwd)/custom-assets:/opt/xslt-assets:ro \
  -e XSLT_ASSETS_EXTERNAL_PATH=/opt/xslt-assets \
  -e XSLT_ASSETS_WATCH_ENABLED=true \
  mersel-xslt-service

External dizinde bulunan dosyalar önceliklidir; bulunmayanlar için dahili (bundled) versiyonlar kullanılır.

Web Arayüzü

Tüm API işlemlerini grafiksel olarak sunabilen yerleşik bir web arayüzü ile gelir: React 19 + TypeScript, Vite 6, TailwindCSS 4 + shadcn/ui, Orval + Axios (OpenAPI codegen) ve TanStack Query v5.

cd xslt-web-ui
pnpm install
pnpm dev          # http://localhost:5173 — API istekleri 8080'e proxy edilir
pnpm generate-api # OpenAPI'den API client üret

Monitoring

Prometheus + Grafana ile kapsamlı izleme:

cd monitoring
docker compose up -d

Grafana dashboard 6 bölüm, 30+ panel içerir:

• Genel Bakış — Servis durumu, toplam doğrulama/dönüşüm/hata, JVM heap
• Doğrulama Metrikleri — İstek hızı, süre (p95), belge tipine göre dağılım, profil kullanımı
• Dönüşüm Metrikleri — Tip bazlı istek hızı, süre (p95), çıktı boyutu, XSLT kaynağı dağılımı
• Güvenlik ve Rate Limiting — Rate limit aşımları, giriş denemeleri
• Operasyon — Asset reload, GİB paket sync, Schematron derleme
• JVM ve Sistem — Heap/Non-Heap bellek, thread sayısı, GC duraklamaları

Production Profili

SPRING_PROFILES_ACTIVE=prod ile etkinleştirilir:

docker run -p 8080:8080 \
  -e SPRING_PROFILES_ACTIVE=prod \
  -e XSLT_ADMIN_PASSWORD=guclu-bir-sifre-buraya \
  mersel-xslt-service

Konfigürasyon Özeti

Sonuç

ebelge-xslt-service, e-Dönüşüm yazılımlarının en temel ihtiyaçlarından biri olan belge doğrulama ve görüntüleme problemini kapsamlı bir şekilde çözer. Özel Schematron kuralları, doğrulama profilleri, hot-reload, GİB paket sync ve web arayüzü ile sadece bir doğrulama motoru değil, tam bir e-Belge yönetim aracıdır.

MIT lisanslı ve açık kaynak. Katkılarınızı bekliyoruz.

• GitHub: github.com/mersel-os/ebelge-xslt-service
• Detay Sayfası: Proje Detayları
• Lisans: MIT