SEO-проекты · token

events События проекта

Группа events переносит в проект журнал изменений сайта из вашей CRM: события появляются на графиках позиций, видимости и трафика и в блоке «События» сводки — так же, как добавленные вручную или загруженные из файла. Лимиты не тратятся.

Адрес
/projects/api/v1/events/<метод>
Доступ
types — любой доступ к проекту; add — владелец или доступ на запись. Промо- и тестовый ключи не принимаются
Лимиты
не тратит

Добавить события

POST /projects/api/v1/events/add

Добавляет до 1000 событий за запрос. Проверка «всё или ничего»: если хотя бы в одном событии ошибка, не добавляется ни одно, а в result.errors приходят ошибки, сгруппированные по виду, с номерами событий в массиве (с 1). Так повторная отправка исправленной пачки не задвоит события.

Одно событие можно передать и без массива — полями date, name и т. д. на верхнем уровне.

Дубли пропускаются: событие с той же датой и названием (без учёта регистра), что уже есть в проекте или выше в этой же пачке, не добавляется и попадает в result.skipped. Поэтому журнал можно отправлять целиком, не отслеживая, что уже передано.

Параметры query и JSON-тело

  • token string обязательный
    Ключ API владельца проекта или пользователя с доступом на запись. Промо- и тестовый ключи не принимаются.
  • project_id int обязательный
    ID проекта. Виден в адресе страницы проекта и в ответе projects/get.
  • events array обязательный
    События. Поля события:
    • date — обязательно, ДД.ММ.ГГГГ или ГГГГ-ММ-ДД;
    • name — обязательно, до 255 символов;
    • type — необязательно: ID или название типа из events/types. Не передан или пустой — «Ручное событие» (ID 20), как у событий из файла. Незнакомое название станет новым типом проекта;
    • description — описание;
    • url — URL документа, к которому относится событие: http(s)://… или адрес без схемы;
    • work_time — трудозатраты в часах, число от 0 до 1000.

Ответ

  • result.created int
    Сколько событий добавлено.
  • result.skipped int
    Сколько пропущено как уже существующие.

Типы событий

GET /projects/api/v1/events/types

Общие типы событий и типы, созданные в проекте. По ним события раскрашиваются и фильтруются на графиках. Для поля type в events/add подходят и ID, и название.

Параметры query

  • token string обязательный
    Ключ API из настроек аккаунта — тот же, что key у методов инструментов.
  • project_id int обязательный
    ID проекта. Виден в адресе страницы проекта и в ответе projects/get.

Ответ

  • result[].id int
    ID типа.
  • result[].name string
    Название типа.

Ошибки

КодСообщениеКогда
50 access error Ключ не передан или не найден, проекта нет, или у владельца ключа нет к нему доступа. Промо- и тестовый ключи не принимаются, для add не хватит и доступа только на чтение.
51 wrong project id Не передан project_id.
52 wrong request data add: ни одно событие не добавлено. result.message — итог, result.errors — ошибки по видам: текст, номера событий (rows) и их число; failed_rows и total_rows — сколько событий с ошибками и сколько всего.

Загрузка из файла

То же самое без API — в блоке «События» на сводке проекта: «Добавить событие» → «Загрузить из файла». Файл XLSX или CSV с колонками: дата, название, описание, URL документа, трудозатраты. Шаблон общий с GEO-проектами, тип в файле не задаётся — все события из файла получают тип «Ручное событие».

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