Geliştirici Dokümantasyonu & API Kılavuzu SVG & Base64 Standardı

Geliştiriciler İçin QR Kod REST API Dokümantasyonu

Stateless mimariyle çalışan, harici kimlik doğrulama gerektirmeyen, vektörel SVG ve Base64 Data-URI çıktıları üreten, PHP 8.4 ve BaconQrCode motoru ile güçlendirilmiş yüksek performanslı REST API.

Canlı QR Aracı

Dokümantasyon Menüsü

QR Kod Aracına Dön

Hızlı İstek (cURL)

curl -s "https://clskn.net/api/qr?text=https://example.com"

Stateless RESTful QR Kod Servisi

clskn.net QR Kod API; oturum, çerez veya karmaşık API anahtarları gerektirmeyen tamamen stateless, milisaniyeler seviyesinde çalışan ve modern web standartlarına tam uyumlu bir mikroservistir. Web bağlantıları, Wi-Fi erişim matrisleri, vCard kartvizitler veya dinamik içerikler için doğrudan vektörel SVG ya da uygulamalarınızda kolayca gömebileceğiniz Base64 Data-URI formatında çıktı üretir.

Stateless & Hızlı

Karmaşık kimlik doğrulama gerekmez. Standart HTTP GET istekleriyle doğrudan tarayıcıya veya backend servislerinize yanıt verir.

Vektörel SVG & Base64

Pikselleşmeyen saf SVG vektör matrisi veya anında <img> etiketine bağlanabilen Base64 Data-URI şeması sunar.

PHP 8.4 & BaconQrCode

Endüstri standardı Reed-Solomon matematiksel hata düzeltme motoru ile %30'a varan veri kurtarma garantisi sağlar.

API Uç Noktaları (Endpoints)

HTTP GET

Tüm istekler güvenli HTTPS protokolü ve standart HTTP GET metodu ile gerçekleştirilir. İhtiyacınıza göre doğrudan ham SVG görseli veya JSON yanıt alabilirsiniz.

GET https://clskn.net/api/qr Standart üretim uç noktası (Varsayılan: image/svg+xml)

GET https://clskn.net/api/v1/qr Sürümlendirilmiş v1 RESTful üretim uç noktası

GET https://clskn.net/api/qrcode Genişletilmiş URI takma adı (Alias)

İstek Parametreleri

Parametre	Konum	Tip	Durum	Varsayılan	Açıklama
text	Query	string	Zorunlu	-	QR koda kodlanacak ham içerik, URL veya format şablonu (Wi-Fi, vCard vb.). Minimum 1, maksimum 2048 karakter uzunluğunda olmalıdır. URL encode edilmiş veri desteklenir.
size	Query	integer	Opsiyonel	300	Üretilecek QR kodun piksel cinsinden genişlik ve yüksekliği. `64` ile `2048` piksel arasında bir tam sayı olmalıdır.
margin	Query	integer	Opsiyonel	2	QR matrisinin çevresindeki sessiz alan (quiet zone) modül genişliği. `0` ile `10` arasında bir değer alabilir.
ecc	Query	string	Opsiyonel	M	Reed-Solomon hata düzeltme seviyesi. Değerler: `L` (%7 kurtarma), `M` (%15 kurtarma), `Q` (%25 kurtarma), `H` (%30 kurtarma). Büyük veya küçük harf duyarsızdır.
color	Query	string (HEX)	Opsiyonel	#000000	QR matris noktalarının (ön plan) rengi. Geçerli 3 veya 6 haneli HEX renk kodu olmalıdır (örnek: `#000000`, `#2563eb`). URL içinde `#` karakteri `%23` olarak kodlanmalıdır.
bgcolor	Query	string (HEX)	Opsiyonel	#ffffff	Arka plan rengi. HEX renk kodu veya saydam arka plan için `transparent` değeri gönderilebilir.
format	Query	string	Opsiyonel	svg	Çıktı formatı: `svg` (ham SVG görseli), `json` veya `base64` (SVG string'i ve Base64 Data-URI içeren JSON nesnesi). İstemci `Accept: application/json` başlığı gönderdiğinde de otomatik JSON yanıt verilir.
download	Query	boolean	Opsiyonel	false	`1` veya `true` gönderildiğinde HTTP yanıtına `Content-Disposition: attachment; filename="qrcode.svg"` başlığı eklenerek doğrudan dosya indirmesi tetiklenir.

Hız Sınırı (Rate Limit) & HTTP Başlıkları

Sunucu kaynaklarını korumak ve kesintisiz hizmet sunmak amacıyla QR üretim uç noktaları IP adresi başına dakikada 60 istek ile sınırlandırılmıştır. Kota durumunuz her yanıtta HTTP başlıklarında iletilir:

60 İstek / Dakika

X-RateLimit-Limit İstemciye tanınan dakikalık tavan istek hakkı (60).

X-RateLimit-Remaining Mevcut 1 dakikalık zaman penceresinde kalan istek hakkınız.

Retry-After Hız limiti aşıldığında (429) yeni istek atmadan önce beklenmesi gereken saniye.

Canlı İstek ve Entegrasyon Örnekleri

cURL: Standart SVG Çıktısı

curl -s "https://clskn.net/api/qr?text=https://example.com" -o qrcode.svg

cURL: Renkli & Şeffaf Arka Plan

curl -s "https://clskn.net/api/qr?text=https://example.com&size=512&ecc=H&color=%232563eb&bgcolor=transparent" -o brand-qr.svg

cURL: JSON & Base64 Data-URI

curl -s "https://clskn.net/api/qr?text=https://example.com&format=json"

HTML: Doğrudan <img> Entegrasyonu

<img src="https://clskn.net/api/qr?text=https://example.com&size=256" alt="QR Kod" width="256" height="256" loading="lazy">

JavaScript (Modern Fetch API ile JSON & Base64)

// JSON formatında SVG ve Base64 Data-URI alma
const params = new URLSearchParams({
  text: 'https://example.com',
  size: '300',
  ecc: 'M',
  format: 'json'
});

fetch(`https://clskn.net/api/qr?${params.toString()}`, {
  headers: {
    'Accept': 'application/json'
  }
})
  .then(response => {
    if (!response.ok) throw new Error(`HTTP Hata: ${response.status}`);
    return response.json();
  })
  .then(payload => {
    console.log('SVG Çıktısı:', payload.data.svg);
    console.log('Data-URI:', payload.data.data_uri);
    // Örnek: Görsel kaynağına bağlama
    // document.getElementById('my-qr-img').src = payload.data.data_uri;
  })
  .catch(error => console.error('QR Kod API Hatası:', error));

Yanıt Şemaları (Response Schemas)

1. Ham SVG Çıktısı (Varsayılan) image/svg+xml

Doğrudan tarayıcıda render edilebilir veya <img src="..."> olarak bağlanabilir saf vektör XML verisi döner.

<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="300" height="300" viewBox="0 0 300 300">
  <rect x="0" y="0" width="300" height="300" fill="#ffffff"/>
  <path fill="#000000" d="M20 20h70v70h-70z M30 30h50v50h-50z..."/>
</svg>

2. JSON & Base64 Data-URI Şeması application/json

?format=json veya Accept: application/json istendiğinde dönen yapılandırılmış REST yanıtı.

{
  "status": "success",
  "data": {
    "svg": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>...",
    "data_uri": "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0...",
    "text": "https://example.com",
    "format": "svg",
    "size": 300,
    "margin": 2,
    "ecc": "M",
    "color": "#000000",
    "bgcolor": "#ffffff"
  },
  "meta": {
    "execution_time_ms": 3.42,
    "timestamp": "2026-09-07T15:08:00+00:00"
  }
}

HTTP Durum Kodları (Status Codes)

200 OK Başarılı

QR kod parametrelere göre hatasız üretildi; ham SVG görseli veya JSON gövdesi iletildi.

422 Unprocessable Doğrulama

text parametresi eksik, 2048 karakter sınırını aşıyor, renk formatı geçersiz veya boyut aralık dışı.

429 Too Many Req. Hız Limiti

Dakikalık istek sınırı (60 istek/dk) aşıldığında döner. Retry-After başlığını kontrol edin.

500 Server Error Sunucu Hatası

Matris hesaplanırken veya SVG derlenirken beklenmeyen bir hata meydana geldiğinde döner.