nLink

Geliştiriciler

nLink API ve webhook'lar

Linklerinizi kendi uygulamanızdan oluşturun ve yönetin, tıklama istatistiklerini çekin; webhook ile tıklama ve link olaylarını anında sisteminize alın. API ve webhook'lar Altın ve Kurumsal planlarında kullanılabilir.

Kimlik doğrulama ve sınırlar

API anahtarınızı Ayarlar → API Erişimi bölümünden oluşturun. Anahtar yalnızca bir kez gösterilir; sunucumuzda yalnızca özeti saklanır. Her istekte başlıkta gönderin:

Authorization: Bearer nlk_xxxxxxxxxxxxxxxx
# ya da / or
X-API-Key: nlk_xxxxxxxxxxxxxxxx
  • Temel adres: https://api.nlink.tr/api/v1
  • İstek sınırı: Altın dakikada 60, Kurumsal dakikada 300. Yanıtta X-RateLimit-Limit ve X-RateLimit-Remaining; aşılırsa 429 ve Retry-After.
  • Plan limitleriniz (aylık link sayısı) API için de geçerlidir.
  • Tüm gövdeler JSON; zamanlar ISO 8601 (UTC).

Uçlar

GET/api/v1/me

Hesap, plan, limitler ve bu ayki tıklama kullanımı.

curl https://api.nlink.tr/api/v1/me -H "Authorization: Bearer $NLINK_API_KEY"

POST/api/v1/links

Link oluşturur. Hedef adres güvenlik taramasından geçer; plan kotanızdan düşer.

urlHedef adres (zorunlu, http/https).
slugÖzel kısa ad (isteğe bağlı). Kullanımdaysa 409 slug_taken.
domainnlink.tr ya da hesabınızda tanımlı özel alan adı (isteğe bağlı).
curl -X POST https://api.nlink.tr/api/v1/links \
  -H "Authorization: Bearer $NLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/yaz-indirimi", "slug": "kampanya"}'
201 Created
{
  "id": "6702f1c4a9b3e1d2c3f4a5b6",
  "slug": "kampanya",
  "short_url": "https://nlink.tr/kampanya",
  "url": "https://example.com/yaz-indirimi",
  "domain": "nlink.tr",
  "created_at": "2026-10-03T12:00:00Z",
  "created_by": null,
  "clicks": 128,
  "last_click_at": "2026-10-04T08:15:02Z",
  "group_ids": []
}

Hatalar

Hata yanıtı her zaman aynı biçimdedir:

{ "error": { "code": "slug_taken", "message": "Bu kısa ad kullanımda." } }
HTTPcodeAnlamı
400invalid_slug · invalid_domainGeçersiz kısa ad ya da alan adı.
401unauthorized · invalid_api_keyAnahtar yok ya da geçersiz.
403plan_requiredAPI Altın ve Kurumsal planlarında.
404not_foundLink bulunamadı (ya da sizin değil).
409slug_taken · slug_reserved · slug_retiredKısa ad kullanımda, ayrılmış ya da silinmiş bir linke ait (silinen linklerin adı tekrar verilmez).
422invalid_url · unsafe_urlHedef adres geçersiz ya da güvenlik taramasına takıldı.
429rate_limited · quota_exceededDakikalık sınır ya da plan kotası doldu.

Webhook

Webhook adreslerinizi Ayarlar → Webhook bölümünden ekleyin (en fazla 5, yalnızca https). Seçtiğiniz olaylar gerçekleştiğinde adresinize imzalı bir POST isteği gönderilir.

link.createdLink oluşturuldu (panel, eklenti ya da API).
link.updatedHedef adres ya da kısa ad değişti.
link.deletedLink silindi.
link.clickedİnsan tıklaması (botlar hariç; aylık tıklama hakkınız içinde). Ülke, şehir, cihaz, kaynak ve kampanya ile; IP adresi gönderilmez.
pingPanelden "deneme gönder".

Örnek istek:

POST https://ornek.com/nlink-webhook
Content-Type: application/json
X-Nlink-Event: link.clicked
X-Nlink-Delivery: 6702f9a1c2d3e4f5a6b7c8d9
X-Nlink-Signature: t=1791047318,v1=5f2b…c91e

{
  "id": "6702f9a1c2d3e4f5a6b7c8d9",
  "event": "link.clicked",
  "created_at": "2026-10-04T08:15:02Z",
  "data": {
    "link": { "id": "6702f1c4…", "slug": "kampanya", "short_url": "https://nlink.tr/kampanya", "url": "https://example.com/yaz-indirimi" },
    "clicked_at": "2026-10-04T08:15:02Z",
    "country": "TR", "region": "İstanbul", "city": "Istanbul",
    "device": "mobile", "os": "iOS", "browser": "Mobile Safari",
    "referrer_host": "instagram.com", "app": "instagram", "campaign": "yaz",
    "unique": true
  }
}

İmzayı doğrulama

X-Nlink-Signature başlığındaki v1, webhook'un imza anahtarıyla (whsec_…) "<t>.<ham gövde>" metninin HMAC-SHA256 değeridir. Gövdeyi ayrıştırmadan önce ham haliyle doğrulayın ve t zaman damgası 5 dakikadan eskiyse isteği reddedin (tekrar oynatma koruması).

Node.js

import crypto from "node:crypto";

// rawBody: isteğin ham gövdesi (JSON.parse ETMEDEN önce), secret: whsec_…
export function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}

Python

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", 0))
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Teslim ve yeniden deneme

  • Adresiniz 10 saniye içinde 2xx dönmelidir; yönlendirmeler izlenmez.
  • Başarısız teslim 1 dk, 5 dk, 30 dk, 2 sa, 6 sa ve 12 sa sonra yeniden denenir. Aynı olay birden fazla gelebilir; X-Nlink-Delivery ile tekilleştirin.
  • Art arda 50 başarısız teslimde webhook kapatılır; panelden yeniden açabilirsiniz. Son teslimler ve hata nedenleri panelde görünür.
  • Olayların sırası garanti edilmez; created_at alanını kullanın.

Sorunuz mu var? [email protected]

Geliştiriciler: Link Kısaltma API'si ve Webhook · nLink