QR Kod API Entegrasyon Rehberi: PHP ve JS Örnekleri

QR kod taramaları 2021-2023 arasında küresel bazda %433 artış gösterdi — QR Code Chimp istatistikleri, bu büyümenin ardında mobil ödemeden envanter takibine kadar geniş bir kullanım yelpazesi yatıyor. Geliştirici olarak senin görevin: bu talebi karşılayacak şekilde QR kod üretimini uygulamanın içine entegre etmek.

Bu rehberde, tryqrcode.com altyapısının sunduğu REST API üzerinden 18 QR tipi ve 34 barkod tipini nasıl programatik üreteceğini PHP ve JavaScript örnekleriyle göreceksin. İşletmen için hemen QR kod oluştur — ücretsiz, kayıtsız, saniyeler içinde.

QR Kod API Nedir? Geliştiricinin Bilmesi Gerekenler

QR Kod API, bir HTTP uç noktasına istek gönderip karşılığında QR kod veya barkod görseli almanı sağlayan bir arayüzdür. Temelinde, ISO/IEC 18004 standardının tanımladığı QR kod spesifikasyonu yatar. Bu standart, modül dizilimini, hata düzeltme seviyelerini (L, M, Q, H) ve veri kodlama modlarını belirler. Bir API, bu teknik detayları senin için soyutlar — sen yalnızca veriyi gönderirsin, API QR kodu üretir.

Geliştirici QR süreçlerinde iki temel API türü karşına çıkar: statik ve dinamik. Statik API'ler, veriyi doğrudan QR kodun içine gömer ve sonradan değiştirilemez. Dinamik API'ler ise kısa bir URL üretir ve hedef adresi sunucu tarafında güncelleyebilmeni sağlar. Kampanya yönetimi, A/B testi ve analitik ihtiyaçların varsa dinamik tipleri tercih et. Statik tipler ise one-time etiketler, menü kodları ve WiFi erişim noktaları için uygundur.

Bir QR Kod API'sinin kalitesini belirleyen üç metrik vardır: yanıt süresi (ms), çıktı formatı çeşitliliği (PNG/SVG/EPS/PDF) ve hata toleransı (ECC) kontrolü. Bu üçünü birlikte sunan API'ler üretim ortamında güvenle kullanılır.

2024 yılında güncellenen ISO/IEC 18004:2024 sürümü, sembolji ve hata düzeltme kurallarında iyileştirmeler getirdi. API seçerken bu standarda uyum, taranabilirlik garantisi anlamına gelir. Uyumlu olmayan API'ler, düşük ışıkta veya hasarlı baskıda tarama başarısızlığı yaşatır. Ayrıca API sürümlemesine dikkat et — sürüm 1 ile sürüm 2 arasında yanıt şeması değişebilir ve kodun kırılır.

Kimlik doğrulama tarafında çoğu API, Bearer token veya API anahtarı kullanır. Anahtarını HTTPS üzerinden gönder, asla plain-text olarak istemci tarafında expose etme. Git deposuna anahtar commit etme; environment variable olarak tut ve CI/CD pipeline'ında inject et.

REST API ile QR Kod Oluşturma Nasıl Çalışır?

REST API QR entegrasyonunda temel akış şu şekildedir: sen bir HTTP POST isteği gönderirsin, API JSON formatında yanıt döner ve bu yanıtın içinde base64 kodlu görsel veya doğrudan indirme URL'i bulunur. Mimarisi akıcı ama dikkat etmen gereken noktalar var: kimlik doğrulama, istek limitleri ve çıktı formatı seçimi.

Bir QR oluşturucu API'sine gönderdiğin tipik istek gövdesi şu alanları içerir: tip (url, text, vcard, wifi vb.), veri (kodlanacak içerik), boyut (piksel veya modül sayısı), ECC seviyesi (L/M/Q/H) ve çıktı formatı (PNG, SVG, EPS, PDF). Her alanın API dokümantasyonunda belirtilen doğrulama kuralları vardır — örneğin URL tipinde veri alanı geçerli bir URL olmalıdır, WiFi tipinde ise SSID ve şifre parametreleri zorunludur.

Bu 3 Adımlı QR API Yayımlama Akışı, küçük projelerden kurumsal ölçeğe kadar tüm senaryolarda geçerlidir. Fark, adım sayısında değil; adım başına yapılan doğrulama ve hata yönetimi derinliğindedir. Kampanya bazlı çalışıyorsan, toplu QR kod oluşturma yöntemiyle Excel'den binlerce kodu tek seferde işleyebilirsin.

API yanıtı tipik olarak şu JSON şemasını izler: status (başarı/başarısızlık), qr_code (base64 görsel veya SVG string), mime_type (çıktı türü), expires_at (dinamik tiplerde geçerlilik süresi). Yanıtı işlemeden önce status alanını kontrol et — success değilse error nesnesini logla ve kullanıcıya anlamlı mesaj göster.

PHP ile API Entegrasyon QR: Adım Adım Uygulama

API Entegrasyon QR sürecinde PHP, sunucu tarafında QR kod üretmek için en sık tercih edilen dildir. cURL kütüphanesi ile HTTP isteği gönderirsin, JSON yanıtını çözümler ve görseli dosya sistemine kaydedersin. İşte çalışan bir örnek:

<?php
// QR Kod API istegi
$endpoint = "https://api.tryqrcode.com/v1/generate";
$payload = [
    "type"       => "url",
    "data"       => "https://example.com/campaign-2025",
    "size"       => "512x512",
    "ecc"        => "H",
    "format"     => "svg"
];

$ch = curl_init($endpoint);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));ncurl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Accept: application/json"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $result = json_decode($response, true);
    $svgContent = $result["qr_code"];
    file_put_contents("campaign-qr.svg", $svgContent);
    echo "QR kod kaydedildi: campaign-qr.svg";
} else {
    $error = json_decode($response, true);
    error_log("QR API hatasi: " . $error["message"]);
    echo "Hata: HTTP $httpCode";
}
?>

Bu örnekte üç kritik nokta var. Birincisi, ECC seviyesini "H" (High) seçtik — bu, QR kodun %30 hasar tolere etmesini sağlar ve baskı kalitesi düşük ortamlarda bile taramayı garanti eder. İkincisi, SVG formatı seçtik — vektörel çıktı her ölçekte net görünür. Üçüncüsü, cURL timeout değerini 10 saniye olarak belirledik — bu, API yanıt vermezse betiğinin sonsuza kadar beklemesini engeller.

Toplu üretim gerekiyorsa, yukarıdaki kodu bir döngüye alıp veritabanından veya CSV'den veri çekebilirsin. Her istek arasında 100-200ms bekleme eklemek, rate limit'e takılmanı önler. Daha verimli bir yol olarak, toplu QR oluşturma aracıyla Excel dosyanı yükleyip yüzlerce kodu tek seferde işleyebilirsin. Hata yönetimi için bir retry mekanizması ekle: ilk istek başarısız olursa 3 saniye bekleyip tekrar dene, üç denemeden sonra fallback loglama yap.

JavaScript ile Geliştirici QR Üretimi

Geliştirici QR akışında JavaScript, istemci tarafında anlık QR kod üretmek için idealdir. Bir form gönderildiğinde API'ye istek atıp sonucu doğrudan sayfada gösterebilirsin. İşte fetch API kullanan bir örnek:

async function generateQRCode(payload) {
  const endpoint = "https://api.tryqrcode.com/v1/generate";

  try {
    const response = await fetch(endpoint, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Accept": "application/json"
      },
      body: JSON.stringify(payload)
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }

    const result = await response.json();
    return result.qr_code; // base64 veya SVG string
  } catch (error) {
    console.error("QR API hatasi:", error);
    return null;
  }
}

// Kullanim
const qr = await generateQRCode({
  type: "url",
  data: "https://example.com/product/123",
  size: "512x512",
  ecc: "M",
  format: "svg"
});

if (qr) {
  document.getElementById("qr-container").innerHTML = qr;
}

JavaScript tarafında dikkat etmen gereken en önemli nokta, CORS yapılandırmasıdır. API sağlayıcının, senin domain'inden gelen isteklere izin verdiğini doğrula. Ayrıca, hata yakalama bloğunu (catch) boş bırakma — kullanıcıya görsel bir hata mesajı göster. İstemci tarafında üretim yaparken API anahtarını expose etmemek için bir backend proxy üzerinden kimlik doğrulama yap.

İstemci tarafında QR Kod API çağrısı yaparken, API anahtarını doğrudan JavaScript koduna gomme. Bir backend proxy uzerinden kimlik dogrulama yap; anahtari tarayicida expose etme.

Mobil uygulaman varsa, App Store QR kod türüyle kullanıcıyı doğrudan indirme sayfasına yönlendirebilirsin. JavaScript ile bu QR tipini de aynı API çağrısıyla üretirsin — yalnızca type alanını app olarak değiştirirsin ve data alanına App Store ve Google Play URL'lerini girersin. API, cihaz türünü algılayıp doğru mağazaya yönlendiren dinamik bir kod üretir.

Desteklenen 18 QR Tipi ve 34 Barkod Tipi Hangileridir?

Modern bir QR Kod API, yalnızca URL kodlamaz. tryqrcode.com altyapısı 18 farklı QR tipi ve 34 barkod tipini destekler. Her tip farklı bir kullanım senaryosuna hitap eder ve doğru tipi seçmek, kullanıcı deneyimini doğrudan etkiler. Tip seçimi yaparken şunu sor: kullanıcı bu kodu taradığında hangi eylemi gerçekleştirmeli?

Bu zengin tip çeşitliliği, tek bir barkod oluşturucu entegrasyonuyla hem QR hem barkod ihtiyaçlarını karşılamanı sağlar. Ayrı ayrı API'ler kullanmak yerine tek uç noktadan tüm tipleri üretmek, bakım maliyetini düşürür ve kod tabanını düzenli tutar. Barkod mu QR kod mu seçeceğin sorusunun cevabı kullanım alanında gizli: barkodlar lineer tarama gerektirir ve daha az veri taşır; QR kodlar 2D tarama ile çok daha fazla veri paketler.

Dinamik QR tipleri (URL, App Store, sosyal medya) hedef adresi sonradan değiştirmene olanak tanır. Bu özellik, kampanya yönetiminde geri dönüşüm maliyetlerini sıfıra indirir — basılmış kodu değiştirmeden yalnızca sunucu tarafındaki yönlendirmeyi güncellersin. Statik tipler (vCard, WiFi, takvim) ise veriyi kodun içine gömer ve değiştirilemez; ancak internet bağlantısı gerektirmez.

API Entegrasyonunda Yaygın Hatalar ve Çözümleri Nelerdir?

QR Kod API entegrasyonunda en sık karşılaşılan hatalar, genellikle temel konfigürasyon eksikliklerinden kaynaklanır. Doğru ECC seviyesi seçmemek, yanlış veri tipi göndermek ve rate limit'i görmezden gelmek başlıca sorunlardır. Bu bölümde her birini pratik çözümleriyle ele alıyoruz.

Pratikte, QR kodunu ürün ambalajına ekleyen işletmeler düzenli olarak şunu bildiriyor: raster yerine SVG çıktı kullandıklarında baskı sonrası tarama başarısı belirgin şekilde artıyor. Bunun nedeni, vektörel formatın DPI bağımsız olması — yazıcı çözünürlüğü ne olursa olsun modüller keskin kenarlarla basılır. Raster PNG ise düşük DPI'da pikselleşir ve tarayıcı modülleri ayırt edemez.

Diğer yaygın hatalar şunlar: API yanıtını kontrol etmeden görseli kaydetmek (bozuk dosya oluşur), UTF-8 olmayan karakter göndermek (özellikle vCard ve WiFi tiplerinde Türkçe karakter sorunu yaratır) ve timeout değeri belirtmemek (API yavaş yanıt verdiğinde betiği kilitler). Her birini, istek öncesi veri doğrulama ve istek sonrası yanıt kontrolü ile çözebilirsin.

Bir API entegrasyonunda başarısızlığın en yaygın nedeni, hata toleransı seviyesinin (ECC) göz ardı edilmesidir; düşük ECC seviyesiyle logo eklenmiş QR kodlar taranamaz hale gelir. ECC-H seviyesi, %30 hasar toleransı sağlar ve baskı kalitesi düşük ortamlarda dahi güvenli tarama sunar.

Timeout yönetimi için şunu uygula: istek gönderirken bir deadline belirle (örn. 10 saniye), süre aşılında gracefully degrade ol — yani önbellekteki son başarılı sonucu göster veya yerel bir yedek QR kod üret. Veri doğrulama tarafında ise regex ile URL formatını, telefon numarası alan kodunu ve e-posta adresini istek göndermeden önce doğrula. Bu, gereksiz API çağrılarını ve hata döngülerini önler.

Vektörel Çıktı, Ölçeklendirme ve Performans Stratejileri

QR kod API entegrasyonunu canlıya aldıktan sonra iki soru gündeme gelir: çıktı kalitesi ve performans. Vektörel çıktı (SVG, EPS), baskı kalitesi açısından raster formattan (PNG, JPG) üstündür çünkü çözünürlük bağımsızdır. Vektörel QR kod SVG ve EPS formatları, ambalaj baskısında, billboard ilanlarında ve büyük formatlı pvc baskıda modül netliğini korur.

Vektörel çıktı (SVG/EPS) sağlayan API'ler, baskı çözünürlüğünden bağımsız olarak her boyutta net tarama sağlar. Raster format ise pikselleşme riski taşır ve yüksek DPI gerektiren baskı projelerinde kullanışsızdır.

Performans tarafında, QR-Verse 2026 projeksiyonları küresel QR pazarının 2026'da 3.7 milyar dolara ulaşacağını öngörüyor. Bu büyüme, API talebinin de artacağı anlamına gelir. Yüksek trafikli bir platformda çalışıyorsan, her QR kodu istek başına üretmek yerine önbelleğe almayı düşünebilirsin. Aynı içeriğe sahip QR kodları bir kez üretip CDN'de saklamak, API çağrı sayısını %60-80 azaltır.

Ölçeklendirme, yalnızca hız değil; güvenilirlik de demektir. QR Code Chimp verilerine göre QR kod etkileşimleri 2021-2023 arasında %433 arttı. Bu trend devam ederken, API'nin kesintisiz çalışması işin sürekliliği için kritik hale geliyor. Retry mekanizması, exponential backoff (her denemede bekleme süresini ikiye katla) ve graceful degradation stratejilerini entegrasyonuna dahil et. API yanıt vermezse yerel bir QR kütüphanesiyle fallback üretim yapabilirsin.

Sıkça Sorulan Sorular

QR Kod API kullanmak için API anahtarı gerekir mi?

tryqrcode.com'un tarayıcı tabanlı arayüzünde kayıt olmadan QR kod üretebilirsin. API üzerinden programatik erişimde ise sağlayıcının politikasına bağlı olarak API anahtarı gerekebilir. Anahtar, kimlik doğrulama ve rate limit takibi için kullanılır.

Hangi QR tipleri dinamik olarak yeniden yönlendirilebilir?

URL, App Store ve sosyal medya tipleri dinamik olarak çalışır — hedef adresi sonradan değiştirebilirsin. vCard, WiFi ve takvim tipleri ise statiktir; veri QR kodun içine gömülür ve sonradan değiştirilemez.

API rate limit'i nasıl yönetilir?

Rate limit, bir zaman diliminde yapabileceğin maksimum istek sayısıdır. Limit aşımına düşmemek için istekler arası bekleme ekle, önbellek kullan ve gereksiz tekrar üretimden kaçın. Toplu üretimde asenkron kuyruk mimarisi, limiti aşmadan yüksek hacimli işlem yapmanı sağlar.

Vektörel QR kod mu yoksa raster QR kod mu tercih edilmeli?

Baskı için vektörel (SVG/EPS), dijital gösterim için raster (PNG) tercih et. Vektörel format çözünürlük bağımsızdır ve her ölçekte net tarama sağlar. Raster ise web ve mobil arayüzlerde hızlı render için uygundur.