API для розробників
Створюйте захищені посилання, отримуйте аналітику з повагою до приватності та фіксуйте конверсії зі свого продукту.
API призначений для зв’язку сервер-сервер. Ніколи не розміщуйте токен у браузерному JavaScript або публічній збірці мобільного застосунку.
Authorization: Bearer 4ul_live_…curl "https://4ul.ink/api/v1/links?per_page=1" \
-H "Authorization: Bearer YOUR_TOKEN"Доступ до будь-якого об’єкта обмежений workspace, до якого прив’язаний токен.
/api/v1/linkslinks:readСписок посилань із пагінацією/api/v1/linkslinks:writeСтворює захищене посилання/api/v1/links/{id}links:writeОновлює передані поля/api/v1/links/{id}links:writeВимикає без видалення аналітики/api/v1/links/{id}/analyticsanalytics:readАгрегована аналітика/api/v1/conversionslinks:writeЗаписує атрибутовану подію/api/v1/domainsdomains:readВласні домени/api/v1/domainsdomains:writeПідключити домен/api/v1/domains/{id}/verifydomains:writeПеревірити DNS/api/v1/domains/{id}domains:writeВидалити/api/v1/webhookswebhooks:readWebhook-адреси/api/v1/webhookswebhooks:writeДодати endpoint/api/v1/webhooks/{id}webhooks:writeОновлює передані поля/api/v1/webhooks/{id}/testwebhooks:writeНадіслати тест/api/v1/webhooks/{id}/rotate-secretwebhooks:writeЗмінити секрет/api/v1/webhooks/{id}webhooks:writeВидалитиНазви полів нижче точно відповідають робочому API v1.
links:write{
"destination_url": "https://example.com",
"slug": "launch",
"title": "Launch article"
}destination_urltitleslugapplication/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"
}
}?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. Об’єкти посилань використовують повну структуру відповіді вище.
analytics:read/api/v1/links/123/analytics?period=custom
&from=2026-07-01
&to=2026-07-20Періоди: 7, 30, 90 або custom. Відповідь містить огляд, порівняння, якість трафіку, конверсії, дані за днями, аудиторіями й годинами — але ніколи вихідні IP відвідувачів.
/api/v1/links/123{
"destination_url": "https://example.com/new",
"title": "New title",
"slug": "new-alias",
"is_active": true
}Змінюються лише передані поля. Зміна призначення автоматично ставить нову перевірку Nova Shield у чергу.
/api/v1/conversions{
"click_token": "4ul_click_…",
"event": "sale",
"external_id": "order_1042",
"amount": 49.00,
"currency": "USD"
}Події: lead, sale або refund. Дублікат зовнішньої події повертає HTTP 409 і ніколи не враховується двічі.
links:readlinks:writeanalytics:readdomains:read / domains:writewebhooks:read / webhooks:writeТокен допускає 120 запитів за хвилину й обмежений місячним лімітом workspace. Для аналітики діє додатковий ліміт 60 запитів за хвилину. HTTP 429 містить Retry-After і RateLimit. Звичайні редиректи працюють далі.
Під час створення посилання передавайте Idempotency-Key довжиною 8–128 друкованих символів. Ключ діє у workspace 24 години. Однаковий повтор повертає збережену відповідь, а інші дані з тим самим ключем — HTTP 409.
Помилки мають єдиний JSON-формат. Основні статуси: 400 неправильний JSON, 401 неправильний токен, 403 немає права або тарифу, 404 об’єкт не знайдено у workspace, 409 конфлікт, 413 завелике тіло, 415 неправильний тип, 422 помилка даних і 429 перевищення ліміту.
{
"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"
}
}Події: link.created, link.updated, link.disabled, link.clicked, conversion.created, shield.status_changed та endpoint.test. Автодоставка виконує до п’яти спроб.
Webhook доступності shield.availability_changed містить переходи стану та обмежену HTTP-діагностику без URL призначення.
X-4ulink-Event: conversion.created
X-4ulink-Delivery: EVENT_UUID
X-4ulink-Timestamp: UNIX_TIMESTAMP
X-4ulink-Signature: sha256=HEX_HMAC$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;
}Використовуйте сире тіло запиту, порівнюйте підписи за сталий час, відхиляйте timestamp старше п’яти хвилин і зберігайте X-4ulink-Delivery для ідемпотентності повторів. Webhook має використовувати публічний HTTPS на порту 443.