Схемы данных
Объекты запросов и ответов. Типы в таблицах методов ведут сюда.
#Money
Денежная сумма.
| Поле | Тип | Описание |
|---|---|---|
amount | string обязательное | Сумма СТРОКОЙ (не число с плавающей точкой), например "123.45". |
currency | string обязательное | Код валюты ISO 4217: RUB (RU), GBP (EN), IDR (ID). |
#FieldError
Ошибка проверки одного поля.
| Поле | Тип | Описание |
|---|---|---|
field | string обязательное | Путь к полю запроса в формате JSON Pointer (RFC 6901): "/limit", "/events/0". |
code | string обязательное | Машинный код причины: out_of_range, required, invalid_format… |
message | string обязательное | Пояснение для человека. |
#Problem
Ошибка в формате application/problem+json (RFC 9457).
| Поле | Тип | Описание |
|---|---|---|
type | string обязательное | Ссылка на описание кода: https://<домен ячейки>/developers/errors#<code>. |
title | string обязательное | Краткое название, одинаковое для кода. |
status | integer обязательное | HTTP-статус. |
code | string обязательное | Стабильный машинный код. Ветвите логику по нему, а не по тексту. Значения: invalid_api_key wrong_cell integration_inactive tenant_inactive scope_missing ip_not_allowed feature_not_in_plan pii_transfer_not_allowed not_found method_not_allowed bad_request idempotency_key_required idempotency_conflict operation_in_progress invalid_state precondition_failed precondition_required payload_too_large validation_failed rate_limited spend_limit_reached insufficient_funds wallet_suspended internal_error service_unavailable upstream_unavailable |
detail | string обязательное | Пояснение к конкретному случаю. Не разбирайте этот текст. |
request_id | string обязательное | Идентификатор запроса (совпадает с заголовком X-Request-Id). Указывайте при обращении в поддержку. |
errors | array<FieldError> необязательное | Ошибки по полям (только validation_failed). |
correct_base_url | string необязательное | Только wrong_cell: базовый адрес ячейки, где выпущен ключ. |
topup_url | string необязательное | Только wallet_suspended: адрес кабинета, где пополняется кошелёк. |
balance | Money необязательное, может быть null | Только wallet_suspended: остаток кошелька на момент отказа. |
#Usage
Стоимость платной операции.
| Поле | Тип | Описание |
|---|---|---|
cost | Money обязательное | |
model | string обязательное | Модель, выполнившая операцию. |
#Operation
Асинхронная операция (единый конверт для всех модулей).
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор операции. |
type | string обязательное | Вид операции, например "article.generation". |
status | string обязательное | Состояние операции. Значения: queued running succeeded failed canceled |
created_at | string обязательное | Время создания, ISO 8601 UTC. |
completed_at | string необязательное | Время завершения; только для succeeded, failed, canceled. |
resource | object необязательное | Ресурс, к которому относится операция; по нему читают результат. |
resource.type | string обязательное | |
resource.id | string обязательное | |
error | object необязательное | Только для failed: код из каталога ошибок или код причины операции. |
error.code | string обязательное | |
error.message | string обязательное | |
usage | Usage необязательное | Только для платных операций. |
#OperationEnvelope
Ответ 202 на создающий запрос.
| Поле | Тип | Описание |
|---|---|---|
operation | Operation обязательное |
#Me
Кто вы: арендатор, интеграция, ключ, пределы, кошелёк.
| Поле | Тип | Описание |
|---|---|---|
tenant | object обязательное | Арендатор — владелец ключа. |
tenant.id | string обязательное | |
tenant.name | string обязательное | |
cell | string обязательное | Ячейка платформы: ru, en или id. Значения: ru en id |
base_url | string обязательное | Базовый адрес API этой ячейки. |
integration | object обязательное | Интеграция (служебная учётная запись), которой принадлежит ключ. |
integration.id | string обязательное | |
integration.name | string обязательное | |
channel_id | string обязательное, может быть null | Канал "api" интеграции; null — канал ещё не создан. |
key | object обязательное | |
key.key_id | string обязательное | Публичный идентификатор ключа (не секрет). |
key.mode | string обязательное | Значения: live test |
key.scopes | array<string> обязательное | Действующие области: область интеграции ∩ текущие права владельца ∩ лицензия. Значения: conversations:read conversations:write ai_seller:invoke leads:read leads:write leads:score analytics:read analytics:write dashboards:read articles:read articles:write articles:generate strategist:read strategist:write strategist:chat webhooks:manage |
key.expires_at | string обязательное | Срок действия ключа, ISO 8601 UTC. |
key.ip_allowlist | array<string> обязательное, может быть null | Разрешённые адреса и сети (CIDR); null — любой адрес. |
limits | object обязательное | Пределы частоты запросов. |
limits.read_per_min | integer обязательное | |
limits.write_per_min | integer обязательное | |
limits.paid_per_min | integer обязательное | |
limits.paid_concurrency | integer обязательное | Одновременных платных операций на арендатора. |
wallet | object обязательное | Кошелёк арендатора (ИИ-операции). |
wallet.balance | Money обязательное, может быть null | Остаток кошелька в рублях; null — состояние неизвестно или арендатор не тарифицируется. |
wallet.state | string обязательное | ok — достаточно; low — мало средств; negative — остаток ниже нуля; blocked — кошелёк заблокирован; unknown — состояние получить не удалось. Подробности — GET /wallet. Значения: ok low negative blocked unknown |
wallet.exchange | string обязательное | suspended при negative и blocked: все маршруты, кроме /me и /wallet, отвечают 402 wallet_suspended. Значения: active suspended |
wallet.topup_url | string обязательное | Адрес кабинета, где пополняется кошелёк. |
wallet.daily_spend | object обязательное | |
wallet.daily_spend.limit | Money обязательное, может быть null | Суточный предел трат интеграции; null — не задан. |
wallet.daily_spend.used | Money обязательное | |
crm_mode | string обязательное | Режим CRM арендатора: "internal" (наша CRM) или внешняя система. |
#Webhook
Подписка на события. Секрет в таких ответах не возвращается.
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор подписки. |
url | string обязательное | Адрес приёма: https, порт 443, имя хоста (не IP), без переадресаций. |
events | array<string> обязательное | Типы событий: точный тип или шаблон семейства "семейство.*". Доступные типы: conversation.created, message.created, conversation.handoff_requested, conversation.summary_ready, lead.created, lead.updated, lead.scored, lead.status_changed, lead.action_requested, task.created, task.completed, contact.merged, crm.mode_changed, article.ready, article.published, article.generation.failed, strategist.report.ready, strategist.turn.completed, operation.completed, api_key.expiring. |
include_pii | boolean обязательное | Полная нагрузка с персональными данными; только для событий lead.*, contact.*, conversation.*. По умолчанию false. |
description | string обязательное, может быть null | Пометка для вас, до 200 знаков. |
status | string обязательное | active — доставки идут; paused — приостановлена. Значения: active paused |
created_at | string обязательное | ISO 8601 UTC. |
updated_at | string обязательное | ISO 8601 UTC. |
secret_rotated_at | string обязательное, может быть null | Время последней ротации секрета; null — не менялся. |
previous_secret_expires_at | string обязательное, может быть null | Пока окно ротации открыто (24 часа) — когда прежний секрет перестанет действовать; иначе null. |
#WebhookWithSecret
Подписка вместе с секретом: ответ создания и ротации.
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор подписки. |
url | string обязательное | Адрес приёма: https, порт 443, имя хоста (не IP), без переадресаций. |
events | array<string> обязательное | Типы событий: точный тип или шаблон семейства "семейство.*". Доступные типы: conversation.created, message.created, conversation.handoff_requested, conversation.summary_ready, lead.created, lead.updated, lead.scored, lead.status_changed, lead.action_requested, task.created, task.completed, contact.merged, crm.mode_changed, article.ready, article.published, article.generation.failed, strategist.report.ready, strategist.turn.completed, operation.completed, api_key.expiring. |
include_pii | boolean обязательное | Полная нагрузка с персональными данными; только для событий lead.*, contact.*, conversation.*. По умолчанию false. |
description | string обязательное, может быть null | Пометка для вас, до 200 знаков. |
status | string обязательное | active — доставки идут; paused — приостановлена. Значения: active paused |
created_at | string обязательное | ISO 8601 UTC. |
updated_at | string обязательное | ISO 8601 UTC. |
secret_rotated_at | string обязательное, может быть null | Время последней ротации секрета; null — не менялся. |
previous_secret_expires_at | string обязательное, может быть null | Пока окно ротации открыто (24 часа) — когда прежний секрет перестанет действовать; иначе null. |
secret | string обязательное, может быть null | Секрет подписи: показывается ОДИН раз, в ответе создания или ротации. При идемпотентном повторе запроса — null: сохраните секрет из первого ответа. |
#WebhookCreate
Тело создания подписки.
| Поле | Тип | Описание |
|---|---|---|
url | string обязательное | Адрес приёма: https, порт 443, имя хоста (не IP), без переадресаций. |
events | array<string> обязательное | Типы событий: точный тип или шаблон семейства "семейство.*". Доступные типы: conversation.created, message.created, conversation.handoff_requested, conversation.summary_ready, lead.created, lead.updated, lead.scored, lead.status_changed, lead.action_requested, task.created, task.completed, contact.merged, crm.mode_changed, article.ready, article.published, article.generation.failed, strategist.report.ready, strategist.turn.completed, operation.completed, api_key.expiring. |
include_pii | boolean необязательное | Полная нагрузка с персональными данными; только для событий lead.*, contact.*, conversation.*. По умолчанию false. |
description | string необязательное, может быть null | Пометка для вас, до 200 знаков. |
#WebhookUpdate
Тело правки: передайте хотя бы одно поле.
| Поле | Тип | Описание |
|---|---|---|
url | string необязательное | Адрес приёма: https, порт 443, имя хоста (не IP), без переадресаций. |
events | array<string> необязательное | Типы событий: точный тип или шаблон семейства "семейство.*". Доступные типы: conversation.created, message.created, conversation.handoff_requested, conversation.summary_ready, lead.created, lead.updated, lead.scored, lead.status_changed, lead.action_requested, task.created, task.completed, contact.merged, crm.mode_changed, article.ready, article.published, article.generation.failed, strategist.report.ready, strategist.turn.completed, operation.completed, api_key.expiring. |
include_pii | boolean необязательное | Полная нагрузка с персональными данными; только для событий lead.*, contact.*, conversation.*. По умолчанию false. |
description | string необязательное, может быть null | Пометка для вас, до 200 знаков. |
status | string необязательное | Приостановить или возобновить доставки. Значения: active paused |
#WebhookPage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<Webhook> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |
#WebhookTestResult
Ответ 202 на тестовую доставку. Тело события приходит на ваш адрес с livemode: false.
| Поле | Тип | Описание |
|---|---|---|
event_id | string обязательное, может быть null | Идентификатор тестового события. |
type | string обязательное | |
status | string обязательное | Событие в очереди; уйдёт на ближайшем запуске доставщика (до минуты). |
#WebhookDelivery
Запись журнала доставок (хранится 30 суток).
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор доставки. |
event_id | string обязательное | Идентификатор события. |
state | string обязательное | pending — ждёт попытки; delivered — доставлено; failed — попытка не удалась, будет повтор; dead — повторы исчерпаны. Значения: pending delivered failed dead |
attempt | integer обязательное | Номер последней попытки (0 — ещё не было). |
status_code | integer обязательное, может быть null | HTTP-код ответа подписчика; null, если ответа не было. |
duration_ms | integer обязательное, может быть null | Длительность попытки, мс. |
error | string обязательное, может быть null | Причина сбоя: тайм-аут, ошибка соединения или сертификата, ответ 3xx. |
next_attempt_at | string обязательное, может быть null | Время следующей попытки; null, если попыток больше не будет. |
delivered_at | string обязательное, может быть null | Время успешной доставки. |
created_at | string обязательное |
#WebhookDeliveryPage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<WebhookDelivery> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |
#Wallet
Состояние кошелька арендатора и обмена данными.
| Поле | Тип | Описание |
|---|---|---|
balance | Money обязательное, может быть null | Остаток кошелька в рублях (кошелёк ведётся в RUB на любой ячейке); null — состояние неизвестно или арендатор не тарифицируется. |
state | string обязательное | ok — достаточно; low — мало средств (обмен идёт); negative — остаток ниже нуля; blocked — кошелёк заблокирован; unknown — состояние получить не удалось. Значения: ok low negative blocked unknown |
exchange | string обязательное | suspended при negative и blocked: все маршруты, кроме /me и /wallet, отвечают 402 wallet_suspended, вебхуки откладываются. При unknown остаётся active: бесплатное чтение идёт с заголовком Sapport-Wallet-State: unknown, платные операции закрыты (503). Значения: active suspended |
topup_url | string обязательное | Адрес кабинета, где пополняется кошелёк (нужен вход сотрудника с правом пополнения). |
daily_spend | object обязательное, может быть null | Суточные траты интеграции; null, пока расход по интеграции не учитывается. |
daily_spend.limit | Money обязательное, может быть null | Суточный предел трат интеграции; null — не задан. |
daily_spend.used | Money обязательное |
#TimeseriesItem
Один временной ряд.
| Поле | Тип | Описание |
|---|---|---|
metric | string обязательное | Значения: sessions pageviews visitors bounce_rate impressions clicks ctr position ai_referrals bot_hits leads deals_won revenue |
from | string обязательное | Дата YYYY-MM-DD. |
to | string обязательное | Дата YYYY-MM-DD. |
granularity | string обязательное | Значения: day week |
agg | string обязательное | Способ свёртки ряда за период. Значения: sum avg |
engine | string обязательное, может быть null | Поисковик ряда; null у метрик, не привязанных к поиску. Значения: google yandex bing |
availability | string обязательное | Значения: ok no_data no_source |
reason | string обязательное, может быть null | Код причины, если availability не ok. |
series | array<object> обязательное | Ряд значений; дни без данных заполнены нулями. При недельном шаге date — первый день недели. |
comparison | object обязательное | |
comparison.current | object обязательное, может быть null | |
comparison.prev | object обязательное, может быть null | |
comparison.delta_pct | number обязательное, может быть null | Изменение в процентах; null, если сравнить не с чем или база равна нулю. |
comparison.data_through | string обязательное, может быть null | Последняя дата, по которую данные полны. |
summary | object обязательное, может быть null | |
summary.total | object обязательное, может быть null | |
summary.latest | object обязательное, может быть null | |
summary.non_zero_days | integer обязательное | |
cluster_applied | boolean обязательное | |
data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
#TimeseriesResponse
Один ряд (одна метрика) либо items в порядке запроса (несколько метрик).
| Поле | Тип | Описание |
|---|---|---|
data | object обязательное |
#TrafficSourceRow
Источник первого визита за период.
| Поле | Тип | Описание |
|---|---|---|
source | string обязательное | Значения: google yandex bing chatgpt perplexity ai_other social ads direct other |
kind | string обязательное | Значения: search ai_assistant social ads direct other |
sessions | integer обязательное | |
visitors | integer обязательное, может быть null | Уникальные посетители за день, просуммированные по периоду; null, когда посчитать нечем (маячок anonymous). |
leads | integer обязательное | |
series | array<object> необязательное | Только при include=series. |
#TrafficSourcesResponse
Источники трафика, больше сессий первыми.
| Поле | Тип | Описание |
|---|---|---|
data | array<TrafficSourceRow> обязательное | |
data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
#FunnelStep
Ступень воронки со своей доступностью и своей датой.
| Поле | Тип | Описание |
|---|---|---|
key | string обязательное | Значения: impressions clicks sessions leads deals_created deals_won revenue |
availability | string обязательное | Значения: ok no_data no_source |
sources | array<string> обязательное | |
unit | string обязательное | Значения: count money |
current | object обязательное, может быть null | |
prev | object обязательное, может быть null | |
delta_pct | number обязательное, может быть null | |
data_through | string обязательное, может быть null |
#FunnelResponse
Воронка «показы → клики → сессии → лиды → сделки → выручка».
| Поле | Тип | Описание |
|---|---|---|
data | object обязательное | |
data.engine | string обязательное | Значения: yandex google both |
data.from | string обязательное | Дата YYYY-MM-DD. |
data.to | string обязательное | Дата YYYY-MM-DD. |
data.steps | array<FunnelStep> обязательное | |
data.by_channel | array<object> обязательное | |
data.search_by_engine | array<object> необязательное | Только engine=both: движки раздельно. |
data.by_product | array<object> обязательное | |
data.crm | object обязательное | |
data.crm.availability | string обязательное | Значения: ok no_data |
data.crm.reason | string необязательное | |
data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
#VisibilityResponse
Видимость: пять самостоятельных разделов.
| Поле | Тип | Описание |
|---|---|---|
data | object обязательное | |
data.from | string обязательное | Дата YYYY-MM-DD. |
data.to | string обязательное | Дата YYYY-MM-DD. |
data.engine | string обязательное | Значения: yandex google both |
data.share | object обязательное | |
data.share.availability | string обязательное | |
data.share.reason | string необязательное | |
data.share.source | string обязательное | |
data.share.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.share.data | object обязательное | |
data.distribution | object обязательное | |
data.distribution.availability | string обязательное | |
data.distribution.reason | string необязательное | |
data.distribution.source | string обязательное | |
data.distribution.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.distribution.data | object обязательное | |
data.sov | object обязательное | |
data.sov.availability | string обязательное | |
data.sov.reason | string необязательное | |
data.sov.source | string обязательное | |
data.sov.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.sov.data | object обязательное | |
data.aeo | object обязательное | |
data.aeo.availability | string обязательное | |
data.aeo.reason | string необязательное | |
data.aeo.source | string обязательное | |
data.aeo.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.aeo.data | object обязательное | |
data.regions | object обязательное | |
data.regions.availability | string обязательное | |
data.regions.reason | string необязательное | |
data.regions.source | string обязательное | |
data.regions.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.regions.data | object обязательное |
#OverviewResponse
Срез экрана «Обзор»: запрошенные блоки в порядке экрана.
| Поле | Тип | Описание |
|---|---|---|
data | object обязательное | |
data.from | string обязательное | Дата YYYY-MM-DD. |
data.to | string обязательное | Дата YYYY-MM-DD. |
data.blocks | object обязательное | |
data.blocks.strategist | object необязательное | |
data.blocks.strategist.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.strategist.reason | string необязательное | |
data.blocks.strategist.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.kpi | object необязательное | |
data.blocks.kpi.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.kpi.reason | string необязательное | |
data.blocks.kpi.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.funnel | object необязательное | |
data.blocks.funnel.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.funnel.reason | string необязательное | |
data.blocks.funnel.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.attention | object необязательное | |
data.blocks.attention.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.attention.reason | string необязательное | |
data.blocks.attention.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.ads | object необязательное | |
data.blocks.ads.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.ads.reason | string необязательное | |
data.blocks.ads.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.ai_assistants | object необязательное | |
data.blocks.ai_assistants.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.ai_assistants.reason | string необязательное | |
data.blocks.ai_assistants.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.popular_pages | object необязательное | |
data.blocks.popular_pages.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.popular_pages.reason | string необязательное | |
data.blocks.popular_pages.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.clusters | object необязательное | |
data.blocks.clusters.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.clusters.reason | string необязательное | |
data.blocks.clusters.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.data_trust | object необязательное | |
data.blocks.data_trust.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.data_trust.reason | string необязательное | |
data.blocks.data_trust.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.sitemap_health | object необязательное | |
data.blocks.sitemap_health.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.sitemap_health.reason | string необязательное | |
data.blocks.sitemap_health.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
data.blocks.status | object необязательное | |
data.blocks.status.availability | string обязательное | Значения: ok no_data no_source not_connected |
data.blocks.status.reason | string необязательное | |
data.blocks.status.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
#PulseAlert
Находка «Пульса»: тема спроса, которая начала расти.
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | |
topic_id | string обязательное | |
topic_name | string обязательное, может быть null | |
keyword | string обязательное | |
horizon | string обязательное | |
status | string обязательное | |
episode_start | string обязательное, может быть null | |
last_seen | string обязательное, может быть null | |
score | number обязательное, может быть null | |
volume | number обязательное, может быть null | |
growth | number обязательное, может быть null | |
sources | array<object> обязательное | |
strategist_topic | object обязательное, может быть null | Связанная тема очереди стратега. |
strategist_topic.id | string обязательное | |
strategist_topic.status | string обязательное |
#PulseResponse
Срез экрана «Пульс».
| Поле | Тип | Описание |
|---|---|---|
data | object обязательное | |
data.period | object обязательное | |
data.period.from | string обязательное | Дата YYYY-MM-DD. |
data.period.to | string обязательное | Дата YYYY-MM-DD. |
data.new_7d | integer обязательное | |
data.truncated | boolean обязательное | |
data.alerts | array<PulseAlert> обязательное | |
data.data_as_of | object обязательное | Источник → дата, по которую его данные полны. Источник без данных в объект не попадает. |
#ArticleSummary
Статья арендатора без содержимого (элемент списка).
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор статьи. |
title | string обязательное | |
slug | string обязательное, может быть null | |
status | string обязательное | draft — черновик; review — на проверке; approved — одобрена; published — опубликована; rejected — отклонена; transferred — передана в блог; external — внешняя. |
locale | string обязательное, может быть null | Язык статьи (ru, en, id). |
keyword | string обязательное, может быть null | Главный запрос статьи. |
meta_title | string обязательное, может быть null | |
meta_description | string обязательное, может быть null | |
cover_image_url | string обязательное, может быть null | |
word_count | integer обязательное | |
created_at | string обязательное, может быть null | ISO 8601 UTC. |
updated_at | string обязательное, может быть null | ISO 8601 UTC. |
published_at | string обязательное, может быть null | ISO 8601 UTC. |
#ArticlePublication
Состояние последней выкладки статьи через модуль сайта.
| Поле | Тип | Описание |
|---|---|---|
target | string обязательное | Куда выкладывается: модуль на вашем сайте. |
state | string обязательное | queued — в очереди или отдано модулю; applied — применено на сайте; skipped — пропущено; conflict — правка на сайте новее; failed — ошибка. Значения: queued applied skipped conflict failed |
published_url | string обязательное, может быть null | Адрес статьи на вашем сайте после применения. |
error | string обязательное, может быть null | Причина сбоя, до 200 знаков. |
#Article
Статья арендатора с содержимым.
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор статьи. |
title | string обязательное | |
slug | string обязательное, может быть null | |
status | string обязательное | draft — черновик; review — на проверке; approved — одобрена; published — опубликована; rejected — отклонена; transferred — передана в блог; external — внешняя. |
locale | string обязательное, может быть null | Язык статьи (ru, en, id). |
keyword | string обязательное, может быть null | Главный запрос статьи. |
meta_title | string обязательное, может быть null | |
meta_description | string обязательное, может быть null | |
cover_image_url | string обязательное, может быть null | |
word_count | integer обязательное | |
created_at | string обязательное, может быть null | ISO 8601 UTC. |
updated_at | string обязательное, может быть null | ISO 8601 UTC. |
published_at | string обязательное, может быть null | ISO 8601 UTC. |
content | object обязательное | Тело статьи в запрошенном формате: html и markdown — строка; blocks — массив блоков {type, html}. HTML очищен от скриптов, опасных ссылок и обработчиков событий. У статьи, чьё тело переехало в блог площадки, содержимое пустое. |
publication | ArticlePublication обязательное, может быть null | null — статью ещё не выкладывали через модуль сайта. |
#ArticlePage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<ArticleSummary> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |
#StrategistReportSummary
Шапка отчёта стратега (элемент списка).
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор отчёта. |
report_date | string обязательное | Дата отчёта YYYY-MM-DD. |
report_type | string обязательное | daily — ежедневный, weekly — недельный. Значения: daily weekly |
summary_text | string обязательное | Краткий вывод. |
actions_count | integer обязательное | Сколько действий рекомендовано. |
data_as_of | object обязательное | Актуальность данных: по каждому показателю (ключ) дата последних данных YYYY-MM-DD; ключ snapshot — дата снимка аналитики, на котором построен отчёт. Пусто, если снимка нет. |
delivered_at | string обязательное, может быть null | Когда отчёт доставлен владельцу; null — ещё нет. ISO 8601 UTC. |
#StrategistReportAction
Рекомендованное действие.
| Поле | Тип | Описание |
|---|---|---|
title | string обязательное | |
priority | string обязательное | Приоритет действия (high, medium, low). |
rationale | string обязательное | Обоснование. Названия конкурентов в нём скрыты. |
target_ref | string обязательное, может быть null | Ссылка на цель (статья, товар, кампания); null, если цели нет или это конкурент. |
expected_effect | object обязательное, может быть null | Ожидаемый эффект; null, если стратег его не назвал. |
expected_effect.metric | string обязательное, может быть null | |
expected_effect.delta | string обязательное, может быть null | |
expected_effect.horizon_days | integer обязательное, может быть null | |
check_after_days | integer обязательное, может быть null | Через сколько дней проверить результат. |
basis | string обязательное | На чём стоит вывод: observed_pattern — наблюдали у других; own_measured — измерили у вас; research — исследование; hypothesis — гипотеза. Значения: observed_pattern own_measured research hypothesis |
#StrategistEvidence
Доказательства по действиям. Дословные формулировки конкурентов не отдаются.
| Поле | Тип | Описание |
|---|---|---|
actions | array<object> обязательное | |
validation | object необязательное | Итог проверки доказательств. relevance_checked всегда false: проверяются ссылки и цитаты, а не смысл. |
validation.refs_valid | boolean обязательное | |
validation.excerpts_valid | boolean обязательное | |
validation.relevance_checked | boolean обязательное | |
validation.limitations | array<string> обязательное |
#StrategistReport
Отчёт стратега целиком. Снимок аналитики, модель и стоимость не отдаются.
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | |
report_date | string обязательное | |
report_type | string обязательное | Значения: daily weekly |
summary_text | string обязательное | |
data_as_of | object обязательное | Актуальность данных: по каждому показателю (ключ) дата последних данных YYYY-MM-DD; ключ snapshot — дата снимка аналитики, на котором построен отчёт. Пусто, если снимка нет. |
highlights | array<object> обязательное | Что идёт хорошо. |
concerns | array<object> обязательное | Что беспокоит. |
actions | array<StrategistReportAction> обязательное | |
evidence | StrategistEvidence обязательное |
#StrategistReportPage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<StrategistReportSummary> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |
#StrategistTopic
Тема в очереди стратега.
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | |
title | string обязательное, может быть null | |
rationale | string обязательное, может быть null | Почему тема предложена. Для тем от конкурентов домены скрыты. |
trend_score | number обязательное, может быть null | Оценка тренда; null — не оценивалась. |
source | string обязательное | Откуда тема: planner, competitors, chat и др. |
status | string обязательное | proposed — ждёт решения; approved — одобрена; generating — статья создаётся; generated — статья создана; rejected — отклонена; duplicate — дубль; expired — срок вышел. Значения: proposed approved generating generated rejected duplicate expired |
cluster_id | string обязательное, может быть null | |
generated_article_id | string обязательное, может быть null | Идентификатор созданной статьи (GET /articles/{id}). |
proposed_at | string обязательное, может быть null | ISO 8601 UTC. |
decided_at | string обязательное, может быть null | ISO 8601 UTC. |
expires_at | string обязательное, может быть null | ISO 8601 UTC. |
#StrategistTopicPage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<StrategistTopic> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |
#StrategistAction
Действие стратега, предложенное в вашей сессии и ждущее решения.
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | |
session_id | string обязательное, может быть null | Сессия разговора, в которой предложено действие. |
type | string обязательное | Вид действия. В v1 — только propose_topic. |
title | string обязательное | Заголовок предлагаемой темы. |
status | string обязательное | proposed — ждёт подтверждения; confirmed — подтверждено, выполняется; executed — выполнено; failed — не удалось; cancelled — отменено; expired — срок вышел (7 суток). Значения: proposed confirmed executed failed cancelled expired |
result | object обязательное, может быть null | Результат выполненного действия: созданная тема. |
result.topic_id | string обязательное | |
error | object обязательное, может быть null | Причина сбоя при status = failed. |
error.code | string обязательное | |
error.message | string обязательное | |
created_at | string обязательное, может быть null | ISO 8601 UTC. |
decided_at | string обязательное, может быть null | ISO 8601 UTC. |
expires_at | string обязательное, может быть null | Когда ожидание истекает: создание + 7 суток. ISO 8601 UTC. |
#StrategistActionPage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<StrategistAction> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |
#Conversation
Диалог. Содержит персональные данные (external_customer_id).
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор диалога (uuid). |
channel | string обязательное, может быть null | Тип канала: api, telegram, website … |
contact_id | string обязательное, может быть null | Идентификатор контакта (клиента) в Sapport. |
external_customer_id | string обязательное, может быть null | Идентификатор клиента в вашей системе. Только у канала api; у остальных каналов null (внешний идентификатор мессенджера не раскрывается). |
status | string обязательное | Состояние диалога: open, handoff_pending, resolved, closed … Набор значений может расширяться — не считайте список закрытым. |
mode | string обязательное | Кто ведёт диалог: ai — отвечает ИИ (режимы auto и supervised), operator — отвечает человек (copilot и manual). Значения: ai operator |
language | string обязательное, может быть null | Язык диалога (ISO 639-1); null — не определён. |
created_at | string обязательное, может быть null | Начало диалога, ISO 8601 UTC. |
updated_at | string обязательное | Последнее изменение или сообщение, ISO 8601 UTC. По нему идёт обход. Счётчик непрочитанного его не меняет. |
#MessageAttachment
Вложение сообщения.
| Поле | Тип | Описание |
|---|---|---|
type | string обязательное, может быть null | Вид содержимого: image, file, audio … |
url | string обязательное | Временная подписанная ссылка на файл (скачивание без ключа API). Не сохраняйте ссылку: запросите сообщение заново. |
expires_at | string обязательное, может быть null | Когда ссылка перестанет работать, ISO 8601 UTC (около часа); null — постоянный путь. |
#Message
Сообщение диалога. Содержит персональные данные клиента (текст, вложения).
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор сообщения (uuid). |
conversation_id | string обязательное | Диалог. |
sender | string обязательное | Отправитель: customer — клиент, ai — ИИ, operator — оператор, system — служебное. Значения: customer ai operator system |
content_type | string обязательное | Вид содержимого: text, image, file … |
content | string обязательное, может быть null | Текст; null — текста нет (только вложение) или сообщение удалено. |
attachments | array<MessageAttachment> обязательное | Вложения (сейчас не больше одного). |
deleted | boolean обязательное | true — сообщение удалено (приходит только при include_deleted=true; текста и вложений нет). |
created_at | string обязательное | Время сообщения, ISO 8601 UTC. |
#ConversationPage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<Conversation> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |
#MessagePage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<Message> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |
#LeadFlags
Флаги ИИ по переписке. true/false ставятся только при уверенности модели.
| Поле | Тип | Описание |
|---|---|---|
buy_intent | boolean обязательное, может быть null | Намерение купить; null — модель не уверена. |
support | boolean обязательное, может быть null | Обращение в поддержку, а не покупка; null — не уверена. |
supplier | boolean обязательное, может быть null | Поставщик или рекламодатель, а не клиент; true уводит лид в архив (ai_not_client). |
#LeadScore
Оценка лида. null у лида, которого ещё не оценивали.
| Поле | Тип | Описание |
|---|---|---|
score | integer обязательное | Балл 0–100. |
grade | string обязательное | Класс: A — 75 и выше, B — 50–74, C — 25–49, D — ниже 25. Значения: A B C D |
reason | string обязательное, может быть null | Объяснение оценки; null, пока не записано. |
flags | LeadFlags обязательное, может быть null | |
source | string обязательное, может быть null | Кто оценил: ai, external или manual; null — неизвестно. Значения: ai external manual |
model | string обязательное, может быть null | Модель, поставившая флаги; null, если оценка не ИИ. |
scored_at | string обязательное, может быть null | Когда выставлена оценка. ISO 8601 UTC. |
#LeadContact
Контакт лида. Содержит персональные данные: выдача пишется в журнал выдач.
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор контакта. |
first_name | string обязательное, может быть null | |
last_name | string обязательное, может быть null | |
email | string обязательное, может быть null | ПДн. |
phone | string обязательное, может быть null | ПДн. |
tags | array<string> обязательное | |
geo_country | string обязательное, может быть null | Страна по IP (ISO 3166-1 alpha-2). |
geo_city | string обязательное, может быть null | Город по IP. |
#LeadAttribution
Откуда пришёл лид (первое касание). null, если следов нет.
| Поле | Тип | Описание |
|---|---|---|
utm_source | string обязательное, может быть null | |
utm_medium | string обязательное, может быть null | |
utm_campaign | string обязательное, может быть null | |
first_page | string обязательное, может быть null | Страница первого визита. |
referrer | string обязательное, может быть null |
#Lead
Лид арендатора.
| Поле | Тип | Описание |
|---|---|---|
id | string обязательное | Идентификатор лида. |
external_id | string обязательное, может быть null | Идентификатор во внешней CRM; null, пока внешняя CRM не подключена. |
external_url | string обязательное, может быть null | |
version | integer обязательное, может быть null | Версия для If-Match; null, пока в базе нет колонки версии — используйте etag. |
etag | string обязательное | Метка версии (совпадает с заголовком ETag карточки). |
status | string обязательное | Один из шести канонических статусов. Архив — флаг archived, не статус. Значения: new qualified proposal negotiation won lost |
archived | boolean обязательное | Лид в архиве. |
archived_reason | string обязательное, может быть null | Причина архива, например ai_not_client. |
owner | string обязательное | Где живёт лид: internal — в нашей CRM. Значения: internal external |
title | string обязательное, может быть null | |
source | string обязательное, может быть null | |
assigned_to | string обязательное, может быть null | Идентификатор ответственного сотрудника. |
value | Money обязательное, может быть null | |
product_id | string обязательное, может быть null | |
course_slug | string обязательное, может быть null | |
contact | LeadContact обязательное, может быть null | |
conversation_id | string обязательное, может быть null | |
attribution | LeadAttribution обязательное, может быть null | |
score | LeadScore обязательное, может быть null | |
flags | LeadFlags обязательное, может быть null | |
intent | string обязательное, может быть null | |
ai_summary | string обязательное, может быть null | |
next_action | string обязательное, может быть null | |
next_action_at | string обязательное, может быть null | ISO 8601 UTC. |
lost_reason | string обязательное, может быть null | |
qualified_at | string обязательное, может быть null | ISO 8601 UTC. |
won_at | string обязательное, может быть null | ISO 8601 UTC. |
lost_at | string обязательное, может быть null | ISO 8601 UTC. |
last_activity_at | string обязательное, может быть null | ISO 8601 UTC. |
created_at | string обязательное | Создан. ISO 8601 UTC. |
updated_at | string обязательное | Изменён. ISO 8601 UTC. |
#LeadPage
Страница списка.
| Поле | Тип | Описание |
|---|---|---|
data | array<Lead> обязательное | |
next_cursor | string обязательное, может быть null | Курсор следующей страницы; null — список закончился. Живёт 24 часа. |