Авторизация#
Для каждого вызова /v1 (кроме публичных, отмеченных Без авторизации) нужен Bearer‑токен. Токены бывают двух видов:
| Токен |
Откуда берётся |
Что позволяет |
sess_… сеанс панели |
POST /v1/sessions с API‑ключом рабочего пространства; сеанс действует 30 дней |
всё; работает на любом тарифе |
sk_live_… API‑ключ |
показывается один раз при создании рабочего пространства |
всё, но только на тарифах с доступом к API (optimize, agency, agency_client, enterprise); на остальных тарифах ответ — 403 api_access_required |
Authorization: Bearer sk_live_…
Лимиты запросов зависят от тарифа; ответ 429 содержит заголовок Retry-After. В POST‑запросах можно передавать заголовок Idempotency-Key: если ключ уже использовался, сервер повторно вернёт ответ на первый запрос (Idempotent-Replayed: true).
Замеры и аналитика#
Методы замеров (/v1/runs, /v1/answers, /v1/visibility, /v1/share-of-voice, /v1/citations) и аналитики (/v1/overview, /v1/trends, /v1/competitors, /v1/sources, /v1/prompt-metrics, /v1/report, /v1/report.pdf) принимают одни и те же фильтры: brand_id, engine, language, from, to (YYYY-MM-DD, включительно). Аналитика сравнивает выбранный период (по умолчанию — последние 28 дней) с предыдущим периодом той же длительности. Недели начинаются с понедельника.
Правки: применение вручную через панель#
Каждая подготовленная правка (GET /v1/content/items) содержит placement (URL, место на странице, пронумерованные шаги, текущий текст, который она заменяет, и все части, готовые к копированию) и facts (подтверждённые факты, на основе которых она написана). Порядок работы без дополнения «Доставка через API»:
proposed → POST /v1/content/{id}/approve → approved (готова к применению).
- Клиент вставляет правку на сайт и вызывает
POST /v1/content/{id}/applied → live; начинается эксперимент (когда ИИ‑системы успеют заметить изменение, проводится повторный замер, затем правку оставляют или откатывают). Для новых страниц вместо этого вызывают POST /v1/pages/{id}/published с фактическим URL.
- Если эксперимент не показал прироста (или клиент откатил правку), правка переходит в статус
remove_requested, и в ней указан текст, который нужно убрать; POST /v1/content/{id}/removed → rolled_back.
Правки в Google Business Profile на любом тарифе остаются автоматическими: после одобрения gbp_profile / gbp_post PromART сам записывает их в Google (флаг функции google_bp).
Доставка через API (платное дополнение)#
С дополнением «Доставка через API» (api_delivery_enabled у рабочего пространства, см. add_ons в GET /v1/usage) одобренная правка сайта сразу получает статус live, а сервер вашего сайта запрашивает её при рендеринге страницы. Без дополнения эти методы возвращают 403 addon_required:
| Что |
Запрос |
Для чего |
| Правки для уже созданной страницы |
GET /v1/content?url=<page URL> |
метаописание, абзац с ответом, FAQ, структурированные данные JSON-LD и blocks[] |
| Только замены разделов |
GET /v1/pages/{url}/blocks (URL экранируется как сегмент пути) или GET /v1/pages/blocks?url= |
заменить или вставить отдельные разделы |
| Новые страницы, которые нужно создать |
GET /v1/pages/new |
одобренные страницы: предлагаемый URL, заголовок, разделы (с таблицами), структурированные данные, внутренние ссылки |
| Отметить, что новая страница на сайте |
POST /v1/pages/{id}/published |
сообщить PromART фактический URL, чтобы страница попала в замеры |
Отдаются только правки, доставляемые через API (delivery: api): правки, которые клиент применил вручную, и так уже есть на странице. Кешируйте ответы не дольше 60 секунд (Cache-Control: private, max-age=60).
Применение блоков#
Каждый блок имеет вид {block_id, selector, action, html, fact_ids, status}. Найдите в готовом HTML страницы первый элемент, который соответствует CSS‑селектору selector, и примените к нему действие из action:
| action |
что сделать |
replace |
заменить элемент целиком (outer HTML) на html |
append |
вставить html последним дочерним элементом |
prepend |
вставить html первым дочерним элементом |
before |
вставить html сразу перед элементом |
after |
вставить html сразу после элемента |
Если селектор ничего не нашёл, пропустите блок. html уже очищен на стороне PromART: допускаются только p br h2 h3 h4 ul ol li strong em b i table thead tbody tr th td a (ссылки — только на ваши собственные хосты), без скриптов, стилей и любых атрибутов, кроме a[href].
Проверка подписи#
Ответы GET /v1/content, GET /v1/pages/{url}/blocks, GET /v1/pages/blocks и GET /v1/pages/new содержат заголовок
X-Sachino-Signature: sha256=<hex HMAC-SHA256(signing_secret, exact response body bytes)>
signing_secret можно получить через GET /v1/me. Проверяйте подпись по сырым байтам тела до разбора JSON и сравнивайте подписи за постоянное время.
Node:
JavaScript
const crypto = require('crypto');
const ok = (raw, header, secret) => {
const want = 'sha256=' + crypto.createHmac('sha256', secret).update(raw).digest('hex');
return header && header.length === want.length &&
crypto.timingSafeEqual(Buffer.from(header), Buffer.from(want));
};
PHP:
PHP
$want = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$ok = hash_equals($want, $_SERVER['HTTP_X_SACHINO_SIGNATURE'] ?? $header);
Go:
Go
m := hmac.New(sha256.New, []byte(secret))
m.Write(raw)
ok := hmac.Equal([]byte(header), []byte("sha256="+hex.EncodeToString(m.Sum(nil))))
Резервный сценарий (обязательно)#
PromART ни при каких условиях не должен ломать ваш сайт. Если запрос к API завершился ошибкой, превысил тайм-аут (рекомендуем 800 мс), вернул статус вне диапазона 2xx (в том числе 403 addon_required) или подпись не совпала, отдавайте исходную страницу без изменений. Не допускайте, чтобы PromART блокировал рендеринг страницы.
IndexNow#
GET /v1/indexnow-key возвращает ключ IndexNow вашего рабочего пространства и указывает, какой файл ваш разработчик должен разместить на каждом домене: https://<domain>/<key>.txt — обычный текст, содержащий только ключ; файл должен отдаваться с кодом HTTP 200 без перенаправления. После каждого события content.published (правку опубликовали через API или отметили как применённую либо подтвердили публикацию новой страницы) PromART отправляет изменённые URL в IndexNow; каждая отправка и её результат видны в GET /v1/actions (канал bing). Как только файл станет доступен, проверка сайта indexnow_key получит статус ok.
Вебхуки#
Чтобы подписаться, вызовите POST /v1/webhooks. События: run.completed, visibility.changed, content.proposed, content.approved, content.published, content.removal_requested, content.rolled_back, facts.stale, alert.triggered, page.approved, integration.invited, review.request (или * — все события).
Каждое уведомление — это запрос POST с JSON‑телом {id, type, created_at, data} и заголовками X-Sachino-Event: <type> и X-Sachino-Signature: sha256=<hex HMAC-SHA256(webhook secret, body)> (секрет возвращается при создании вебхука). Если ваш сервер ответил кодом вне диапазона 2xx, уведомление отправляется повторно, до 3 раз.
Интеграции с аккаунтами и флаги функций#
Google Business Profile (google_bp, область доступа business.manage), Search Console (gsc) и GA4 (ga4, analytics.readonly) подключаются через Google OAuth; токены хранятся в зашифрованном виде. Для Cloudflare (cloudflare) нужно вставить API‑токен с правами на настройки ботов зоны; эта интеграция используется только для того, чтобы открыть доступ ИИ‑краулерам. cloudflare и google_bp включаются флагами функций на сервере: если флаг выключен, связанные методы возвращают 403 с кодом feature_disabled, а GET /v1/integrations возвращает этот тип интеграции с enabled: false.
Ошибки#
Все ошибки приходят в едином формате: {"error": {"code": "...", "message": "..."}}. Коды: unauthorized (401), plan_limit (402), api_access_required (403: API‑ключ на тарифе без доступа к API; панель работает через сеансы и доступна на любом тарифе), addon_required (403: дополнение «Доставка через API» не подключено), feature_disabled (403), not_found (404), invalid_request / invalid_json (400), rate_limited (429), internal (500). Обрабатывайте ошибки по code: он задаёт общую категорию и не меняется. На запрос к несуществующему пути в /v1 сервер тоже отвечает 404 с кодом not_found в том же формате, а на запрос с методом, который путь в /v1 не поддерживает, — 405 с кодом invalid_request и заголовком Allow.
Если у ошибки есть более конкретная причина, в ней также передаются reason (стабильный ключ сообщения, например http.err.brand_id_required или core.err.not_found.brand) и params (значения, подставленные в сообщение; если значений нет, поле не передаётся). Если параметр что-то называет (тариф, статус, ИИ‑систему), в нём передаётся код, как и в английских сообщениях. У таких ошибок message приходит на языке ответа (см. раздел «Язык ответов»); на английском это тот же текст, что и до появления reason.
JSON
{"error": {"code": "api_access_required",
"message": "plan monitor does not include API access; use the panel, or upgrade to Optimize or higher",
"reason": "http.err.api_access_required", "params": {"plan": "monitor"}}}
Язык ответов#
Тексты, которые пишет PromART (сообщения об ошибках, примечания, рекомендации, шаги по размещению, оповещения, страница приглашения), могут приходить на грузинском, русском или английском. Язык задаётся параметром запроса lang (ka, ru или en, в любом методе) или заголовком Accept-Language (берётся поддерживаемый язык с наибольшим значением q; lang имеет приоритет). Если не передан ни параметр, ни заголовок или в заголовке только неподдерживаемые языки, ответы приходят на английском, как и раньше. Каждый ответ сообщает свой язык в заголовке Content-Language, который могут читать браузеры (Access-Control-Expose-Headers), и содержит Vary: Accept-Language. Исключение — ответы, одинаковые на всех языках: содержимое сайта из GET /v1/content и GET /v1/pages/{url}/blocks, /healthz, шрифты и файлы страницы документации приходят без этих заголовков. /docs тоже открывается на запрошенном языке (грузинском, русском или английском, с Vary: Accept-Language); /openapi.yaml доступен только на английском и отдаётся с Content-Language: en без Vary. Ответ на POST‑запрос, повторённый с тем же Idempotency-Key, приходит на языке первого запроса и с тем же Content-Language. Коды, идентификаторы и ваши собственные данные (названия брендов, факты, промпты, ответы ИИ, сгенерированное содержимое сайта) никогда не переводятся.