API для SEO-статей: схема интеграции для агентства

API для генерации SEO-статей связывает контентный процесс с CMS: система получает готовый материал, проверяет обязательные поля, создаёт или обновляет страницу и возвращает результат публикации. Для агентства это способ убрать ручное копирование, не теряя редакционный контроль. Важно разделить два потока — новые статьи и обновления — и считать публикацию завершённой только после проверки URL, метатегов, HTML и структурированных данных.

В SerpJet генерация настраивается внутри проекта, а внешний API отвечает за доставку подготовленных материалов на сайт. Интеграция работает по pull-модели: CMS сама забирает доступные задания и затем сообщает, принято оно или отклонено. Актуальные методы, параметры и примеры запросов собраны в документации External API SerpJet.

Краткие выводы:

не смешивайте создание новой страницы и обновление существующей;

сохраняйте идентификатор доставки до окончательного результата;

проверяйте контент до записи в CMS и страницу после публикации;

повторяйте только безопасные операции, а спорные материалы отправляйте редактору;

возвращайте итоговый URL, чтобы связать материал в SerpJet с реальной страницей.

Что именно автоматизирует API для SEO-статей

Надёжная интеграция начинается с правильной границы ответственности. SerpJet готовит заголовок, описание, HTML-контент и JSON-LD. CMS отвечает за собственный slug, шаблон страницы, категории, автора, дату публикации и техническую доступность URL. Между ними находится небольшой обработчик: cron-задача, фоновый worker или модуль CMS.

Такой обработчик не должен «угадывать», что делать со статьёй. Он читает тип доставки и выполняет один из двух сценариев. Для нового материала создаётся новая запись. Для улучшения находится уже опубликованная запись и изменяются только согласованные поля. Это защищает комментарии, аналитику, постоянный URL и другие данные, которые живут на стороне сайта.

Поток новых материалов

Обработчик запрашивает новые статьи по идентификатору проекта. В ответе есть идентификатор доставки и данные материала. После локальной проверки CMS создаёт черновик или сразу публикует страницу — это зависит от правил агентства. Затем обработчик отправляет статус accepted вместе с итоговым URL либо rejected с понятной причиной.

Поток обновлений

Улучшения нужно забирать отдельным методом. В таком задании уже может быть URL действующей страницы. CMS сопоставляет его со своей записью, сохраняет резервную версию, применяет изменения и проверяет страницу. Отклонение улучшения не должно удалять старую публикацию: действующая версия остаётся на сайте.

Контракт интеграции: какие данные хранить

Минимальная таблица состояния избавляет от дублей и упрощает разбор ошибок. Её можно хранить в отдельной модели CMS, служебной таблице или очереди задач. Секретный API-ключ в журнал и текст ошибок не записывают.

Поле	Зачем нужно	Практическое правило
delivery_id	Однозначно определяет доставку	Используйте как ключ идемпотентности и не создавайте вторую запись при повторе
article_id	Связывает версии одного материала	Храните рядом с локальным ID страницы
kind	Разделяет новый материал и улучшение	Не отправляйте результат в метод другого потока
external_url	Показывает адрес публикации	После accepted передавайте канонический публичный URL
status	Фиксирует исход обработки	Отправляйте accepted только после локальной проверки
note	Объясняет отказ или особое решение	Пишите короткую причину без ключей, токенов и персональных данных

Как подключить генерацию SEO-статей к CMS

Создайте отдельный проект для сайта и зафиксируйте его project_id. Один обработчик может обслуживать несколько проектов, но состояние доставки нужно хранить раздельно.
Сгенерируйте API-ключ в аккаунте и передавайте его только в заголовке запроса. Ограничьте доступ к конфигурации на стороне сервера.
Настройте периодический запрос новых материалов и улучшений. Не запускайте следующий цикл, пока предыдущий обрабатывает ту же доставку.
До записи в CMS проверьте title, description, content и json_ld. Запретите скрипты, формы, iframe и второй H1, если H1 уже выводит шаблон.
Создайте черновик либо публикацию по правилам проекта. Для обновления сначала найдите существующую запись по сохранённой связи или external_url.
Откройте итоговый URL и проверьте HTTP-ответ, canonical, robots, title, description, один H1, длину текста, JSON-LD и внутренние ссылки.
Только после успешной проверки отправьте accepted и URL. При содержательной ошибке верните rejected с причиной, а при временном сетевом сбое оставьте задачу для безопасного повтора.

Если сайт работает на WordPress, сначала оцените готовый плагин публикации SerpJet: он может закрыть типовой сценарий без разработки собственного клиента. Для нестандартной CMS полезно сверить роли проекта и общий порядок работы в инструкции по SerpJet.

Проверки перед автоматической публикацией

Самая опасная ошибка — считать успешный ответ CMS доказательством качества страницы. Запись могла сохраниться, но шаблон вывел два H1, экранировал HTML или поставил noindex. Поэтому контроль делят на два уровня.

Проверка данных до сохранения

title и slug не заняты другой страницей;
HTML содержит только разрешённые теги и не включает внутренние комментарии редактора;
чистый текст достигает редакционного минимума;
seo title и meta description укладываются в принятые лимиты;
JSON-LD разбирается как объект и соответствует типу страницы;
внутренние ссылки ведут на существующие страницы;
обновление относится к нужной записи, а не к похожему URL.

Проверка страницы после сохранения

публичный URL отвечает без ошибки и лишней цепочки редиректов;
canonical совпадает с итоговым адресом;
страница доступна для индексирования, если публикация предназначена для поиска;
в исходном HTML присутствуют title, meta description и Article JSON-LD;
шаблон выводит ровно один H1;
текст не исчез после фильтрации редактором CMS;
ссылки и CTA отображаются в нужном контексте.

Эти проверки дополняют, а не заменяют редактуру. Для небольшой команды удобно встроить их в редакционный процесс SEO-статей как отдельный технический шлюз перед публикацией.

Повторы, дубли и идемпотентность

Сетевой таймаут не говорит, был ли запрос обработан. Если после таймаута безусловно создать статью повторно, в блоге появится дубль. Поэтому до создания CMS проверяет delivery_id в локальном журнале. Если запись уже создана, обработчик повторно проверяет её URL и завершает исходную доставку, а не создаёт новую.

Безопасно повторять чтение очереди и проверку страницы. Создание и обновление повторяют только при наличии идемпотентного правила. Отправку финального результата не превращают в бесконечный цикл: ответ о том, что доставка уже разрешена, нужно считать сигналом сверить локальное состояние.

Для временных ошибок применяют ограниченное число повторов с растущей паузой. Ошибки данных — пустой title, запрещённый HTML, неизвестная страница для обновления — отправляют в очередь ручного разбора. Так техническая проблема не маскируется под редакционное решение.

Типичные ошибки интеграции

Отправлять API-ключ в URL. Он может попасть в журналы, аналитику и историю запросов.
Смешивать new и improvements в одном обработчике без явного ветвления по kind.
Подтверждать accepted до проверки публичной страницы.
Создавать новую запись для улучшения и тем самым менять URL опубликованной статьи.
Повторять POST после таймаута без проверки delivery_id и локального состояния.
Считать любой HTTP 200 успешной публикацией, не проверяя canonical, robots и содержимое.
Писать в note стек ошибки, конфигурацию или секретные значения.
Автоматически публиковать всё без возможности перевести проект в режим черновиков.

Как выбрать режим для небольшого агентства

Начните с минимального контура: один проект, один сайт, небольшая пачка материалов и публикация в черновики. После нескольких стабильных циклов добавьте автоматический accepted для статей, прошедших все проверки. Обновления лучше включать отдельно, потому что цена ошибки на действующей странице выше.

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

FAQ

Можно ли через API сразу публиковать статью без редактора?

Да, если CMS поддерживает автоматическую публикацию и материал проходит формальные и содержательные проверки. На старте безопаснее создавать черновик. Прямую публикацию включают после того, как команда проверила несколько циклов, настроила журнал доставок и подготовила откат для обновлений.

Чем pull-модель отличается от вебхука?

При pull-модели ваш сайт сам обращается к SerpJet за доступными материалами. Не нужно открывать входящий endpoint и обрабатывать подпись вебхука. Взамен CMS должна запускать задачу по расписанию, хранить состояние доставок и корректно переживать временное отсутствие новых материалов.

Как не получить дубли при повторном запросе?

Используйте delivery_id как ключ идемпотентности. Перед созданием записи проверяйте локальный журнал и уникальность slug. Если статья уже существует, не создавайте её заново: проверьте текущий URL и завершите обработку на основе сохранённого состояния.

Нужно ли писать интеграцию для WordPress?

Не обязательно. Для стандартной публикации сначала проверьте готовый плагин SerpJet. Собственный клиент нужен, когда у сайта нестандартные типы записей, особая маршрутизация, дополнительные проверки, сложный редакционный статус или несколько CMS в одном контуре.

Что делать, если обновление не прошло проверку?

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

Заключение

API для генерации SEO-статей приносит пользу не количеством запросов, а предсказуемым переходом от готового материала к проверенной странице. Разделите новые статьи и обновления, храните состояние по delivery_id, проверяйте данные до записи и URL после неё. Тогда агентство масштабирует публикацию без дублей и без потери контроля.

Чтобы собрать первый безопасный контур, создайте проект в SerpJet, настройте правила генерации и подключите CMS через готовый плагин или External API.

API для генерации SEO-статей: схема интеграции для агентства