API ile Toplu Kısa Link Üretimi: Geliştirici Rehberi

Bir kısa link elle üretilebilir. Bin tanesi üretilemez. Fatura bildirimleri, sipariş takipleri, kişiye özel kampanyalar — bunların hepsi kendi sisteminizden tetiklenen link üretimi gerektirir.

Kimlik doğrulama

API herkese açık değildir. Panelden ürettiğiniz bir kullanıcı adı (key_id) ve şifre (secret) çiftiyle HTTP Basic kimlik doğrulaması yapılır.

curl -u "lk_9f3c2a71b0e84d55:sk_XXXXXXXXXXXXXXXXXXXX" \
  https://lnkz.tr/api/v1/me

Şifre yalnızca üretildiği anda gösterilir; veritabanında yalnızca özeti saklanır. Kaybederseniz yeni anahtar üretmeniz gerekir — bu bilinçli bir tasarım tercihidir.

Anahtar hijyeni

• Anahtarı koda gömmeyin; ortam değişkeninde tutun.
• Her uygulama için ayrı anahtar üretin. Bir sızıntıda yalnızca o anahtarı iptal edersiniz.
• Anahtarı istemci tarafında (tarayıcı JavaScript'i, mobil uygulama) kullanmayın — orada saklanan hiçbir sır gizli kalmaz. Çağrıyı kendi sunucunuzdan yapın.

Tek link oluşturma

POST /api/v1/links
Content-Type: application/json

{
  "url": "https://randevu.selfklinik.com/?GUID=a8faa905-477a-11f0-89df-52e18006e243",
  "title": "Randevu bağlantısı",
  "tags": ["klinik", "randevu"],
  "expires_at": "2026-12-31 23:59:00",
  "max_clicks": 5000
}

Başarılı yanıt 201 döner ve içinde short_url, code, qr_url alanları bulunur. Her başarılı üretim 1 kontör harcar; doğrulama hatasında kontör otomatik iade edilir.

PHP

function shorten(string $url, array $extra = []): array
{
    $ch = curl_init('https://lnkz.tr/api/v1/links');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 15,
        CURLOPT_USERPWD        => getenv('LNKZ_KEY_ID') . ':' . getenv('LNKZ_KEY_SECRET'),
        CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS     => json_encode(['url' => $url] + $extra),
    ]);

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

    $data = json_decode((string) $response, true);

    if ($status !== 201) {
        throw new RuntimeException($data['error']['message'] ?? 'Link üretilemedi');
    }

    return $data['link'];
}

Python

import os, requests

AUTH = (os.environ["LNKZ_KEY_ID"], os.environ["LNKZ_KEY_SECRET"])

def shorten(url, **extra):
    response = requests.post(
        "https://lnkz.tr/api/v1/links",
        auth=AUTH,
        json={"url": url, **extra},
        timeout=15,
    )
    payload = response.json()
    if response.status_code != 201:
        raise RuntimeError(payload["error"]["message"])
    return payload["link"]

Toplu üretim

Uç nokta tek seferde bir link üretir. On binlerce kayıt işlerken üç kural var:

1. Hız sınırına saygı gösterin

Anahtar başına dakikada 120 istek sınırı vardır. Aşarsanız 429 ve Retry-After başlığı dönerim. Kuyruk mantığıyla çalışın; istekleri paralel açıp sınırı zorlamayın.

import time

def shorten_with_retry(url, attempts=5, **extra):
    for attempt in range(attempts):
        try:
            return shorten(url, **extra)
        except RuntimeError:
            raise                      # doğrulama hatası: tekrar denemenin anlamı yok
        except requests.HTTPError as e:
            if e.response.status_code == 429:
                wait = int(e.response.headers.get("Retry-After", 60))
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("hız sınırı aşıldı")

2. Yeniden denemeyi ayırın

Hataların hepsi aynı değildir:

Kod	Anlamı	Ne yapmalı?
401	Anahtar geçersiz	Tekrar deneme; yapılandırmayı düzelt
402	Kontör yetersiz	Durdur, uyar, kontör yükle
422	Geçersiz alan / kullanılmış kod	Veriyi düzelt; aynı istekle deneme
429	Hız sınırı	Retry-After kadar bekle, tekrar dene
5xx	Sunucu hatası	Üstel geri çekilme ile tekrar dene

3. Sonucu kendi tarafınızda saklayın

Üretilen code değerini kendi veritabanınıza yazın. Aynı kaydı iki kez işlemeyi önler (ve iki kez kontör harcamayı). Basit bir kural: kaydınızda short_code doluysa API'ye hiç gitmeyin.

Kontör bütçesi

Üretime başlamadan önce bakiyenizi kontrol edin:

GET /api/v1/me
→ { "account": { "credits": 4820 }, "costs": { "link": 1, "ai_slug": 5 } }

50.000 linklik bir gönderim 50.000 kontör gerektirir. İşin ortasında bakiyenin bitmesi, yarım kalmış bir gönderim demektir; toplu işlerden önce gereken kontörü hesaplayıp yükleyin.

AI ile anlamlı kod üretme

İnsanların göreceği linklerde rastgele kod yerine okunabilir kod kullanmak tıklama oranını artırır. AI uç noktası hedef sayfayı analiz edip öneri üretir:

POST /api/v1/ai/suggest
{ "task": "slug", "url": "https://ornek.com/kampanyalar/yaz-indirimi-2026" }

→ {
  "result": {
    "suggestions": [
      { "code": "yaz-indirimi", "reason": "Kampanya adı doğrudan tanınır" },
      { "code": "yaz26-firsat", "reason": "Dönemi de belirtir" }
    ]
  },
  "credits_charged": 5
}

Bu çağrı 5 kontör harcadığı için toplu üretimde her kayıt başına kullanılması ekonomik değildir. Doğru kullanım: kampanya, ürün ya da kategori gibi tekil ve insana görünen linklerde çağırın; kişiye özel binlerce linkte rastgele kod bırakın.

Kontrol listesi

1. Anahtarı ortam değişkeninde tutun, uygulama başına ayrı üretin.
2. Her istekte zaman aşımı tanımlayın (15 sn yeterli).
3. 429 için Retry-After'a uyun; 4xx'te tekrar denemeyin.
4. Üretilen kodu kendi veritabanınıza yazın; tekrar üretimi engelleyin.
5. Toplu işten önce kontör bakiyesini doğrulayın.
6. Kişiye özel linklerde expires_at ve max_clicks tanımlayın.
7. Üretimi önce 10 kayıtla test edin, sonra tam listeye geçin.