Geliştiriciler

Onelinks API

Onelinks'i kendi araçlarınıza ve iş akışlarınıza entegre edin. Tam API erişimi Kurumsal planda sunulur.

Kimlik Doğrulama Hızlı Başlangıç Links API Analytics API Profil API Token API Hata Kodları Hız Limitleri SLA Garantisi

Kimlik Doğrulama

Onelinks API, oturum tabanlı kimlik doğrulama kullanır. onelinks_token adlı HTTP-only cookie ile çalışır. Kimlik doğrulamak için POST /api/auth/login endpoint'ini kullanıcı adı ve şifrenizle çağırın — bu işlem cookie'yi ayarlar ve sonraki tüm isteklere dahil edilmesi gerekir.

HTTP-only Cookie

TARAYICI

Uygulama içindeki tüm API istekleri onelinks_tokenJWT cookie'si ile otomatik kimlik doğrular. CSRF koruması dahildir.

Cookie: onelinks_token=<jwt>

Bearer Token

API

Dış entegrasyonlar ve otomasyon için. Dashboard → Entegrasyonlar bölümünden oluşturulur. Sadece Kurumsal Plan'da kullanılabilir.

Authorization: Bearer ol_live_...

Bearer token kullanılmaz

API, Authorization header veya API anahtarı desteklemiyor. Tüm istekler, giriş sonrasında elde edilen onelinks_token oturum cookie'si ile doğrulanır.

Token Formatı

ol_live_<64 hex karakter>

Tokenler ol_live_ öneki ile başlar ve ardından 64 karakterlik bir hex dizisi içerir. Toplam uzunluk 72 karakterdir. Token üretildiğinde yalnızca bir kez gösterilir — kaydetmeyi unutma.

Hızlı Başlangıç

Aşağıdaki örnekler API tokeninizi kullandığınızı varsayar. Tokeni Dashboard → Entegrasyonlar bölümünden oluşturabilirsiniz.

1Linklerinizi listeleyin

curl https://onelinks.co/api/links \
  -H "Authorization: Bearer ol_live_YOUR_TOKEN_HERE"

2Yeni link oluşturun

curl -X POST https://onelinks.co/api/links \
  -H "Authorization: Bearer ol_live_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"title":"GitHub Profilim","url":"https://github.com/kullanici","type":"SOCIAL"}'

3Analitik verisini çekin

curl "https://onelinks.co/api/analytics?range=7d" \
  -H "Authorization: Bearer ol_live_YOUR_TOKEN_HERE"

JavaScript / Node.js Örneği

Node.js ortamında cookie tabanlı oturum açmak için onelinks_token cookie değerini manuel olarak Cookie başlığı ile iletebilirsiniz. API tokeni olan Kurumsal kullanıcılar için Authorization: Bearer tercih edilen yöntemdir.

Linkler

GET/api/links

Kimliği doğrulanmış kullanıcıya ait tüm linkleri order alanına göre sıralanmış olarak döner.

Yanıt

[
  {
    "id":           "clxyz123abc",
    "title":        "GitHub Profilim",
    "url":          "https://github.com/kullanici",
    "description":  null,
    "type":         "SOCIAL",
    "icon":         "github",
    "featured":     false,
    "active":       true,
    "order":        0,
    "clicks":       142,
    "scheduledAt":  null,
    "expiresAt":    null,
    "linkPassword": null,
    "createdAt":    "2026-06-01T10:00:00.000Z",
    "updatedAt":    "2026-07-15T08:30:00.000Z"
  }
]

curl https://onelinks.co/api/links \
  -H "Authorization: Bearer ol_live_YOUR_TOKEN_HERE"

POST/api/links

Yeni bir link oluşturur. Başarılı durumda HTTP 201 Created ile oluşturulan link nesnesini döner.

İstek gövdesi

Alan	Tür	Zorunlu	Açıklama
`title`	string	Evet	Linkin görünen adı. 1–100 karakter.
`url`	string	Evet	Geçerli bir URL. https:// ile başlamalıdır.
`description`	string \| null	Hayır	İsteğe bağlı açıklama. Maks 200 karakter.
`type`	string	Hayır	"GENERAL" \| "SOCIAL" \| "PHONE" \| "EMAIL" \| "WHATSAPP" — varsayılan: "GENERAL"
`icon`	string \| null	Hayır	Platform slug (örn. github, instagram). Otomatik algılanabilir.
`featured`	boolean	Hayır	Öne çıkarılmış link. Profilde vurgulanır. Varsayılan: false.
`scheduledAt`	string \| null	Hayır	ISO 8601 datetime — bu tarihten önce link görünmez. Pro+ planı gerektirir.
`expiresAt`	string \| null	Hayır	ISO 8601 datetime — bu tarihten sonra link devre dışı kalır. Pro+ planı gerektirir.
`linkPassword`	string \| null	Hayır	Linke erişim için parola. Pro+ planı gerektirir.

Hata yanıtları

// 201 Created — başarı
{ "id": "clxyz456", "title": "GitHub Profilim", ... }

// 400 Bad Request — doğrulama hatası
{ "error": "Geçersiz veri." }

// 401 Unauthorized — token yok / geçersiz
{ "error": "Giriş gerekli." }

// 403 Forbidden — plan limiti aşıldı
{ "error": "Ücretsiz plan link limitine ulaşıldı.", "limitReached": true, "maxLinks": 5 }

// 500 Internal Server Error
{ "error": "Sunucu hatası." }

curl -X POST https://onelinks.co/api/links \
  -H "Authorization: Bearer ol_live_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Portföy Sitem",
    "url": "https://ornek.com",
    "type": "GENERAL",
    "featured": true
  }'

PATCH/api/links/[id]

Var olan bir linkin alanlarını kısmen günceller. Yalnızca gönderilen alanlar değiştirilir. Linkin mevcut sahibine ait olması zorunludur. Güncellenmiş link nesnesini döner.

İstek gövdesi (tüm alanlar opsiyonel)

Alan	Tür	Zorunlu	Açıklama
`title`	string	Hayır	Linkin yeni adı.
`url`	string	Hayır	Yeni URL.
`description`	string \| null	Hayır	Açıklama güncelle veya null yaparak kaldır.
`active`	boolean	Hayır	Linki etkinleştir / devre dışı bırak.
`featured`	boolean	Hayır	Öne çıkarılmış durumunu değiştir.
`icon`	string \| null	Hayır	Platform ikonunu değiştir.
`scheduledAt`	string \| null	Hayır	Zamanlama güncelle veya kaldır. Pro+ planı.
`expiresAt`	string \| null	Hayır	Bitiş tarihi güncelle veya kaldır. Pro+ planı.
`linkPassword`	string \| null	Hayır	Parola güncelle veya kaldır. Pro+ planı.

curl -X PATCH https://onelinks.co/api/links/clxyz123abc \
  -H "Authorization: Bearer ol_live_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"active": false, "title": "Eski GitHub Profilim"}'

Hata yanıtları

// 200 OK
{ "id": "clxyz123abc", "active": false, ... }

// 401 Unauthorized — giriş yapılmamış
{ "error": "Giriş gerekli." }

// 404 Not Found — link bulunamadı veya başka kullanıcıya ait
{ "error": "Link bulunamadı." }

DELETE/api/links/[id]

Belirtilen ID'ye sahip linki kalıcı olarak siler. Linkin mevcut sahibine ait olması zorunludur.

curl -X DELETE https://onelinks.co/api/links/clxyz123abc \
  -H "Authorization: Bearer ol_live_YOUR_TOKEN_HERE"

Yanıt

{ "success": true }

POST/api/links/reorder

Birden fazla linki toplu olarak yeniden sıralar. Gönderilen ids dizisinin sırası, linklerin yeni görüntülenme sırası olarak kaydedilir.

İstek gövdesi

Alan	Tür	Zorunlu	Açıklama
`ids`	string[]	Evet	Yeni sırayla link ID'lerinin dizisi. Tüm link ID'leri dahil edilmelidir.

curl -X POST https://onelinks.co/api/links/reorder \
  -H "Authorization: Bearer ol_live_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["clxyz1", "clxyz3", "clxyz2", "clxyz4"]}'

Herkese Açık Endpoint'ler

Aşağıdaki iki endpoint kimlik doğrulaması gerektirmez. Ziyaretçi tarayıcıları tarafından otomatik olarak çağrılır.

POST/api/links/[id]/clickPUBLIC

Bir kullanıcı profile gidip bir linke tıkladığında ziyaretçi tarafından bu endpoint çağrılır. Tıklama analitik verisini kaydeder (cihaz, coğrafi konum, referrer). Ağ hatası durumunda sessizce başarısız olur.

// İstek gövdesi (opsiyonel)
{
  "referrer": "https://instagram.com"
}

// Yanıt
{ "success": true }

POST/api/links/[id]/unlockPUBLIC

Şifreli bir linki ziyaretçinin girdiği parola ile doğrular. Doğru parola girildiğinde linkin gerçek URL'ini döner.

Alan	Tür	Zorunlu	Açıklama
`password`	string	Evet	Ziyaretçinin girdiği parola.

// 200 OK — parola doğru
{ "url": "https://hedef-url.com" }

// 401 Unauthorized — yanlış parola
{ "error": "Yanlış parola." }

// 404 Not Found — link bulunamadı veya şifresiz
{ "error": "Link bulunamadı." }

Analitik

GET/api/analytics?range=7d

Kimliği doğrulanmış kullanıcının tüm linkleri için birleştirilmiş analitik verisini döner. Gelişmiş analitik (saatlik dağılım, coğrafi veriler, referrer kaynakları) Kurumsal Plan'da tam olarak raporlanır.

Query Parametreleri

Alan	Tür	Zorunlu	Açıklama
`range`	string	Hayır	"24h" \| "7d" \| "30d" — varsayılan: "7d"

Yanıt

{
  "total":    843,
  "thisWeek": 312,
  "range":    "7d",
  "since":    "2026-07-11T00:00:00.000Z",

  // Saatlik dağılım — son 24 saatin her saati için tıklama sayısı
  "hourly": [12, 5, 2, 1, 0, 0, 3, 8, 22, 35, 41, 38, 29, 27, 31, 44, 52, 67, 71, 58, 43, 29, 18, 14],

  // Günlük dağılım
  "daily": [
    { "date": "2026-07-12", "count": 97 },
    { "date": "2026-07-13", "count": 115 },
    { "date": "2026-07-14", "count": 134 }
  ],

  // Cihaz dağılımı
  "device": [
    { "device": "Mobil",     "key": "mobile",  "pct": 78 },
    { "device": "Masaüstü",  "key": "desktop", "pct": 19 },
    { "device": "Tablet",    "key": "tablet",  "pct": 3  }
  ],

  // Coğrafi dağılım (Kurumsal Plan)
  "geo": [
    { "country": "Türkiye",  "code": "TR", "clicks": 612, "pct": 73 },
    { "country": "Almanya",  "code": "DE", "clicks": 91,  "pct": 11 },
    { "country": "ABD",      "code": "US", "clicks": 67,  "pct": 8  }
  ],

  // Referrer kaynakları (Kurumsal Plan)
  "referrers": [
    { "source": "instagram.com", "clicks": 501, "pct": 59 },
    { "source": "direct",        "clicks": 189, "pct": 22 },
    { "source": "twitter.com",   "clicks": 87,  "pct": 10 }
  ],

  // Link bazlı performans
  "links": [
    { "id": "clxyz123", "title": "GitHub Profilim",     "clicks": 312 },
    { "id": "clxyz456", "title": "Portföy Sitem",       "clicks": 198 },
    { "id": "clxyz789", "title": "LinkedIn Profilim",   "clicks": 156 }
  ]
}

# Son 7 günün analitikleri
curl "https://onelinks.co/api/analytics?range=7d" \
  -H "Authorization: Bearer ol_live_YOUR_TOKEN_HERE"

# Son 30 günün analitikleri
curl "https://onelinks.co/api/analytics?range=30d" \
  -H "Authorization: Bearer ol_live_YOUR_TOKEN_HERE"

Profil

GET/api/auth/me

Oturum açmış kullanıcı ve ilgili profil verisini döner. Şifre alanı asla yanıta dahil edilmez.

Yanıt

{
  "id":          "clxyz000abc",
  "name":        "Ada Şahin",
  "email":       "[email protected]",
  "username":    "ada",
  "accountType": "INDIVIDUAL",
  "plan":        "CORPORATE",
  "isAdmin":     false,
  "createdAt":   "2026-01-15T09:00:00.000Z",
  "profile": {
    "bio":              "İçerik üreticisi & fotoğrafçı",
    "jobTitle":         "Freelance Fotoğrafçı",
    "location":         "İstanbul",
    "website":          "https://adasahin.com",
    "theme":            "midnight",
    "avatar":           "/api/avatars/ada.jpg",
    "companyName":      null,
    "brandColor":       null,
    "slogan":           null,
    "customDomain":     null,
    "ga4Id":            null,
    "gtmId":            null,
    "zapierWebhookUrl": null
  }
}

curl https://onelinks.co/api/auth/me \
  -H "Authorization: Bearer ol_live_YOUR_TOKEN_HERE"

PATCH/api/profile

Profil alanlarını kısmen günceller. Yalnızca gönderilen alanlar değiştirilir. Güncellenmiş kullanıcı + profil nesnesini döner.

İstek gövdesi (tüm alanlar opsiyonel)

Alan	Tür	Zorunlu	Açıklama
`name`	string	Hayır	Görünen ad. 1–100 karakter.
`bio`	string	Hayır	Profil biyografisi. Maks 500 karakter.
`jobTitle`	string	Hayır	İş unvanı. Maks 80 karakter.
`location`	string	Hayır	Konum bilgisi. Maks 80 karakter.
`website`	string	Hayır	Web sitesi URL'i. Geçerli URL veya boş string.
`theme`	string	Hayır	Aktif tema slug. Maks 50 karakter.
`companyName`	string \| null	Hayır	Şirket adı (Kurumsal hesaplar için).
`brandColor`	string \| null	Hayır	Marka rengi — hex formatında (örn. #14b8a6). Kurumsal Plan.
`slogan`	string \| null	Hayır	Şirket sloganı. Kurumsal Plan.
`customDomain`	string \| null	Hayır	Özel alan adı (örn. links.sitem.com). Kurumsal Plan.
`ga4Id`	string \| null	Hayır	Google Analytics 4 ölçüm ID (G-XXXXXXXXXX). Analitik entegrasyon özelliği.
`gtmId`	string \| null	Hayır	Google Tag Manager container ID (GTM-XXXXXXX). Analitik entegrasyon özelliği.
`zapierWebhookUrl`	string \| null	Hayır	Zapier webhook URL. Webhook entegrasyon özelliği.

curl -X PATCH https://onelinks.co/api/profile \
  -H "Authorization: Bearer ol_live_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "bio": "Full-stack developer & açık kaynak tutkunuzu",
    "location": "İstanbul, Türkiye",
    "website": "https://benim.dev"
  }'

Token Yönetimi

Sadece Kurumsal Plan

Token yönetimi endpoint'leri yalnızca aktif Kurumsal Plan'a sahip hesaplarda kullanılabilir. Ücretsiz veya Pro hesaplar için 403 Forbidden döner.

GET/api/tokenCORPORATE

Mevcut API token bilgilerini döner. Güvenlik için token'in tamamı yerine yalnızca son 8 karakteri gösterilir.

Yanıt

{
  "hasToken":   true,
  "tokenHint":  "...a3f9bc12",
  "createdAt":  "2026-07-10T14:22:00.000Z"
}

// Token yoksa
{ "hasToken": false }

curl https://onelinks.co/api/token \
  -H "Authorization: Bearer ol_live_YOUR_TOKEN_HERE"

POST/api/tokenCORPORATE

Yeni bir API token üretir veya mevcut token'i yeniler. Önceki token geçersiz kılınır. Yanıt olarak token yalnızca bu noktada tam haliyle döner — kaydetmeyi unutma.

Bu endpoint'i çağırdıktan sonra eski token geçersiz olur. Tüm entegrasyonlarınızı yeni token ile güncellemeyi unutmayın.

Yanıt

{
  "token":     "ol_live_a1b2c3d4e5f6...64hexchars",
  "createdAt": "2026-07-18T10:30:00.000Z"
}

# Cookie ile (Dashboard oturumu)
curl -X POST https://onelinks.co/api/token \
  -b cookies.txt

Hata Kodları

Tüm API yanıtları HTTP standart durum kodlarını kullanır. Hata yanıtları aşağıdaki yapıda döner:

{
  "error": "Hata açıklaması"
  // Bazı endpoint'lerde ek alanlar da bulunabilir:
  // "limitReached": true, "maxLinks": 5
}

Kod	Durum	Açıklama
200	OK	İstek başarıyla tamamlandı.
201	Created	Kaynak başarıyla oluşturuldu (POST /api/links).
400	Bad Request	İstek gövdesi veya parametreler geçersiz. Doğrulama hatası.
401	Unauthorized	Geçerli bir kimlik doğrulama bilgisi (cookie veya Bearer token) bulunamadı.
403	Forbidden	Kimlik doğrulandı ancak bu kaynağa erişim iznin yok. Plan limiti aşımı veya başka kullanıcının kaynağına erişim.
404	Not Found	Kaynak bulunamadı. Link mevcut değil veya başka kullanıcıya ait.
429	Too Many Requests	Hız limiti aşıldı. Retry-After başlığını kontrol ederek bekleme süresini öğrenebilirsiniz.
500	Server Error	Beklenmeyen bir sunucu hatası oluştu. Sorun devam ederse destek ile iletişime geçin.

Rate Limit ve Plan Gereksinimleri

Şu an herhangi bir rate limit uygulanmamaktadır. API erişimi (programatik kullanım) Kurumsal plan gerektirir. Link zamanlama, şifreli linkler ve özel alan adı gibi özellikler plan bazlıdır; planınız bu özellikleri desteklemiyorsa sessizce göz ardı edilir.

Ücretsiz Plan

60 istek/dakika

Kullanıcı başına

Pro Plan

300 istek/dakika

Kullanıcı başına

Kurumsal Plan

1000 istek/dakika

Kullanıcı başına

Limit Aşımı

API token (Bearer) ile kimlik doğrulanan istekler dakikada 1000 istek (Kurumsal) ile sınırlıdır. Limit aşıldığında istek 429 Too Many Requests ve { "error": "...", "code": "RATE_LIMITED" }yanıtı döner. Bir sonraki dakika penceresinde sayaç sıfırlanır.

API tokenine nasıl ulaşırsınız?

1Dashboard → Entegrasyonlar sayfasına gidin.
2"API Token Oluştur" butonuna tıklayın (sadece Kurumsal Plan).
3Token yalnızca bir kez gösterilir — güvenli bir yere kaydedin.
4İsteklerinizde Authorization: Bearer <token> başlığını kullanın.

API'yi Denemeye Hazır mısın?

Kurumsal plan ile API tokenini hemen oluştur ve entegrasyona başla.

Kurumsal Planı İncele Dashboard'a Git

SLA Garantisi (Kurumsal)

Kurumsal plan için ölçülebilir hizmet seviyesi taahhüdü. Aşağıdaki değerler sözleşmenin bir parçasıdır.

Uptime Hedefi

%99.9

Aylık, zamanlanmış bakım hariç

Ölçüm

5 dk aralık

Harici izleme; /status sayfasında yayınlanır

İzin verilen kesinti

~43 dk/ay

%99.9 → aylık azami

İhlal halinde servis kredisi

Aylık uptime	Servis kredisi
%99.0 – %99.9	aylık ücretin %10'u
%95.0 – %99.0	aylık ücretin %25'i
%95.0 altı	aylık ücretin %50'si

Kredi Talebi

Ölçüm harici izleme (uptime monitörü) ile yapılır ve /status sayfasında yayınlanır. Kredi talebi, ihlalin gerçekleştiği ayı takip eden 30 gün içinde [email protected] adresine yazılı bildirimle yapılır; kredi bir sonraki fatura döneminden düşülür. Zamanlanmış bakım ve mücbir sebepler kapsam dışıdır.