QR Kod API Rehberi: Kodları Programlı Olarak Oluşturma ve Yönetme (2026)

Çoğu QR kod kullanım durumu (menüler, kartvizitler veya pazarlama için birkaç düzine kod) QR oluşturucu platformlarının kontrol paneli arayüzleriyle kolayca karşılanır. Tıkla, URL yapıştır, resmi indir, tamam.

QR API'ler, müşteri başına kodlar, sipariş başına kodlar, başka bir sistemle entegrasyon, bir veritabanına bağlı toplu oluşturma gibi insanın bir kontrol paneli üzerinden yönetebileceğinin ötesinde ölçeklenme gerektiğinde gerçek anlamını bulur. İyi yönetildiğinde, bir QR API size kodları altyapı olarak ele alma imkanı sunar: kendi yazılımınızla oluşturulur, yönetilir ve takip edilir.

Bu rehber, QR API'lerin mühendislik çabasının ne zaman değerli olduğunu, genellikle destekledikleri işlemleri, çalışan kod örneklerini ve sağlayıcı API'lerinin birbirine karşı nasıl değerlendirilmesi gerektiğini ele alır.

30 saniyelik özet

QR kod API'leri şu durumlarda kullanmaya değer:

1. Müşteri başına veya sipariş başına kodlara ihtiyacınız varsa programlı olarak oluşturulan (etkinlik biletleri, sadakat kartları, sahteciliğe karşı seri numaralar).
2. QR oluşturmayı daha büyük bir sisteme entegre ediyorsanız (CRM'iniz, envanter yönetiminiz, e-ticaret platformunuz).
3. Kontrol paneliyle başa çıkmanın zor olduğu bir hacim oluşturuyorsanız: tipik olarak ayda birkaç düzineden fazla kod.
4. Hedefleri programlı olarak güncellemeniz gerekiyorsa envanter, zaman veya kullanıcı davranışına bağlı olarak.

API’ler gereksizdir, şöyle ki:

1. Pazarlama için birkaç kod gerekiyorsa. Kontrol paneli daha hızlıdır.
2. Kodlar değişmeyecekse ve hacim küçükse. Statik oluşturma araçları yeterlidir.
3. Entegrasyon, bakım ve izleme için mühendislik kapasiteniz yoksa bir API entegrasyonu için.

Yaygın QR API işlemleri

Çoğu QR API beş veya altı temel işlem sunar. Sağlayıcılar arasındaki uç nokta isimleri farklılık gösterse de işlem yapısı benzerdir.

1. Yeni bir QR kodu oluşturun.

Bir hedef URL’yi (ve isteğe bağlı meta veriyi) sağlayıcıya POST edin; kod kimliği ve indirilebilir QR resim URL'si alın.

2. Mevcut dinamik bir kodun hedefini düzenleyin.

Bir kodun uç noktasına PUT veya PATCH isteği göndererek yönlendirme adresini değiştirin. Envantere bağlı hedefler, günün saatine göre yönlendirme veya A/B testi için faydalıdır.

3. Bir kodun analizlerini alın.

Bir kodun tarama sayıları, zaman serileri, coğrafi dağılım ve cihaz dağılımını GET ile alın. Kontrol paneli entegrasyonu veya raporlama için yararlıdır.

4. Mevcut kodları listeleyin veya arayın.

Hesabınızdaki kodların sayfalı listesini GET ile alın; tarih, etiket veya hedefe göre filtreleyebilirsiniz. Yönetim arayüzleri için kullanışlıdır.

5. Bir kodu silin veya arşivleyin.

DELETE kodu tamamen kaldırır (kodlar çözülmeyi durdurur). Bazı sağlayıcılar, silmeden duraklatma işlevi gören "arşivle" özelliği sunar.

6. Toplu işlemler.

Birçok sağlayıcı toplu uç noktalar sunar: aynı anda N kod oluşturma, filtreye uyan tüm kodları güncelleme, birçok kod için analizleri dışa aktarma. Bunların kendi hız sınırlamaları ve fiyatlandırma etkileri vardır.

Kimlik doğrulama yöntemleri

QR API’leri genellikle üç kimlik doğrulama modelinden birini kullanır:

Başlıkta API anahtarı. En basit yöntem: her isteğe Authorization Bearer token içeren bir başlık eklemek. Uygulaması kolaydır; ancak anahtar döndürme ve iptal hijyeni gerekir.

OAuth 2.0. Daha karmaşıktır ancak çok kullanıcılı veya ortak entegrasyonlar için daha uygundur. Token tabanlı, kapsam kontrollü ve zamana bağlıdır.

HMAC ile imzalı istekler. Bazı sağlayıcılar yüksek güvenlik gereken durumlarda kullanır. İstemci, yeniden oynatma saldırılarını önlemek için her isteği gizli anahtar ve zaman damgasıyla imzalar.

Çoğu kullanım durumu için API anahtarı modeliyle çalışacaksınız. Anahtarı ortam değişkenlerinde saklayın, kaynak kontrolüne asla kaydetmeyin ve periyodik olarak yenileyin.

Kod örnekleri

Aşağıdaki örnekler genel bir QR API modelini kullanır. Taban URL’yi sağlayıcınızın gerçek uç noktasıyla değiştirin ve alan adlarını uyacak şekilde ayarlayın.

JavaScript (Node.js) ile kod oluşturma:

Tipik bir Node fetch çağrısı, hedef URL, etiket ve kod türü içeren JSON’u POST eder. Yanıtta saklayabileceğiniz ve referans verebileceğiniz code_id ve image_url bulunur.

Python ile kod oluşturma:

Python’da karşılığı, requests kütüphanesi ile aynı JSON yükünü POST eder. API anahtarı için ortam değişkenlerini kullanın ve 2xx dışı yanıtlarda hata verdirin.

Bir kodun hedefini güncelleme:

Koda PATCH isteği ile yeni hedef URL göndererek, basılı tüm mevcut kopyaların yönlendirilme yerini değiştirirsiniz.

Tarama analizlerini alma:

Kodu analiz uç noktasına yapılan GET isteği, isteğe bağlı tarih aralığı parametreleriyle, sayım ve döküm bilgilerini döner.

Bunlar örnek desenlerdir. Gerçek uç noktalar ve istek/yanıt formatları için her zaman özel sağlayıcının dokümantasyonuna bakın.

Yaygın API kullanım örnekleri

Gerçek dünya QR API entegrasyonlarında sıkça karşılaşılan desenler:

Sipariş başına veya müşteri başına kodlar.

E-ticaret: Her sipariş, o siparişe özel ve müşterinin belirli açılış sayfasına (tekrar sipariş, yorum talebi, gönderi takibi vb.) bağlanan benzersiz bir QR koduyla gönderilir. Kod, ödeme sırasında API tarafından oluşturulur ve paket şablonuna gömülür.

Bilet başına veya katılımcı başına etkinlik kodları.

Etkinlik biletlemesi: Her bilet, kapıda doğrulanan benzersiz bir QR kodu alır. Aynı API daha sonra iade/transfer kodları veya etkinlik sonrası takip kodları da oluşturabilir.

Ürün başına izlenebilirlik kodları.

Üretim ve hızlı tüketim malları: Değişken verili baskı ile her birime, o birimin parti, menşei ve izlenebilirlik verileriyle bağlantılı eşsiz bir kod konur. Bazı düzenlemeler, örneğin FSMA 204 ve FDA UDI bunu zorunlu kılar.

Konum veya bölge başına kodlar.

Birden fazla şubesi olan işletmeler: API her konum için bir kod oluşturur ve hedef o konuma ait sayfa veya giriş akışı olarak ayarlanır. Konumlar açıldığında, kapandığında veya detaylar değiştiğinde güncellemeler API aracılığıyla yayılır.

Stok tabanlı hedefler.

Perakende: Raf etiketlerindeki QR kodları ürünün listeleme sayfasına yönlendirir, ancak ürün satışa çıktığında, stok tükendiğinde veya yeni bir varyantla değiştirildiğinde hedef değişir. API, stok olaylarına yanıt olarak hedefleri günceller.

Sadakat ve ödül kodları.

Konaklama ve perakende: Her müşterinin sadakat kartı benzersiz bir QR koda sahiptir. Kod, o müşterinin sadakat profiline bağlanır. API, kayıt sırasında kod verir ve zaman içinde yönlendirme mantığını günceller.

Sahtecilik önleyici kodlar.

Premium ürünler: Her birim benzersiz bir QR alır. API, tarama desenlerini izler: "aynı" kodun farklı konumlardan birden fazla kez taranması (gerçek benzersiz bir kod için mümkün olmayan) olası sahteciliği işaret eder.

İstek sınırları ve toplu işlemler

QR API’lerinin istek sınırları vardır: saniye, dakika veya saat başına yapabileceğiniz istek sayısına sınırlamalar.

Tipik istek sınırları:

• Ücretsiz / hobi kullanımı katmanları: Dakikada 60 istek.
• Orta seviye ücretli: Dakikada 1.000-10.000 istek.
• Kurumsal: özel (genellikle dakikada 100.000 üzeri istek veya adil kullanım politikası ile sınırsız).

Toplu oluşturma için iki seçeneğiniz vardır:

1. İstek sınırı yönetimi ile ardışık oluşturma. Bir döngü içinde bireysel API çağrıları yapın, 429 (Çok Fazla İstek) yanıtlarını yakalayın ve bekleyin. Basit, birkaç bin hacme kadar her işlem için uygundur.
2. Toplu uç noktalar. Birçok sağlayıcı, tek istekte kod dizilerini kabul eden uç noktalar sunar. Yüksek hacimlerde çok daha verimlidir.

Çok yüksek hacimler (milyonlarca kod) için bazı sağlayıcılar asenkron toplu oluşturma sunar: bir iş gönderin, tamamlanmayı kontrol edin, sonuçların CSV’sini indirin. Kurumsal planlarda her zaman; bazen alt seviyelerde sunulur.

Webhooklar ve sorgulama

QR API’leri genellikle tarama olaylarını almak için iki yöntem destekler:

Sorgulama. Uygulamanız düzenli olarak analitik uç noktasını çağırarak yeni taramalar var mı kontrol eder. Uygulaması basittir, ancak gerçek zamanlı değildir ve yeni etkinlik olmadığında gereksiz istek yapılır.

Webhooklar. Sağlayıcı, her taramada (veya yapılandırılabilir bir takvime göre) sunucunuzdaki bir URL’ye POST yapar. Gerçek zamanlı, verimli ancak sunucunuzun herkese açık bir uç noktası açması ve gelen istekleri doğrulaması gerekir.

Gerçek zamanlı kullanım senaryoları için (etkinlik bileti, dolandırıcılık tespiti, anlık müşteri etkileşimi tetikleyicileri) webhooklar gereklidir. Periyodik raporlama için sorgulama uygundur.

Sağlayıcılar arasında QR API karşılaştırması

Çoğu büyük QR sağlayıcısı API sunar, ancak olgunluk seviyesi oldukça değişkendir.

Karşılaştırılacak noktalar:

• Dokümantasyon kalitesi. İyi dokümante edilmiş bir API ve örnekler, mühendislik süresinden tasarruf sağlar. Belgeleri okuyup en basit durumu uygulamayı hayal ederek test edin.
• İstek sınırları. Sağlayıcının sınırlarını beklenen hacminizle eşleştirin.
• Fiyatlandırma modeli. Kod başına, isteğe bağlı, kullanım hakkı içeren aylık abonelik veya bunların bir kombinasyonu.
• Webhook desteği. Gerçek zamanlı kullanım senaryoları için gereklidir.
• Toplu uç nokta kullanılabilirliği. Yüksek hacimli entegrasyonlarda büyük zaman tasarrufu sağlar.
• SDK bulunabilirliği. Dilinizde resmi SDK'lar entegrasyon süresini önemli ölçüde kısaltır.
• Kodların ömür politikası. Panodan kullanımda olduğu gibi, ödeme yapmayı bıraktığınızda kodlarınız ne olur?

Sağlayıcı notları (yayın tarihi itibarıyla):

• Uniqode ve qr-code-generator.com (Bitly Inc.) geniş özellik kapsamına sahip olgun, kurumsal sınıf API'lara sahiptir. Daha yüksek fiyatlandırma bunu yansıtır.
• QR Tiger uygun fiyatlarla sağlam bir API sunar.
• QR Cake ücretli planlarda API erişimi sağlar; dokümantasyon ve SDK bulunabilirliği geliştirilmektedir.
• Bitly'nin QR API'si zaten Bitly kısa bağlantılarına entegreyseniz gerçekten güçlüdür.

Taahhütte bulunmadan önce mevcut dokümanları ve fiyatları karşılaştırın. API'lar değişebilir. En İyi QR Kod Oluşturucular gönderisi daha geniş sağlayıcı yelpazesini kapsar.

Güvenlik hususları

QR kod API'larının işaret edilmesi gereken birkaç özel güvenlik tuzağı vardır:

1. API anahtarı saklama.

Anahtarları kaynak kontrolüne asla dahil etmeyin. Ortam değişkenleri, gizli yönetim araçları (AWS Secrets Manager, HashiCorp Vault, Doppler) veya platformunuzun yerleşik gizli alanlarını kullanın. Çalışanlar ayrıldığında veya anahtarlar yanlışlıkla açığa çıktığında anahtarları değiştirin.

2. Hedef URL doğrulaması.

Uygulama kullanıcılarınız QR kodları için hedef URL belirleyebiliyorsa (örneğin, müşterilerin kendi kodlarını oluşturduğu çok kiracılı bir uygulama), URL'leri doğrulayın. Rastgele hedeflere izin vermeyerek açık yönlendirme saldırılarını engelleyin.

3. Webhook imza doğrulaması.

Webhook kullanıyorsanız, sağlayıcı genellikle yükü gizli bir anahtarla imzalar. Her gelen webhook'ta imzayı doğrulayın; bunu yapmazsanız bir saldırgan tarama etkinliklerini taklit edebilir.

4. Kendi tarafınızda hız sınırı uygulaması.

QR kod oluşturmayı son kullanıcılara açıyorsanız (örneğin, müşteri odaklı bir uygulama), kendi hız sınırınızı uygulayın. Yoksa kötü niyetli bir kişi sağlayıcı hız sınır kotanızı tüketebilir.

5. Kod hedef denetimi.

Uzun ömürlü kodlar (ambalajlarda, kartvizitlerde) için her hedef değişikliğini kaydedin. Eğer bir saldırgan sağlayıcı hesabınızı ele geçirip hedefleri oltalama URL'lerine değiştirirse, denetim kaydı sizin adli siciliniz olur.

Yaygın QR API hataları

Hata 1: QR oluşturmayı tek seferlik bir kurulum olarak görmek. Kodların yönetilmesi gerekir: güncellemeler, arşivleme, izleme. Sadece ilk oluşturma için değil, sürekli işletme için tasarlayın.

Hata 2: Oran limitlerini test etmemek. Bir Kara Cuma kampanyası sırasında sağlayıcınızın oran limitine takılmak, bu sorunu fark etmek için kötü bir zamandır.

Hata 3: QR kod görüntüsünü saklayıp kod kimliğini saklamamak. Her zaman sağlayıcının kod kimliğini saklayın (böylece kodu sonra güncelleyebilir veya silebilirsiniz). Görüntü sadece önbelleğe alınmış bir render'dır.

Hata 4: Yeniden deneme mantığının olmaması. API'ler zaman zaman başarısız olur. Üssel geri çekilmeyle tekrar denemeler olmadan, geçici hatalar kalıcı iş hatalarına dönüşür.

Hata 5: Webhook imza doğrulamayı göz ardı etmek. İmza doğrulaması olmayan webhook uç noktası, herkesin taklit edebileceği herkese açık bir URL'dir.

Hata 6: Sağlayıcının alan adını kodlarınıza sabitlemek. Sağlayıcının altyapısına işaret eden kendi alt alan adınızı kullanın, böylece bastığınız kodları değiştirmeden sağlayıcı değiştirebilirsiniz.

Hata 7: Staging URL'lerine işaret eden kodlar oluşturmak. Ambalajlarda basılan veya müşterilere gönderilen kodların staging URL'lerine işaret etmesi gerçek bir risk oluşturur. Hedefleri doğrulayın.

Hata 8: URL değiştiğinde hedefleri güncellemeyi unutmak. Site yeniden tasarımı sırasında URL yapınız değişirse, her dinamik kodun hedefi güncellenmelidir. Bu kolayca gözden kaçabilir.

Sıkça sorulan sorular

Dinamik QR kodları kullanmak için API gerekli mi? Hayır. Çoğu dinamik QR sağlayıcısının API entegrasyonu olmadan çoğu kullanım durumunu yöneten panelleri vardır. API'lar büyük ölçekli programatik oluşturma içindir.

Sağlayıcı API'si olmadan QR kodları oluşturabilir miyim? Evet, statik kodlar için. qrcode (Python, JavaScript) ve pyqrcode gibi kütüphaneler statik QR görüntülerini yerel olarak, dış bir servis kullanmadan oluşturur. Dinamik kodlar için (düzenlenebilir hedefler ve analizlerle birlikte) sağlayıcı gereklidir.

QR kod API'sini kullanmak ücretsiz mi? Bazı sağlayıcılar sınırlı istek hacmiyle ücretsiz katmanlar sunar. Çoğu ücretli plan API erişimi içerir. Hem istek başına hem de kod başına fiyatları karşılaştırın.

Bir uygulamada birden fazla QR API sağlayıcı kullanabilir miyim? Teknik olarak evet. Her kod, onu oluşturan sağlayıcıya bağlıdır. Sağlayıcıları karıştırmak yönetimi zorlaştırır; genellikle birinde standartlaşmak daha iyidir.

Bir QR API sağlayıcısından diğerine nasıl geçiş yaparım? Yeni sağlayıcıda yeni kodlar oluşturursunuz. Eski kodlar, silinene kadar ya da eski abonelik bitince yönlendirmeyi durdurana kadar eski sağlayıcının sunucularına işaret etmeye devam eder. Özel bir alan adı kullandıysanız, DNS'i yeni sağlayıcının altyapısına yönlendirerek kodları yeniden oluşturmak zorunda kalmazsınız; bu geçiş dostu yoldur.

API ile milyonlarca QR kodu oluşturabilir miyim? Evet, uygun oran limitleri ve toplu uç noktaları içeren kurumsal planlarda. Taahhütte bulunmadan önce seçilen planın bunu desteklediğini doğrulayın.

QR API'leri webhook'ları destekler mi? Çoğu kurumsal ve birçok orta seviye plan destekler. Ücretsiz ve giriş seviyesi planların çoğu desteklemez. Üretim kullanım durumları için webhook'a güvenmeden önce kontrol edin.

Bir QR API'yi entegre etmek ne kadar sürer? Basit kullanım durumu (mevcut uygulamanızda bir kod oluşturma): birkaç saat. Hata yönetimi, yeniden denemeler, izleme ve webhook işlemleri içeren üretim düzeyinde entegrasyon: birkaç gün. Toplu işlemler, özel alan adları ve SSO içeren tam kurumsal entegrasyon: haftalar sürer.

API devre dışı kalırsa QR kodlarım çalışır mı? Oluşturma ve düzenleme yapılamaz. Zaten oluşturulmuş kodlar, sağlayıcının yönlendirme altyapısı ayakta olduğu sürece çalışmaya devam eder; bu altyapı genellikle API altyapısından ayrı olup daha yüksek güvenilirlik hedeflerine sahiptir.

QR kod servisimi tamamen kendi altyapımda çalıştırabilir miyim? Statik kodlar için evet; her ana programlama dilinde kütüphaneler mevcuttur. Yönlendirmeli ve analizli dinamik kodlar için kendiniz inşa edebilirsiniz, ancak bu durumda küçük bir SaaS işletiyorsunuz demektir. Çoğu ekip için, bir sağlayıcıya ödeme yapmak geliştirmekten daha ekonomiktir.

Sonuç olarak

QR API'leri, bir insanın dashboard üzerinden yönetebileceğinden daha yüksek ölçeklere çıkan işletmeler için altyapıdır. Modeller yerleşiktir: oluştur, güncelle, analizleri al, arşivle. İhtiyaçlarınıza uygun API olgunluğuna sahip bir sağlayıcı seçin, dikkatlice entegre edin ve kodları zaman içinde yönetilen bir kaynak olarak ele alın.

QR Cake'in fiyatlandırması ve API erişimi hakkında bilgi alın