Geliştirici Dokümantasyonu

Temel Adres (Base URL)

https://vvvv.tr/api/v1

Tüm uç noktalar bu adrese görecelidir. İstek ve yanıt gövdeleri JSON'dır (UTF-8).

Kimlik Doğrulama

Panel → API bölümünden bir anahtar oluşturun. Anahtar yalnızca bir kez gösterilir. Her isteğe iki yöntemden biriyle ekleyin:

# Önerilen — Bearer token
curl "https://vvvv.tr/api/v1/account" \
  -H "Authorization: Bearer API_ANAHTARINIZ"

# Alternatif — özel başlık
curl "https://vvvv.tr/api/v1/account" \
  -H "X-Api-Key: API_ANAHTARINIZ"

Kapsamlar (Scopes)

Her anahtar yalnızca sahip olduğu kapsamdaki işlemleri yapabilir. Eksik kapsamda 403 insufficient_scope döner.

Hız Limitleri & Kota

Günlük istek kotanız paketinize göredir. Her yanıtta güncel durum başlıklarda döner:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 996
X-RateLimit-Reset: 1787011200   # kotanın sıfırlanacağı Unix zamanı

Kota dolunca 429 quota_exceeded, IP taban limiti veya anahtarın dakikalık sınırı (varsayılan 120/dk) aşılınca 429 rate_limited döner (Retry-After başlığıyla).

Anahtar Güvenliği

• IP izin listesi: Panelden her anahtara IPv4/IPv6 adres veya CIDR aralığı tanımlayın; diğer IP'lerden gelen istekler 403 ip_not_allowed alır.
• Dakikalık sınır: Anahtar başına 1-6000 istek/dk; sızan bir anahtarın zararı sınırlanır.
• İstek kimliği: Her yanıtta X-Request-Id başlığı ve hata gövdesinde request_id bulunur — destek taleplerinde paylaşın.
• İçerik türü: Yazma isteklerinde Content-Type: application/json (veya form) zorunludur; diğerleri 415 alır. Gövde en fazla 256 KB.
• Anahtarlar yalnızca başlıkta kabul edilir (URL parametresiyle asla); sunucuda yalnızca SHA-256 özeti saklanır.

Yanıt Biçimi

Tüm yanıtlar tutarlı bir zarf kullanır:

# Başarılı
{ "ok": true, "data": { ... }, "meta": { ... } }

# Hatalı
{ "ok": false, "error": { "type": "validation", "message": "..." } }

Uç Nokta Referansı

POST /shorten — Link kısalt

curl -X POST "https://vvvv.tr/api/v1/shorten" \
  -H "Authorization: Bearer API_ANAHTARINIZ" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://ornek.com/cok/uzun/link",
        "alias": "kampanya",          // opsiyonel (Pro)
        "title": "Yaz kampanyası",     // opsiyonel
        "expires_at": "2026-12-31",    // opsiyonel (Pro)
        "max_clicks": 1000,            // opsiyonel (Pro)
        "tags": "kampanya,instagram"   // opsiyonel
      }'

Yanıt (201):

{ "ok": true, "data": {
    "code": "kampanya",
    "short_url": "https://vvvv.tr/kampanya",
    "url": "https://ornek.com/cok/uzun/link",
    "status": "active", "clicks": 0,
    "scan_status": "safe", "created_at": "2026-01-01 12:00:00"
} }

GET /link/{code}/stats — Detaylı istatistik

curl "https://vvvv.tr/api/v1/link/kampanya/stats?days=30" \
  -H "Authorization: Bearer API_ANAHTARINIZ"

{ "ok": true, "data": {
    "clicks": 1240, "unique_visitors": 980,
    "daily":       [ { "day": "2026-01-01", "clicks": 42, "uniques": 30 }, ... ],
    "by_country":  [ { "country": "TR", "n": 900 }, ... ],
    "by_device":   [ { "device": "Mobil", "n": 700 }, ... ],
    "by_referrer": [ { "host": "instagram.com", "n": 300 }, ... ]
} }

PATCH /link/{code} — Güncelle

curl -X PATCH "https://vvvv.tr/api/v1/link/kampanya" \
  -H "Authorization: Bearer API_ANAHTARINIZ" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Yeni başlık", "status": "paused" }'

POST /links/bulk — Toplu

curl -X POST "https://vvvv.tr/api/v1/links/bulk" \
  -H "Authorization: Bearer API_ANAHTARINIZ" \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://a.com", "https://b.com"] }'

POST /scan — VVVV Zeka güvenlik analizi

Bir URL'yi link oluşturmadan, yerleşik akıllı motorla analiz eder. 0-100 risk skoru, karar (safe/review/malicious) ve gerekçeleri döndürür.

curl -X POST "https://vvvv.tr/api/v1/scan" \
  -H "Authorization: Bearer API_ANAHTARINIZ" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://ornek.com/sayfa" }'

# Yanıt
{ "ok": true, "data": {
    "verdict": "review", "score": 47, "risk": "medium",
    "reasons": ["Riskli TLD", "Rastgele görünen alan adı (yüksek entropi)"] } }

POST /qrs — Dinamik QR oluştur

Basılı QR kodu her zaman aynı aracı adresi (/q/{kod}) taşır; hedefi istediğiniz zaman PATCH /qr/{code} ile değiştirirsiniz. Her hedef değişikliği güvenlik taramasından geçer.

curl -X POST "https://vvvv.tr/api/v1/qrs" \
  -H "Authorization: Bearer API_ANAHTARINIZ" \
  -H "Content-Type: application/json" \
  -d '{ "target_url": "https://ornek.com/menu", "title": "Masa QR",
        "style": { "fg": "#7c3aed", "fg2": "#ec4899", "grad": "linear",
                   "module": "dots", "eyestyle": "circle", "ecl": "Q" } }'

# Hedefi değiştir (kod ve basılı QR aynı kalır)
curl -X PATCH "https://vvvv.tr/api/v1/qr/AbC12xY" \
  -H "Authorization: Bearer API_ANAHTARINIZ" \
  -H "Content-Type: application/json" \
  -d '{ "target_url": "https://ornek.com/yeni-menu" }'

# Görsel (SVG veya PNG; size 128-2048)
curl "https://vvvv.tr/api/v1/qr/AbC12xY/image?format=png&size=1024" \
  -H "Authorization: Bearer API_ANAHTARINIZ" -o qr.png

Stil alanları: fg, fg2, bg, eye (#rrggbb), grad (none/linear/radial), module (square/rounded/dots/diamond), eyestyle (square/rounded/circle), ecl (L/M/Q/H), margin (0-8), transparent (true/false).

GET /analytics — Hesap özeti

curl "https://vvvv.tr/api/v1/analytics?days=30" \
  -H "Authorization: Bearer API_ANAHTARINIZ"

JavaScript (fetch) Örneği

const res = await fetch("https://vvvv.tr/api/v1/shorten", {
  method: "POST",
  headers: {
    "Authorization": "Bearer API_ANAHTARINIZ",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ url: "https://ornek.com/uzun-link" })
});
const { ok, data, error } = await res.json();
if (ok) console.log(data.short_url); else console.error(error.message);

API, CORS destekler (Access-Control-Allow-Origin: *). Anahtarınızı tarayıcı tarafı koda gömmeyin; sunucu tarafında kullanın.