Быстрый старт своей CMS: pull → upsert → result

Как устроен обмен

SerpJet ничего не отправляет на ваш сайт сам. Ваша CMS по расписанию забирает готовые статьи, сохраняет их у себя и сообщает результат. Базовый адрес API — https://serpjet.ru/external/. Интерактивная схема — /external/docs, OpenAPI — /external/openapi.json.

1. Pull — получить новые статьи и обновления опубликованных.
2. Upsert — создать или обновить запись в CMS по постоянному идентификатору статьи.
3. Result — сообщить, принята ли статья, и её публичный адрес.

Подготовка

1. Создайте ключ: проект → «Подключения» → карточка «Внешний API» → «Создать ключ». Сохраните его сразу — полный ключ больше не покажется — X-Api-Key, Project ID, права и безопасная ротация ключа аккаунта.
2. Узнайте Project ID — число в адресе проекта в панели: /panel/projects/7/….

1. Забрать статьи

GET /external/articles/new/pull?project_id=7&limit=20
X-Api-Key: <ваш ключ>
X-SerpJet-Capabilities: stable-article-identity-v1

В ответе — items со снимками статей: delivery_id, article_id, article_identity, title, description, content (HTML), json_ld, cover. Обновления опубликованных статей забираются отдельно: GET /external/articles/improvements/pull — Новые статьи и улучшения: различия жизненного цикла.

2. Сохранить в CMS

• Ищите запись по article_identity (вида serpjet:7:421): если нашли — обновите, нет — создайте. Не используйте delivery_id как ключ записи: это номер версии, а не статьи — article_id, delivery_id, article_identity, capability и защита от дублей.
• Сохраните title, description, content, обложку и разметку json_ld — Справочник публичных методов, параметров, схем и примеров.

3. Сообщить результат

POST /external/articles/new/15/result
X-Api-Key: <ваш ключ>
Content-Type: application/json

{"status": "accepted", "external_url": "https://site.example.com/blog/article-slug"}

accepted переводит статью в «Опубликована» и записывает адрес. rejected — статья отклонена вашей стороной. Для обновлений используйте /external/articles/improvements/{delivery_id}/result.

Расписание и повторы

• Опрашивайте оба pull-метода регулярно, например раз в несколько минут.
• Пустой items не значит, что очередь пуста навсегда — просто продолжайте опрос.
• Если не получили ответ на result, повторите тот же запрос — это безопасно — Polling, тайм-аут, повтор результата и идемпотентность.

Как проверить

После первого accepted статья в панели получит статус «Опубликована» с вашим адресом и каналом публикации. Ошибки — Ошибки 401 / 404 / 409 / 429, superseded и пустая очередь.