#Публикация статей через модули сайта

Статус: Доступно для сайтов на Bitrix (модуль sapport.connector 1.2.1) и WordPress (модуль sapport-connector 1.1.1). Пакеты для FastAPI и Nuxt в публичный доступ не выпущены. Заказ публикации сегодня выполняется в кабинете Sapport; публичного серверного API публикации нет (см. API статей, статус Планируется).

Модуль сайта — это небольшой плагин, который вы привязываете к вашему сайту. Он раз в несколько минут спрашивает у платформы, есть ли для него задания, проверяет подпись задания, применяет его к вашей CMS и сообщает итог. Страница объясняет, как устроено задание, чем платформа ограждает ваш сайт и что делать при конфликтах. Она предназначена и для владельца сайта, и для разработчика адаптера.

Доступ: в кабинете — право seo.manage для публикации, seo.view для просмотра. Платно: нет. ПДн: нет.

#Как это работает

1. Вы привязываете сайт: в кабинете создаётся одноразовый код привязки, вы вводите его в модуле. Платформа выдаёт сайту секрет (показывается один раз).
2. В кабинете вы выбираете статью и нажимаете «Опубликовать на сайт через модуль», указав режим: черновик или публикация.
3. Платформа создаёт задание, подписывает его и ставит в очередь для вашего сайта.
4. Модуль забирает задания (опрос раз в 10 минут; ежечасный heartbeat сообщает число ожидающих заданий), проверяет подпись и применяет.
5. Модуль возвращает итог: applied с адресом страницы либо skipped, conflict, failed с кодом причины. В кабинете у статьи и у сайта виден статус, адрес страницы, идентификатор записи в вашей CMS и ошибка.

Адрес платформы (api_base) для модуля — домен ячейки привязки: RU https://formula-cream.pro, EN https://wfacademy.org, ID https://wfacademy.id. Ячейку определяет префикс кода привязки.

Полный протокол «облако — модуль» (привязка, heartbeat, опрос заданий, итог, отвязка, подпись запросов HMAC) и коды ошибок описаны в PROTOCOL.md и ERRORS.md пакета коннектора. Здесь — то, что нужно, чтобы понимать публикацию статей.

#Задание

#Содержимое (payload)

{
  "job_id": "00000000-0000-4000-8000-000000000001",
  "kind": "article",
  "action": "upsert",
  "source_id": "11111111-1111-4111-8111-111111111111",
  "version": 1,
  "payload": {
    "title": "Пептиды: полный гид",
    "slug": "peptidy-polnyj-gid",
    "html": "<p>Текст статьи</p>",
    "excerpt": "",
    "cover_url": "https://formula-cream.pro/storage/v1/object/public/sapport-files/covers/a.webp",
    "cover_alt": "Пептиды: полный гид",
    "seo": { "title": "Пептиды", "description": "Описание", "canonical": null },
    "tags": ["пептиды", "уход"],
    "category_hint": "ingredients",
    "locale": "ru",
    "publish_mode": "draft",
    "scheduled_at": null
  },
  "payload_sha256": "bbaee6d585670f93302af42addc4d8c2cb70638d1571e4616576a492fe0d26d1",
  "kid": "test-1",
  "sig": "mHgK/Ud/fbDzwnjpKiSKtyi49Mzth+sOOWc+ti2oXYHzzu0CtX92SxKVVH3aNYfuiatMnakLIsODBhieLRHfBw==",
  "issued_at": 1790000000
}

Пример взят из тестовых векторов пакета (ключ test-1 — тестовый и боевыми ячейками не используется).

#Пределы

Статья, превысившая предел, не превращается в задание: в кабинете вы увидите исход «слишком велика» либо «пустая».

Относительные адреса картинок и ссылок в HTML превращаются в абсолютные на домен ячейки. Модуль скачивает медиа только с адреса платформы (api_base), без переадресаций: обложка с чужого CDN завершит задание ошибкой media_foreign_origin.

#Подпись задания

Каждое задание подписано Ed25519 закрытым ключом ячейки. Это защищает ваш сайт от подмены задания по пути и от чужих заданий:

• подписывается канонический JSON конверта {action, issued_at, job_id, kind, payload_sha256, site_id, source_id, version} (и expect_cms_id, если он есть);
• site_id в конверте — идентификатор вашего сайта из привязки, поэтому задание другого сайта подпись не пройдёт;
• kid показывает, каким ключом подписано; префикс идентификатора указывает ячейку: ru-, en-, id-;
• открытые ключи ячеек публикуются в файле integrations/common/job-keys.json пакета коннектора, по одному на kid. Если модуль не знает kid (ключ ротировали), он сообщает «нужно обновить модуль» и не гасит задание: платформа выдаст его снова.

Канонический JSON: ключи объектов сортируются по кодовым единицам UTF-16 рекурсивно, без пробелов, числа только целые в пределах ±(2^53−1), вложенность не глубже 32; отклоняются дробные числа, одиночные суррогаты и повторяющиеся ключи. Тестовые векторы и реализация — в пакете коннектора (каталог tests/_vectors/).

Подпись самих запросов модуля к платформе (HMAC-SHA256 с заголовками X-Sapport-Site, X-Sapport-Ts, X-Sapport-Nonce, X-Sapport-Sig, окно ±300 секунд) — отдельный механизм привязки сайта; он описан в протоколе коннектора.

#Что делает модуль с содержимым

Модуль в любом случае чистит HTML сам — независимо от очистки на платформе.

#Потолок режима

Владелец сайта может ограничить модуль: «только черновики». Тогда задание на публикацию применится как черновик, а статья, которую человек уже опубликовал на сайте, вернёт конфликт published_awaits_approval.

#Версии

• Каждое изменение источника (правка статьи и повторная отправка) создаёт новую версию задания: max + 1.
• Повторная отправка неизменённой статьи новой версии не создаёт: кабинет отвечает «уже в работе».
• Устаревшие невыданные версии помечаются superseded.
• Версия, не новее уже применённой, получает skipped stale_version — это нормальный результат при повторах.
• Снятие с сайта (unpublish) не создаёт новую версию и допустимо только если на сайте уже есть применённая публикация; иначе — отказ «не опубликовано».
• «Создать заново» — отправка с recreate: true и без expect_cms_id, когда запись удалили на сайте и вы хотите опубликовать её снова.

#Итог задания

Модуль возвращает один итог на задание; первый записанный итог окончателен и не перезаписывается.

Требования к полям: cms_id — ^[A-Za-z0-9_-]{1,64}$; url — только http или https; error — до 500 знаков. Временные сбои (база, сеть, потеря аренды) модуль не отправляет: задание вернётся через 15 минут.

#Коды конфликтов и пропусков

Полный перечень (подпись, обложка, база сайта, настройка разделов) — в ERRORS.md пакета коннектора.

#Что вы видите в кабинете

У статьи и у сайта (блок «Публикации»): заголовок, режим публикации, статус задания (в очереди, выдано, применено, пропущено, конфликт, ошибка), адрес страницы, идентификатор записи в CMS и текст ошибки. Одновременно список заданий читают сотрудники с правом seo.view, seo.manage или admin.api_keys.

#Публичного API для этого пока нет

Кабинетные маршруты публикации требуют сессии сотрудника и для внешних систем не предназначены. Серверный вызов «опубликовать» с ключом — часть будущего API статей: POST /articles/{id}/publish с target: connector.

#Открытые вопросы

• scheduled_at (техническое). Сегодня всегда null; модуль с отложенной публикацией (future в WordPress) получит её только когда платформа начнёт её передавать.
• canonical (техническое). Всегда null: управление каноническим адресом на стороне платформы пока не реализовано.
• Пакеты FastAPI и Nuxt (к владельцу). В публичный доступ не выложены; станут ли публичными, не решено.
• Домен-псевдоним (техническое). Сайт на домене, который не привязан и не является www-вариантом привязанного, на подписанных запросах получает 400; поведение не закреплено в документации привязки.
• Публичный адрес job-keys.json (техническое). Файл лежит в репозитории пакета; публичный адрес для его скачивания не определён.