REST API, который умеет всё то же, что и панель

Две области действия ключей, потому что вызывающих сторон тоже две

Ключ рабочего пространства действует внутри одного пространства: ссылки, аналитика, доступные ему домены и собственное потребление лимитов. Партнёрский ключ действует в масштабах бизнеса: клиенты и их подписки, продаваемые вами тарифы, все домены, платежи с разбивкой по комиссиям, выплаты и сводный обзор аналитики. Префиксы у них заметно разные, поэтому ключ, вставленный не в тот сервис, сразу отказывает, а не делает что-то неожиданное.

Ключи создаются в панели, показываются один раз и хранятся только как хеш. У каждого ключа свой список прав, поэтому интеграции, которой нужно только читать аналитику, можно выдать ключ, не способный ничего создать или удалить. Ключу можно задать срок действия и мгновенно его отозвать, а время последнего использования отображается — именно так находится интеграция, о настройке которой никто не помнит.

• ✓POST /links, GET /links, GET /links/{id}, PATCH /links/{id}, DELETE /links/{id}
• ✓POST /links/bulk — до ста ссылок за вызов
• ✓GET /links/{id}/qr — PNG или SVG, с пресетом и размером
• ✓GET /analytics/summary, /timeseries, /breakdown, /links/top, /export.csv
• ✓GET и POST /domains — подключить домен и прочитать нужные ему DNS-записи
• ✓GET /workspace — лимиты тарифа и текущее потребление
• ✓GET /partner/clients, /partner/plans, /partner/payments, /partner/payouts

Предсказуемость в том, что важно в три часа ночи

Каждая ошибка имеет одну и ту же форму — код, человекочитаемое сообщение и адрес документации, — поэтому клиентская библиотека может ветвиться по коду, а человек прочитать сообщение. Списки разбиваются на страницы курсорами, а не номерами страниц, и результат остаётся стабильным, пока под вами создаются новые ссылки.

Лимит частоты по умолчанию — шестьсот запросов в минуту для ключа рабочего пространства и вдвое больше для партнёрского ключа, а сам лимит, остаток и время сброса возвращаются заголовками в каждом ответе. Превышение даёт 429 с заголовком Retry-After, а не разрыв соединения, поэтому воспитанные клиенты корректно отступают. Экспорт аналитики идёт потоком, поэтому сто тысяч строк не требуют держать отчёт в памяти ни с одной стороны.

Webhook для событий, которые иначе пришлось бы опрашивать

Зарегистрируйте эндпоинт и получайте создание, изменение и удаление ссылок; события жизненного цикла домена, когда имя хоста переходит из ожидания SSL в активное состояние или в ошибку; а на партнёрских ключах — события подписок и платежей клиентов. Опрос эндпоинта статуса домена раз в минуту — ровно тот код, который никому не следует писать.

Каждая доставка несёт заголовок подписи HMAC-SHA256 с отметкой времени, чтобы ваш приёмник мог убедиться, что данные пришли от нас и не являются повтором. Неудавшиеся доставки повторяются пять раз с растущими паузами — минута, пять, тридцать, два часа, двенадцать, — после чего эндпоинт помечается неисправным и уходит письмо. Тестовое событие отправляется из панели, поэтому интеграцию можно проверить до того, как от неё начнёт что-то зависеть.

Документация, сгенерированная из работающего кода

Спецификация OpenAPI собирается из тех же схем, по которым API проверяет входные данные, а значит, она не может разойтись с реализацией так, как расходится написанный руками справочник. Она публикуется файлом, который можно скормить генератору клиентов, и отрисовывается как просматриваемый справочник на этом сайте, рядом с написанными вручную руководствами по быстрому старту, пагинации, ошибкам, webhook и лимитам частоты.

Первая версия заморожена. Новые поля могут добавляться, существующее поведение не изменится, а всё, что сломало бы вызывающую сторону, ждёт второй версии по другому пути. Если вы выбираете сокращатель, чтобы строить на нём, а не просто пользоваться, это обещание стоит больше любого отдельного эндпоинта.

Код, который говорит сам за себя

curl -X POST https://api.linkprofit.com/v1/links \
  -H 'Authorization: Bearer lp_live_XXXXXXXX' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/spring-collection",
    "domain_id": "dom_8kq2vn41",
    "slug": "spring",
    "title": "Spring collection",
    "utm": {
      "utm_source": "newsletter",
      "utm_medium": "email",
      "utm_campaign": "spring-2026"
    }
  }'

const response = await fetch("https://api.linkprofit.com/v1/links", {
  method: "POST",
  headers: {
    Authorization: "Bearer lp_live_XXXXXXXX",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/spring-collection",
    domain_id: "dom_8kq2vn41",
    slug: "spring",
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(error.code + ": " + error.message);
}

const link = await response.json();
console.log(link, response.headers.get("X-RateLimit-Remaining"));

import requests

response = requests.post(
    "https://api.linkprofit.com/v1/links",
    headers={"Authorization": "Bearer lp_live_XXXXXXXX"},
    json={
        "url": "https://example.com/spring-collection",
        "domain_id": "dom_8kq2vn41",
        "slug": "spring",
    },
    timeout=10,
)

if response.status_code == 429:
    raise SystemExit("rate limited, retry after " + response.headers["Retry-After"])

response.raise_for_status()
print(response.json())