QR kodlu PDF’yi Java ile okuma

Giriş

Yüzlerce PDF faturası, nakliye etiketi veya envanter belgesinden barkod bilgilerini çıkarmanız gerektiği oldu mu? Sayfaları manuel olarak taramak zahmetli ve hataya açıktır. Otomatik bir belge işleme sistemi oluşturuyor ya da ürün orijinalliğini doğruluyor olsanız da, PDF’lerde barkodları verimli bir şekilde bulmak zorlayıcı olabilir.

Bu rehberde, GroupDocs.Signature API’sını kullanarak QR kodlu PDF belgelerini verimli bir şekilde nasıl okuyacağınızı öğreneceksiniz. Bu güçlü API, saatler sürebilecek manuel işi sadece birkaç satır kodla halleder. Tüm belgeleri tarayabilir, belirli barkod türlerini (örneğin QR kodları veya Code128) bulabilir ve verilerini otomatik olarak çıkarabilirsiniz.

Öğrenecekleriniz:

GroupDocs.Signature’ı Java için dakikalar içinde kurma
PDF belgelerinde barkod imzalarını arama
Kesin, hedeflenmiş sonuçlar için arama seçeneklerini yapılandırma
Farklı barkod türlerini işleme (QR kodları, EAN, Code128 vb.)
Yaygın sorunları giderme ve performansı optimize etme

Hadi başlayalım!

Hızlı Yanıtlar

GroupDocs.Signature PDF’lerden QR kodlarını okuyabilir mi? Evet, QR, Data Matrix, PDF417 ve birçok 1D barkodu algılar.
Üretim kullanımı için lisansa ihtiyacım var mı? Ticari bir lisans gereklidir; değerlendirme için ücretsiz deneme mevcuttur.
Hangi Java sürümü gerekiyor? Java 8+ (Java 11+ önerilir).
Aramayı belirli sayfalara nasıl sınırlayabilirim? BarcodeSearchOptions.setAllPages(false) kullanın ve setPageNumber() ayarlayın.
API toplu işleme için thread‑safe mi? Evet, her thread için ayrı bir Signature örneği oluşturduğunuzda.

PDF’lerde Barkod Aramanın Nedenleri

Teknik detaylara girmeden önce, bunun gerçek dünya uygulamalarında neden önemli olduğunu görelim:

Yaygın İş Senaryoları

Fatura İşleme – Tedarikçi faturalarından sipariş numaralarını veya takip kodlarını otomatik olarak çıkarır.
Envanter Yönetimi – Ürün kataloglarını tarar ve veri tabanı güncellemeleri için SKU barkodlarını çıkarır.
Nakliye & Lojistik – Nakliye manifestolarındaki paket takip kodlarını doğrular.
Belge Doğrulama – Gömülü güvenlik barkodlarını kontrol ederek imzalı belgeleri doğrular.
Sağlık Kayıtları – Medikal belgelerden hasta kimliklerini veya reçete kodlarını çıkarır.

GroupDocs.Signature API, ağır işleri halleder—görüntü işleme, barkod çözümleme algoritmaları veya PDF renderleme karmaşıklıklarıyla uğraşmanıza gerek yok. Hepsi yerleşik.

Önkoşullar

Bu öğreticiye başlamadan önce aşağıdakilerin hazır olduğundan emin olun:

Gerekli Kütüphaneler ve Bağımlılıklar

Java projenize GroupDocs.Signature kütüphanesini eklemeniz gerekir. İşte Maven veya Gradle kullanarak nasıl ekleyeceğiniz:

Maven:

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-signature</artifactId>
    <version>23.12</version>
</dependency>

Gradle:

implementation 'com.groupdocs:groupdocs-signature:23.12'

Not: En son sürümü her zaman GroupDocs.Signature for Java releases adresinde kontrol edin. En yeni sürümü kullanmak, hata düzeltmeleri ve yeni özellikler almanızı sağlar.

Ortam Kurulumu

JDK 8 veya üzeri – GroupDocs.Signature en az Java 8 gerektirir (daha iyi performans için Java 11+ önerilir).
IDE – Herhangi bir metin editörü çalışır, ancak IntelliJ IDEA veya Eclipse otomatik tamamlama ve hata ayıklama ile işinizi kolaylaştırır.
PDF Belgesi – Barkodlu bir test PDF’niz olsun (faturalar, nakliye etiketleri veya ürün katalogları iyi çalışır).

Bilgi Önkoşulları

Temel Java sözdizimi ve nesne‑yönelimli kavramlar
try‑catch bloklarıyla istisna yönetimi
IDE’nizde harici kütüphanelerle çalışma

Üçüncü taraf Java kütüphanelerine yeniyseniz endişelenmeyin—her şeyi adım adım göstereceğiz.

GroupDocs.Signature’ı Java için Kurma

GroupDocs.Signature ile başlamak sadece birkaç dakika sürer. İşte tam kurulum süreci:

Adım 1: Bağımlılığı Ekleyin

Kütüphaneyi eklemek için Maven veya Gradle kullanın (yukarıdaki koda bakın). Bağımlılığı ekledikten sonra, JAR dosyalarını indirmek için projenizi yenileyin.

Adım 2: Lisans Alımı

Ücretsiz Deneme – Test için mükemmel. GroupDocs releases adresinden indirin.
Geçici Lisans – Temporary License Page üzerinden 30 gün tam erişim alın.
Ticari Lisans – Üretim kullanımı için lisansı GroupDocs Purchase adresinden satın alın.

Pro İpucu: Kanıt‑konseptinizi oluşturmak için ücretsiz deneme ile başlayın, ardından API ihtiyaçlarınıza uygunsa yükseltin.

Adım 3: Temel Başlatma

İşte PDF’nizle çalışmak için bir Signature nesnesi oluşturma örneği:

import com.groupdocs.signature.Signature;

String filePath = "YOUR_DOCUMENT_DIRECTORY/sample_signed.pdf"; // Replace with your PDF path
Signature signature = new Signature(filePath);

Signature sınıfı ana giriş noktanızdır. PDF’yi belleğe yükler ve arama, doğrulama ve imza verilerini (barkodlar dahil) çıkarma yöntemleri sağlar.

Önemli: Dosya yolunun doğru ve PDF’nin mevcut olduğundan emin olun. Yaygın yeni başlayan hatası? Windows’ta ters eğik çizgileri kaçırmadan kullanmak (C:\\Documents\\file.pdf yerine C:\Documents\file.pdf).

Uygulama Kılavuzu

Şimdi eğlenceli kısma geçelim—PDF’nizde barkodları aramak için kodu yazalım.

PDF Belgesinde Barkod İmzalarını Arama

Bu bölüm, bir PDF’yi tarayıp tüm barkod imzalarını nasıl bulacağınızı gösterir. Her bölümü açıklamalarla birlikte sindirilebilir adımlara ayıracağız.

Adım 1: Signature Nesnesini Başlatma

PDF belgenizi şu şekilde yükleyin:

import com.groupdocs.signature.Signature;

String filePath = "YOUR_DOCUMENT_DIRECTORY/sample_signed.pdf"; // Replace with actual file path
Signature signature = new Signature(filePath);

Burada Ne Oluyor
Signature sınıfı PDF’nizi açar ve işleme hazır hale getirir. Bir metin editöründe dosya açmak gibi—belgeyi belleğe yüklüyorsunuz, böylece üzerinde çalışabilirsiniz.

Gerçek Dünya Notu
Kullanıcı yüklemelerinden PDF işliyorsanız, Signature nesnesini oluşturmadan önce dosya yolunu doğrulayın ve dosyanın varlığını kontrol edin. Bu, ileride belirsiz hataları önler.

Adım 2: BarcodeSearchOptions Oluşturma

Barkodları nasıl aramak istediğinizi yapılandırın:

import com.groupdocs.signature.options.search.BarcodeSearchOptions;

// Configure options for searching barcodes
BarcodeSearchOptions options = new BarcodeSearchOptions();
options.setAllPages(true); // Search every page in the document

Ana Yapılandırma Seçenekleri

setAllPages(true): Tüm sayfaları tarar. Sadece belirli sayfaları kontrol etmek istiyorsanız false yapın (setPageNumber() ile yapılandırın).
Neden Önemli: Barkodların her zaman 1. sayfada olduğu faturaları işliyorsanız, tüm sayfaları aramak kaynakları boşa harcar. Çok sayfalı nakliye manifestoları için setAllPages(true) gerekir.

Pro İpucu: Barkod tipine göre de filtreleyebilirsiniz (aşağıdaki Desteklenen Barkod Türleri bölümünde daha fazla). Aradığınız formatı bildiğinizde aramaları hızlandırır.

Adım 3: Aramayı Gerçekleştir ve Sonuçları İşle

Aramayı çalıştırın ve sonuçları işleyin:

import com.groupdocs.signature.domain.signatures.BarcodeSignature;
import java.util.List;

try {
    // Execute the barcode search
    List<BarcodeSignature> signatures = signature.search(BarcodeSignature.class, options);
    
    // Check if any barcodes were found
    if (signatures.isEmpty()) {
        System.out.println("No barcode signatures found in the document.");
    } else {
        System.out.println("Found " + signatures.size() + " barcode signature(s):\n");
        
        // Loop through each barcode and display details
        for (BarcodeSignature barcodeSignature : signatures) {
            System.out.println("----------------------------------------");
            System.out.println("Barcode Type: " + barcodeSignature.getEncodeType().getTypeName());
            System.out.println("Barcode Text: " + barcodeSignature.getText());
            System.out.println("Page Number: " + barcodeSignature.getPageNumber());
            System.out.println("Position: X=" + barcodeSignature.getLeft() + 
                             ", Y=" + barcodeSignature.getTop());
            System.out.println("Size: Width=" + barcodeSignature.getWidth() + 
                             ", Height=" + barcodeSignature.getHeight());
            System.out.println("----------------------------------------\n");
        }
    }
} catch (Exception e) {
    System.err.println("Error searching for barcodes: " + e.getMessage());
    e.printStackTrace();
} finally {
    // Always dispose of the signature object to free resources
    if (signature != null) {
        signature.dispose();
    }
}

Bu Kodda Ne Oluyor

Arama Çalıştırma – signature.search() PDF’yi tarar ve bir BarcodeSignature nesneleri listesi döndürür.
Boş Kontrol – Barkodların gerçekten bulunup bulunmadığını doğrular (null‑pointer istisnalarını önler).
Veri Çıkarma – Her barkod için şunları çıkarırız:
- Tür – Barkod formatı (QR Code, Code128, EAN13 vb.)
- Metin – Çözülmüş veri (sipariş numarası, takip kodu, SKU vb.)
- Konum – Sayfa numarası ve X/Y koordinatları
- Boyutlar – Genişlik ve yükseklik (doğrulama için faydalı)
Hata Yönetimi – try‑catch bir şeyler ters gittiğinde (bozuk PDF, eksik dosya vb.) çöküşleri önler.
Kaynak Temizliği – finally bloğu Signature nesnesinin düzgün bir şekilde serbest bırakılmasını sağlar, belleği boşaltır.

Gerçek Dünya Uygulaması
Diyelim ki nakliye etiketlerini işliyorsunuz. getText() değerini (takip numarası) çıkarıp veri tabanınıza kaydedersiniz. Sayfa numarası, toplu belgeleri işlerken hangi etiketin hangi gönderiye karşılık geldiğini gösterir.

Barkod Tipine Göre Filtreleme

Aradığınız barkod tipini belirterek aramaları hızlandırabilirsiniz:

import com.groupdocs.signature.domain.barcodes.BarcodeTypes;

BarcodeSearchOptions options = new BarcodeSearchOptions();
options.setEncodeType(BarcodeTypes.QR); // Only search for QR codes
options.setAllPages(true);

Ne Zaman Filtrelemeli
Faturalarınızın yalnızca Code128 barkodları içerdiğini biliyorsanız, tipine göre filtreleme büyük belgelerde işlem süresini %30‑50 azaltır.

Desteklenen Barkod Türleri

GroupDocs.Signature, çok çeşitli barkod formatlarını algılayabilir. İşte arayabileceğinizler:

1D Barkodlar (Doğrusal)

Code128 – Nakliye ve ambalajda yaygın
Code39 – Otomotiv ve savunma sektörlerinde kullanılır
EAN13/EAN8 – Perakende ürün barkodları (her ürünün üzerinde görürsünüz)
UPC‑A/UPC‑E – Kuzey Amerika perakende standardı
Interleaved2of5 – Depo ve dağıtım

2D Barkodlar (Matris)

QR Code – En popüler—URL’ler, Wi‑Fi şifreleri, ödeme bilgileri için kullanılır
Data Matrix – Küçük öğeler (elektronik bileşenler) için kompakt format
PDF417 – Hükümet kimlikleri, biniş kartları, sürücü belgeleri
Aztec Code – Ulaşım biletleri

Tipine Göre Filtreleme (yukarıdaki örnek) ihtiyacınız olan tam formata odaklanmanıza yardımcı olur.

Gerçek Dünya Kullanım Senaryoları

Geliştiricilerin barkod aramayı üretimde nasıl kullandıklarına bir göz atalım:

1. Otomatik Fatura İşleme

Senaryo – Muhasebe departmanı günde 500+ tedarikçi faturasını PDF olarak alır.
Çözüm – Her PDF’yi, fatura numaralarını içeren Code39 barkodları için tarar, bunları ERP sistemindeki satın alma siparişleriyle otomatik eşleştirir. Bu, manuel veri girişini ortadan kaldırır ve hataları azaltır.

// Pseudo-code workflow
for (PDF invoice : invoiceBatch) {
    List<BarcodeSignature> barcodes = searchBarcodes(invoice);
    String invoiceNumber = barcodes.get(0).getText();
    updateERPSystem(invoiceNumber, invoice);
}

2. Depo Envanter Güncellemeleri

Senaryo – Bir depo, ürün SKU’larını EAN13 barkodları olarak içeren PDF paket listeleriyle gönderileri alır.
Çözüm – Paket listelerindeki tüm barkodları çıkarır, envanter sayımlarını otomatik günceller ve tutarsızlıkları inceleme için işaretler.

3. Belge Doğrulama

Senaryo – Hukuki belgeler, özgünlük doğrulaması için kriptografik imzalar içeren QR kodları içerir.
Çözüm – İmzalı sözleşmelerde QR kodlarını arar, imza verilerini çözer ve güvenilir bir sertifika otoritesine karşı doğrular. Bu, belgelerin değiştirilmediğini garanti eder.

4. Sağlık Kayıtları Yönetimi

Senaryo – Hastanelerdeki hasta dosyaları, numune kimlikleri için Code128 barkodları içeren PDF laboratuvar raporları barındırır.
Çözüm – Numune kimliklerini otomatik çıkarır ve laboratuvar sonuçlarını hastane bilgi sistemindeki (HIS) hasta kayıtlarıyla bağlar.

Yaygın Sorunlar ve Çözümler

Karşılaşabileceğiniz sorunlar ve çözüm yolları:

Sorun 1: “Barkod Bulunamadı” (Oysa Var)

Olası Nedenler

Barkod görüntü kalitesi çok düşük (bulanık, pikselli taramalar)
PDF görüntü tabanlı ama barkod çok küçük
Yanlış barkod tipini arıyorsunuz

Çözümler

Görüntü Çözünürlüğünü Kontrol Edin – Barkodların güvenilir algılanması için en az 200 DPI gerekir. Belgeleri tarıyorsanız 300 DPI veya daha yüksek kullanın.
Tip Filtrelemesini Kaldırın – İlk olarak tüm barkod tiplerini aramayı deneyin (setEncodeType() ayarlamayın), ardından belgede ne olduğunu belirledikten sonra daraltın.
Barkod Kalitesini Doğrulayın – PDF’yi Adobe Acrobat’ta açıp yakınlaştırın. Barkod size bulanık geliyorsa API için de zor olacaktır.

Sorun 2: Büyük PDF’lerde `OutOfMemoryError`

Neden – Yüksek çözünürlüklü görüntüler içeren 500 sayfalık bir PDF’yi yüklemek büyük bellek tüketir.

Çözüm

Sayfaları Toplu İşleyin – setAllPages(true) yerine, 50 sayfa bir seferde işleyin:

for (int startPage = 1; startPage <= totalPages; startPage += 50) {
    BarcodeSearchOptions options = new BarcodeSearchOptions();
    options.setPageNumber(startPage);
    options.setPagesSetup(new PagesSetup());
    options.getPagesSetup().setLastPage(Math.min(startPage + 49, totalPages));
    
    List<BarcodeSignature> batchResults = signature.search(BarcodeSignature.class, options);
    // Process results...
}

JVM Yığın Boyutunu Artırın – Java komutunuza -Xmx4g ekleyerek 4 GB bellek ayırın (gereksinimlerinize göre ayarlayın).

Sorun 3: Çok Sayfalı Belgelerde Yavaş Performans

Neden – Tüm sayfaları sırayla aramak zaman alır, özellikle PDF417 gibi karmaşık barkodlarda.

Çözümler

Paralel İşleme – Barkodlar her zaman belirli sayfalarda (ör. faturaların 1. sayfası) ise sadece o sayfaları arayın.
Sonuçları Önbellekle – Aynı belgeyi birden fazla kez işliyorsanız, barkod verilerini önbelleğe alarak yeniden taramayı önleyin.
SSD Kullan – Büyük PDF’leri yüklerken I/O hızı önemlidir. SSD’ler, HDD’lere göre yükleme süresini %60‑70 azaltır.

Sorun 4: Yanlış Pozitifler (Rastgele Desenleri Barkod Olarak Algılamak)

Neden – Tablolar, ızgaralar veya çizgi desenleri barkod olarak yanlış algılanabilir.

Çözüm – Çözülmüş metin uzunluğunu ve formatını kontrol ederek sonuçları doğrulayın:

for (BarcodeSignature barcode : signatures) {
    String text = barcode.getText();
    
    // Example: Invoice numbers are always 10 digits
    if (text.matches("\\d{10}")) {
        // Valid invoice number
        processBarcode(barcode);
    } else {
        System.out.println("Skipping invalid barcode: " + text);
    }
}

Büyük Belgeler İçin Performans İpuçları

Binlerce PDF işliyorsunuz? İşte nasıl optimize edileceği:

1. Toplu İşleme Stratejisi

Dosyaları tek tek işlemek yerine, bir thread havuzu kullanarak birden fazla PDF’yi aynı anda yönetin:

ExecutorService executor = Executors.newFixedThreadPool(4); // 4 parallel threads

for (String pdfPath : pdfFiles) {
    executor.submit(() -> {
        try (Signature sig = new Signature(pdfPath)) {
            List<BarcodeSignature> results = sig.search(BarcodeSignature.class, options);
            // Process results...
        } catch (Exception e) {
            e.printStackTrace();
        }
    });
}

executor.shutdown();
executor.awaitTermination(1, TimeUnit.HOURS);

Performans Kazancı – 1 000 dosyanın işlenmesi, dört çekirdekli bir makinede ~2 saatten ~30 dakikaya düşer.

2. Arama Kapsamını Azaltma

İş mantığınız izin veriyorsa, arama alanını sınırlayın:

// Only search the top‑right corner where barcodes are typically placed
options.setRectangle(new Rectangle(400, 50, 150, 150)); // X, Y, Width, Height

Performans Kazancı – Barkod konumlarının tutarlı olduğu belgelerde %40‑60 daha hızlı.

3. Bellek Kullanımını İzleme

Uzun süren toplu işlemler için yığın kullanımını izleyin ve gerekirse açıkça çöp toplama önerin:

Runtime runtime = Runtime.getRuntime();
long usedMemory = runtime.totalMemory() - runtime.freeMemory();

if (usedMemory > (runtime.maxMemory() * 0.8)) {
    System.gc(); // Suggest garbage collection
}

En İyi Uygulamalar

Üretim hazır kod için bu yönergeleri izleyin:

1. Signature Nesnelerini Her Zaman Serbest Bırakın

Kodunuzu try‑with‑resources (Java 7+) içinde sararak kaynakları otomatik kapatın:

try (Signature signature = new Signature(filePath)) {
    // Your search code here...
} // Automatically disposed

2. Girdi Dosyalarını Doğrulayın

İşleme başlamadan önce dosyanın varlığını ve geçerli bir PDF olup olmadığını kontrol edin:

File pdfFile = new File(filePath);
if (!pdfFile.exists() || !pdfFile.canRead()) {
    throw new FileNotFoundException("PDF not found or not readable: " + filePath);
}

// Optional: Verify it's actually a PDF (check magic bytes)

3. Barkod Tespit Sonuçlarını Günlüğe Kaydedin

Hata ayıklama ve denetim için bulduklarınızı günlüğe kaydedin:

Logger logger = Logger.getLogger(BarcodeSearcher.class.getName());

for (BarcodeSignature barcode : signatures) {
    logger.info(String.format("Detected %s barcode '%s' on page %d at (%.2f, %.2f)",
        barcode.getEncodeType().getTypeName(),
        barcode.getText(),
        barcode.getPageNumber(),
        barcode.getLeft(),
        barcode.getTop()));
}

4. Farklı Barkod Formatlarını İşleyin

Farklı sektörler farklı standartlar kullanır. Kodunuzu esnek tutun:

switch (barcode.getEncodeType().getTypeName()) {
    case "QR":
        // QR codes might contain URLs or JSON data
        processQRCode(barcode.getText());
        break;
    case "Code128":
        // Code128 typically contains alphanumeric order/tracking numbers
        processTrackingNumber(barcode.getText());
        break;
    default:
        logger.warning("Unexpected barcode type: " + barcode.getEncodeType());
}

5. Gerçek Dünya Belgeleriyle Test Edin

Mükemmel örnek PDF’lerle sadece test yapmayın. Üretim ortamınızdaki gerçek belgeleri kullanın:

Kahve lekeli taranmış faturalar
Gürültülü faks gönderilen nakliye etiketleri
Düşük çözünürlüklü telefon fotoğraflarının PDF’ye dönüştürülmüş halleri

Bu, demolarda bulamayacağınız uç durumları ortaya çıkarır.

Sıkça Sorulan Sorular

S: QR kodlu PDF dosyalarını lisans olmadan okuyabilir miyim?
C: Ücretsiz deneme, değerlendirme amaçlı QR kodlu PDF dosyalarını okumanıza izin verir, ancak üretim dağıtımları için ticari lisans gereklidir.

S: API şifre korumalı PDF’leri destekliyor mu?
C: Evet. Signature nesnesi oluştururken şifreyi şu şekilde geçebilirsiniz: new Signature(filePath, "password").

S: Düşük çözünürlüklü taramalarda algılamayı nasıl iyileştirebilirim?
C: Kaynak taramanın DPI’sını artırın (minimum 200 DPI) ve yanlış pozitifleri azaltmak için barkod tipine göre filtrelemeyi düşünün.

S: Arama paralel işleme için thread‑safe mi?
C: Her thread kendi Signature örneğini kullanmalıdır. API, bu şekilde kullanıldığında thread‑safe’dir.

S: Bu öğreticide hangi GroupDocs.Signature sürümü test edildi?
C: Kod, GroupDocs.Signature 23.12 ile doğrulandı.

Sonuç

Java ve GroupDocs.Signature API’sını kullanarak QR kodlu PDF belgelerini nasıl okuyacağınızı yeni öğrendiniz. Şimdi neler kapsadık:

✅ Kurulum – GroupDocs.Signature’ı projenize ekleme ve lisans seçenekleri
✅ Uygulama – Barkod verilerini aramak, çıkarmak ve işlemek için tam kod
✅ Barkod Türleri – Hangi formatların desteklendiğini (1D ve 2D) anlama
✅ Gerçek Dünya Kullanım Senaryoları – Fatura işleme, envanter yönetimi, belge doğrulama, sağlık kayıtları
✅ Sorun Giderme – Bellek hataları ve yanlış pozitifler gibi yaygın sorunları çözme
✅ Performans – Büyük ölçekli belge işleme için aramaları optimize etme

GroupDocs.Signature API, PDF ayrıştırma ve barkod algılamanın karmaşıklığını halleder, böylece iş mantığınızı geliştirmeye odaklanabilirsiniz. İster fatura işleme, ister nakliye etiketlerini doğrulama, ister envanter verilerini çıkarma otomatikleştiriyor olun, artık sağlam bir çözümünüz var.

Son Güncelleme: 2026-03-01
Test Edilen: GroupDocs.Signature 23.12
Yazar: GroupDocs