# Команды

Итоги добавления лидов и остановки, состояния и очередь.

Базовый адрес: https://api.melioralab.io/v1. Ключ передается в заголовке `Authorization: Bearer mel_live_...`.

Маршруты:

- `GET /v1/commands/{id}`: Получить команду

## Объект Command

Команда приема или остановки. Завершение обработки не подтверждает отправку.

| Поле | Тип | Описание |
|---|---|---|
| `object` | string | Тип объекта, всегда `command`. |
| `id` | string (uuid) | Идентификатор для опроса команды. |
| `kind` | string | `enroll`: добавление; `stop`: остановка. Значения: `enroll`, `stop`. |
| `state` | string | `accepted`, `running`, `done`, `done_with_unknown`, `failed`. Это состояние обработки команды. Значения: `accepted`, `running`, `done`, `done_with_unknown`, `failed`. |
| `workspace_id` | string (uuid) | Пространство исходной команды. |
| `campaign_id` | string (uuid) | Кампания исходной команды. |
| `lead_id` | string (uuid) или null | Лид стопа; у пакета `null`. |
| `created_at` | string (date-time) | Время приема команды. |
| `finished_at` | string (date-time) или null | Время завершения или `null`. |
| `cleanup_pending` | boolean | Осталась уборка остановленных задач. Продолжайте опрос. |
| `result` | object | Счетчики приема либо итог остановки. |
| `items` | array of object | Результаты лидов в исходном порядке. У стопа пустой массив. |
| `items[].input_index` | integer | Номер входного элемента с нуля. |
| `items[].lead_id` | string (uuid) или null | Принятый или существующий лид; `null` при отказе. |
| `items[].username` | string или null | Нормализованный ник или `null`. |
| `items[].external_id` | string или null | Внешний идентификатор или `null`. |
| `items[].status` | string | `accepted`: новый лид; `existing`: существующий без изменений; `rejected`: отказ. Значения: `accepted`, `existing`, `rejected`. |
| `items[].reason` | string или null | Причина отказа или удержания, либо `null`. |
| `items[].warnings` | array of string | `first_message_long` при длине от 700 символов. |
| `items[].queue_state` | string | `waiting`, `queued`, `held`, `failed`, `stopped`, `not_required`. Постановка не подтверждает отправку. Значения: `waiting`, `queued`, `held`, `failed`, `stopped`, `not_required`. |

Пример:

```json
{
  "object": "command",
  "id": "bd465c91-d715-4987-ab61-e63a9f01c625",
  "kind": "enroll",
  "state": "accepted",
  "workspace_id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43",
  "campaign_id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14",
  "lead_id": null,
  "created_at": "2026-10-27T09:15:42.000Z",
  "finished_at": null,
  "cleanup_pending": false,
  "result": {
    "accepted": 1,
    "inserted": 1
  },
  "items": [
    {
      "input_index": 0,
      "lead_id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31",
      "username": "example_lead",
      "external_id": "crm-1042",
      "status": "accepted",
      "reason": null,
      "warnings": [],
      "queue_state": "waiting"
    }
  ]
}
```

## Объект CommandItem

Итог приема и постановки одного лида.

| Поле | Тип | Описание |
|---|---|---|
| `input_index` | integer | Номер входного элемента с нуля. |
| `lead_id` | string (uuid) или null | Принятый или существующий лид; `null` при отказе. |
| `username` | string или null | Нормализованный ник или `null`. |
| `external_id` | string или null | Внешний идентификатор или `null`. |
| `status` | string | `accepted`: новый лид; `existing`: существующий без изменений; `rejected`: отказ. Значения: `accepted`, `existing`, `rejected`. |
| `reason` | string или null | Причина отказа или удержания, либо `null`. |
| `warnings` | array of string | `first_message_long` при длине от 700 символов. |
| `queue_state` | string | `waiting`, `queued`, `held`, `failed`, `stopped`, `not_required`. Постановка не подтверждает отправку. Значения: `waiting`, `queued`, `held`, `failed`, `stopped`, `not_required`. |

Пример:

```json
{
  "input_index": 0,
  "lead_id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31",
  "username": "example_lead",
  "external_id": "crm-1042",
  "status": "accepted",
  "reason": null,
  "warnings": [],
  "queue_state": "waiting"
}
```

## Объект EnrollResult



| Поле | Тип | Описание |
|---|---|---|
| `accepted` | integer | Число новых лидов, принятых к постановке. |
| `inserted` | integer | Число созданных записей, включая возможный отказ политики после создания. Без `existing`. |

Пример:

```json
{
  "accepted": 1,
  "inserted": 1
}
```

## Объект StopResult



| Поле | Тип | Описание |
|---|---|---|
| `automation_state` | string | `stopping`: отправка начата; `stopped`: новых попыток не будет. Значения: `stopped`, `stopping`. |
| `send_in_flight` | boolean | Уже начатая отправка еще может завершиться. |
| `unknown_outcome_message_ids` | array of string | Непрозрачные идентификаторы неизвестных исходов. Не повторяйте отправку по ним. |

Пример:

```json
{
  "automation_state": "stopping",
  "send_in_flight": true,
  "unknown_outcome_message_ids": []
}
```

## Получить команду

`GET /v1/commands/{id}`

Нужно право вида команды: `leads:enroll` для enroll, `leads:stop` для stop. Опрос не запускает отправку.

Право: `leads:enroll | leads:stop`. Вес запроса: 1.

### Параметры

| Параметр | Где | Тип | Обязательный | Описание |
|---|---|---|---|---|
| `id` | путь | string (uuid) | да | Идентификатор команды. |

### Ответ

Объект `Command`.

### Особые ошибки

- `scope_required` (403): Ключ не разрешает операцию. Для команды нужно право ее вида.
- `not_found` (404): Объект не найден или находится вне охвата ключа. Неизвестный путь тоже дает 404.

Общие ошибки: https://docs.melioralab.io/md/errors.md

### Пример запроса

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

### Пример ответа

```json
{
  "object": "command",
  "id": "bd465c91-d715-4987-ab61-e63a9f01c625",
  "kind": "enroll",
  "state": "accepted",
  "workspace_id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43",
  "campaign_id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14",
  "lead_id": null,
  "created_at": "2026-10-27T09:15:42.000Z",
  "finished_at": null,
  "cleanup_pending": false,
  "result": {
    "accepted": 1,
    "inserted": 1
  },
  "items": [
    {
      "input_index": 0,
      "lead_id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31",
      "username": "example_lead",
      "external_id": "crm-1042",
      "status": "accepted",
      "reason": null,
      "warnings": [],
      "queue_state": "waiting"
    }
  ]
}
```