API dla deweloperów

Dokumentacja API

Twórz chronione linki, odczytuj analitykę dbającą o prywatność i rejestruj konwersje ze swojego produktu.

Wykonaj pierwsze żądanie

API działa serwer-serwer. Nigdy nie ujawniaj tokenu w JavaScript przeglądarki ani publicznym pakiecie mobilnym.

1Włącz Pro lub BusinessDostęp do API jest włączony w obsługiwanych płatnych planach i podczas okresu próbnego Pro.
2Utwórz token z odpowiednimi zakresamiW Konsoli deweloperskiej wybierz tylko uprawnienia potrzebne integracji.
3Wysyłaj przez HTTPSAuthorization: Bearer 4ul_live_…
4Przechowuj jak hasłoPełny token jest wyświetlany raz. Natychmiast go unieważnij, jeśli mógł zostać ujawniony.

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

Dokumentacja endpointów

Dostęp do każdego obiektu jest ograniczony do workspace przypisanego do tokenu.

MetodaŚcieżkaZakresWynik

GET/api/v1/linkslinks:readLinki z paginacją

POST/api/v1/linkslinks:writeTworzy chroniony link

PATCH/api/v1/links/{id}links:writeAktualizuje przesłane pola

DELETE/api/v1/links/{id}links:writeWyłącza bez usuwania analityki

GET/api/v1/links/{id}/analyticsanalytics:readZagregowana analityka

POST/api/v1/conversionslinks:writeRejestruje przypisane zdarzenie

GET/api/v1/domainsdomains:readDomeny niestandardowe

POST/api/v1/domainsdomains:writePodłącz domenę

POST/api/v1/domains/{id}/verifydomains:writeSprawdź DNS

DELETE/api/v1/domains/{id}domains:writeUsuń

GET/api/v1/webhookswebhooks:readEndpointy webhook

POST/api/v1/webhookswebhooks:writeDodaj endpoint

PATCH/api/v1/webhooks/{id}webhooks:writeAktualizuje przesłane pola

POST/api/v1/webhooks/{id}/testwebhooks:writeWyślij test

POST/api/v1/webhooks/{id}/rotate-secretwebhooks:writeZmień sekret

DELETE/api/v1/webhooks/{id}webhooks:writeUsuń

Żądania i odpowiedzi

Nazwy pól odpowiadają działającemu API v1.

POST

Utwórz link

links:write

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

destination_url: Wymagany publiczny adres HTTP lub HTTPS.
title: Opcjonalne, do 190 znaków.
slug: Opcjonalny alias, od 3 do 80 znaków.

201

Odpowiedź z linkiem

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

Lista linków

?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 przyjmuje od 1 do 100. Obiekty linków używają pełnej struktury odpowiedzi pokazanej wyżej.

GET

Odczytaj analitykę

analytics:read

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

Okresy to 7, 30, 90 lub custom. Odpowiedź zawiera przegląd, porównania, jakość ruchu, konwersje, serie dzienne, odbiorców i wzorce godzinowe, nigdy surowe adresy IP.

PATCH

Zaktualizuj link

/api/v1/links/123

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

Zmieniają się tylko przesłane pola. Zmiana celu automatycznie zleca nową analizę Nova Shield.

POST

Zarejestruj konwersję

/api/v1/conversions

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

Zdarzenia to lead, sale lub refund. Duplikat zewnętrznego zdarzenia zwraca HTTP 409 i nigdy nie jest liczony podwójnie.

Zakresy tokenu

links:read: wyświetla linki.
links:write: tworzy, aktualizuje i wyłącza linki oraz rejestruje konwersje.
analytics:read: odczytuje analitykę linków.
domains:read / domains:write: Domeny niestandardowe
webhooks:read / webhooks:write: Podpisane webhooki

Limity żądań

Tokeny pozwalają na 120 żądań na minutę plus miesięczny limit workspace. Analityka ma dodatkowy limit 60 na minutę. HTTP 429 zawiera Retry-After i RateLimit. Przekierowania nadal działają.

Idempotencja

Przy tworzeniu linku wysyłaj Idempotency-Key o długości 8–128 drukowalnych znaków. Klucz działa 24 godziny w workspace. Identyczna próba odtwarza odpowiedź; inne dane z tym samym kluczem zwracają HTTP 409.

HTTP

Błędy

Błędy mają jeden format JSON. Typowe statusy: 400 błędny JSON, 401 błędny token, 403 brak zakresu lub planu, 404 brak obiektu, 409 konflikt, 413 za duże body, 415 zły typ, 422 walidacja i 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

Weryfikuj każdy webhook

Zdarzenia: link.created, link.updated, link.disabled, link.clicked, conversion.created, shield.status_changed i endpoint.test. Automatyczna dostawa ponawia do pięciu razy.

Webhooki dostępności używają shield.availability_changed i zawierają przejścia oraz ograniczoną diagnostykę HTTP bez adresów docelowych.

Nagłówki dostawy

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

Weryfikacja PHP

$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;
}

Używaj surowego body, porównuj podpisy w stałym czasie, odrzucaj znaczniki starsze niż pięć minut i zapisuj X-4ulink-Delivery dla idempotentnych ponowień. Endpoint musi używać publicznego HTTPS na porcie 443.