Документация

UUID, короткие ссылки и совместимость

У сайтов, сценариев, прогонов и других рабочих ресурсов есть публичный UUID. Вы можете передавать его в API и сохранять ссылки, не привязываясь к порядковому номеру объекта. Ранее созданные ресурсы и адреса с числовыми ID продолжают работать.

Какой формат выбрать

Запрос	Идентификаторы в ответе
`/api/v1/…` без дополнительного заголовка	Прежние числовые ID
`/api/v1/…` с `X-Identifier-Format: uuid`	Публичные UUID
`/api/v2/…`	Публичные UUID по умолчанию

В v2 доступны те же рабочие методы, что в v1. Авторизация, права, лимиты и тело результата не меняются, кроме объявленных полей идентичности. Токен прямой выгрузки и адрес /api/export/… остаются отдельным интерфейсом.

Для новой интеграции выбирайте v2. Действующую интеграцию можно оставить на v1 и перевести на новый формат после проверки собственного клиента.

Первый запрос с UUID

curl --fail-with-body "$BASE/api/v2/sites" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Accept: application/json'

Тот же выбор в v1:

curl --fail-with-body "$BASE/api/v1/sites" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'X-Identifier-Format: uuid' \
  -H 'Accept: application/json'

BASE и API_KEY задайте в защищённых переменных окружения. Не вставляйте ключ в ссылку или клиентский код страницы. Как выдать API-ключ.

В UUID-режиме известный объект содержит такие поля. Пример сокращён:

{
  "id": "019a0740-dc00-7abc-8def-0123456789ab",
  "public_id": "019a0740-dc00-7abc-8def-0123456789ab",
  "short_id": "~1CULXneEtSGKRmiQRog8Zx",
  "legacy_id": 175,
  "code": "catalog",
  "name": "Каталог"
}

id удобно хранить как основной ключ объекта в своей программе. public_id явно называет канонический UUID, short_id подходит для короткой ссылки, legacy_id позволяет сопоставить ответ с прежней интеграцией. Значения условные: всегда берите действительные идентификаторы из своей установки.

Как передавать идентификатор

Объявленные параметры ресурса принимают три формы. Например, для одного сайта:

/api/v2/sites/175
/api/v2/sites/019a0740-dc00-7abc-8def-0123456789ab
/api/v2/sites/~1CULXneEtSGKRmiQRog8Zx

В вашем окружении эти три адреса указывают на один объект, если значения взяты из одной его карточки. Тот же принцип применяется к site_id, script_id, version_id, agent_id, connection_id и другим объявленным ссылкам в query и JSON-теле. Передавайте null, если поле необязательное и связь не выбрана.

{
  "site_id": "019a0740-dc00-7abc-8def-0123456789ab",
  "name": "Ежедневный каталог"
}

Этот пример задаёт сайт при создании сценария. Остальные параметры берите из описания соответствующего метода.

Короткая форма кодирует весь UUID без потери данных. Начальный ~ обязателен, регистр букв значим. Не сокращайте UUID самостоятельно и не убирайте символы. Ошибочное значение не превращается в новый ресурс.

Что остаётся прежним

Ключи собранных записей, артикулы, символьные code и slug.
Номера версий, счётчики, даты, суммы и позиции строк.
Курсоры cursor, next_cursor, after и Last-Event-ID.
Ваши data, params, JSON-поля и содержимое выгрузок.
Уже выданные токены, идентификаторы внешних систем, UUID файлов и артефактов.

В журнале прогона у строки есть публичный id, а поле ответа cursor остаётся числом. Для продолжения передавайте after из cursor последнего ответа. Не подставляйте в after UUID строки журнала.

UUID является адресом ресурса, а не секретом. Человек с чужой ссылкой всё равно должен иметь доступ к нужному пространству и сайту. API-ключ остаётся привязанным к своему пространству независимо от формы ID.

Внутренний SDK сценариев и обмен заданиями с собственным агентом сохраняют свой контракт. Подменять все числа внутри сценария на UUID не требуется.

Как обновить существующий клиент

Сохраните работающий v1-клиент без нового заголовка на время перехода.
В отдельном тестовом запросе включите UUID. Храните ID как строки: не вызывайте parseInt, Number и не вычисляйте следующий ID прибавлением единицы.
Сопоставьте прежние сохранённые объекты с новыми по legacy_id.
Проверьте чтение, фильтры, создание и изменение ресурсов, которыми пользуется клиент.
Переключитесь на v2 или оставьте v1 с заголовком X-Identifier-Format: uuid.

Не переносите числовые ID вручную между разными установками: локальный номер там может принадлежать другому объекту. Сохраняйте публичную идентичность вместе с данными при резервном копировании. Для сортировки используйте дату или другое поле объекта: время выдачи UUID старой записи не является датой её создания.

Подробности отдельных операций: все методы API.