Public API — кабинет, баланс, коммуникации

Базовый URL

https://s2t.a5x.pro/api/public

Передайте API-ключ (sk_live_...) в заголовке Authorization: Bearer <token> или X-API-Key: <token>. Ключ создаётся в личном кабинете A5X. Невалидный ключ → 401 invalid_api_key; клиент на паузе (is_active=false) → 403 client_inactive на write-путях (Speech/STT и POST /v1/chats/.../messages). На паузе остаются доступны чтение коммуникаций и спикеров, а также /v1/balance, /v1/balance/history, /v1/payment-link, /v1/session-link и /v1/chats/list — чтобы пополнить баланс и посмотреть список чатов.

Быстрый старт

curl -X POST "https://s2t.a5x.pro/api/public/v1/session-link" \
  -H "Authorization: Bearer YOUR_API_KEY"

Коммуникация

GEThttps://s2t.a5x.pro/api/public/v1/communications

Получить коммуникацию по id или request_record_id — обязателен хотя бы один параметр. После webhook (transcription.completed, summary.completed, qc.completed, memory.completed) запрашивайте этот endpoint: реплики только из content, язык — language, длительность — duration_ms. Summary и qc_evaluation — когда готовы. Статусы summary_generation_status / qc_generation_status / memory_generation_status — в таблице ниже. Коды критериев — в справочнике внизу страницы. Доступен при is_active=false.

Параметры запроса

Поле	Тип	Описание
`id`	string (uuid)	UUID коммуникации.
`request_record_id`	string	Ваш ID записи в CRM (1–64 символа).

summary_generation_status / qc_generation_status / memory_generation_status

Поле	Тип	Описание
`pending`	status	Задача ещё не взята в работу.
`processing`	status	Идёт генерация — продолжайте опрос.
`success`	status	Готово. Терминальный статус для опроса; в ответе есть summary / `qc_evaluation` (для memory — факты в профиле спикера).
`error`	status	Ошибка генерации. Терминальный статус; детали — в `*_generation_error_message` (если есть).
`skipped`	status	Генерация не запускалась или отсеяна (не запрошена, feature off, слишком короткий транскрипт и т.п.). Терминальный статус.

Примеры запросов

curl "https://s2t.a5x.pro/api/public/v1/communications?id=YOUR_COMMUNICATION_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Успешный ответ (200)

{
  "tenant_id": "2c8e5f14-9a3b-4d71-b6e0-1f4a8c2d9e37",
  "id": "c7e1a904-3b5d-4f82-9a1e-0d2c6b8e4f15",
  "kind": "call",
  "channel_type": "phone",
  "communication_status": "closed",
  "request_record_id": "crm-48291",
  "created_at": "2026-06-14T09:12:03.218400Z",
  "occured_at": "2026-07-09T14:22:18.503200Z",
  "duration_ms": 47280,
  "language": "ru",
  "direction": "in",
  "transcription_status": "success",
  "summary_generation_status": "success",
  "qc_generation_status": "success",
  "memory_generation_status": "success",
  "qc_generation_error_message": null,
  "qc_generation_updated_at": "2026-07-09T14:26:10.112000Z",
  "qc_evaluation": {
    "evaluation_id": "9c2e1a44-7b8d-4f01-a3c5-6e0f8d2b1a77",
    "scenario_code": "sales_inbound",
    "score_pct": 75,
    "comment": "Оператор поприветствовал клиента и зафиксировал следующий шаг.",
    "status": "success",
    "criteria": [
      {
        "code": "greeting",
        "value_type": "binary",
        "value": true,
        "evidence": "Добрый день, A5X Cloud, меня зовут Андрей."
      }
    ]
  },
  "content": [
    {
      "idx": 0,
      "kind": "audio_utterance",
      "at": "2026-07-09T14:22:19.743Z",
      "text": "Добрый день, A5X Cloud, меня зовут Андрей. Звоню по вашей заявке на демо речевой аналитики — удобно сейчас пару минут?",
      "label": "SPEAKER_00",
      "start_ms": 1240,
      "end_ms": null,
      "media": []
    },
    {
      "idx": 1,
      "kind": "audio_utterance",
      "at": "2026-07-09T14:22:30.583Z",
      "text": "Да, слушаю.",
      "label": "SPEAKER_01",
      "start_ms": 12080,
      "end_ms": null,
      "media": []
    },
    {
      "idx": 2,
      "kind": "audio_utterance",
      "at": "2026-07-09T14:22:31.923Z",
      "text": "Отлично. Вы интересовались транскрибацией и виджетом для сайта. Что для команды приоритетнее?",
      "label": "SPEAKER_00",
      "start_ms": 13420,
      "end_ms": null,
      "media": []
    },
    {
      "idx": 3,
      "kind": "audio_utterance",
      "at": "2026-07-09T14:22:40.153Z",
      "text": "Скорее транскрибация, у нас колл-центр на двести операторов.",
      "label": "SPEAKER_01",
      "start_ms": 21650,
      "end_ms": null,
      "media": []
    },
    {
      "idx": 4,
      "kind": "audio_utterance",
      "at": "2026-07-09T14:22:45.803Z",
      "text": "Понял. Могу прислать расчёт по минутам и кейс из ритейла.",
      "label": "SPEAKER_00",
      "start_ms": 27300,
      "end_ms": null,
      "media": []
    },
    {
      "idx": 5,
      "kind": "audio_utterance",
      "at": "2026-07-09T14:22:50.643Z",
      "text": "Давайте на почту, которую оставляли.",
      "label": "SPEAKER_01",
      "start_ms": 32140,
      "end_ms": null,
      "media": []
    },
    {
      "idx": 6,
      "kind": "audio_utterance",
      "at": "2026-07-09T14:22:54.383Z",
      "text": "Хорошо, отправлю сегодня до шести.",
      "label": "SPEAKER_00",
      "start_ms": 35880,
      "end_ms": null,
      "media": []
    },
    {
      "idx": 7,
      "kind": "audio_utterance",
      "at": "2026-07-09T14:22:57.523Z",
      "text": "Спасибо, жду.",
      "label": "SPEAKER_01",
      "start_ms": 39020,
      "end_ms": null,
      "media": []
    },
    {
      "idx": 8,
      "kind": "audio_utterance",
      "at": "2026-07-09T14:23:00.063Z",
      "text": "До связи.",
      "label": "SPEAKER_00",
      "start_ms": 41560,
      "end_ms": null,
      "media": []
    }
  ],
  "summary_text": "Клиент заинтересован в транскрибации для колл-центра на 200 операторов. Договорились отправить расчёт по минутам и ритейл-кейс на e-mail до 18:00.",
  "user_summary": "## Итог
Клиент хочет пилот на 200 операторов. До 18:00 отправить расчёт и кейс.",
  "category": "sales",
  "category_label": "Продажи",
  "speakers": [
    {
      "id": "a4e7c1b9-2f58-4a6d-9c3e-8b1f0d5a6e82",
      "external_id": "client_07",
      "name": "АО «Вектор Логистик»",
      "role": "client",
      "label": "SPEAKER_01"
    },
    {
      "id": "d9f3a6c2-8e41-4b7d-a5f2-3c8e1b0d4f93",
      "external_id": "emp_14",
      "name": "Петров Андрей",
      "role": "sales",
      "label": "SPEAKER_00"
    }
  ],
  "summary_items": [
    {
      "id": "e1b4c8d2-6a3f-4e9b-8c1d-2f5a7b0e3d64",
      "item_type": "criteria",
      "subtype": "objection",
      "content": "Нужна оценка ROI по минутам и пилот на 200 операторов",
      "meta": null,
      "created_at": "2026-07-09T14:25:41.882100Z"
    },
    {
      "id": "a3c9e1f4-2b7d-4a8e-9c0f-1d6e8b2a4c57",
      "item_type": "criteria",
      "subtype": "offer",
      "content": "Расчёт по минутам и ритейл-кейс",
      "meta": null,
      "created_at": "2026-07-09T14:25:41.882100Z"
    },
    {
      "id": "b8d2f6a1-4e9c-4b3a-8f1e-0c7a5d9e2b14",
      "item_type": "criteria",
      "subtype": "agreement",
      "content": "Отправить материалы на e-mail до 18:00",
      "meta": null,
      "created_at": "2026-07-09T14:25:41.882100Z"
    },
    {
      "id": "c4e8a2b7-9d1f-4c6e-8a3b-5f0d7e1c9a28",
      "item_type": "commitment",
      "subtype": null,
      "content": "Отправить КП и кейс на e-mail до 18:00",
      "meta": { "deadline": "2026-07-09T18:00:00Z" },
      "speaker_id": "d9f3a6c2-8e41-4b7d-a5f2-3c8e1b0d4f93",
      "created_at": "2026-07-09T14:25:41.882100Z"
    }
  ]
}

Коды ответов

HTTP	error.code	Ситуация
400	—	Bad request.
401	`invalid_api_key`	Нет ключа, ключ недействителен или отозван.
404	—	Not found.

ContentItem

Канонический таймлайн

kind: audio_utterance (звонок), chat_message, email_message.
at — время реплики (ISO UTC) или null.
Пустые реплики без текста не попадают в массив; для вложения без текста допускается text: "".

Поле	Тип	Описание
`idx`*	integer	Порядок 0…n−1.
`kind`*	string	`audio_utterance` \| `chat_message` \| `email_message`.
`at`	string \| null	Время реплики (ISO 8601 UTC) или `null`.
`text`*	string	Текст; `""` — если есть только `media`.
`label`	string \| null	Ключ автора → `speakers[].label`.
`start_ms`	integer \| null	Начало в записи (мс); у чата/письма обычно `null`.
`end_ms`	integer \| null	Конец в записи (мс) или `null`.
`media`*	array	Вложения `{ type, ref, mime?, name?, size_bytes?, duration_ms? }`. У звонков обычно `[]`.

Список коммуникаций

GEThttps://s2t.a5x.pro/api/public/v1/communications/list

Список коммуникаций по спикеру. Обязателен хотя бы один из: speaker_id, speaker_name, speaker_external_id. В элементах — id (коммуникация), kind, channel_type, summary. Доступен при is_active=false.

Параметры запроса

Поле	Тип	Описание
`speaker_id`	string (uuid)	UUID спикера.
`speaker_name`	string	Имя спикера (1–64 символа).
`speaker_external_id`	string	Внешний ID спикера в CRM (1–64 символа).
`limit`	integer	Лимит элементов (1–100). По умолчанию 20.
`offset`	integer	Смещение для пагинации. По умолчанию 0.

По speaker_external_id

curl "https://s2t.a5x.pro/api/public/v1/communications/list?speaker_external_id=emp_14&limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Успешный ответ (200)

{
  "items": [
    {
      "tenant_id": "2c8e5f14-9a3b-4d71-b6e0-1f4a8c2d9e37",
      "id": "c7e1a904-3b5d-4f82-9a1e-0d2c6b8e4f15",
      "kind": "call",
      "channel_type": "phone",
      "request_record_id": "crm-48291",
      "created_at": "2026-06-14T09:12:03.218400Z",
      "occured_at": "2026-07-09T14:22:18.503200Z",
      "duration_ms": 47280,
      "language": "ru",
      "direction": "in",
      "category": "sales",
      "label_ru": "Продажи",
      "summary_text": "Клиент заинтересован в транскрибации для колл-центра на 200 операторов. Договорились отправить расчёт по минутам и ритейл-кейс на e-mail до 18:00.",
      "user_summary": "## Итог
Клиент хочет пилот на 200 операторов. До 18:00 отправить расчёт и кейс.",
      "speakers": [
        {
          "id": "a4e7c1b9-2f58-4a6d-9c3e-8b1f0d5a6e82",
          "external_id": "client_07",
          "name": "АО «Вектор Логистик»",
          "role": "client"
        },
        {
          "id": "d9f3a6c2-8e41-4b7d-a5f2-3c8e1b0d4f93",
          "external_id": "emp_14",
          "name": "Петров Андрей",
          "role": "sales"
        }
      ]
    },
    {
      "tenant_id": "2c8e5f14-9a3b-4d71-b6e0-1f4a8c2d9e37",
      "id": "d8f2b015-4c6e-5083-ab2f-1e3d7c9f5026",
      "kind": "chat",
      "channel_type": "telegram",
      "request_record_id": null,
      "created_at": "2026-06-10T11:05:22.104800Z",
      "occured_at": "2026-07-03T10:15:44.891300Z",
      "duration_ms": null,
      "language": null,
      "direction": null,
      "category": "support",
      "label_ru": "Поддержка",
      "summary_text": "Клиент в Telegram уточнил статус пилота. Договорились прислать обновлённый чек-лист ИБ.",
      "user_summary": null,
      "speakers": [
        {
          "id": "a4e7c1b9-2f58-4a6d-9c3e-8b1f0d5a6e82",
          "external_id": "client_07",
          "name": "АО «Вектор Логистик»",
          "role": "client"
        },
        {
          "id": "d9f3a6c2-8e41-4b7d-a5f2-3c8e1b0d4f93",
          "external_id": "emp_14",
          "name": "Петров Андрей",
          "role": "sales"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "count": 2
  }
}

Коды ответов

HTTP	error.code	Ситуация
400	—	Bad request.
401	`invalid_api_key`	Нет ключа, ключ недействителен или отозван.

Профиль спикера

GEThttps://s2t.a5x.pro/api/public/v1/speakers/profile

Профиль спикера по speaker_name или speaker_external_id — обязателен хотя бы один параметр. Доступен при is_active=false.

Параметры запроса

Поле	Тип	Описание
`speaker_name`	string	Имя спикера (1–64 символа).
`speaker_external_id`	string	Внешний ID спикера в CRM (1–64 символа).

По speaker_external_id

curl "https://s2t.a5x.pro/api/public/v1/speakers/profile?speaker_external_id=emp_14" \
  -H "Authorization: Bearer YOUR_API_KEY"

Успешный ответ (200)

{
  "tenant_id": "2c8e5f14-9a3b-4d71-b6e0-1f4a8c2d9e37",
  "speaker_id": "d9f3a6c2-8e41-4b7d-a5f2-3c8e1b0d4f93",
  "speaker_external_id": "emp_14",
  "speaker_name": "Петров Андрей",
  "speaker_role": "sales",
  "speaker_department": "Продажи",
  "speaker_created_at": "2026-03-18T08:30:00Z",
  "speaker_updated_at": "2026-07-09T14:25:41Z",
  "summary_items": [
    {
      "id": "e1b4c8d2-6a3f-4e9b-8c1d-2f5a7b0e3d64",
      "item_type": "memory",
      "subtype": "preference",
      "content": "Нужна оценка ROI по минутам и пилот на 200 операторов",
      "meta": null,
      "created_at": "2026-07-09T14:25:41.882100Z"
    },
    {
      "id": "c4e8a2b7-9d1f-4c6e-8a3b-5f0d7e1c9a28",
      "item_type": "commitment",
      "subtype": null,
      "content": "Отправить расчёт по минутам сегодня до 18:00",
      "meta": { "deadline": "2026-07-09T18:00:00Z" },
      "speaker_id": "d9f3a6c2-8e41-4b7d-a5f2-3c8e1b0d4f93",
      "created_at": "2026-07-09T14:25:41.882100Z"
    }
  ]
}

Коды ответов

HTTP	error.code	Ситуация
400	—	Bad request.
401	`invalid_api_key`	Нет ключа, ключ недействителен или отозван.
404	—	Not found.

Баланс

GEThttps://s2t.a5x.pro/api/public/v1/balance

Баланс и флаги биллинга по API-ключу. Доступен при is_active=false — чтобы увидеть паузу и режим кредита. allow_credit=true значит отрицательный баланс сам по себе не отключает клиента.

Узнать баланс

curl "https://s2t.a5x.pro/api/public/v1/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"

Успешный ответ (200)

{
  "balance_rub": "1234.56",
  "is_active": true,
  "allow_credit": false
}

Коды ответов

HTTP	error.code	Ситуация
401	`invalid_api_key`	Нет ключа, ключ недействителен или отозван.

История баланса

GEThttps://s2t.a5x.pro/api/public/v1/balance/history

Постраничная история операций по балансу (ledger). Можно фильтровать по kind, периоду from / to. Доступна при is_active=false.

Параметры запроса

Поле	Тип	Описание
`limit`	integer	Лимит элементов (1–100). По умолчанию 20.
`offset`	integer	Смещение для пагинации. По умолчанию 0.
`kind`	string	Тип операции: `credit` или `debit`.
`from`	string (date-time)	Начало периода (ISO 8601).
`to`	string (date-time)	Конец периода (ISO 8601).

История списаний

curl "https://s2t.a5x.pro/api/public/v1/balance/history?limit=10&offset=0&kind=debit" \
  -H "Authorization: Bearer YOUR_API_KEY"

Успешный ответ (200)

{
  "items": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "amount_rub": -12.5,
      "kind": "debit",
      "description": "speech.transcribe",
      "product": "speech",
      "source": "s2t",
      "source_ref": null,
      "lines": null,
      "created_at": "2026-08-04T10:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "count": 1,
    "total": 42
  }
}

Коды ответов

HTTP	error.code	Ситуация
400	—	Bad request (например, неверный kind).
401	`invalid_api_key`	Нет ключа, ключ недействителен или отозван.

Создать ссылку на оплату

POSThttps://s2t.a5x.pro/api/public/v1/payment-link

Создать ссылку на пополнение баланса. Минимальная сумма — 100 ₽. Email для чека опционален: из тела запроса, иначе из профиля; без email ссылка создаётся без фискального чека. Доступен при is_active=false — чтобы вывести клиента из паузы картой.

Параметры запроса

Поле	Тип	Описание
`amount_rub`*	number	Сумма пополнения в рублях (минимум 100).
`customer_email`	string (email)	Email плательщика для чека. Если не передан и в профиле нет email — ссылка без фискализации.
`redirect_url`	string (uri)	URL редиректа после успешной оплаты.
`fail_redirect_url`	string (uri)	URL редиректа при неуспешной оплате.

Примеры запросов

curl -X POST "https://s2t.a5x.pro/api/public/v1/payment-link" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_rub": 500,
    "customer_email": "user@example.com",
    "redirect_url": "https://partner.example/paid",
    "fail_redirect_url": "https://partner.example/fail"
  }'

Успешный ответ (200)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "payment_url": "https://pay.example/link",
  "amount_rub": 500,
  "status": "pending",
  "customer_email": "user@example.com",
  "purpose": "Услуги по предоставлению доступа к облачной платформе A5X Cloud",
  "expires_at": "2026-08-04T09:15:00.000Z",
  "paid_at": null,
  "created_at": "2026-08-04T09:00:00.000Z"
}

Коды ответов

HTTP	error.code	Ситуация
400	—	Неверные параметры (например, amount_rub < 100).
401	`invalid_api_key`	Нет ключа, ключ недействителен или отозван.
503	—	Payment links не настроены.

Статус ссылки на оплату

GEThttps://s2t.a5x.pro/api/public/v1/payment-link/{id}

Получить статус заказа пополнения по UUID ссылки. Доступен при is_active=false.

Параметры запроса

Поле	Тип	Описание
`id`*	string (uuid)	UUID payment-link из ответа POST.

Проверить статус

curl "https://s2t.a5x.pro/api/public/v1/payment-link/YOUR_PAYMENT_LINK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Успешный ответ (200)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "payment_url": "https://pay.example/link",
  "amount_rub": 500,
  "status": "paid",
  "customer_email": "user@example.com",
  "purpose": "Услуги по предоставлению доступа к облачной платформе A5X Cloud",
  "expires_at": "2026-08-04T09:15:00.000Z",
  "paid_at": "2026-08-04T09:05:00.000Z",
  "created_at": "2026-08-04T09:00:00.000Z"
}

Коды ответов

HTTP	error.code	Ситуация
400	—	Неверный id.
401	`invalid_api_key`	Нет ключа, ключ недействителен или отозван.
404	—	Payment link не найден.

Ссылка входа в кабинет

POSThttps://s2t.a5x.pro/api/public/v1/session-link

Создать одноразовую ссылку для входа в личный кабинет (Dashboard). TTL ~60 с. У клиента должен быть задан email. Доступен при is_active=false — чтобы оплатить счёт / пополнить баланс.

Получить session-link

curl -X POST "https://s2t.a5x.pro/api/public/v1/session-link" \
  -H "Authorization: Bearer YOUR_API_KEY"

Успешный ответ (200)

{
  "tenant_id": "2c8e5f14-9a3b-4d71-b6e0-1f4a8c2d9e37",
  "url": "https://app.a5x.pro/session-link?code=abc",
  "expires_in": 60,
  "expires_at": "2026-08-04T09:01:00.000Z"
}

Коды ответов

HTTP	error.code	Ситуация
401	`invalid_api_key`	Нет ключа, ключ недействителен или отозван.
422	—	У клиента не задан email — session-link недоступен.

Список активных чатов

GEThttps://s2t.a5x.pro/api/public/v1/chats/list

Активные чаты аккаунта: id, имя, public_key для эмбеда на сайте (data-widget-key) и пространства базы знаний по умолчанию. Требует включённый продукт «Чат». Доступен при is_active=false.

Список чатов

curl "https://s2t.a5x.pro/api/public/v1/chats/list" \
  -H "Authorization: Bearer YOUR_API_KEY"

Успешный ответ (200)

{
  "items": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "name": "По умолчанию",
      "header_title": "A5X AI Agent",
      "is_default": true,
      "default_space_ids": [],
      "workflow_flow_id": "770e8400-e29b-41d4-a716-446655440099",
      "public_key": "wk_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "created_at": "2026-09-01T10:00:00.000Z",
      "updated_at": "2026-09-10T12:00:00.000Z"
    }
  ]
}

Коды ответов

HTTP	error.code	Ситуация
401	`invalid_api_key`	Нет ключа, ключ недействителен или отозван.
403	`feature_disabled`	Продукт «Чат» отключён для аккаунта.

Сообщение в чат

POSThttps://s2t.a5x.pro/api/public/v1/chats/{chat_id}/messages

Отправить вопрос агенту выбранного чата и получить полный ответ в одном HTTP-ответе. В теле: text (обязательно); опционально history, space_ids. Без опциональных полей используются настройки чата. Историю хранит интегратор. Чтобы отменить — оборвите HTTP-запрос. Тарифицируется как сообщения чата. Требует активного клиента.

Параметры запроса

Поле	Тип	Описание
`chat_id`	string (uuid)	Id чата из `GET /v1/chats/list`.
`text`*	string	Текст вопроса.
`history`	array	Предыдущие реплики `{ role, content }` (`user` / `assistant`).
`space_ids`	string[] (uuid)	Пространства базы знаний. По умолчанию — из настроек чата.

Задать вопрос

curl -X POST "https://s2t.a5x.pro/api/public/v1/chats/YOUR_CHAT_ID/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Сколько звонков за неделю?"}'

Успешный ответ (200)

{
  "request_id": "990e8400-e29b-41d4-a716-446655440099",
  "markdown": "За неделю было 42 звонка…",
  "context": {
    "communications": [],
    "documents": [],
    "memory": []
  }
}

Коды ответов

HTTP	error.code	Ситуация
400	—	Пустой / слишком длинный text или невалидное тело.
401	`invalid_api_key`	Нет ключа, ключ недействителен или отозван.
403	`client_inactive`	Клиент на паузе — сообщения недоступны.
404	—	Чат не найден или неактивен.
429	—	Превышен лимит запросов.

Формат ошибки (auth)

{
  "error": {
    "message": "API key is invalid or revoked",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Типичные коды

HTTP	error.code	Ситуация
400	—	Неверные параметры запроса.
401	`invalid_api_key`	Нет ключа, ключ недействителен или отозван (`missing_api_key` / `malformed_bearer` / `invalid_api_key`).
403	`client_inactive`	Клиент неактивен (`is_active=false`) на write-путях (Speech/STT, `POST /v1/chats/.../messages`). Не путать с 401: ключ валиден, сервис на паузе. Чтение коммуникаций/спикеров и `/v1/balance`, `/v1/balance/history`, `/v1/payment-link`, `/v1/session-link`, `/v1/chats/list` остаются доступны.
404	—	Ресурс не найден.
422	—	Запрос понят, но не может быть выполнен (например, нет email для session-link).

Критерии QC

Коды критериев в qc_evaluation.criteria[].code. Тип binary — да/нет (или null, если критерий неприменим); numeric — числовая оценка. Набор критериев в сценарии настраивается в кабинете; ниже — полный каталог платформы.

Код критерия

Поле	Тип	Описание
`greeting`	binary	Приветствие — оператор поприветствовал клиента.
`brand_mention`	binary	Упоминание бренда — оператор назвал компанию / бренд.
`operator_self_intro`	binary	Представление оператора — оператор представился (имя).
`ask_client_name`	binary	Запрос имени клиента — оператор спросил, как обращаться.
`address_by_name`	numeric	Обращение по имени — сколько раз оператор обратился к клиенту по имени.
`need_clarified`	binary	Уточнение потребности — оператор уточнил запрос клиента.
`identify_entity`	binary	Идентификация сущности — заказ / тикет / договор / счёт.
`confirm_details`	binary	Подтверждение деталей — оператор подтвердил ключевые детали с клиентом.
`contact_exchange`	binary	Обмен контактными данными — запросил / подтвердил контакты или оставил свои для связи.
`official_contacts_only`	binary	Только официальный канал — личный телефон / мессенджер / личная почта = false; иначе true. Рабочий номер компании не нарушение.
`next_step_stated`	binary	Следующий шаг — оператор озвучил следующий шаг.
`ask_reason`	binary	Причина — оператор спросил причину (отмены / жалобы / ухода).
`handle_objection`	binary	Работа с возражением — оператор отработал возражение / сомнение.
`offer_presented`	binary	Презентация предложения — оператор презентовал оффер / решение.
`verification_done`	binary	Верификация — оператор провёл верификацию клиента.
`disclaimer_stated`	binary	Дисклеймер — оператор озвучил обязательный дисклеймер.
`thanks`	binary	Благодарность — оператор поблагодарил клиента.
`farewell`	binary	Прощание — оператор попрощался.
`aggression_response`	binary	Реакция на агрессию — при агрессии клиента корректно отреагировал; если агрессии не было — value null.
`tone_of_voice`	numeric	Тон общения — оценка тона оператора от 0 до 1.

Сценарии QC

Код сценария в qc_evaluation.scenario_code. Готовые шаблоны; в кабинете можно включать, отключать и менять набор критериев.

Код сценария

Поле	Тип	Описание
`new_request`	scenario	Новое обращение — первый контакт, новая заявка «с нуля».
`existing_case`	scenario	По существующему кейсу — статус / изменение по заказу, тикету, договору.
`cancellation`	scenario	Отказ / отмена — клиент инициирует отмену или отказ.
`sales_outbound`	scenario	Исходящие продажи — аутрич, презентация.
`sales_inbound`	scenario	Входящие продажи — клиент интересуется покупкой.
`support_incident`	scenario	Поддержка: инцидент — сбой / «не работает».
`support_howto`	scenario	Поддержка: консультация — как сделать / настройка.
`billing_inquiry`	scenario	Биллинг / оплата — счёт, долг, возврат.
`complaint`	scenario	Жалоба — претензия / эскалация.
`retention`	scenario	Удержание — угроза ухода / непродление.
`collection`	scenario	Напоминание об оплате — soft-collection.
`base_etiquette`	scenario	Базовый этикет — минимум вежливости без узкого сценария.

Категории коммуникаций

Категория коммуникации (category) и типичные подтипы (subtype).

Поле	Тип	Описание
`no_contact`	category	Нет живого контакта: IVR, автоответчик, недозвон, занято, сброс. Ключи: `contact_outcome`, `dial_hint`.
`sales`	category	Продажи и пресейл: новый клиент, допродажа, квалификация, демо; тип — в `deal_type`. Ключи: `deal_type`, `funnel_stage`, `offer`, `objection`, `agreement`, `competitors`, `next_touch_at`.
`renewal`	category	Продление, пересмотр условий текущего контракта, удержание, риск ухода. Ключи: `topic`, `churn_risk`, `agreement`, `next_touch_at`.
`support`	category	Сбои, настройки, доступ, обучение, типовые вопросы по API/интеграции. Ключи: `topic`, `outcome`, `urgency`, `resolution`.
`billing`	category	Счета, акты, оплата, задолженность (не баг функционала). Ключи: `topic`, `outcome`, `disputes`.
`supply`	category	Заказ, отгрузка, документы, доставка, склад, маршруты. Ключи: `topic`, `order_status`, `documents`, `delivery_status`, `constraints`, `urgency`, `outcome`.
`complaint`	category	Жалоба, эскалация, ультиматумы, требование компенсации или руководства. Ключи: `topic`, `severity`, `requested_resolution`, `escalation`.
`internal`	category	Внутреннее совещание / планерка / standup / 1:1 / синк — без внешнего контрагента. Ключи: `topic`, `decisions`, `outcome`, `next_touch_at`.

Типы элементов summary

Тип элемента в массиве summary_items (item_type).

Поле	Тип	Описание
`criteria`	item_type	Факты коммуникации: возражения, оффер, исход и др. (см. subtype).
`commitment`	item_type	Обещания сотрудника; дедлайн — в meta.deadline.
`memory`	item_type	Накопленные факты о клиенте между касаниями (привязаны к speaker_id).