e-Fatura Validator (UBL-TR 1.2.1)

GİB (Gelir İdaresi Başkanlığı) UBL-TR 1.2.1 e-Fatura (Invoice) belgelerini üç katmanda doğrulayan, her zaman açık (Standby) HTTP API.

Bir e-Fatura XML'i gönderirsiniz; servis belgenin iyi biçimli (well-formed) olup olmadığını, XSD şemasına uyup uymadığını ve GİB iş kurallarına (Schematron) uygun olup olmadığını kontrol eder. Yanıt; geçerlilik durumu, hatalı alanların konumu (XPath) ve GİB'in kendi hata mesajlarını içerir.

Neden bu actor?

• Resmi GİB paketleri ile çalışır (UBL-TR 1.2.1 XSD + UBL-TR Schematron).
• Üç katmanlı gerçek doğrulama — sadece XSD değil, GİB iş kuralları (Schematron) dahil.
• KVKK uyumlu: fatura içeriği (ad, adres, VKN/TCKN, kalemler) loglanmaz ve yanıtta geri döndürülmez. Yalnızca yapısal hata bilgisi döner.
• Standby mod: REST API gibi anında yanıt, soğuk başlatma yok.

Doğrulama katmanları

Katman	Kontrol	Motor
1	XML iyi biçimli mi	lxml
2	UBL-TR 1.2.1 XSD şema uyumu	lxml
3	GİB iş kuralları (Schematron / SVRL)	Saxon-HE

Not: XSD (katman 2) başarısızsa Schematron (katman 3) atlanır — bozuk yapı üzerinde iş kuralı sonucu yanıltıcı olurdu. ZARF (StandardBusinessDocument) ile sarılı belgelerde içteki Invoice otomatik çıkarılır. Bu sürüm Invoice belge tipini doğrular.

Kullanım

Standby HTTP endpoint'ine POST ile ham XML gönderin (gövde içinde — KVKK gereği query parametresinde değil).

Endpoint

POST  https://<actor-standby-url>/validate
Content-Type: application/xml
Body: <UBL-TR Invoice XML>

GET / çağrısı servis bilgisini döner; GET /openapi.json tam OpenAPI şemasını verir.

Örnek istek (curl)

curl -X POST "https://<actor-standby-url>/validate?token=<APIFY_TOKEN>" \
     -H "Content-Type: application/xml" \
     --data-binary "@fatura.xml"

Örnek yanıt

{
  "isValid": false,
  "documentType": "Invoice",
  "ublVersion": "2.1",
  "layers": { "well_formed": true, "xsd": true, "schematron": false },
  "errorCount": 1,
  "errors": [
    {
      "layer": "schematron",
      "code": "business_rule_violation",
      "message": "Para birimi TRY olmayan belgelerde kur bilgisi zorunludur.",
      "line": null,
      "location": "/*[local-name()='Invoice']",
      "ruleTest": "not(cbc:DocumentCurrencyCode!='TRY') or cac:PricingExchangeRate/cbc:CalculationRate"
    }
  ]
}

Geçerli belgede isValid: true, errorCount: 0 döner.

Yanıt alanları

Alan	Açıklama
isValid	Tüm katmanlar geçtiyse true
documentType	Tespit edilen belge tipi (Invoice)
ublVersion	Belgedeki cbc:UBLVersionID değeri
layers	Her katmanın geç/kalma durumu
errorCount	Toplam hata sayısı
errors[]	Hata listesi: layer, code, message, line, location (XPath), ruleTest

Hata kodları

not_well_formed · no_invoice_in_envelope · unsupported_document_type · xsd_violation · business_rule_violation

Ücretlendirme

Pay-per-event: her doğrulama isteği (api-call) için sabit ücret. Belge geçerli olsun ya da olmasın ücretlendirilir — doğrulamanın kendisi hizmettir.

KVKK / Gizlilik

Fatura XML içeriği yalnızca işlem süresince bellekte tutulur; diske yazılmaz, loglanmaz. Yanıttaki hata mesajları GİB'in standart kural metinleri ve yapısal XPath konumlarıdır — fatura içeriğindeki kişisel veriler (ad, adres, kimlik no, tutarlar) asla yanıtta yer almaz.

Sınırlar / yol haritası

• Bu sürüm Invoice doğrular (ApplicationResponse / DespatchAdvice ileride).
• GİB paketi güncellendiğinde Schematron yeniden derlenir; sürüm bu README'de belirtilir.

---

Bu actor resmi bir GİB ürünü değildir; resmi UBL-TR 1.2.1 paketlerini temel alır.