events События проекта
Группа events переносит в проект журнал изменений сайта из вашей CRM: события появляются на графиках позиций, видимости и трафика и в блоке «События» сводки — так же, как добавленные вручную или загруженные из файла. Лимиты не тратятся.
- Адрес
/projects/api/v1/events/<метод>- Доступ
types— любой доступ к проекту;add— владелец или доступ на запись. Промо- и тестовый ключи не принимаются- Лимиты
- не тратит
Добавить события
/projects/api/v1/events/add
Добавляет до 1000 событий за запрос. Проверка «всё или ничего»: если хотя бы в одном событии ошибка, не добавляется ни одно, а в result.errors приходят ошибки, сгруппированные по виду, с номерами событий в массиве (с 1). Так повторная отправка исправленной пачки не задвоит события.
Одно событие можно передать и без массива — полями date, name и т. д. на верхнем уровне.
Дубли пропускаются: событие с той же датой и названием (без учёта регистра), что уже есть в проекте или выше в этой же пачке, не добавляется и попадает в result.skipped. Поэтому журнал можно отправлять целиком, не отслеживая, что уже передано.
Параметры query и JSON-тело
-
tokenstring обязательныйКлюч API владельца проекта или пользователя с доступом на запись. Промо- и тестовый ключи не принимаются. -
project_idint обязательныйID проекта. Виден в адресе страницы проекта и в ответе projects/get. -
eventsarray обязательныйСобытия. Поля события:date— обязательно,ДД.ММ.ГГГГилиГГГГ-ММ-ДД;name— обязательно, до 255 символов;type— необязательно: ID или название типа из events/types. Не передан или пустой — «Ручное событие» (ID20), как у событий из файла. Незнакомое название станет новым типом проекта;description— описание;url— URL документа, к которому относится событие:http(s)://…или адрес без схемы;work_time— трудозатраты в часах, число от 0 до 1000.
Ответ
-
result.createdintСколько событий добавлено. -
result.skippedintСколько пропущено как уже существующие.
Типы событий
/projects/api/v1/events/types
Общие типы событий и типы, созданные в проекте. По ним события раскрашиваются и фильтруются на графиках. Для поля type в events/add подходят и ID, и название.
Параметры query
-
tokenstring обязательныйКлюч API из настроек аккаунта — тот же, чтоkeyу методов инструментов. -
project_idint обязательныйID проекта. Виден в адресе страницы проекта и в ответе projects/get.
Ответ
-
result[].idintID типа. -
result[].namestringНазвание типа.
Ошибки
| Код | Сообщение | Когда |
|---|---|---|
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-проектами, тип в файле не задаётся — все события из файла получают тип «Ручное событие».