Руководство по API ОРД v5.0

Что такое ОРД и зачем нужен этот API

ОРД (оператор рекламных данных) - организация, через которую участники рынка интернет-рекламы передают сведения о рекламе в ЕРИР (Единый реестр интернет-рекламы Роскомнадзора). Обязанность передавать такие сведения установлена ст. 18.1 Федерального закона "О рекламе" (№ 38-ФЗ).

Через API ОРД от SberAds вы:

• регистрируете контрагентов (рекламодателей, агентств, ОРС, рекламораспространителей) и их площадки;
• регистрируете договоры между контрагентами;
• получаете маркер (erid) для каждого рекламного креатива - без него креатив нельзя размещать;
• отчитываетесь актами и статистикой.

Каждый объект проходит два этапа: сначала он регистрируется в ОРД, затем ОРД передаёт его в ЕРИР. Текущее положение объекта видно в поле state (см. Статусная модель).

API Endpoints

Актуальная машиночитаемая спецификация: https://api.ord-lab.ru/swagger-api-v5.0/index.html.

Версия v5.0 работает с новым API ЕРИР (v8). Версии /api/v4 ... /api/v4.9 продолжают работать со старым API ЕРИР (v7) и будут выведены из эксплуатации с 1 октября 2026г. Всем интеграциям рекомендуется перейти на v5.0 - перечень отличий приведён в разделе Миграция с v4 на v5.

Протокол

Для реализации API используется протокол HTTP REST. Типы данных определяются в соответствии со спецификацией OpenAPI: спецификация публикуется в двух форматах - Swagger 2.0 и OpenAPI 3.0. Тело запроса и ответа - application/json в кодировке UTF-8 (исключение - пакетная загрузка файлов, см. раздел Пакетная загрузка).

Используются следующие методы HTTP:

Запросы PUT и POST могут выполняться частично асинхронно (то есть уже после возврата управления из запроса). При этом:

• регистрация объекта в ОРД выполняется всегда синхронно;
• загрузка медиафайлов в хранилище ОРД может выполняться синхронно или асинхронно;
• регистрация сущности в ЕРИР происходит после загрузки медиафайлов и также может выполняться синхронно или асинхронно.

Поэтому ответ 202 Accepted - нормальный результат: объект принят ОРД, но подтверждение от ЕРИР ещё не получено. Итоговый статус нужно опрашивать методом GET /{сущность}/{id}/status или HEAD. Подробнее о статусной модели сущностей в разделе Статусная модель сущностей. 

Коды ответов HTTP

Аутентификация

Поддерживается единственный метод аутентификации - Bearer (JWT). Токен передаётся в заголовке каждого запроса:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

В случае ошибки аутентификации возвращается ответ с кодом 401 Unauthorized.

Полный запрос целиком:

curl -X POST 'https://api.ord-lab.ru/api/v5.0/organizations' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
        "type": "ul",
        "isOrs": false,
        "isRr": false,
        "inn": "7705008280",
        "kpp": "770501001",
        "name": "ООО \"Ромашка\"",
        "address": "г. Москва, ул. Примерная, д. 1, оф. 5"
      }'

Дальше в руководстве примеры приводятся в сокращённой записи - метод, путь и тело запроса.

Токены выпускаются и отзываются через API - см. раздел Токены. Рекомендации:

• выпускайте отдельный токен на каждую интеграцию, чтобы отозвать её можно было независимо от остальных;
• храните токен как секрет: он даёт полный доступ к данным вашего namespace;
• задавайте daysToLive исходя из регламента ротации - максимум 3650 дней (10 лет), минимум 1 день;
• при компрометации немедленно вызовите POST /tokens/revoke/{id}.

Ограничение частоты запросов (rate limiting)

Для защиты API от перегрузки и обеспечения стабильной работы для всех клиентов применяется механизм ограничения частоты запросов (rate limit).

Ограничение реализовано по принципу корзины токенов (token bucket):

1. У каждого клиента есть персональная корзина с токенами — она не влияет на корзины других клиентов.
2. Каждый запрос расходует один токен из корзины.
3. Корзина автоматически пополняется с заданной периодичностью.
4. Если токенов в корзине не хватает, API возвращает ошибку 429 Too Many Requests

Ручки с активным Rate Limit

Ограничение частоты запросов включено для следующих эндпоинтов:

Группа 1: Удаление
 

Эндпоинты:

Группа 2: Статистика в актах
 

Эндпоинты:

Сокращённый ответ (short)

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

Два равнозначных способа:

POST /api/v5.0/creatives?short=true

POST /api/v5.0/creatives
Accept: application/vnd.ord-lab.ru.api.entity.short+json

Отличие от v4. В версиях v4.x медиатип содержал номер версии: application/vnd.ord-lab.ru.api.v3.entity.short+json. В v5.0 используется медиатип без номера версии: application/vnd.ord-lab.ru.api.entity.short+json. Параметр ?short=true работает одинаково в обеих версиях.

Расширенный ответ статистики (extended)

Для группы /creative-statistics доступен расширенный формат ответа. Включается параметром ?extended=true либо заголовком:

Accept: application/vnd.ord-lab.ru.api.v2.creative-statistics.extended+json

Заголовки ответов (Custom HTTP Response Headers)

Данные заголовки могут присутствовать в ответах каждого из запросов API. Они дублируют поля объекта Status и удобны для метода HEAD, у которого нет тела ответа.

Статусная модель

Если объект "завис" в PENDING из-за временной ошибки, ОРД сам поставит его в очередь на повторную отправку с интервалом от одного часа. Не дожидаясь этого, повторную попытку можно запустить вручную методом POST /{сущность}/{id}.

Типовые сценарии жизненного цикла

Жизненный цикл сущности зависит от того, зарегистрированы ли вышестоящие объекты в ЕРИР на момент её создания. Ниже описаны два основных сценария.

Сценарий 1: 

Первичная регистрация всех вышестоящих объектов
Этот сценарий возникает, когда вы создаете полную цепочку сущностей "с нуля" — от организации до креатива или акта. Ни один из вышестоящих объектов еще не прошел проверку в ЕРИР.

Пример ситуации:

Вы регистрируете новую организацию, новую площадку, новый контракт и новый креатив.

Все объекты создаются последовательно, но ни один из них еще не проверен в ЕРИР.

Путь статусов

PENDING → ACCEPTED → APPROVED/DECLINED

Сценарий 2: 

Создание при наличии ранее утвержденных вышестоящих объектов
Этот сценарий возникает, когда вы создаете сущность в рамках уже существующей и проверенной цепочки объектов. Вышестоящие объекты уже имеют статус APPROVED на момент создания.

Пример ситуации:

У вас уже есть контракт, успешно прошедший проверку в ЕРИР (статус APPROVED).

Вы создаете новый креатив по этому контракту.

Путь статусов

ACCEPTED → APPROVED/DECLINED

Объект Status

Данный объект возвращается в ответ на запросы POST и PUT со статусом 200, 201, 202, а также методом GET /{сущность}/{id}/status. Часть полей объекта дублирует соответствующие заголовки ответов.

Пример:

{
  "id": "bff52b20-a7a3-4cea-a516-2618b5e1e960",
  "state": "APPROVED",
  "erirRegisteredAt": "2026-08-01T13:20:50.052+03:00",
  "marker": "2Ranyn7YfuE"
}

Методы, принимающие массив объектов (POST /creative-statistics, POST /invoices/creatives), в сокращённом режиме возвращают массив статусов:

{
  "statuses": [
    { "id": "7d04bccb-1a0e-4ce1-9b30-ae06ca51cbf1", "state": "ACCEPTED" },
    { "id": "c1a6d4b8-2f37-4e55-9d0a-8b7c6e5f4a31", "state": "PENDING" }
  ]
}

Объект Error

Данный объект возвращается в ответ на запросы, имеющие статусные коды 4xx и, в ряде случаев, 5xx.

Пример ответа при непройденном контроле:

{
  "requestId": "0e29c0f6-6d5e-4a30-9f5a-2f4d2b2a1f77",
  "status": 400,
  "code": "parameter-error",
  "title": "invalid parameter value",
  "detail": "I_185: Не передан обязательный массив \"intermediaryReportIdList\" для актов типа \"Акт на вознаграждение посредника\""
}

Коды ошибок

Объект Pagination - постраничный вывод

Данный объект возвращается в составе ответа на списочные запросы (POST /{сущность}/search) в поле meta.

Все фильтры поиска дополнительно поддерживают поля page, limit, sorting (массив полей сортировки) и cursor (курсорная пагинация - начать выборку с указанного элемента; предпочтительна при обходе больших выборок).

{
  "data": [ { "...": "объекты запрошенной сущности" } ],
  "meta": { "page": 1, "limit": 100, "total": 3471 }
}

Общие принципы работы с идентификаторами

Все системные идентификаторы объектов в ОРД имеют формат UUID v4. Идентификаторы генерируются автоматически при создании сущности методом POST. Задать собственное значение системного идентификатора невозможно. Но есть исключения из правил:

1. feedId (товарный фид) - Идентификатор контейнера товарного фида генерируется клиентом и передается при создании.
2. externalId (площадки, медиаданные креатива) - Необязательный пользовательский идентификатор. Присваивается площадке или медиаданным креатива для внутренней идентификации объекта в системе клиента. Используется исключительно для удобства самого пользователя и не влияет на логику работы API.

Специальные идентификаторы

CID - используется, когда договор в ОРД не регистрировался в вашем ЛК ОРД, но на него нужно ссылаться. Например, вы получили cid от другого участника цепочки, который зарегистрировал договор в своем ЛК ОРД.

Поля cid и contractId являются взаимоисключающими — при создании или обновлении сущности можно передать только одно из них:

• contractId - если договор зарегистрирован в данном ЛК ОРД.
• cid- если договор был зарегистрирован в ОРД другим участником цепочки. 

Данные в примерах

Все примеры в этом руководстве построены на одном наборе вымышленных участников и объектов. Идентификаторы сквозные: договор, на который ссылается акт в разделе "Акты", - тот же самый, что зарегистрирован в разделе "Договоры". Реквизиты, ссылки и наименования вымышлены; совпадения с действующими организациями и сайтами случайны.

Домены *.example, example.com и подобные зарезервированы стандартом для документации и в сети не резолвятся - в рабочих запросах указывайте собственные адреса.

Порядок вызовов при первом подключении

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

Выдерживать паузы между шагами не нужно: достаточно соблюдать порядок вызовов, а очерёдностью отправки в ЕРИР ОРД управляет сам. Как именно - ниже.

Ожидание зависимостей

Объект, который ссылается на другие сущности, после регистрации в ОРД не уходит в ЕРИР немедленно. Сначала он попадает в очередь ожидания и остаётся в статусе PENDING, пока все объекты, на которые он ссылается, не будут зарегистрированы в ЕРИР. Только после этого ОРД отправляет его дальше.

Поэтому связанные объекты можно отправлять подряд, не дожидаясь APPROVED по каждому предыдущему. Договор допустимо зарегистрировать сразу вслед за контрагентами, акт - вслед за договором.

Кого ждёт каждая сущность:

Что из этого следует на практике:

• Порядок вызовов всё равно важен. Ожидание снимает требование ждать APPROVED, но не отменяет того, что ссылаться можно только на уже созданный в ОРД объект: его идентификатор нужно откуда-то взять.
• Ожидание не бесконечно. Попытки повторяются с интервалом порядка трёх часов и в какой-то момент прекращаются. Если объект надолго завис в PENDING, ищите причину среди тех, кого он ждёт.
• При отклонении сущности в ЕРИР (статус DECLINED) отказ распространяется по цепочке зависимостей вниз. Все нижестоящие сущности, которые ожидали подтверждения отклоненной сущности, также автоматически переводятся в статус DECLINED. Если ЕРИР отклоняет контракт, все креативы и акты, привязанные к нему, также получают статус DECLINED. 

Разбираться нужно с первопричиной, а не с последним объектом в цепочке. После внесения изменений в объект, отклоненный ЕРИР необходимо все последующие объекты переотправить через запрос POST /{сущность}/id с тем же содержимым. 

• Статус удобнее запрашивать методом HEAD - он отдаёт ORD-State в заголовках и не тратит трафик на тело ответа.