SerpJet Публичный API доставки
Своя CMS: получение статей, результат доставки и повторы.
- Быстрый старт своей CMS: pull → upsert → result Своя CMS подключается к SerpJet по циклу pull → upsert → result: по расписанию забирайте статьи с ключом аккаунта, сохраняйте их по постоянному идентификатору статьи и сообщайте результат с адресом публикации.
- X-Api-Key, Project ID, права и безопасная ротация ключа аккаунта Внешний API работает по ключу аккаунта в заголовке X-Api-Key и Project ID в параметрах. Ключ один на все проекты аккаунта: его замена отключает прежний ключ сразу во всех интеграциях.
- Справочник публичных методов, параметров, схем и примеров Публичный API доставки: pull новых статей и обновлений, result по доставке, исправление адреса публикации и CSV-фид Tilda. Все методы под /external/ с заголовком X-Api-Key.
- Новые статьи и улучшения: различия жизненного цикла Новые статьи и обновления опубликованных приходят разными методами: /articles/new/pull и /articles/improvements/pull. Отклонение обновления не снимает статью с публикации.
- Polling, тайм-аут, повтор результата и идемпотентность Опрашивайте pull-методы по расписанию; пустой ответ не означает конец очереди. Если ответ на result потерялся, повторите тот же запрос с тем же delivery_id — повтор безопасен и не меняет статью.
- article_id, delivery_id, article_identity, capability и защита от дублей delivery_id — номер версии для доставки, article_id и article_identity — постоянная статья. Записывайте статью в CMS по article_identity и передавайте заголовок X-SerpJet-Capabilities: stable-article-identity-v1, чтобы получать все доставки без риска дублей.
- HTML, JSON-LD, обложки, иллюстрации и безопасная обработка содержимого Поле content — HTML статьи с иллюстрациями в тегах figure, cover — обложка WebP с размерами и alt, json_ld — разметка для вставки в script type=application/ld+json. Обрабатывайте HTML безопасно и не дублируйте заголовок.
- Исправить URL публикации с проверкой предыдущего значения Если адрес опубликованной статьи изменился, вызовите PATCH /external/articles/{article_id}/publication-url с новым адресом и, для защиты от гонок, прежним адресом в expected_external_url.
- Ошибки 401 / 404 / 409 / 429, superseded и пустая очередь Коды ответов внешнего API: 401 — нет или неверный ключ, 404 — проект, доставка или статья не найдены, 409 — конфликт состояния, 429 — превышен лимит. Пустой ответ pull — не ошибка.
- CSV-фид Tilda для разработчика GET /external/tilda/feed.csv?project_id= возвращает CSV для импорта в Tilda Потоки с ключом API. Выгрузка имеет те же побочные эффекты, что и кнопка «Скачать CSV»: записывает дату экспорта и ожидаемые адреса.