Geliştirici API’si

API belgeleri

Korumalı bağlantılar oluşturun, gizlilik odaklı analizleri okuyun ve ürününüzden dönüşümleri kaydedin.

İlk isteğinizi gönderin

API sunucudan sunucuya çalışır. Tokeni tarayıcı JavaScript’inde veya herkese açık mobil pakette asla göstermeyin.

1Pro veya Business’ı başlatınAPI erişimi desteklenen ücretli planlarda ve Pro denemesi sırasında etkindir.
2Kapsamlı bir token oluşturunGeliştirici Konsolunda yalnızca entegrasyonunuzun ihtiyaç duyduğu izinleri seçin.
3HTTPS üzerinden gönderinAuthorization: Bearer 4ul_live_…
4Parola gibi saklayınTam token bir kez gösterilir. Açığa çıkmış olabileceğinde hemen iptal edin.

curl "https://4ul.ink/api/v1/links?per_page=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Uç nokta referansı

Tüm nesne erişimi tokenin atandığı workspace ile sınırlıdır.

YöntemYolKapsamSonuç

GET/api/v1/linkslinks:readSayfalanmış bağlantılar

POST/api/v1/linkslinks:writeKorumalı bağlantı oluşturur

PATCH/api/v1/links/{id}links:writeGönderilen alanları günceller

DELETE/api/v1/links/{id}links:writeAnalizleri silmeden devre dışı bırakır

GET/api/v1/links/{id}/analyticsanalytics:readToplu analizler

POST/api/v1/conversionslinks:writeİlişkilendirilmiş olay kaydeder

GET/api/v1/domainsdomains:readÖzel alan adları

POST/api/v1/domainsdomains:writeBir alan adı bağlayın

POST/api/v1/domains/{id}/verifydomains:writeDNS'i doğrula

DELETE/api/v1/domains/{id}domains:writeKaldır

GET/api/v1/webhookswebhooks:readWebhook uç noktaları

POST/api/v1/webhookswebhooks:writeUç nokta ekle

PATCH/api/v1/webhooks/{id}webhooks:writeGönderilen alanları günceller

POST/api/v1/webhooks/{id}/testwebhooks:writeTest gönder

POST/api/v1/webhooks/{id}/rotate-secretwebhooks:writeGizli anahtarı yenile

DELETE/api/v1/webhooks/{id}webhooks:writeSil

İstekler ve yanıtlar

Alan adları canlı v1 API ile tam olarak eşleşir.

POST

Bağlantı oluştur

links:write

{
    "destination_url": "https://example.com",
    "slug": "launch",
    "title": "Launch article"
}

destination_url: Zorunlu genel HTTP veya HTTPS URL’si.
title: İsteğe bağlı, en fazla 190 karakter.
slug: İsteğe bağlı özel takma ad, 3–80 karakter.

201

Bağlantı yanıtı

application/json

{
  "data": {
    "id": 123,
    "slug": "launch",
    "short_url": "https://4ul.ink/launch",
    "destination_url": "https://example.com/article",
    "title": "Launch article",
    "click_count": 0,
    "is_active": true,
    "created_at": "2026-07-25 12:00:00"
  }
}

GET

Bağlantıları listele

?page=1&per_page=25

{
  "data": [{ "id": 123, "slug": "launch", "is_active": true }],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}

per_page 1–100 kabul eder. Bağlantı nesneleri yukarıdaki tam yanıt yapısını kullanır.

GET

Analizleri oku

analytics:read

/api/v1/links/123/analytics?period=custom
  &from=2026-07-01
  &to=2026-07-20

Dönemler 7, 30, 90 veya custom olabilir. Yanıt özet, karşılaştırma, trafik kalitesi, dönüşümler, günlük seri, kitle ve saat kalıplarını içerir; ham ziyaretçi IP’lerini asla içermez.

PATCH

Bağlantıyı güncelle

/api/v1/links/123

{
  "destination_url": "https://example.com/new",
  "title": "New title",
  "slug": "new-alias",
  "is_active": true
}

Yalnızca gönderilen alanlar değişir. Hedef değişikliği otomatik olarak yeni Nova Shield analizini kuyruğa alır.

POST

Dönüşüm kaydet

/api/v1/conversions

{
  "click_token": "4ul_click_…",
  "event": "sale",
  "external_id": "order_1042",
  "amount": 49.00,
  "currency": "USD"
}

Olaylar lead, sale veya refund olabilir. Yinelenen harici olay HTTP 409 döndürür ve iki kez sayılmaz.

Token kapsamları

links:read: bağlantıları listeler.
links:write: bağlantıları oluşturur, günceller, devre dışı bırakır ve dönüşümleri kaydeder.
analytics:read: bağlantı analizlerini okur.
domains:read / domains:write: Özel alan adları
webhooks:read / webhooks:write: İmzalı webhook’lar

İstek limitleri

Tokenler dakikada 120 isteğe ve workspace aylık kotasına tabidir. Analiz için ek limit dakikada 60’tır. HTTP 429 Retry-After ve RateLimit başlıklarını içerir. Normal yönlendirmeler çalışmaya devam eder.

İdempotans

Bağlantı oluştururken 8–128 yazdırılabilir karakterden oluşan Idempotency-Key gönderin. Anahtar workspace içinde 24 saat geçerlidir. Aynı tekrar kayıtlı yanıtı döndürür; aynı anahtarla farklı veri HTTP 409 döndürür.

HTTP

Hatalar

Hatalar tek JSON biçimini kullanır. Yaygın durumlar: 400 geçersiz JSON, 401 geçersiz token, 403 kapsam veya plan yok, 404 bulunamadı, 409 çakışma, 413 gövde büyük, 415 yanlış tür, 422 doğrulama ve 429 limit.

{
  "error": "destination_url must be a valid public HTTP or HTTPS URL.",
  "code": "invalid_destination",
  "field": "destination_url",
  "request_id": "req_7fd9c0c8d821e84b3d69d171",
  "error_details": {
    "code": "invalid_destination",
    "message": "destination_url must be a valid public HTTP or HTTPS URL.",
    "field": "destination_url",
    "request_id": "req_7fd9c0c8d821e84b3d69d171"
  }
}

HMAC

Her webhook’u doğrulayın

Olaylar: link.created, link.updated, link.disabled, link.clicked, conversion.created, shield.status_changed ve endpoint.test. Otomatik teslimat en fazla beş kez dener.

Erişilebilirlik webhook’ları shield.availability_changed kullanır; hedef URL olmadan durum geçişleri ve sınırlı HTTP tanıları içerir.

Teslimat başlıkları

X-4ulink-Event: conversion.created
X-4ulink-Delivery: EVENT_UUID
X-4ulink-Timestamp: UNIX_TIMESTAMP
X-4ulink-Signature: sha256=HEX_HMAC

PHP doğrulaması

$raw = file_get_contents('php://input');
$signed = $timestamp . '.' . $raw;
$expected = 'sha256=' . hash_hmac('sha256', $signed, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

Ham istek gövdesini kullanın, imzaları sabit zamanda karşılaştırın, beş dakikadan eski zaman damgalarını reddedin ve tekrarların idempotent kalması için X-4ulink-Delivery değerini saklayın. Uç nokta 443 portunda genel HTTPS kullanmalıdır.