API сокращателя ссылок: 30-минутный быстрый старт на пяти языках

API сокращателя ссылок — одна из тех небольших интеграций, которые обычно висят в бэклоге инженерной команды. Три эндпоинта, заголовок аутентификации, JSON-полезная нагрузка. Страница документации обещает первый успешный вызов через пять минут. Но затем в продакшен приходит трафик, логика повторных попыток создает дубликаты ссылок, панель управления заполняется вариантами /foo-1, /foo-2, /foo-3 для одного и того же адреса назначения, и кто-то заводит тикет.

В этом посте мы разберем реальный процесс интеграции. Аутентификация, первый вызов, четыре эндпоинта, которые покрывают большинство сценариев, идемпотентность, обработка ошибок, лимиты запросов (rate limits) и нюансы продакшена, которые пропускают «пятиминутные» руководства. Примеры кода на TypeScript, Python, Go, Ruby и PHP: первые три через официальные SDK (@elido/sdk, elido-python, github.com/elido/elido-go), последние два — через обычные HTTP-клиенты.

Предварительные условия#

Войдите в панель управления, перейдите в /settings/api и создайте персональный токен доступа (personal access token). Токены привязаны к области рабочего пространства (workspace) — токен, выданный в рабочем пространстве A, не может создавать ссылки в рабочем пространстве B. Токены сервисных аккаунтов (для систем CI, внутренних инструментов, интеграций machine-to-machine) создаются на том же экране в тарифах Pro и выше; они имеют явные области доступа (links:write, analytics:read, domains:write) и ротируются независимо от персональных токенов.

Базовый URL — https://api.elido.app/v1. Домены редиректа (f.elido.me, s.elido.me, b.elido.me) отделены от поверхности API. Ваши короткие ссылки работают на доменах редиректа, а API предназначен для их создания, изменения и чтения.

Спецификация OpenAPI опубликована по адресу https://api.elido.app/v1/openapi.json и соответствует стандарту OpenAPI 3.1. Официальные SDK генерируются на основе этой спецификации и обновляются с каждым релизом API; вы также можете сгенерировать собственный клиент на любом языке, поддерживающем OpenAPI.

Первый вызов#

Создадим короткую ссылку из целевого URL. Пять строк на TypeScript:

import { Elido } from "@elido/sdk";

const elido = new Elido({ token: process.env.ELIDO_TOKEN! });

const link = await elido.links.create({
  destinationUrl: "https://shop.example.com/spring-sale",
});

console.log(link.shortUrl); // https://s.elido.me/abc123

Python:

from elido import Elido

client = Elido(token=os.environ["ELIDO_TOKEN"])

link = client.links.create(
    destination_url="https://shop.example.com/spring-sale",
)

print(link.short_url)  # https://s.elido.me/abc123

Go:

import "github.com/elido/elido-go/v2/elido"

client := elido.NewClient(elido.WithToken(os.Getenv("ELIDO_TOKEN")))

link, err := client.Links.Create(ctx, &elido.LinkCreateInput{
    DestinationURL: "https://shop.example.com/spring-sale",
})
if err != nil {
    return fmt.Errorf("create link: %w", err)
}

fmt.Println(link.ShortURL)

Ruby (без официального SDK — используем net/http):

require "net/http"
require "json"

uri = URI("https://api.elido.app/v1/links")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV['ELIDO_TOKEN']}"
req["Content-Type"] = "application/json"
req.body = { destination_url: "https://shop.example.com/spring-sale" }.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
link = JSON.parse(res.body)
puts link["short_url"]

PHP (Guzzle):

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.elido.app/v1/']);

$res = $client->post('links', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('ELIDO_TOKEN')],
    'json'    => ['destination_url' => 'https://shop.example.com/spring-sale'],
]);

$link = json_decode((string) $res->getBody(), true);
echo $link['short_url'];

Все пять вариантов дают одинаковый результат. Тело ответа содержит короткий URL, канонический ID ссылки, ID рабочего пространства и временную метку создания. Слаг (slug) — в примере выше это abc123 — генерируется сервером, если вы не передали custom_slug в запросе. Алфавит слага — base62 ([0-9A-Za-z]); длина по умолчанию — шесть символов.

Четыре эндпоинта, которые вы действительно будете использовать#

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

Создание ссылки#

POST /v1/links принимает целевой URL и дополнительные поля:

custom_slug — слаг, который вы выбираете сами (должен быть уникальным в пределах рабочего пространства).
domain_id — для ссылок на кастомных доменах; если не указано, используется основной домен рабочего пространства.
tags — массив строк в свободной форме для организации ссылок.
utm — параметры кампании, которые будут добавлены к целевому URL при редиректе.
expires_at — временная метка ISO 8601, после которой ссылка будет возвращать 410 Gone.
password — если установлено, перед перенаправлением будет отображаться страница запроса пароля.
metadata — произвольный JSON-объект, который не интерпретируется при редиректе; полезен для ваших собственных ключей связки.

Пользовательский слаг (custom_slug) — это поле, на котором часто обжигаются команды. Если вы передадите слаг, который уже используется другой ссылкой в том же рабочем пространстве, API вернет 409 Conflict. Наивный обработчик повторов, который просто добавляет счетчик (my-slug-1, my-slug-2), создает проблему дубликатов, описанную в начале статьи. Правильное поведение при повторных попытках описано ниже в разделе про идемпотентность.

Чтение ссылки#

GET /v1/links/{id} возвращает полную запись ссылки, включая текущее количество кликов, метку времени последнего клика и все настройки. ID ссылки — это канонический идентификатор: слаги могут меняться (Pro+ поддерживает переименование слагов), а ID — нет.

GET /v1/links?domain_id=…&tag=…&limit=… выводит список ссылок в рабочем пространстве с фильтрами. Пагинация основана на курсорах; значение next_cursor в ответе является непрозрачным и передается обратно в параметре запроса cursor для получения следующей страницы.

Обновление ссылки#

PATCH /v1/links/{id} принимает те же поля, что и создание. Самые частые обновления: изменение целевого URL (полезно для ротации кампаний без перепечатки QR-кодов), изменение тегов, продление expires_at. Обновление слага выполняется через отдельный эндпоинт POST /v1/links/{id}/rename, который настраивает 301 редирект со старого слага на заданный период удержания (по умолчанию 30 дней).

Удаление ссылки#

DELETE /v1/links/{id} выполняет «мягкое» удаление. Ссылка будет возвращать 410 Gone в течение следующих 90 дней, после чего будет удалена окончательно. В панели управления есть раздел «Корзина» с мягко удаленными ссылками; их можно восстановить через интерфейс или через POST /v1/links/{id}/restore в течение 90-дневного окна.

Ключи идемпотентности#

Каждый изменяющий запрос — POST, PATCH, DELETE — принимает заголовок Idempotency-Key. Значение заголовка — произвольная строка до 255 символов; сервер хранит тело ответа и код состояния в течение 24 часов, привязывая их к паре (workspace_id, idempotency_key), и возвращает сохраненный ответ при повторном использовании того же ключа.

Официальные SDK автоматически генерируют ключи идемпотентности, если они не указаны явно. Вы можете их переопределить:

const link = await elido.links.create(
  { destinationUrl: "https://shop.example.com/spring-sale" },
  { idempotencyKey: "order-12345-link" },
);

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

Важный нюанс: кэш идемпотентности живет 24 часа, а не вечно. Повторная попытка через три дня после сбоя задачи создаст новую ссылку. Если ваша интеграция работает с многодневными батчами, сохраните ID ссылки, возвращенный при первом успешном создании, и проверяйте его перед повторным выпуском.

Второй нюанс: идемпотентность работает в рамках рабочего пространства. Один и тот же ключ в двух разных рабочих пространствах создаст две разные ссылки. Это правильная семантика для API с поддержкой нескольких рабочих пространств, но это может удивить команды, ожидающие глобальной уникальности ключа.

Обработка ошибок#

API возвращает стандартные коды состояния HTTP и структурированное тело ошибки:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Workspace rate limit of 100 req/s exceeded. Retry after 1 second.",
    "request_id": "req_01HXYZAB123",
    "retry_after": 1
  }
}

Коды, которые вы будете встречать чаще всего:

400 invalid_request — ошибка валидации полезной нагрузки. Поле message перечисляет конкретные поля. Не повторяйте запрос, исправьте данные.
401 unauthorized — токен отсутствует или невалиден. Не повторяйте запрос без ротации токена.
403 forbidden — у токена нет нужной области доступа. Проверьте список областей доступа токена в /settings/api.
404 not_found — ресурс не существует или у токена нет к нему доступа (мы возвращаем 404 вместо 403, чтобы не раскрывать существование ресурса неавторизованным отправителям).
409 conflict — слаг уже используется или обнаружено одновременное редактирование (PATCH для устаревшей версии). Получите актуальные данные и попробуйте снова.
429 rate_limit_exceeded — сделайте паузу согласно значению retry_after.
500 internal_server_error — ошибка на стороне сервера. Можно безопасно повторить с тем же ключом идемпотентности.
502 bad_gateway, 503 service_unavailable, 504 gateway_timeout — временные проблемы инфраструктуры. Сделайте паузу и повторите запрос.

Официальные SDK реализуют экспоненциальную задержку с джиттером (jitter) для кодов 429, 500, 502, 503 и 504. Они не повторяют запросы с кодами 400, 401, 403, 404 или 409 — это ошибки программирования или конфликты бизнес-логики, а не временные сбои. Кастомные HTTP-клиенты должны следовать тому же паттерну; повтор запроса 400 с той же нагрузкой не даст иного результата.

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

Лимиты запросов (Rate limits)#

Опубликованные лимиты составляют 100 запросов в секунду на рабочее пространство в тарифе Pro, 500 в тарифе Business и индивидуальный лимит в тарифе Enterprise. Бесплатный уровень — 10 запросов в секунду.

Состояние лимитов передается в трех заголовках каждого ответа API:

X-RateLimit-Limit — текущий лимит запросов в секунду.
X-RateLimit-Remaining — количество запросов, оставшихся в текущей секунде.
X-RateLimit-Reset — временная метка Unix, когда счетчик обнулится.

Лимит 100/с реализован по алгоритму token-bucket с возможностью всплеска (burst) до 200 — это значит, что вы можете отправить 200 запросов одновременно, если «ведро» полно, а затем перейти к устойчивой скорости 100/с. Большинство задач по созданию коротких ссылок комфортно укладываются в этот всплеск; интеграции с интенсивной аналитикой, перебирающие исторические события кликов, выигрывают от запаса тарифа Pro.

Для массовых операций в тарифах Business+ эндпоинт POST /v1/links/bulk принимает до 1000 ссылок в одном запросе и считается как одна единица лимита. Это правильный выбор для любой задачи, создающей более сотни ссылок за раз.

Что делают SDK, чего не делает обычный HTTP#

Официальные SDK предоставляют четыре возможности, которые быстро окупаются:

Автоматический повтор с задержкой для кодов состояния, допускающих повтор.
Генерация ключей идемпотентности, если они не указаны явно.
Типизированные ошибки, чтобы вы могли использовать catch (err) { if (err instanceof ElidoRateLimitError) { … } } вместо парсинга JSON в блоках catch.
Итераторы пагинации, благодаря которым эндпоинты со списками предоставляют асинхронные итераторы или генераторы вместо ручной обработки курсоров.

SDK для Go дополнительно предоставляет доступ к базовому HTTP-клиенту для инструментирования — это полезно, если вы хотите подключить его к существующей системе трассировки. Полный обзор представлен на странице возможностей API + SDKs; справочник API опубликован в /docs/api-reference.

Доступ к аналитике#

Эндпоинты аналитики предназначены только для чтения и находятся по адресу /v1/workspaces/{id}/analytics/. Самые частые запросы:

GET .../links/{id}/clicks?from=…&to=… — «сырые» события кликов с пагинацией. Полезно для пайплайнов экспорта.
GET .../timeseries?from=…&to=…&bucket=day — агрегированное количество кликов за период времени.
GET .../breakdown/country?from=…&to=… — распределение по странам.
GET .../breakdown/referrer?from=…&to=… — распределение по реферерам.

Поток «сырых» событий кликов — самый объемный. Рабочее пространство с 10 млн кликов в месяц генерирует около 600 МБ JSON-данных в месяц. Для экспорта в таком масштабе в руководстве по экспорту в ClickHouse описан механизм массового экспорта, который обходит JSON-оболочку и стримит данные напрямую из хранилища аналитики.

Вебхуки для событий кликов#

Вебхуки — это противоположность опросу (polling): вместо того чтобы вы спрашивали API о новых кликах, API доставляет их на ваш эндпоинт. Настройка выполняется в /settings/webhooks:

await elido.webhooks.create({
  url: "https://your-app.example/webhooks/elido",
  events: ["link.click", "link.created", "link.expired"],
  secret: process.env.WEBHOOK_SIGNING_SECRET,
});

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

Семантика доставки — «как минимум один раз» (at-least-once) с экспоненциальной задержкой до максимального срока удержания в 72 часа. Подробности о структуре данных и поведении при повторах читайте в посте вебхуки против опроса.

Практический пример: автоматизация кампаний#

Интеграция, которая чаще всего мотивирует к переходу на API, выглядит так. Ваша система автоматизации маркетинга создает кампанию в Customer.io или HubSpot. При публикации кампании срабатывает хук. Ваш обработчик создает короткую ссылку, прикрепляет ее к записи кампании и отправляет обратно в инструмент управления кампаниями для подстановки в шаблон письма.

На TypeScript:

import { Elido } from "@elido/sdk";

const elido = new Elido({ token: process.env.ELIDO_TOKEN! });

export async function onCampaignPublished(campaign: Campaign) {
  const link = await elido.links.create(
    {
      destinationUrl: campaign.destinationUrl,
      tags: ["campaign", `campaign:${campaign.id}`, campaign.channel],
      utm: {
        source: campaign.channel,
        medium: "email",
        campaign: campaign.slug,
      },
      metadata: { campaign_id: campaign.id, batch: campaign.batchId },
    },
    {
      idempotencyKey: `campaign-${campaign.id}-link`,
    },
  );

  await campaignStore.update(campaign.id, { shortUrl: link.shortUrl });
  return link;
}

Ключ идемпотентности вычисляется на основе ID кампании. Если хук публикации кампании сработает дважды (а вебхуки доставляются по принципу at-least-once), второй вызов вернет ту же ссылку без создания дубликата. Поле metadata хранит ваши собственные ключи связки, чтобы вы могли соотнести события кликов Elido с кампанией без парсинга тегов.

Для сквозной атрибуции кампаний с UTM-шаблонами и передачей конверсий ознакомьтесь с материалом отслеживание UTM от начала до конца.

Чего еще нет в API#

Две вещи, о которых часто спрашивают, но которые пока недоступны:

Единый GET-запрос аналитики для ссылки, возвращающий все распределения за один вызов. Текущая модель требует отдельных вызовов для кликов, стран, рефереров, устройств и временных рядов. Агрегация есть в планах; пока что SDK параллелят эти запросы с помощью одного вспомогательного метода.
Повтор (replay) вебхуков через API. Панель управления отображает историю доставок вебхуков и поддерживает повторную отправку, но в API этого пока нет. Это также стоит в планах.

Если функция есть в спецификации OpenAPI, она поддерживается. Если она есть в этом посте, но ее нет в спецификации — считайте ее планируемой, а не гарантированной.

Что еще почитать#

Что такое смарт-ссылки — базовый материал по разделу функций; рассказывает, как движок редиректа обрабатывает ссылки на границе сети (edge).
Вебхуки против опроса для отслеживания кликов — когда какой паттерн интеграции использовать.
Отслеживание конверсий на стороне сервера через короткие ссылки — расширение использования API в потоке передачи конверсий.
Массовый импорт кампаний из Google Таблиц — практический пример использования эндпоинта массовых операций.
Операционное руководство: гайд по MCP-серверу для подключения поверхности API Elido к Claude, Cursor и другим клиентам с поддержкой MCP.
Разделы продукта: /features/api-sdks и /solutions/developers.