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.
| url | Hedef adres (zorunlu, http/https). |
| slug | Özel kısa ad (isteğe bağlı). Kullanımdaysa 409 slug_taken. |
| domain | nlink.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": []
}GET/api/v1/links
Linkleriniz, en yeni önce, sayfalı.
| page | Sayfa (varsayılan 1). |
| limit | Sayfa başına 1–100 (varsayılan 50). |
| q | Hedef adres, kısa ad ya da başlıkta arama. |
curl "https://api.nlink.tr/api/v1/links?page=1&limit=50" -H "Authorization: Bearer $NLINK_API_KEY"
{ "data": [ … ], "page": 1, "limit": 50, "total": 312, "has_more": true }GET/api/v1/links/{id}
Tek link. {id} link kimliği ya da kısa ad olabilir.
curl https://api.nlink.tr/api/v1/links/kampanya -H "Authorization: Bearer $NLINK_API_KEY"
PATCH/api/v1/links/{id}
Hedef adresi ve/veya kısa adı değiştirir. Yeni hedef yeniden taranır; değişiklik link geçmişine yazılır.
| url | Yeni hedef adres. |
| slug | Yeni kısa ad. |
curl -X PATCH https://api.nlink.tr/api/v1/links/kampanya \
-H "Authorization: Bearer $NLINK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/kis-indirimi"}'DELETE/api/v1/links/{id}
Linki kalıcı olarak siler (204). Kısa ad bir daha kullanılmaz; açan herkes "kaldırıldı" sayfasını görür.
curl -X DELETE https://api.nlink.tr/api/v1/links/kampanya -H "Authorization: Bearer $NLINK_API_KEY"
GET/api/v1/links/{id}/stats
Tıklama istatistikleri (botlar hariç): günlük seri, ülke, şehir, cihaz, tarayıcı, kaynak, kampanya.
| days | Gün sayısı 1–365 (varsayılan 30). |
curl "https://api.nlink.tr/api/v1/links/kampanya/stats?days=7" -H "Authorization: Bearer $NLINK_API_KEY"
Hatalar
Hata yanıtı her zaman aynı biçimdedir:
{ "error": { "code": "slug_taken", "message": "Bu kısa ad kullanımda." } }| HTTP | code | Anlamı |
|---|---|---|
| 400 | invalid_slug · invalid_domain | Geçersiz kısa ad ya da alan adı. |
| 401 | unauthorized · invalid_api_key | Anahtar yok ya da geçersiz. |
| 403 | plan_required | API Altın ve Kurumsal planlarında. |
| 404 | not_found | Link bulunamadı (ya da sizin değil). |
| 409 | slug_taken · slug_reserved · slug_retired | Kısa ad kullanımda, ayrılmış ya da silinmiş bir linke ait (silinen linklerin adı tekrar verilmez). |
| 422 | invalid_url · unsafe_url | Hedef adres geçersiz ya da güvenlik taramasına takıldı. |
| 429 | rate_limited · quota_exceeded | Dakikalı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.created | Link oluşturuldu (panel, eklenti ya da API). |
| link.updated | Hedef adres ya da kısa ad değişti. |
| link.deleted | Link 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. |
| ping | Panelden "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]