Объект кампании, блокеры и предупреждения

Объект кампании

Приходит в POST /v1/campaigns, GET /v1/campaigns/{id}, POST …/launch, POST …/pause, POST …/resume, POST …/cancel.

Поле	Тип	Описание
`campaign_id`	string	Идентификатор (`cam-…`).
`status`	string	`draft` \| `scheduled` \| `running` \| `paused` \| `completed` \| `cancelled`.
`created_via`, `launched_via`	string	`api` \| `web` \| `""`. `launched_via` проставляется на переходе запуска и у черновика остаётся `""`.
`name`, `agent_id`	string	Как сохранено (название обрезано по пробелам).
`timezone`	string	Действующая зона IANA.
`timezone_source`	string	`request`, если зону назвали вы, и `organization`, если она унаследована. Одинаково на всех путях (создание, чтение, список).
`starts_at`, `ends_at`	number \| null	Секунды эпохи.
`accepts_call_additions`	boolean
`calls_per_minute`	integer	Ступень, с которой кампания набирает. Совпадает с тем, что вы прислали.
`call_strategy`, `classification`	string
`consent_tier`	string	`pewc` \| `pec` — выводится из `classification`, не хранится; тип, под формулировкой которого стоит ваша подпись.
`retry_config`	object	Нормализованная форма; идентификаторы правил присвоены.
`duplicate_action`, `use_contact_timezone`, `working_hours`		Нормализованные отражения присланных настроек.
`binding`	object	`{"trunk_id", "route_id", "from_number"}` — действующая привязка; `route_id` равен `""`, когда группа разрешается из транка при запуске, а не хранится.
`import`	object \| null	Сводка загрузки `planned_calls` этого запроса (только при создании). `null`, если `planned_calls` был пуст, и на всех путях чтения — сводка живёт в `GET /v1/imports/{import_id}`.
`dnc_screen`	object \| null	Сверка текущей (запусковой) загрузки кампании: живая у черновика, зафиксированная после запуска. `null`, если у кампании нет загрузки.
`blockers`, `warnings`	array	Есть при создании, чтении и `launch`; отсутствуют у `pause`/`resume`/`cancel`.

Как читать ответ на создание

status — running (набор идёт), scheduled (окно в будущем) или draft (не начался). Ничто другое в теле не означает «запустилось».
Непустой blockers при создании ⟹ status: "draft". Кампания и отчёт по загрузке сохраняются. Исправьте то, что названо в блокерах, и вызовите POST /v1/campaigns/{id}/launch.
import равен null, если planned_calls был пуст; в blockers тогда лежит no_pending_contacts (если кампания не открыта к добавлению звонков).
warnings ничего не блокируют. Два из них есть практически у каждой кампании: starts_immediately (нет будущего starts_at) и frequency_policy_active (действующие ограничения частоты на номер) — последний заменяется на frequency_limits_disabled, когда эти ограничения выключены.
timezone_source — request, если зону назвали вы, и organization, если она унаследована. Читается одинаково на всех путях: ответ на создание, GET /v1/campaigns/{id} и список согласованы.

Блокеры и предупреждения

blockers и warnings считает та же проверка запуска, что работает в кабинете. Каждый элемент — объект с машиночитаемым code; у большинства блокеров есть ещё field — поле запроса, о котором идёт речь. Форма зависит от пути — читайте только то, что гарантировано:

Где	Форма элемента	Примечания
успешный объект кампании (`POST /v1/campaigns`, `GET /v1/campaigns/{id}`, `POST …/launch`, `GET …/launch-check`)	`{"code", "field"?, "message", …доп. поля}`	`message` — русское человекоориентированное пояснение, в контракт не входит: не разбирайте его и не показывайте конечным пользователям. Дополнительные поля контекста по каждому коду перечислены ниже и стабильны.
`409 launch_blocked` (`error.blockers`)	`{"code", "field", "dnc_screen"?}`	Только коды и поля; блокеры по реестру дополнительно несут обновлённую `dnc_screen`.
`201` у `POST …/calls`	`{"code", "field"}`	Только коды и поля (`field` может быть `""`).

Как читать blockers в GET /v1/campaigns/{id} и launch-check. На путях чтения список отвечает на вопрос «что сказала бы проверка запуска прямо сейчас», причём считается без подписи и независимо от текущего статуса. Следствия: у работающей кампании всегда виден attestation_required (подпись даётся на каждый запуск, а не хранится как состояние), а у работающей кампании с опустевшей очередью — no_pending_contacts. То есть на путях чтения непустой blockers не означает status: "draft" — для этого есть status, а blockers читайте как список того, что должен будет пройти будущий launch / resume.

Коды блокеров

Код	`field`	Доп. поля	Что означает
`no_pending_contacts`	`contacts`		Нет контактов, ждущих набора. Не поднимается у кампании с `accepts_call_additions: true`.
`agent_not_published`	`agent_id`		У агента нет опубликованной версии.
`binding_invalid`	`trunk_id`		Транк, группа или номер привязки недоступны (агента нет в группе, пуст пул номеров, нет гранта на транк…).
`starts_date_past`	`starts_at`		Дата начала (в зоне кампании) в прошлом. Прошедшее время сегодняшней даты — это только предупреждение `starts_immediately`.
`ends_before_starts`	`ends_at`		`ends_at` ≤ `starts_at`.
`ends_at_past`	`ends_at`		`ends_at` уже прошёл.
`policy_unavailable`	`market_profile`		Политика набора (пакет рынка) вашей организации не установлена; обратитесь в поддержку.
`contacts_missing_geo`	`contacts`		Рынок США: у контактов загрузки нет геолокации.
`contacts_geo_rejected`	`contacts`	`rejected`, `filename`	Рынок США: строки текущей загрузки отклонены из-за непригодной локации. Снимается только новой загрузкой.
`dnc_screen_required`	`contacts`	`dnc_screen`	У текущей загрузки нет записанной построчной проекции реестра: загрузите контакты заново.
`dnc_matches`	`contacts`	`dnc_screen`, `registry_changed`	Совпадения с реестром и нет действующего решения `skip` для этого точного состава. `registry_changed: true` означает, что решение было, но реестр с тех пор изменился.
`all_contacts_suppressed`	`contacts`	`dnc_screen`	Все ожидающие контакты в реестре; пропустить нельзя.
`attestation_required`	`attestation`		В этом запросе нет подтверждения согласия.
`attestation_stale`	`attestation`		`attestation.import_id` — не текущая загрузка кампании.
`rules_empty`	`retry_config`		Стратегия `expert` без правил.
`rule_permanent_retry`	`retry_config`	`rule_id`	Правило повторяет постоянный исход (`invalid_destination`, `spam_blocked`; `user_declined` под профилем США).
`campaign_paused`	`status`		Только у `POST …/calls`: партия принята, но до `resume` ничего не набирается.

Коды предупреждений

Код	Доп. поля	Что означает
`starts_immediately`		Нет будущего `starts_at`: набор начнётся при запуске.
`frequency_policy_active`	`rolling_7d_cap`, `daily_cap`, `source` (`organization` \| `platform_default`)	Действующие для этой кампании ограничения частоты на номер. Присутствует, пока лимиты включены, — то есть у каждой кампании, кроме случая ниже.
`frequency_limits_disabled`	`source` (`campaign` \| `organization`)	Настраиваемые частотные лимиты выключены, `source` говорит какой настройкой. Приходит вместо `frequency_policy_active`, не вместе с ним. Reg F и капы штатов продолжают действовать.
`working_hours_law_only`	`field: "working_hours"`	Рынок США, пустое расписание: действует только законное окно.
`working_hours_org_window_only`	`field: "working_hours"`, `start`, `end`, `source`	Пустое расписание: действует окно обзвона организации `start`–`end`.
`retry_schedule_exceeds_end`	`lost`	Лестница повторов длиннее остатка окна кампании; `lost` повторов не состоится.
`variable_uncovered`	`variable`	Агент использует переменную, которую строки не принесли; движок подставляет пустую строку.
`variable_case_mismatch`	`variable`, `column`	Колонка сопоставлена с переменной без учёта регистра и разделителей.
`variable_partial`	`variable`	Переменная заполнена только у части строк.
`rule_action_unsupported`	`rule_id`	Правило `expert` использует действие, которое движок не исполняет (`retry_in`); решает общая таблица исходов.
`rule_goal_without_criteria`	`rule_id`	Правило `goal_not_achieved` при том, что агент не задаёт критерия успеха — правило никогда не сработает.
`rule_budget_masked`	`rule_id`	`max_matches` правила не меньше числа попыток кампании — недостижимо.

​Объект кампании, блокеры и предупреждения