# Команды

Команда связывает прием запроса с результатами его обработки. Проверяйте ее после добавления лидов или остановки.

> **Важно.** Доступ к записи включается для кабинета по запросу.

## Получение команды

`GET /v1/commands/{id}` возвращает HTTP 200 и [объект команды](https://docs.melioralab.io/reference/commands/). `id` берется из ответа 202 на добавление или стоп. Вес 1; тело и `Idempotency-Key` для GET не нужны.

Для `kind=enroll` ключу нужно `leads:enroll`, для `kind=stop` нужно `leads:stop`. Одного `leads:read` недостаточно. Проверяются кабинет и охват исходной кампании и пространства, в том числе после удаления или переноса карточки. Ключ другого кабинета команду не увидит.

```bash
curl https://api.melioralab.io/v1/commands/bd465c91-d715-4987-ab61-e63a9f01c625 \
  -H "Authorization: Bearer $MELIORA_API_KEY"
```

## Состояния

- `accepted`: команда сохранена, обработка еще ожидается.
- `running`: команда обрабатывается.
- `done`: обработка завершена. Для добавления проверьте каждый элемент: среди них могут быть отказы и удержания. Состояние не подтверждает отправку сообщения.
- `done_with_unknown`: остановка завершена, но исход некоторых прошлых отправок неизвестен. Смотрите `result.unknown_outcome_message_ids`; не повторяйте отправку.
- `failed`: обработка команды завершилась ошибкой. Сохраните команду и причины элементов для диагностики; сначала сверьте лидов, затем решайте, какие отклоненные элементы исправить и отправить отдельной операцией.

`finished_at` заполнен после завершения, до него `null`. У стопа `cleanup_pending` показывает незавершенную уборку. Наблюдение команды не является действием отправки и не возобновляет цепочку.

## Итоги

У добавления `result.accepted` и `result.inserted` содержат счетчики, а `items` содержит результаты в исходном порядке с `input_index` от нуля. `status` (`accepted`, `existing`, `rejected`) фиксирует итог приема. `queue_state` (`waiting`, `queued`, `held`, `failed`, `stopped`, `not_required`) показывает дальнейшую постановку. Их значения описаны в [добавлении лидов](https://docs.melioralab.io/enroll-leads/#rezultat).

У стопа `items=[]`. В `result` приходят `automation_state` (`stopped` или `stopping`), `send_in_flight` и `unknown_outcome_message_ids`. См. [остановку лида](https://docs.melioralab.io/stop-lead/#rezultat). Команда не возвращает первый текст и не позволяет изменить уже принятые поля.

## Опрос

Опрашивайте одну команду с паузой, например 2 секунды, без параллельных циклов. При 429/503 повторяйте GET после `Retry-After` с разбросом; при 401/403 остановите опрос и исправьте доступ. Не повторяйте POST с новым ключом только потому, что команда еще работает.

Примеры используют функцию `meliora()` из [лимитов и повторов](https://docs.melioralab.io/rate-limits/#povtor-bezopasen), которая обрабатывает 429/503. Ограничение в 60 опросов прекращает ожидание, но не отменяет команду: сохраните ID для продолжения позже.

```python
terminal = {"done", "done_with_unknown", "failed"}
command_id = "bd465c91-d715-4987-ab61-e63a9f01c625"
for _ in range(60):
    command = meliora(f"/commands/{command_id}")
    if command["state"] in terminal and not command["cleanup_pending"]:
        print(command)
        break
    time.sleep(2)
else:
    raise TimeoutError(f"Command still pending: {command_id}")
```
```js
const terminal = new Set(['done', 'done_with_unknown', 'failed']);
const commandId = 'bd465c91-d715-4987-ab61-e63a9f01c625';
let settled = false;
for (let i = 0; i < 60; i++) {
  const command = await meliora(`/commands/${commandId}`);
  if (terminal.has(command.state) && !command.cleanup_pending) {
    console.log(command);
    settled = true;
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 2000));
}
if (!settled) throw new Error(`Command still pending: ${commandId}`);
```

После `done` у добавления смотрите состояния лидов и [события](https://docs.melioralab.io/events-polling/): только подтвержденный факт отправки дает `message.sent` или `lead.first_message_sent`. После стопа ожидайте `lead.stopped`; его публикация может произойти позже ответа команды.