для разработчиков

REST API

Читайте заявки и диалоги компании и создавайте заявки из своих систем: 1С, сайта, CRM, скриптов. API отвечает JSON.

Ключ API

Ключ выпускает владелец или администратор в кабинете: Настройки → API и вебхуки → Ключи API. Ключ вида cn_live_… показывается один раз — сохраните его сразу. Мы храним только хэш.
Права ключа: только чтение или чтение и запись (запись — создание заявок).
Отзыв ключа действует сразу: следующий запрос с ним получит 401. До 20 действующих ключей на компанию.

Запросы

Адрес API — https://app.chatneuron.ru/api/v1. Ключ передаётся в заголовке Authorization: Bearer cn_live_… (или X-Api-Key). Не больше 120 запросов в минуту на ключ: сколько осталось — в заголовках X-RateLimit-Remaining и X-RateLimit-Reset, сверх лимита ответ 429 с заголовком Retry-After. У каждого ответа есть X-Request-Id — назовите его поддержке, если что-то пошло не так.

curl https://app.chatneuron.ru/api/v1/me \
  -H "Authorization: Bearer cn_live_…"

Ошибки

Ошибка приходит с HTTP-статусом и телом:

{
  "error": {
    "code": "unauthorized",
    "message": "Ключ не найден или отозван"
  }
}

Статус	code	Когда
400	`invalid_request`	Некорректное тело запроса или параметры
401	`unauthorized`	Нет ключа, ключ отозван или неверный
403	`forbidden`	Ключу не хватает прав (запись ключом только на чтение)
403	`locked`	Запись скрыта до оплаты тарифа
404	`not_found`	Нет такой заявки или диалога в компании ключа
409	`idempotency_in_progress`	Запрос с этим Idempotency-Key ещё выполняется
422	`idempotency_mismatch`	Idempotency-Key уже использован с другим телом запроса
429	`rate_limited`	Больше 120 запросов в минуту

Списки и страницы

Списки отдаются новыми записями вперёд. Параметры: limit — от 1 до 100 (по умолчанию 50), since — дата ISO 8601, с которой брать записи, cursor — значение nextCursor из прошлого ответа. Когда nextCursor равен null, страниц больше нет.

Справочник

Поля ресурса, параметры, примеры на cURL, Node.js и Python, ответы и ошибки — на странице каждого раздела.

КомпанияПроверка ключа: к какой компании он относится и какие у него права.ЗаявкиЗаявки, которые собрали AI-сотрудники во всех каналах, и создание заявок из ваших систем.ДиалогиДиалоги AI-сотрудников с клиентами во всех каналах: сайт, мессенджеры, телефон, приложения.СотрудникиAI-сотрудники компании: кто собирает заявки и ведёт диалоги. Их id — agentId в заявках и диалогах.КлиентыКлиенты компании — одна карточка на человека по всем каналам — и контрагенты: компании-клиенты и поставщики.ПодключенияКаналы и системы, из которых собираются AI-сотрудники, и подключены ли они у компании.СобытияЛента событий компании за 30 дней — те же, что уходят в исходящие вебхуки. Чтобы догнать пропущенное или обойтись без вебхуков.

Метод	Что делает
get/me	Проверить ключ
get/leads	Список заявок
post/leads	Создать заявку
get/leads/{id}	Заявка
patch/leads/{id}	Изменить заявку
get/dialogs	Список диалогов
get/dialogs/{id}	Диалог
get/dialogs/{id}/messages	Переписка диалога
get/employees	Список AI-сотрудников
get/customers	Список клиентов
get/counterparties	Список контрагентов
get/connectors	Каналы и системы
get/events	Лента событий

Права ключа

При выпуске ключа выберите «Только чтение», «Чтение и запись» или отметьте права по ресурсам — тогда ключ получит только их. Право, которое нужно методу, указано на его странице; без него ответ — 403 с названием права. Какие права у ключа, покажет GET /me.

Право	Что открывает
`leads:read`	Заявки — чтение
`leads:write`	Заявки — создание и изменение
`dialogs:read`	Диалоги и переписка
`customers:read`	Клиенты и контрагенты
`employees:read`	AI-сотрудники
`connectors:read`	Подключённые системы
`events:read`	Лента событий

Каждый вызов виден в кабинете: «Настройки → API и вебхуки → Ключи API → Журнал» — метод, путь, ответ, время и id запроса.

Повтор запросов

Если сеть оборвалась и непонятно, дошёл ли POST или PATCH, повторите его с тем же заголовком Idempotency-Key — любой вашей строкой до 255 символов, например UUID или номером заказа. В течение 24 часов повтор вернёт прежний ответ с заголовком Idempotent-Replayed: true и не создаст вторую заявку.

curl -X POST https://app.chatneuron.ru/api/v1/leads \
  -H "Authorization: Bearer cn_live_…" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+79991234567","message":"Заявка с сайта"}'

Версии

Версия — в адресе: /api/v1. Внутри v1 изменения только добавляют новые поля, методы и события — пропускайте незнакомые поля, и код не сломается. Несовместимые изменения выйдут в /api/v2, а v1 проработает рядом не меньше 12 месяцев. Всё новое — на странице «Изменения».

Спецификация OpenAPI

Полное описание API и вебхуков в формате OpenAPI 3.1 — по адресу https://app.chatneuron.ru/api/v1/openapi.json, без ключа. Импортируйте его в Postman или Insomnia или сгенерируйте клиент на своём языке.

curl https://app.chatneuron.ru/api/v1/openapi.json

Дальше

Чтобы узнавать о новых заявках и диалогах сразу, без опроса API, подключите исходящие вебхуки.