SerpJet
SerpJet
Главная

Мой профиль
External API

Документация по интеграции API SerpJet

На странице описан порядок взаимодействия сайта с SerpJet: получение подготовленных материалов, обработка публикации и передача итогового статуса по каждому delivery. Материал структурирован по этапам интеграции и основным методам API.

Начало работы Методы API Swagger OpenAPI JSON
Базовый URL
https://www.serpjet.ru/external/
Авторизация
X-Api-Key
Всего методов
4 метода API
Лимит
До 60 запросов в секунду

WordPress-плагин SerpJet

Бесплатно · v1.1.0

Используете WordPress? Не нужно писать интеграцию вручную — готовый плагин сам забирает статьи из API и публикует их без серверного cron.

Скачать плагин
1. Получите доступ

Сгенерируйте API key в профиле пользователя и сохраните его в используемой CMS или интеграционном сервисе.

2. Определите project_id

Каждый проект получает материалы по собственному идентификатору. Используйте соответствующий project_id в pull-запросах.

3. Регулярно выполняйте pull-запросы

Получайте новые статьи и улучшения отдельно, например по расписанию или через очередь задач.

4. Передайте итоговый статус

После публикации или отклонения материала обязательно вызовите соответствующий result-метод и передайте accepted либо rejected.

Порядок работы

Типовой сценарий интеграции

Базовый цикл взаимодействия состоит из трех этапов: получение delivery, обработка материала на стороне вашей системы и передача итогового статуса обратно в SerpJet.

01

Получение delivery

Вызовите pull-метод, получите массив items и сохраните delivery_id, поскольку он потребуется для передачи итогового результата.

02

Обработка материала

Новая статья может быть опубликована либо отклонена. Улучшение может быть принято либо отклонено, при этом текущая опубликованная версия статьи сохраняется.

03

Передача результата

Передайте result в тот же поток, из которого был получен delivery. При accepted для новой статьи рекомендуется указать итоговый URL публикации.

Общий формат

Структура каждого delivery

Оба pull-метода возвращают одинаковую структуру ответа. Отличается только назначение данных: для новых статей поле kind равно new, для улучшений равно update.

Верхний уровень ответа
ok
Показывает, что ответ выполнен без ошибки.
count
Сколько delivery пришло в массиве items.
items[]
Список задач на публикацию или обновление.
Ключевые поля внутри items[]
delivery_id
Главный идентификатор для result-метода.
title / description / content
Готовые данные статьи, которые нужно обработать в вашей системе.
json_ld
Структурированные данные страницы, если вы хотите их отдать вместе с публикацией.
external_url
Для update обычно уже содержит URL текущей страницы. Для new чаще всего пустой.
Минимальный набор данных

Обязательные элементы запроса

X-Api-Key в заголовке каждого запроса.
project_id в pull-методах.
delivery_id в URL result-методов.
status в теле result-запроса: только accepted или rejected.
Методы API

Описание четырех методов API

Ниже приведены два метода для новых статей и два метода для улучшений с кратким описанием назначения, параметров и типового ответа.

GET /external/articles/new/pull

Получение новых статей для публикации

Метод используется для получения материалов, которые ранее не публиковались. В ответе передаются подготовленные данные статьи и delivery_id для последующей фиксации результата.

Метод предназначен для обработки новых материалов.
Параметры
project_id
Обязателен. Определяет, для какого проекта отдать статьи.
limit
Необязателен. По умолчанию 20, максимум 100.
Что важно в ответе
kind = "new"
Показывает, что это новая статья, а не обновление.
external_url = null
Для новых статей URL обычно еще не существует.
Последующие действия

Сохраните delivery_id и после завершения обработки вызовите result-метод. Если статья опубликована, передайте итоговый URL страницы.

Пример запроса
GET https://www.serpjet.ru/external/articles/new/pull?project_id=7&limit=20
X-Api-Key: <YOUR_API_KEY>
Пример ответа
{
  "ok": true,
  "count": 1,
  "items": [
    {
      "delivery_id": 15,
      "project_id": 7,
      "article_id": 284,
      "kind": "new",
      "title": "Как выбрать CRM для малого бизнеса",
      "description": "Практический разбор критериев выбора CRM для команды продаж.",
      "content": "<h2>Что такое CRM и зачем она нужна</h2>...",
      "json_ld": {"@context": "https://schema.org", "@type": "Article"},
      "external_url": null
    }
  ]
}
POST /external/articles/new/{delivery_id}/result

Передача результата по новой статье

Метод вызывается после принятия решения о публикации новой статьи или об отказе от публикации на стороне CMS, редактора или автоматизированного процесса.

Разрешенные статусы: accepted или rejected.
Тело запроса
status
Обязателен. Только accepted или rejected.
external_url
Желательно передавать при accepted, чтобы связать публикацию с вашим сайтом.
note
Необязательный комментарий от CMS или редактора.
Что произойдет

accepted переводит статью в публикацию.

rejected помечает новую статью как отклоненную.

После этого тот же delivery больше не вернется через pull.

Минимум для работы

{"status": "accepted"}

Пример запроса
POST https://www.serpjet.ru/external/articles/new/15/result
X-Api-Key: <YOUR_API_KEY>
Content-Type: application/json

{
  "status": "accepted",
  "external_url": "https://example.com/blog/article-slug",
  "note": "Материал опубликован"
}
Пример ответа
{
  "ok": true,
  "delivery_id": 15,
  "status": "accepted",
  "article_status": "publish"
}
GET /external/articles/improvements/pull

Получение улучшений опубликованных статей

Метод используется, когда для уже опубликованной статьи подготовлена обновленная версия контента: новый заголовок, описание, текст и обновленные structured data.

Формат ответа соответствует методу получения новых статей.
Параметры
project_id
Обязателен. Определяет проект, по которому нужно выдать улучшения.
limit
Необязателен. По умолчанию 20, максимум 100.
Ключевое отличие

Поле kind всегда равно update.

Поле external_url обычно уже содержит URL действующей публикации.

Последующие действия

Сопоставьте обновленную версию с действующей публикацией, примените изменения при необходимости и затем отправьте accepted или rejected через result-метод улучшений.

Пример запроса
GET https://www.serpjet.ru/external/articles/improvements/pull?project_id=7&limit=20
X-Api-Key: <YOUR_API_KEY>
Пример ответа
{
  "ok": true,
  "count": 1,
  "items": [
    {
      "delivery_id": 21,
      "project_id": 7,
      "article_id": 284,
      "kind": "update",
      "title": "Как выбрать CRM для малого бизнеса в 2026 году",
      "description": "Расширенный материал с новыми критериями выбора и сравнением популярных CRM.",
      "content": "<h2>Критерии выбора CRM в 2026 году</h2>...",
      "json_ld": {"@context": "https://schema.org", "@type": "Article"},
      "external_url": "https://example.com/blog/crm-guide"
    }
  ]
}
POST /external/articles/improvements/{delivery_id}/result

Передача результата по улучшению

Метод фиксирует принятие или отклонение обновления существующей статьи. Использование допускается только для delivery из потока improvements.

Текущая опубликованная версия статьи сохраняется даже при rejected.
Тело запроса
status
Обязателен. accepted или rejected.
external_url
Необязателен. Нужен, если URL статьи после обновления поменялся.
note
Необязательный комментарий с причиной решения.
Что произойдет

accepted фиксирует, что улучшение применено.

rejected отклоняет только предложенное обновление, а не уже опубликованную статью.

Типичная ошибка

Нельзя передавать в этот метод delivery, полученный из new/pull. В таком случае API вернет ошибку delivery_kind_mismatch.

Пример запроса
POST https://www.serpjet.ru/external/articles/improvements/21/result
X-Api-Key: <YOUR_API_KEY>
Content-Type: application/json

{
  "status": "rejected",
  "note": "Редактор отклонил обновление"
}
Пример ответа
{
  "ok": true,
  "delivery_id": 21,
  "status": "rejected",
  "article_status": "publish"
}
Примеры интеграции

Типовые шаблоны запросов

Python / requests
import requests

base_url = "https://www.serpjet.ru/external"
headers = {"X-Api-Key": "<YOUR_API_KEY>"}

payload = requests.get(
    f"{base_url}/articles/new/pull",
    params={"project_id": 7, "limit": 20},
    headers=headers,
    timeout=30,
).json()

for item in payload.get("items", []):
    requests.post(
        f"{base_url}/articles/new/{item['delivery_id']}/result",
        json={"status": "accepted", "external_url": "https://example.com/blog/article-slug"},
        headers={**headers, "Content-Type": "application/json"},
        timeout=30,
    )
JavaScript / fetch
const baseUrl = "https://www.serpjet.ru/external";
const headers = {
  "X-Api-Key": "<YOUR_API_KEY>",
  "Content-Type": "application/json",
};

const pull = await fetch(
  `${baseUrl}/articles/improvements/pull?project_id=7&limit=20`,
  { headers }
);

const data = await pull.json();

for (const item of data.items || []) {
  await fetch(`${baseUrl}/articles/improvements/${item.delivery_id}/result`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      status: "accepted",
      external_url: item.external_url,
    }),
  });
}
Ваши проекты

Project ID для pull-методов

Используйте указанные идентификаторы в query-параметре project_id.

Проекты пока не созданы. После создания проекта его идентификатор появится в этом разделе.