Главная

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

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

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

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

WordPress-плагин SerpJet Publisher

Бесплатно · v2.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
Структурированные данные страницы, если вы хотите их отдать вместе с публикацией.
cover
Обложка статьи: url, alt, width, height. null, если обложки нет. Иллюстрации уже вставлены в content тегами figure.
external_url
URL на момент создания delivery. Для new чаще всего пустой. После исправления адреса через PATCH URL в старом снимке не меняется.
Минимальный набор данных

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

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

Пять методов доставки и управления URL

Два метода для новых статей, два для улучшений и отдельный PATCH для изменения URL опубликованной статьи. Выгрузка Tilda CSV описана ниже.

GET /external/articles/new/pull

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

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

Метод предназначен для обработки новых материалов.
Параметры
project_id
Обязателен. Определяет, для какого проекта отдать статьи.
limit
Необязателен. По умолчанию 20, максимум 100.
Что важно в ответе
kind = "new"
Показывает, что это новая статья, а не обновление.
external_url = ""
Для новых статей 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"},
      "cover": {"url": "https://serpjet-images.s3.twcstorage.ru/projects/7/articles/284/cover.webp", "alt": "Менеджер работает с CRM", "width": 1536, "height": 1024},
      "external_url": ""
    }
  ]
}
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",
  "external_url": "https://example.com/blog/article-slug"
}
GET /external/articles/improvements/pull

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

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

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

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

Поле external_url содержит адрес на момент создания снимка. Если адрес исправили через PATCH, старый delivery сохранит прежний 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",
  "external_url": "https://example.com/blog/crm-guide"
}
PATCH /external/articles/{article_id}/publication-url

Изменить URL опубликованной статьи

Используйте этот метод, если CMS сначала передала адрес вида /node/284, а затем получила постоянный адрес /blog/article-slug. Он работает и после закрытия delivery со статусом accepted.

В URL запроса нужен article_id — ID статьи из pull, а не delivery_id. Передайте тот же X-Api-Key владельца проекта.

Публикация должна быть подтверждена: сохранена published_at, установлен статус publish или есть принятая доставка. Статус checked и наличие URL сами по себе публикацию не подтверждают.

Тело запроса
external_url
Обязательный постоянный HTTP(S)-адрес. Схема, домен и порт должны совпадать с адресом проекта либо подтверждённым адресом аналитики. Без логина, пароля, query и fragment. Drupal aliases поддерживаются.
expected_external_url
Необязательный последний известный адрес. Если он уже изменён, API вернёт 409 external_url_conflict. Это защищает более свежее исправление от перезаписи.
Результат

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

Повтор с уже сохранённым новым URL возвращает 200, даже если expected_external_url остался старым. Повторная запись аудита не создаётся.

История аналитики сохраняется. Если аналитика подключена и есть подтверждённая версия статьи, DOM будет проверен заново по новому адресу. Импортированные статьи не подключаются к аналитике автоматически.

Пример запроса
PATCH https://www.serpjet.ru/external/articles/284/publication-url
X-Api-Key: <YOUR_API_KEY>
Content-Type: application/json

{
  "external_url": "https://example.com/blog/article-slug",
  "expected_external_url": "https://example.com/node/284"
}
Ответ 200
{
  "ok": true,
  "article_id": 284,
  "external_url": "https://example.com/blog/article-slug",
  "article_status": "checked",
  "published_at": "2026-10-14T08:00:00+00:00"
}

В примере статус checked сохраняется: у статьи уже есть публикация, а новая редакция ещё ждёт подтверждения. Исправление адреса не меняет её состояние.

Повторные подтверждения и исправление адреса

Если CMS отправила результат, но не получила HTTP-ответ, повторите запрос с тем же delivery_id в том же result-методе. Одинаковое решение accepted или rejected вернёт 200 без изменения статьи, дат, аналитики и состояния улучшения.

При повторном accepted передайте URL исходного подтверждения либо опустите external_url. Если в историческом подтверждении URL не был сохранён отдельно, проверяется адрес неизменяемого снимка. При rejected поле external_url игнорируется.

Ответ содержит текущие article_status и external_url. Например, после публикации могло появиться новое улучшение со статусом checked. Повтор старого подтверждения не откатит это состояние.

Для изменения адреса закрытой доставки используйте PATCH по article_id. Другое решение, другой URL в повторном accepted или подтверждение superseded-доставки вернут 409 delivery_already_resolved.

Если ожидающий снимок создан до исправления URL через PATCH, его первое accepted со старым адресом вернёт 409 external_url_conflict. Повторите подтверждение с актуальным URL либо без external_url. Уже закрытое подтверждение с исходным URL можно повторять безопасно — исправленный адрес сохранится.

Продолжайте регулярно опрашивать оба pull-метода. Закрытые снимки больше не выдаются, новая редакция получает новый delivery_id. Пустой items не доказывает отсутствие очереди: следующий запрос может продолжить ограниченный скан.

Примеры интеграции

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

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", []):
    # После успешной публикации статьи в CMS:
    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 || []) {
  // После успешного применения обновления в CMS:
  await fetch(`${baseUrl}/articles/improvements/${item.delivery_id}/result`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      status: "accepted",
    }),
  });
}
Tilda-интеграция

Выгрузка в Tilda CSV-фид

Метод для прямой интеграции с Tilda Потоками. Возвращает CSV-файл, готовый к импорту через раздел «Статьи» в Tilda.

GET /external/tilda/feed.csv
project_id
int, обязателен
ID проекта
days
int, необязателен
Только статьи, обновлённые за последние N дней

Структура CSV

Фид содержит все статьи проекта со статусами publish и checked. Колонки: Post ID, Alias, Title, Description, Text, Date, Visibility, SEO Title, SEO Description.

  • Alias — латинский slug (до 80 символов), используется как адрес страницы в Tilda.
  • Visibility — published или draft в зависимости от настройки «Выгружать посты как опубликованные» в потоке Tilda.
  • После выгрузки метод автоматически записывает tilda_exported_at и строит extrnal_url для статей без адреса.
curl
curl -L \
  "https://www.serpjet.ru/external/tilda/feed.csv?project_id=7" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -o tilda-feed.csv
Ваши проекты

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

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

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