Türkiye Cumhuriyeti Gelir İdaresi Başkanlığı tarafından PDF formatında verilen/indirilen vergi levhalarından bilgileri yapılandırılmış (structured) olarak çıkaran bir Golang kütüphanesi.
A Go library for extracting structured data from Turkish tax plate (Vergi Levhası) PDF documents.
Bu kütüphane, vergi levhası PDF'lerinden aşağıdaki bilgileri çıkarabilir:
- Adı Soyadı - Kişi adı ve soyadı (şahıs için)
- Ticaret Ünvanı - Şirket ticaret ünvanı (şirket için)
- İş Yeri Adresi - İşyeri adresi bilgisi
- Vergi Türü - Vergi türleri (Gelir Vergisi, KDV, vb.)
- Faaliyet Kodları ve Adları - NACE faaliyet kodları ve açıklamaları
- Vergi Dairesi - Bağlı olunan vergi dairesi
- Vergi Kimlik No - Vergi kimlik numarası
- TC Kimlik No - TC kimlik numarası (şahıs için)
- İşe Başlama Tarihi - İşe başlama tarihi
- Geçmiş Matrahlar - Geçmiş yıllara ait matrah bilgileri
go get github.com/alparslanahmed/vergilevhasi-parser-gopackage main
import (
"encoding/json"
"fmt"
"log"
"github.com/alparslanahmed/vergilevhasi-parser-go"
)
func main() {
// Parser oluştur
parser := vergilevhasi.NewParser()
// PDF dosyasını parse et
result, err := parser.ParseFile("vergi-levhasi.pdf")
if err != nil {
log.Fatal(err)
}
// Sonuçları JSON olarak yazdır
jsonData, _ := json.MarshalIndent(result, "", " ")
fmt.Println(string(jsonData))
// Belirli alanları yazdır
fmt.Printf("Vergi Kimlik No: %s\n", result.VergiKimlikNo)
fmt.Printf("Vergi Dairesi: %s\n", result.VergiDairesi)
}file, err := os.Open("vergi-levhasi.pdf")
if err != nil {
log.Fatal(err)
}
defer file.Close()
parser := vergilevhasi.NewParser()
result, err := parser.Parse(file)
if err != nil {
log.Fatal(err)
}Debug modunu aktifleştirerek PDF'den çıkarılan ham metni görebilirsiniz:
parser := vergilevhasi.NewParser()
parser.SetDebug(true)
result, err := parser.ParseFile("vergi-levhasi.pdf")Not: Aşağıdaki veriler tamamen hayalidir ve yalnızca örnek amaçlıdır.
{
"adi_soyadi": "Ali Örnek",
"vergi_kimlik_no": "1234567890",
"tc_kimlik_no": "11111111110",
"vergi_dairesi": "Örnek Vergi Dairesi",
"is_yeri_adresi": "Örnek Mah. Test Cad. No:1, Ankara",
"ise_baslama_tarihi": "2020-01-15T00:00:00Z",
"vergi_turu": [
"Gelir Vergisi",
"KDV"
],
"faaliyet_kodlari": [
{
"kod": "4711",
"ad": "Gıda, içecek ve tütün ağırlıklı olan mağazalarda perakende ticaret"
}
],
"gecmis_matrahlar": [
{
"yil": 2020,
"tutar": 100000.0
},
{
"yil": 2021,
"tutar": 150000.0
}
]
}Yeni bir parser örneği oluşturur.
Debug modunu aktif/pasif eder. Debug modunda PDF'den çıkarılan ham metin konsola yazdırılır.
Belirtilen yoldaki PDF dosyasını parse eder ve yapılandırılmış veriyi döndürür.
io.ReadSeeker'dan PDF dosyasını parse eder ve yapılandırılmış veriyi döndürür.
type VergiLevhasi struct {
AdiSoyadi string // Adı Soyadı
TicaretUnvani string // Ticaret Ünvanı
IsYeriAdresi string // İş Yeri Adresi
VergiTuru []string // Vergi Türleri
FaaliyetKodlari []Faaliyet // Faaliyet Kodları
VergiDairesi string // Vergi Dairesi
VergiKimlikNo string // Vergi Kimlik No
TCKimlikNo string // TC Kimlik No
IseBaslamaTarihi *time.Time // İşe Başlama Tarihi
GecmisMatra []Matrah // Geçmiş Matrahlar
}type Faaliyet struct {
Kod string // Faaliyet kodu (örn: "4711")
Ad string // Faaliyet açıklaması
}type Matrah struct {
Yil int // Yıl
Donem string // Dönem (varsa)
Tutar float64 // Tutar
Tur string // Matrah türü (varsa)
}# Run basic tests
go test -v
# Run tests with coverage
go test -v -coverProje içinde örnek uygulama bulunmaktadır:
# Örneği çalıştır
go run example/main.go path/to/vergi-levhasi.pdf- github.com/pdfcpu/pdfcpu - PDF işleme ve metin çıkarma kütüphanesi
- github.com/makiuchi-d/gozxing - Barkod tarama kütüphanesi (VKN çıkarma için)
MIT License - Detaylar için LICENSE dosyasına bakın.
Katkılarınızı bekliyoruz! Detaylar için CONTRIBUTING.md dosyasına bakın.
Önemli: Gerçek vergi levhası PDF'lerini veya kişisel verileri repository'ye eklemeyin. Test verileri için yalnızca hayali/sahte veriler kullanın.
Bu kütüphane, Gelir İdaresi Başkanlığı'nın PDF formatındaki vergi levhalarından bilgi çıkarmak için regex tabanlı bir yaklaşım kullanır. PDF formatı değişiklik gösterebileceğinden, tüm vergi levhası formatları ile tam uyumlu olmayabilir. Farklı formatlarla karşılaşırsanız, lütfen bir issue açın veya pull request gönderin.
- Vergi Kimlik No (VKN): Bazı GİB PDF'lerinde VKN, barkod fontları ile veya barkod görseli içinde render edildiğinden metin olarak çıkarılamayabilir. Bu durumlarda VKN alanı boş kalabilir. VKN'yi çıkarmak için OCR kullanabilirsiniz (aşağıya bakın).
- Türkçe Karakter Sorunları: PDF'den metin çıkarma sırasında bazı Türkçe karakterler (Ö, Ü, İ, vb.) eksik veya hatalı çıkabilir. Bu, PDF kütüphanesinin sınırlamalarından kaynaklanmaktadır.
Bazı GİB PDF'lerinde VKN barkod görseli olarak render edildiğinden normal metin çıkarma ile elde edilemez. Bu durumda OCR (Optik Karakter Tanıma) kullanabilirsiniz.
OCR özelliği tamamen saf Go ile yazılmıştır ve hiçbir harici bağımlılık gerektirmez:
- ❌ ONNX Runtime gerekmez
- ❌ TensorFlow gerekmez
- ❌ Tesseract gerekmez
- ❌ Harici araç gerekmez
package main
import (
"fmt"
"log"
vergilevhasi "github.com/alparslanahmed/vergilevhasi-parser-go"
)
func main() {
// OCR parser oluştur (hiçbir parametre gerekmez!)
parser, err := vergilevhasi.NewOCRParser()
if err != nil {
log.Fatal(err)
}
defer parser.Close()
// Görsel dosyasından VKN çıkar
vkn, err := parser.ExtractVKNFromImage("vergi-levhasi.png")
if err != nil {
log.Printf("OCR hatası: %v", err), err)
} else {
fmt.Printf("Vergi Kimlik No: %s\n", vkn)
}
}# Normal build (OCR is included by default)
go build .
# Örneği çalıştır
go run example/main.go path/to/vergi-levhasi.pdf- PNG: Doğrudan işlenir
- JPG/JPEG: Doğrudan işlenir
- PDF: Otomatik olarak görsele çevrilir
- Görsel kalitesi: Yüksek çözünürlüklü, net görsel kullanın
- Kontrast: Siyah metin, beyaz arka plan tercih edilir
- Kırpma: Sadece VKN numarasını içeren bölgeyi kırpın
- Eğim: Görsel düz olmalı, eğik olmamalı
OCR modülü şu adımları izler:
- Gri tonlamaya çevirme: Renk bilgisi kaldırılır
- Adaptif binarizasyon: Görsel siyah-beyaza dönüştürülür
- Bağlı bileşen analizi: Her rakam ayrı ayrı tespit edilir
- Özellik çıkarma: Her rakam için geometrik özellikler hesaplanır
- Sınıflandırma: Özellikler kullanılarak rakam tanınır
- VKN deseni arama: 10 haneli numara bulunur
Not: Bu saf Go implementasyonu, MNIST tabanlı sinir ağı modellerine göre daha düşük doğruluğa sahip olabilir. En iyi sonuçlar için görsel kalitesine dikkat edin.
Not: OCR özelliği opsiyoneldir. Temel PDF metin çıkarma için OCR gerekli değildir.
This library can extract the following information from tax plate PDFs:
- Full Name (Adı Soyadı) - For individual taxpayers
- Trade Name (Ticaret Ünvanı) - For companies
- Business Address (İş Yeri Adresi)
- Tax Types (Vergi Türü) - Income Tax, VAT, etc.
- Activity Codes (Faaliyet Kodları) - NACE activity codes and descriptions
- Tax Office (Vergi Dairesi)
- Tax ID Number (Vergi Kimlik No - VKN)
- Turkish ID Number (TC Kimlik No) - For individuals
- Business Start Date (İşe Başlama Tarihi)
- Historical Tax Bases (Geçmiş Matrahlar)
go get github.com/alparslanahmed/vergilevhasi-parser-gopackage main
import (
"encoding/json"
"fmt"
"log"
vergilevhasi "github.com/alparslanahmed/vergilevhasi-parser-go"
)
func main() {
parser := vergilevhasi.NewParser()
result, err := parser.ParseFile("vergi-levhasi.pdf")
if err != nil {
log.Fatal(err)
}
jsonData, _ := json.MarshalIndent(result, "", " ")
fmt.Println(string(jsonData))
}Some GİB PDFs encode the VKN as a barcode image rather than text. For these cases, use the OCR parser:
parser, _ := vergilevhasi.NewOCRParser()
defer parser.Close()
vkn, err := parser.ExtractVKNFromImage("vergi-levhasi.png")
// or from PDF bytes:
// vkn, err := parser.ExtractVKNFromPDFBytes(pdfData)See the Türkçe section for detailed OCR documentation.