Документация API

Версия API: v1. Базовый адрес: https://crm.linkodium.com.

API нужен, чтобы заявки и звонки попадали в CRM автоматически, а внешние системы работали с заявками, почтой и чатами сотрудников:

• заявки с форм сайта, из квизов, чат-ботов и рекламных кабинетов (раздел 8);
• чтение, правка и выгрузка заявок, лента событий с записями и расшифровками звонков, комментарии с файлами (синхронизация с 1С, учётной системой, своим ботом, разделы 9-14). Это делает ключ сотрудника с его правами (раздел 1);
• почта и чаты сотрудника: чтение переписки, отправка писем и ответы клиентам в Telegram, MAX, Авито и виджете сайта от его имени (разделы 15 и 16);
• звонки из любой АТС (Novofon, Zadarma, Mango, Asterisk и других) вместе с записями разговоров (разделы 17-19);
• всё остальное, что сотрудник делает в кабинете: импорт заявок, расшифровка звонков, правка и удаление сообщений, управление ящиками почты (разделы 21-24), настройки компании, сотрудники, ключи, интеграции и профиль (отдельная страница);
• ИИ-ассистенты Claude, ChatGPT и Cursor по протоколу MCP (раздел 26).

Содержание

1. Ключ API
2. Аутентификация
3. Формат запросов и ответов
4. Ошибки
5. Лимиты
6. Идемпотентность
7. Справочники: GET /api/v1/me, /managers, /statuses, /services
8. Заявки: POST /api/v1/leads
9. Список заявок: GET /api/v1/leads
10. Заявка: GET и PATCH /api/v1/leads/{номер}
11. Статус, архив, объединение
12. Лента событий: GET /api/v1/leads/{номер}/events
13. Комментарии и файлы
14. Выгрузка: GET /api/v1/leads/export.xlsx
15. Почта: /api/v1/mail
16. Чаты: /api/v1/chats
17. Телефония: POST /api/v1/calls
18. Запись звонка файлом: POST /api/v1/calls/recording
19. Пример прослойки для Novofon и Zadarma
20. Переход со старых адресов
21. Импорт через API
22. Расшифровка звонков
23. Чаты: правка, удаление, стикеры, голосовые
24. Почта: ящики, участники, удаление
25. Компания, сотрудники, интеграции
26. ИИ-ассистенты (MCP)
27. Изменения API

1. Ключ API

Ключ выпускает администратор компании для любого сотрудника: Настройки компании -> API-ключи -> Выпустить ключ. Сотрудник может выпустить ключ и сам себе: Профиль -> API-ключи, если администратор не запретил это в «Правах доступа» (право «Выпускать себе API-ключи в профиле», по умолчанию разрешено). При выпуске ключу дают название (например, «Форма на сайте»), по нему ключ потом легко найти в списке.

• Ключ выглядит так: crm_ и 40 символов 0-9a-f, например crm_3f9a....
• Полное значение показывается один раз, сразу после выпуска. Скопируйте его и сохраните в настройках своего сервера. CRM хранит только отпечаток ключа и показать его снова не может. В списке ключей видны только первые символы. Если ключ потерян, выпустите новый и отзовите старый.
• Ключ привязан к компании: всё, что приходит с ним, попадает в эту компанию. Выбрать другую компанию полем запроса нельзя.
• Ключ привязан к сотруднику и действует с его правами. Он видит только те заявки, которые видит сотрудник (при видимости «только свои» только его заявки), и не делает того, что сотруднику запрещено в «Правах доступа». События в ленте заявки подписаны сотрудником с пометкой «через API» (кроме событий звонков из раздела 17 и события «создана» у заявки, созданной звонком: они, как и прежде, пишутся без автора).
• Права сотрудника действуют и на телефонию (calls:write): ключ сотрудника с видимостью «только свои» не показывает номера чужих заявок и не принимает записи к их звонкам (раздел 17). Для телефонии всей компании выпустите ключ администратору или сотруднику с видимостью «все заявки»; прежний ключ компании (ниже) работает как раньше.
• При выпуске выбираются области ключа: какие адреса API он вызывает. Области не дают больше прав, чем есть у сотрудника: leads:read, leads:create, leads:write, leads:export, calls:write, а также почта и чаты: mail:read (ящики, переписка, вложения, «прочитано»), mail:send (отправка писем, привязка переписки к заявке), chats:read (чаты, сообщения, файлы, «прочитано»), chats:write (ответы клиентам, привязка чата к заявке). Почта по ключу сотрудника: только ящики, где он участник, и только по ключу, который сотрудник выпустил себе сам (mail:read и mail:send только себе); чаты: по его режиму доступа к чатам.
• Ключ перестаёт действовать сам, если сотрудника исключили из компании или отключили его учётную запись (ответ 401).
• Ключи, выпущенные до появления ключей сотрудников, остаются ключами компании: они по-прежнему создают заявки (раздел 8) и передают звонки (разделы 17, 18), а на прочие адреса отвечают 403 SCOPE_REQUIRED. Для чтения и правки заявок выпустите ключ сотрудника.
• Заведите отдельный ключ на каждую интеграцию (форма сайта, телефония, чат-бот, синхронизация). Тогда при утечке одного ключа достаточно отозвать только его. Для формы сайта достаточно области leads:create, для телефонии calls:write.
• Отозвать ключ можно там же, в списке ключей; сотрудник отзывает свои ключи в профиле. Отзыв действует сразу.
• Кнопка «Выйти на всех устройствах» в профиле ключи не отзывает: ключ принадлежит интеграции, а не устройству. Исключение сотрудника из компании, смена его роли и его выход из компании отзывают ключи, которые он выпустил и которые привязаны к нему, только с отметкой «Отозвать API-ключи» в карточке сотрудника и у кнопки «Покинуть компанию». Но ключ, привязанный к самому сотруднику, после его исключения или выхода из компании не действует и без отметки (ответ 401); без отзыва он снова заработает, если сотрудника пригласят обратно.
• У компании может быть до 100 действующих ключей, у сотрудника в компании до 10.

Новые области по выбору: области из второй части таблицы (с leads:import) появились 09.10.2026 и выдаются только по выбору при выпуске ключа. Прежние ключи их не получают и работают ровно как раньше.

Только себе: почту, правку сообщений чатов, области управления компанией и профилем (с пометкой «только себе») сотрудник выпускает только себе, в профиле, а администратор себе на вкладке «API-ключи». На ключ другого сотрудника они не выпускаются: на вкладке «API-ключи» ошибка «Область «Почта: Чтение» сотрудник выпускает только себе в профиле», через API 403 PERMISSION_DENIED с permission: "keys.self_only". У ключа, выпущенного за другого, они не действуют и при вызове (403 SCOPE_REQUIRED; GET /api/v1/me их в key.scopes не показывает, прочие области такого ключа работают). Ключ с keys:write не выпускает ключ с областями шире своих.

С 14.10.2026 «только себе» и почтовые области mail:read и mail:send: ключ, который администратор выпустил за сотрудника, его почту не читает и писем от его имени не отправляет, в том числе ключи, выпущенные так раньше. Для почты сотрудник выпускает ключ себе сам в профиле.

Где ключ хранить нельзя: в коде страницы сайта, в JavaScript, в мобильном приложении, в публичном репозитории, в адресе запроса (?key=...). Адрес запроса попадает в журналы серверов и историю браузера, поэтому ключ из адреса CRM не читает вовсе.

2. Аутентификация

Ключ передаётся в заголовке запроса. Подходит любой из двух вариантов:

X-API-Key: crm_0123456789abcdef0123456789abcdef01234567

Authorization: Bearer crm_0123456789abcdef0123456789abcdef01234567

Нет ключа, ключ неверный или отозван, компания заблокирована, сотрудника ключа нет в компании или его учётная запись отключена: ответ 401 UNAUTHORIZED. Без ключа или с неверным ключом (в ответе ещё заголовок WWW-Authenticate: Bearer) текст такой: «Нужен действующий API-ключ в заголовке X-API-Key (или Authorization: Bearer). Ключ выпускает администратор в настройках компании (раздел API-ключи) или сотрудник сам себе в профиле (раздел API-ключи).». У ключа нет нужной области: 403 SCOPE_REQUIRED.

Проверить ключ: GET /api/v1/me (раздел 7) отвечает, чей это ключ, какие у него области и права сотрудника.

curl https://crm.linkodium.com/api/v1/me -H "X-API-Key: $CRM_API_KEY"

3. Формат запросов и ответов

• Только HTTPS. Методы: GET (чтение), POST (создание и действия), PATCH (правка заявки, настроек компании и каналов, профиля), PUT (замена списка: услуги, быстрые ссылки, настройки заявок из чатов), DELETE (удаление комментария). Адрес без нужного метода отвечает 405 с заголовком Allow.
• Необратимые действия (удаление писем и переписки, отключение ящика или канала, исключение сотрудника, передача владения и другие, отмечены в таблицах) требуют в теле "confirm": true, иначе 400 CONFIRM_REQUIRED.
• Тело запроса: JSON-объект (Content-Type: application/json, кодировка UTF-8) или обычная форма. У POST форма бывает application/x-www-form-urlencoded или multipart/form-data (файлы: запись звонка, комментарий, письмо, ответ в чат, импорт, фото). У PATCH, PUT и DELETE только JSON или application/x-www-form-urlencoded: тело multipart/form-data у них не разбирается, поля теряются, и запрос получает 400.
• Время в ответах: ISO-8601 в UTC с Z (2026-10-03T09:15:00Z). Время в параметрах: ISO-8601 со смещением или Z (2026-10-03T12:15:00+03:00).
• Сотрудники, события, файлы, чаты и переписка обозначаются uuid, заявки номером в компании.
• Списки постраничные: параметр limit (до 100, по умолчанию 50), в ответе items, has_more и next_cursor; следующая страница с параметром cursor=<next_cursor> и теми же остальными параметрами.
• Тело, которое начинается с { или [, разбирается как JSON при любом Content-Type. Если это не корректный JSON-объект (ошибка в JSON или массив вместо объекта), ответ 400 VALIDATION_ERROR.
• Ответ JSON в UTF-8, в том числе отказы, которые сервер выдаёт до разбора запроса: слишком частые запросы (429), слишком большое тело (413), технические работы (503). Обработчик запросов не ответил вовремя (например, перезапуск во время обновления CRM или запрос дольше предела сервера): ответ 503 SERVICE_UNAVAILABLE в том же JSON с заголовком Retry-After: 5. Сами 502 и 504 CRM не отдаёт: их может вернуть только промежуточный прокси между вами и CRM, и тогда без JSON. Проверяйте код ответа до разбора тела и повторяйте 502 и 504 так же, как 503.
• Адреса пишутся строчными буквами, как в таблицах разделов. Путь, который начинается не со строчной латинской буквы (/api/v1/Leads, /api/v1/1), и сам /api/v1 без пути до API не доходят: сервер отвечает обычной HTML-страницей 404, а не JSON. Прочий неизвестный адрес под /api/v1/ отвечает JSON 404 NOT_FOUND.

Успешный ответ:

{
  "success": true,
  "data": { "lead_number": 128, "is_duplicate": false, "message": "Заявка создана" }
}

Ответ с ошибкой:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Ошибка валидации данных",
    "details": ["Некорректный формат email"]
  }
}

• lead_number: номер заявки внутри вашей компании, тот же, что менеджеры видят в CRM (#128).
• Неизвестные поля запроса молча игнорируются, кроме адресов компании, сотрудников, приглашений, прав, услуг и быстрых ссылок, ключей компании и интеграций (/company, в том числе /company/leave и /company/transfer-ownership, /members, /invites, /permissions, /services/items, /sidebar-links, /api-keys, /integrations, API компании): там неизвестное поле тела даёт 400 VALIDATION_ERROR (в error.details строка «<поле>: неизвестное поле» и список допустимых полей), и ничего не сохраняется. Поля client_request_id и confirm допустимы везде.
• Ответы не кэшируются (Cache-Control: no-store).
• В каждом ответе есть заголовок X-Request-ID. Если пишете в поддержку о конкретном запросе, приложите его значение.

4. Ошибки

Рекомендация по повторам: при 429, 500, 502, 503, 504 и обрыве связи повторяйте запрос с растущей паузой (например, 10 секунд, 1 минута, 5 минут), а если в ответе есть заголовок Retry-After, не раньше указанного в нём числа секунд. Повтор безопасен: /api/v1/calls и загрузка записи идемпотентны, а создание заявки и прочие действия повторяйте с тем же заголовком Idempotency-Key (раздел 6). Для заявки ключ идемпотентности обязателен, чтобы повтор был безопасен: повторное обращение (раздел 8) распознаётся только у активной заявки с email или телефоном от 10 цифр. Заявка, созданная сразу в этапе «Успешно», «Провал» или «Спам», заявка только с именем, с телефоном короче 10 цифр без email или с dedup: false при повторе без ключа идемпотентности создастся второй раз (и для этапов кроме «Спама» менеджеры получат второе уведомление). 404 CALL_NOT_FOUND повторяйте, только если начало звонка ещё может прийти. Ошибки 400, 401, 403, 404, 405, 413, 422 повтором не исправляются.

Отказ принять запись разговора по ссылке ошибкой всего запроса не считается: звонок и заявка сохраняются, а причина отказа приходит в ответе полем recording_error (раздел 17).

5. Лимиты

Превышение лимита запросов или одновременных загрузок: 429 RATE_LIMITED с заголовком Retry-After.

Очередь записей по ссылке. Пока у компании меньше 20 записей ждут скачивания, её новые записи принимаются всегда, как бы ни была загружена очередь остальных компаний (предел в 20 записей на одну заявку действует и тогда). Если очередь заполнена (своя, общая для компаний владельца или общая для сервиса), звонок всё равно сохраняется, а запись получает отказ QUEUE_FULL в поле recording_error (раздел 17). Живая телефония держит в очереди единицы записей и в этот потолок не упирается.

6. Идемпотентность

Создание заявки, статус, архив, возврат из архива, объединение, комментарий, письмо, ответ в чат и привязка переписки или чата к заявке можно безопасно повторять: передайте заголовок Idempotency-Key (или поле client_request_id в теле), 1-255 видимых символов ASCII, уникальных для каждого нового действия (например, номер заказа в вашей системе или UUID).

• Повтор того же запроса с тем же ключом в течение суток не выполняет действие второй раз: CRM отдаёт сохранённый ответ (тот же код и тело) с заголовком Idempotent-Replayed: true.
• Тот же ключ с другим запросом (другой адрес, тело или файлы): 422 IDEMPOTENCY_MISMATCH.
• Первый запрос ещё выполняется: 409 IDEMPOTENCY_IN_PROGRESS с Retry-After.
• Сохраняются только успешные ответы. Если запрос получил ошибку (400, 403, 409 и другие), исправьте его и повторите с тем же ключом.
• Правка заявки (PATCH) защищена версией (раздел 10), звонки распознаются по call_id, а удаление комментария безопасно повторять и так: повтор тем же ключом в течение суток отвечает 200 {deleted: true, already: true} (раздел 13).
• Новые адреса, которые создают сущность или отправляют сообщение (спам, импорт, расшифровка, стикер и голосовое, правка и повтор сообщения, участник ящика, заявка из письма, приглашение, виджет, компания, обращение в поддержку), принимают ключ идемпотентности так же. Выпуск API-ключа его не принимает: сырой ключ не хранится, повтор выпустит второй ключ.
• Письмо и ответ в чат с ключом идемпотентности не уйдут дважды и после суток: повтор отвечает 200 с duplicate: true и тем же письмом или сообщением, файлы второй раз не сохраняются.

7. Справочники: GET /api/v1/me, /managers, /statuses, /services

GET /api/v1/me отвечает любому действующему ключу: чей ключ, его области, права сотрудника и лимиты.

{
  "success": true,
  "data": {
    "key": { "uuid": "5f0e...", "name": "Синхронизация", "prefix": "crm_3f9a01b2", "scopes": ["leads:read", "leads:write"], "personal": true, "created_at": "2026-10-03T09:00:00Z" },
    "company": { "uuid": "b150...", "name": "Linkodium", "timezone": "Europe/Moscow" },
    "user": { "uuid": "1b4e...", "name": "Анна", "email": "anna@example.com", "role": "manager" },
    "permissions": { "leads.visibility": "own", "leads.create": true, "leads.edit": true, "leads.status": true, "leads.archive": true, "leads.reassign": false, "leads.merge": false, "leads.comment": true, "leads.export": true, "leads.import": false, "api.keys": true },
    "limits": { "requests_per_5_minutes": 3000, "writes_per_5_minutes": 1500, "page_size_max": 100 }
  }
}

У ключа компании user и permissions равны null, personal: false.

Справочники (ключ сотрудника с областью leads:read, leads:create или leads:write), ответ { "items": [...] }:

8. Заявки: POST /api/v1/leads

Создаёт заявку в компании ключа. Ответственного можно указать полем manager (uuid или email сотрудника). Без него ответственным становится менеджер по умолчанию компании (Настройки компании -> Сотрудники), а если он не назначен, владелец компании. У ключа сотрудника ответственный зависит ещё и от того, какие заявки видит сотрудник (ниже). Сотрудники получают уведомление в Telegram по своим настройкам.

Повтор создания передавайте с заголовком Idempotency-Key (раздел 6), например с номером заказа или UUID формы: так потерянный ответ можно смело повторить, и вторая заявка не появится.

Нужна область leads:create (или leads:write). Ключ сотрудника создаёт заявку с его правами и понимает дополнительные поля (ниже); ключ компании работает как описано здесь.

Поля

Обязательно хотя бы одно из полей name, phone, email.

Заявка не теряется из-за длины: слишком длинные значения обрезаются по ширине поля (phone 50 символов, landing_page, form_page, referrer 500, ip_address 45, message, client_needs и user_agent около 65 000 байт, остальные строки 255 символов). Исключение ym_client_id: значение длиннее 64 символов не обрезается, а не сохраняется вовсе (поле выше). Байты не в UTF-8 заменяются знаком замены (U+FFFD).

ip_address, user_agent, referrer передавайте с данными посетителя сайта. CRM не подставляет вместо них адрес вашего сервера.

Заявка со статусом «Спам» сохраняется, но уведомление о ней не отправляется. Так удобно передавать заявки, которые отметил антиспам формы: если он ошибся, заявку видно в CRM под фильтром «Спам».

Повторное обращение

Если в компании уже есть активная заявка (этап «Новая заявка» или «В работе», не в архиве), созданная не раньше 30 суток назад, с тем же телефоном (российские номера и номера без «+» сравниваются по последним 10 цифрам, номер с кодом другой страны целиком; номер короче 10 цифр не сверяется, подробнее ниже) или тем же email, новая заявка не создаётся. В существующую добавляется событие «Повторное обращение» с полями source, name, company, phone, email, service, message, client_needs, form_page, ip_address, метками UTM (utm_source, utm_medium, utm_campaign, utm_term, utm_content), ym_client_id, landing_page и referrer, ответ 200 с is_duplicate: true и номером существующей заявки. Уведомление при этом не отправляется.

С 10.11.2026 активная заявка старше 30 суток (по дате создания) повторного обращения не принимает: создаётся новая заявка, как у нового клиента. То же правило у ключа сотрудника и у входящих звонков (раздел 17).

Остальные поля повторного обращения (website, user_agent, status) не сохраняются. Поля самой существующей заявки не меняются: метки и ym_client_id повторного обращения лежат в его событии в ленте заявки, а не в карточке.

Телефон, в котором меньше 10 цифр (например, городской номер без кода города), для поиска повторного обращения не используется: по короткому хвосту он совпал бы с номером другого клиента. Такая заявка сверяется только по email.

Номер с кодом другой страны (записан с «+», код страны не 7) сравнивается целиком, вместе с кодом страны: +84912345678 не совпадает с российским +74912345678, хотя последние 10 цифр у них одни. Российский номер в любой записи (8 912 ..., +7 912 ..., 912 ...) и номер без «+» сравниваются по последним 10 цифрам. Номер с +8 и следующей цифрой 3 или 9 (+8 916 ...) CRM считает российским, набранным с опечаткой.

Ответы

Новая заявка, 201 Created:

{ "success": true, "data": { "lead_number": 128, "is_duplicate": false, "message": "Заявка создана" } }

Повторное обращение, 200 OK:

{ "success": true, "data": { "lead_number": 97, "is_duplicate": true, "message": "Повторное обращение добавлено к существующей заявке" } }

Решение антиспама в ответе

С 12.11.2026. Форма сайта, которая сама отправляет письмо владельцу сайта (Contact Form 7, веб-формы 1С-Битрикс), может передать заявку в CRM до письма и не отправлять письмо со спамом. Для этого в теле поле spam_check_wait: true. CRM записывает заявку как обычно, ждёт решение антиспама (Антиспам; обычно 1-2 секунды, не дольше 4) и добавляет в data ответа ключ spam_check:

spam_check: null: заявка не проверялась (антиспам выключен, ключ с отметкой «Не проверять заявки на спам», нет полей формы сайта у ключа сотрудника) или это повторное обращение. Письмо отправляйте. Правило для формы одно: не отправлять письмо только при action: "reject". Ошибка связи, таймаут (ставьте не меньше 9 секунд) или ответ 5xx: письмо отправляйте, а заявку повторите тем же телом и тем же Idempotency-Key. Без поля spam_check_wait ответ прежний (ключа spam_check нет), запрос не ждёт. Так работают плагин «Linkodium CRM для Contact Form 7» с версии 5.1.0 (справка) и модуль «Linkodium CRM» для 1С-Битрикс с версии 2.1.0 (справка).

{ "success": true, "data": { "lead_number": 129, "is_duplicate": false, "message": "Заявка создана",
  "spam_check": { "state": "done", "verdict": "spam", "live": true, "action": "reject", "reasons": ["no_script", "links_in_text"] } } }

Ключ сотрудника

Ключ сотрудника создаёт заявку так же, как сотрудник кнопкой «Новая заявка», и понимает те же поля, что выше, плюс:

Ответственный по полю «Какие заявки видит сотрудник» в «Правах доступа» сотрудника ключа (с 14.10.2026):

• «Только свои (где сотрудник ответственный)»: ответственным всегда становится сам сотрудник ключа. Поле manager не учитывается и ошибки не даёт.
• «Все заявки компании», поле manager не передано, null, пустая строка или одни пробелы: менеджер по умолчанию компании, а если он не назначен, владелец компании. Право «Менять ответственного» для этого не нужно.
• «Все заявки компании», в manager сам сотрудник ключа: он.
• «Все заявки компании», в manager другой сотрудник: нужно право «Менять ответственного», как в CRM. С правом заявку получает указанный сотрудник, без права ответ 403 PERMISSION_DENIED (error.permission: "leads.reassign"), заявка не создаётся.
• Сотрудник из manager не из этой компании, неизвестный или отключённый: 400 VALIDATION_ERROR («manager: сотрудник не найден в компании»).

Администратор компании видит все заявки и имеет все права.

• Нужно право сотрудника «Создавать заявки», иначе 403 PERMISSION_DENIED. В ленте заявки событие «создана» (source: api, раздел 12) подписано сотрудником с пометкой «через API», в карточке «Заявка создана через API».
• В ответе ещё lead (заявка целиком, как в разделе 10) и visible. lead приходит только ключу с областью leads:read, и у новой заявки, и у повторного обращения: ключ формы сайта с одной leads:create получает lead: null (номер, matched_by и visible те же). Заявка, созданная интеграцией по ключу сотрудника, ему всегда видна (visible: true). visible: false (и lead: null) бывает только у заявки от ИИ-ассистента (ниже) при видимости «только свои» и чужом ответственном.
• Повторное обращение к заявке, которую сотрудник не видит: ответ 200 с lead_number: null, is_duplicate: true, hidden: true. Обращение добавлено к той заявке, её номер не раскрывается.
• Уведомление «Новая заявка» получает и сам сотрудник ключа, по своим галочкам в профиле: «Новые заявки, где я ответственный» или «Все новые заявки компании» (только если заявка ему видна). Заявки со статусом «Спам» уведомлений не дают. Исключение: заявка, созданная ИИ-ассистентом по просьбе сотрудника (раздел 26), как кнопка «Новая заявка» в кабинете, ему самому уведомления не присылает.
• Антиспам (с 10.11.2026): заявка с непустым tracking_token, form_page или landing_page похожа на форму сайта и проверяется на спам так же, как заявка по ключу компании (Антиспам): при боевом режиме уведомление приходит после проверки, явный спам уходит в «Спам». Без этих полей и у заявки от ИИ-ассистента проверки нет. Отметка ключа «Не проверять заявки на спам» (skip_antispam) снимает проверку и с ключа сотрудника.
• Для формы сайта выпускайте ключ сотруднику с видимостью «Все заявки компании» (тогда заявки получает менеджер по умолчанию или тот, кого форма укажет в manager, с правом «Менять ответственного») или тому, кто должен вести эти заявки сам (видимость «Только свои»: каждая заявка с ключа его).
• Заявку, созданную ИИ-ассистентом по просьбе сотрудника (инструмент create_lead, раздел 26), ассистент создаёт как сотрудник кнопкой «Новая заявка» в CRM: без права «Менять ответственного» ответственный сам сотрудник, выбор другого сотрудника даёт 403 PERMISSION_DENIED; там manager только uuid: пустая строка не принимается, ассистент получает ошибку проверки аргументов VALIDATION_ERROR («manager: ожидается uuid») при любых правах.

curl -X POST https://crm.linkodium.com/api/v1/leads \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10452" \
  -d '{"title": "Заказ 10452", "name": "Анна", "phone": "+79991234567",
       "manager": "1b4e28ba-2fa1-41d2-883f-0016d3cca427", "status": 2}'

Пример: curl

curl -X POST https://crm.linkodium.com/api/v1/leads \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: form-7f3c9a52-1d4e-4b8a-9c61-0e2f5a7b3d10" \
  -d '{
        "name": "Анна",
        "phone": "+7 999 123-45-67",
        "email": "anna@example.com",
        "message": "Нужна консультация",
        "source": "Сайт example.com",
        "form_page": "https://example.com/contacts/",
        "utm_source": "yandex",
        "utm_campaign": "brand"
      }'

Пример: PHP

<?php
// Ключ храните в настройках сервера, не в коде страницы.
$apiKey = getenv('CRM_API_KEY');

$lead = [
    'name'       => $_POST['name'] ?? '',
    'phone'      => $_POST['phone'] ?? '',
    'email'      => $_POST['email'] ?? '',
    'message'    => $_POST['message'] ?? '',
    'source'     => 'Сайт example.com',
    'form_page'  => $_SERVER['HTTP_REFERER'] ?? '',
    'ip_address' => $_SERVER['REMOTE_ADDR'] ?? '',
    'user_agent' => $_SERVER['HTTP_USER_AGENT'] ?? '',
];
// Один ключ идемпотентности на одну отправку формы: повтор с ним же
// (после таймаута, из очереди) вторую заявку не создаст. Храните его
// вместе с заявкой, если повторяете позже.
$idem = bin2hex(random_bytes(16));

$ch = curl_init('https://crm.linkodium.com/api/v1/leads');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($lead, JSON_UNESCAPED_UNICODE),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json', 'X-API-Key: ' . $apiKey,
                               'Idempotency-Key: ' . $idem],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 15,
]);
$body = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$resp = json_decode((string)$body, true);

// 201 - новая заявка, 200 - повторное обращение: оба случая означают «заявка у менеджера».
if (in_array($code, [200, 201], true) && !empty($resp['success'])) {
    $number = $resp['data']['lead_number'];
} else {
    // Заявку не потеряйте: сохраните её у себя вместе с $idem или отправьте
    // письмом и повторите позже с тем же Idempotency-Key.
    error_log('CRM: HTTP ' . $code . ' ' . $body);
}

9. Список заявок: GET /api/v1/leads

Ключ сотрудника, область leads:read. Те же фильтры, что в списке заявок CRM, и видимость сотрудника: при «только свои» в списке только его заявки.

Ответ: { "items": [заявка, ...], "next_cursor": "...", "has_more": true }. Заявка описана в разделе 10.

curl -G https://crm.linkodium.com/api/v1/leads \
  -H "X-API-Key: $CRM_API_KEY" \
  --data-urlencode "status=1,2" \
  --data-urlencode "updated_since=2026-10-01T00:00:00Z" \
  --data-urlencode "limit=100"

Синхронизация: запомните updated_at последней полученной заявки и в следующий раз передайте его в updated_since. Заявка, изменённая во время обхода страниц, придёт в следующем обходе. С updated_since список не отдаёт правки последних 30 секунд: время правки ставится в начале записи, а видна правка после её завершения, и без такого окна отметка могла уйти вперёд правки, которая ещё записывается. Такие заявки придут в следующем опросе (заявка, которую правят без пауз, придёт, когда правки стихнут на 30 секунд), поэтому updated_at последней полученной заявки безопасная отметка, если запись заявки завершается быстрее 30 секунд (обычный случай; правка, застрявшая в ожидании блокировки дольше, может прийти позже со старым updated_at). Первую полную выгрузку тоже делайте с updated_since, например 2000-01-01T00:00:00Z: тогда и её последняя заявка годится как отметка. Без updated_since список отдаёт и самые свежие правки.

updated_since работает внутри остальных фильтров. Заявка, которая после изменения под них больше не подходит, в выдачу не попадёт: с status=1,2 не придёт заявка, переведённая в «Успешно», без archived=1 не придёт заявка, ушедшая в архив, без «Спама» в status не придёт заявка, отмеченная спамом (без параметра status «Спам» тоже не приходит). Для полной копии обходите с одним и тем же updated_since два списка: рабочий со всеми этапами (status=1,2,5,6,7) и архив (archived=1). Заявка, поглощённая объединением, не приходит ни в один список, в том числе в архив: по её номеру GET /api/v1/leads/{номер} отвечает 409 LEAD_MERGED с номером главной в error.merged_into, а в ленте главной есть событие merged (раздел 12).

Сводка: GET /api/v1/leads/stats

Область leads:read. Те же числа, что на дашборде CRM, по заявкам, которые видит сотрудник: timezone, total, today, month, conversion (won, lost, rate: карточка «Конверсия закрытых», доля «Успешно» среди закрытых заявок без архива), by_status (status, count), recent (5 последних). С параметрами date_from и date_to (ГГГГ-ММ-ДД в поясе компании, обе вместе, не больше 366 дней) ещё period: созданные за период created, by_status и by_source (до 10 источников).

Канбан: GET /api/v1/leads/board

Область leads:read. Заявки колонками по этапам, как вид «Канбан» в CRM: те же фильтры и видимость, что у списка (archived, manager, date_from, date_to, search). status: колонки (номера или названия через запятую), без параметра все пять, включая «Спам». limit: заявок в каждой колонке, до 100, по умолчанию 50. cursor: next_cursor колонки, только вместе с status этой одной колонки.

Ответ: { "columns": [ { "status": {"id", "name", "color"}, "total", "items": [заявка, ...], "next_cursor", "has_more" } ] }. В колонке заявки по номеру, новые первыми; устаревшие этапы 3 и 4 лежат в колонке «В работе». Перенос в другую колонку: POST /api/v1/leads/{номер}/status (раздел 11).

Источники обращений: GET /api/v1/tracking/report

Область leads:read. Отчёт «Источники обращений» с дашборда (Сквозная аналитика) по заявкам, которые видит сотрудник. Параметры date_from и date_to обязательны: ГГГГ-ММ-ДД в поясе компании, обе границы включительно, период не длиннее 366 дней, иначе 400 VALIDATION_ERROR. Объединённые (поглощённые) заявки не считаются.

Ответ: { "report": { "date_from", "date_to", "rows", "totals", "by_channel", "by_method" } }. Строка rows: site ({uuid, host} или null), channel, method (null: у заявки нет визита), precision, leads (заявки без спама), spam, won («Успешно»), conversion (колонка «Конверсия обращений»: доля «Успешно» от leads в процентах с одним знаком, 0 при leads = 0), won_amount (сумма выигранных сделок или null). totals: те же числа по всем заявкам периода; by_channel и by_method: сводки по каналу и по способу.

• channel: ad (реклама), email (рассылки), social (соцсети), search (поиск), utm (метки UTM), referral (переходы с сайтов), direct (прямые заходы), maps (карты), other (прочее), unknown (нет данных). Входящий звонок на номер с отметкой «Рекламный» получает ad и без клика на сайте; канал, заданный у номера в «Трекинге», заменяет у входящего звонка только unknown и direct (правила каналов).
• method: form, call, telegram, max, widget, api. precision: exact (точно), probable (вероятно: за 10 минут до звонка один клик по номеру или несколько кликов одного посетителя; звонок на рекламный номер без клика: за 20 минут до звонка на сайте был ровно один посетитель из рекламы), none (нет данных).

curl -G https://crm.linkodium.com/api/v1/tracking/report \
  -H "X-API-Key: $CRM_API_KEY" \
  --data-urlencode "date_from=2026-11-01" \
  --data-urlencode "date_to=2026-11-30"

10. Заявка: GET и PATCH /api/v1/leads/{номер}

GET /api/v1/leads/128 (область leads:read): { "lead": {...} } и заголовок ETag с версией заявки.

{
  "number": 128,
  "title": "Анна, ООО Ромашка",
  "display_title": "Анна, ООО Ромашка",
  "status": { "id": 2, "name": "В работе" },
  "loss_reason": null,
  "amount": 50000.0,
  "manager": { "uuid": "1b4e28ba-2fa1-41d2-883f-0016d3cca427", "name": "Анна" },
  "name": "Анна", "company": "ООО Ромашка", "phone": "+79991234567", "email": "anna@example.com",
  "website": null, "service": "Сайт", "source": "Сайт example.com", "client_needs": null, "message": "Нужна консультация",
  "utm": { "source": "yandex", "medium": null, "campaign": "brand", "term": null, "content": null },
  "landing_page": null, "form_page": "https://example.com/contacts/", "referrer": null, "ym_client_id": null,
  "is_archived": false,
  "created_at": "2026-10-03T09:00:00Z",
  "updated_at": "2026-10-03T09:15:42.123456Z",
  "version": "2026-10-03T09:15:42.123456Z",
  "url": "https://crm.linkodium.com/c/b15092d3-.../leads/128/"
}

Заявки нет, она в другой компании или сотрудник её не видит: 404 NOT_FOUND. Заявка объединена с другой: 409 LEAD_MERGED с номером главной в error.merged_into.

IP-адрес и браузер, с которых пришла заявка (ip_address, user_agent), есть в заявке только у ключа с областью visitors:read; у прочих ключей этих полей нет вовсе, а из текста повторных обращений в ленте убрана строка с IP (раздел 12).

amount: «Сумма сделки» числом JSON (рубли с копейками) или null, если сумма не указана. Ключ появился 07.11.2026, после обновления базы данных; до обновления его в заявке нет.

pinned_comment (с 08.11.2026, только в GET одной заявки, не в списке): закреплённый комментарий карточки или null: uuid, text, has_files, author (uuid, name), created_at, pinned_at, pinned_by. Ключ есть после обновления базы данных.

spam_check (с 10.11.2026, только в GET одной заявки, не в списке): проверка заявки на спам или null, если заявка не проверялась: state (pending: проверяется, done, unchecked: сервис проверки не ответил, skipped: не проверялась), verdict (ok, suspect, spam или null), score (0..100), reasons (коды причин, например no_interaction, links_in_text, honeypot), checked (full или partial: на странице формы не было общего кода), live (true: боевой режим, false: только считать), human_label (отметка сотрудника spam или ham). IP-адреса и браузера в объекте нет. Ключ есть после обновления базы данных (Антиспам).

История клиента GET /api/v1/leads/{номер}/history (область leads:read), как блок «История клиента» карточки: другие заявки того же клиента в компании (тот же телефон или email по правилу повторных обращений, прошлая заявка клиента чата; архивные и закрытые тоже, поглощённые объединением нет), свежие первыми. Параметр limit от 1 до 50 (умолчание 20). Ответ: count, has_more, items (number, status, amount, created_at, url). Заявки, которые сотрудник ключа не видит, не попадают ни в items, ни в count.

PATCH /api/v1/leads/128 (область leads:write) меняет поля заявки и ответственного:

• поля title, source, service, client_needs, name, company, phone, email, website, message (null или пустая строка очищает поле) и manager (uuid или email сотрудника, регистр email не важен; null, пустая строка или одни пробелы снимают ответственного); поле без ключа не меняется;
• amount: сумма сделки числом (50000, 12500.5), строкой ("12 500,50") или null (очистить), от 0 до 9999999999.99, два знака после запятой. Другое значение: 400 VALIDATION_ERROR («amount: Сумма сделки: число от 0 до 9 999 999 999,99»). Правка суммы требует того же права «Править поля заявки». Сумма уходит ценой конверсии «Сделка» в Метрику и ДАРА (Сквозная аналитика);
• версия обязательна: заголовок If-Match со значением ETag из GET или поле version. Без версии: 428 PRECONDITION_REQUIRED. Если заявку уже изменили (менеджер в CRM, другая интеграция): 409 VERSION_CONFLICT, ничего не сохраняется, текущая версия в error.current_version;
• права сотрудника: поля требуют права «Править поля заявки», ответственный права «Менять ответственного», иначе 403 PERMISSION_DENIED;
• ответ: changed (изменённые поля), manager_changed, lead (заявка после правки, новый ETag). Если сотрудник видит только свои заявки и передал заявку другому, lead равен null, visible: false.

curl -X PATCH https://crm.linkodium.com/api/v1/leads/128 \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "2026-10-03T09:15:42.123456Z"' \
  -d '{"company": "ООО Ромашка", "manager": "1b4e28ba-2fa1-41d2-883f-0016d3cca427"}'

Визит заявки: GET /api/v1/leads/{номер}/visit

Область leads:read. Данные сквозной аналитики заявки, как раздел «Маркетинг» в карточке (Сквозная аналитика): { "visit": {...} } или { "visit": null }, если визита нет (заявка создана вручную, импортом, из почты или до подключения трекинга). Заявки нет или сотрудник её не видит: 404 NOT_FOUND; заявка объединена с другой: 409 LEAD_MERGED с номером главной в error.merged_into.

{
  "visit": {
    "method": "telegram",
    "precision": "exact",
    "channel": "ad",
    "site": { "uuid": "5d0c3a2e-8f41-4b6a-9c3d-2e1f0a9b8c7d", "host": "example.com", "title": "Example" },
    "line": null,
    "from_ad": true,
    "utm": { "source": "yandex", "medium": "cpc", "campaign": "brand", "term": null, "content": null },
    "referrer": "https://yandex.ru/",
    "landing_page": "https://example.com/?utm_source=yandex&utm_medium=cpc&utm_campaign=brand",
    "page_url": "https://example.com/contacts/",
    "first_touch": { "source": null, "medium": null, "campaign": null, "referrer": "https://www.google.com/",
                     "landing_page": "https://example.com/", "seen_at": "2026-11-01T08:00:00Z" },
    "ym_client_id": "1696427893123456789",
    "dara_visitor": "0b7e6f8a-3c2d-4e5f-9a1b-2c3d4e5f6a7b",
    "clicked_at": "2026-11-07T09:02:00Z",
    "note": null,
    "created_at": "2026-11-07T09:02:05Z",
    "conversions": [ { "goal": "qualified", "target": "metrika", "status": "sent", "skip_reason": null, "sent_at": "2026-11-07T09:40:31Z" } ]
  }
}

• method, precision, channel: значения как в отчёте. line ({uuid, number, display}) у звонков: номер, на который звонил клиент. note: пояснение точности, например «Вероятно, по клику на номер в 14:02».
• conversions: что отправлено в Метрику и ДАРА (goal: lead, call_target, qualified, deal; target: metrika, dara; status: pending, processing, sent, skipped, dead; skip_reason у пропущенных).
• ip_address и user_agent визита есть только у ключа с областью visitors:read, как у заявки.
• Время ISO-8601 в UTC с Z.

11. Статус, архив, объединение

Область leads:write, права сотрудника те же, что у кнопок карточки заявки.

Объединение необратимо: события, звонки, чаты и переписка поглощённой заявки переходят в заявку из адреса, пустые поля дополняются, поглощённая уходит в архив. Повтор по уже объединённой паре отвечает успехом с already: true.

Предпросмотр (dry_run: true) ничего не меняет и отвечает { "dry_run": true, "preview": {...} }, тем же, что показывает окно объединения в CRM: preview.already (пара уже объединена), preview.main и preview.absorbed (кратко о заявках: number, title, name, phone, email, source, status (name, color, bg), archived, manager (имя), created_at, url), preview.moved (счётчики того, что перейдёт: comments, calls, other_events, files, recordings, chats, chat_messages, mail_threads) и preview.moved_lines (то же строками), preview.fill (пустые поля главной, которые дополнятся: label, value; строки «IP» и «Браузер» только у ключа с областью visitors:read, как поля ip_address и user_agent заявки), preview.diff (поля, где значения различаются и останется значение главной: label, main, merged), preview.manager (имя ответственного после объединения). Полей main_number и absorbed_number у предпросмотра нет: номера в preview.main.number и preview.absorbed.number.

curl -X POST https://crm.linkodium.com/api/v1/leads/128/status \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": 6, "loss_reason": "Дорого"}'

12. Лента событий: GET /api/v1/leads/{номер}/events

Область leads:read. События заявки, свежие первыми (order=asc: старые первыми), постранично.

Событие: uuid, type, created_at, updated_at (ISO-8601 в UTC с Z; пока событие не менялось, равно created_at), author (uuid и name сотрудника или null у событий системы; у автора с фото ещё avatar_url), via (api, import или mcp у действий не из интерфейса, antispam у перевода в «Спам» антиспамом), data по типу:

Синхронизация ленты. Событие звонка дополняется на месте: статус, длительность, записи и расшифровка приходят позже, а created_at не меняется. События, перенесённые объединением из поглощённой заявки (раздел 11), сохраняют свой created_at, но считаются изменёнными. Поэтому since такие изменения пропускает. Запоминайте наибольший updated_at из полученных событий, в следующем опросе передавайте updated_since, равный ему минус 60 секунд, и сверяйте события по uuid: пришедшее снова событие заменяет прежнее. Удалённый комментарий из ленты пропадает и с updated_since больше не приходит.

Первая страница (без cursor) кратко перечисляет чаты (chats: uuid, name, channel, unread) и переписку почты (mail_threads: uuid, subject, message_count, last_message_at, last_direction, unread, account_email) заявки, доступные сотруднику так же, как в карточке. Там же прошлые заявки клиента из почты: past_leads (number, url, до 5) и past_leads_total (до 100), то есть другие заявки с тем же email или телефоном (от 10 цифр), которые видит сотрудник и к которым привязана переписка из его ящиков (кроме переписки, привязанной и к этой заявке). Прошлая заявка без такой переписки (с формы сайта, из звонка) сюда не попадает: ищите её в списке по телефону или email (search, раздел 9). mail_threads_total: сколько всего переписки заявки в ящиках сотрудника (в mail_threads первые 20). У ключа, выпущенного администратором за сотрудника, mail_threads и past_leads пустые, mail_threads_total и past_leads_total равны 0. У ключа с mail:read ещё unbound_mail_count: письма с адресом клиента в ящиках сотрудника, не привязанные к заявке. Фото автора: GET /api/v1/users/{uuid}/avatar (область leads:read).

curl -G https://crm.linkodium.com/api/v1/leads/128/events \
  -H "X-API-Key: $CRM_API_KEY" \
  --data-urlencode "types=call,comment"

13. Комментарии и файлы

POST /api/v1/leads/{номер}/comments (область leads:write, право «Писать комментарии и прикреплять файлы»): поле text и файлы. Файлы передаются формой multipart/form-data в полях files[] (или file): до 10 файлов, каждый до 100 МБ, но весь запрос вместе с текстом не больше 110 МБ (больше: 413 PAYLOAD_TOO_LARGE; крупные файлы отправляйте отдельными комментариями). Место файлы занимают в хранилище компании (403 QUOTA_EXCEEDED, если его не хватает). Ответ 201 с comment (событие, как в разделе 12). Ответственный за заявку получает уведомление, как от комментария в CRM.

curl -X POST https://crm.linkodium.com/api/v1/leads/128/comments \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Idempotency-Key: comment-77" \
  -F "text=Счёт и договор во вложении" \
  -F "files[]=@/tmp/invoice.pdf" \
  -F "files[]=@/tmp/contract.pdf"

Только текст можно отправить и JSON: {"text": "Перезвонить в пятницу"}.

Закреп. POST /api/v1/leads/{номер}/comments/{uuid}/pin закрепляет комментарий над лентой заявки, DELETE того же адреса открепляет (область leads:write, право «Писать комментарии и прикреплять файлы»). У заявки один закреп: новый заменяет прежний. Ответ: changed, pinned, pinned_comment. Закреп и снятие видны в ленте событием field_change с полем pinned_comment; удалённый комментарий снимается с закрепа сам. До обновления базы данных: 503 SERVICE_UNAVAILABLE.

DELETE /api/v1/comments/{uuid} (область leads:write): удаляет свой комментарий (администратор компании: любой) вместе с файлами. Ответ { "deleted": true, "already": false }. Повтор тем же ключом API после удаления (в течение суток) отвечает { "deleted": true, "already": true }, а не 404. Чужой комментарий: 403, не комментарий: 400.

GET /api/v1/attachments/{uuid} (область leads:read): файл из ленты (комментария или записи звонка) заявки, которую видит сотрудник. Отдаётся файлом (Content-Disposition: attachment), заголовок Range поддерживается.

curl -o call.mp3 https://crm.linkodium.com/api/v1/attachments/5d0c7a4e-8f3b-4f5e-9a51-2b7f0c1d9e20 \
  -H "X-API-Key: $CRM_API_KEY"

14. Выгрузка: GET /api/v1/leads/export.xlsx

Область leads:export и право сотрудника «Выгружать заявки в XLSX». Тот же файл, что кнопка «Скачать XLSX» в CRM: те же фильтры, что у списка (раздел 9, кроме updated_since, limit, cursor; с archived=1 фильтр status так же не действует), видимость сотрудника, даты в часовом поясе компании. Сортировка: sort (number, created_at, title, name, phone, status) и order.

• Больше 100 000 строк: 422 TOO_MANY_ROWS с числом строк в error.rows. Сузьте фильтр (даты, этапы) и выгрузите частями.
• Не больше 30 выгрузок за 10 минут на сотрудника, сверх этого 429.

curl -G -o leads.xlsx https://crm.linkodium.com/api/v1/leads/export.xlsx \
  -H "X-API-Key: $CRM_API_KEY" \
  --data-urlencode "date_from=2026-09-01" \
  --data-urlencode "date_to=2026-09-30"

15. Почта: /api/v1/mail

Ключ сотрудника с областью mail:read (чтение) или mail:send (отправка, привязка к заявке); обе области «только себе» (раздел 1): ключ, выпущенный администратором за сотрудника, на этих адресах отвечает 403 SCOPE_REQUIRED. Видны только ящики, где сотрудник участник: чужой ящик, переписка, письмо и вложение отвечают 404 NOT_FOUND, как несуществующие (администратор компании чужие ящики через эти адреса не видит). Заявки в переписке показываются по видимости сотрудника. У сотрудника нет ни одного ящика: списки ящиков и переписки приходят пустыми (200, пустой items), адреса конкретного ящика, переписки и письма отвечают 404. 404 NOT_FOUND на всех адресах раздела бывает, только если подключение новых ящиков компании закрыто и у сотрудника нет ни одного ящика или почта в CRM ещё не включена.

Данные раздела, журнал изменений, ящик целиком, подключение и настройки ящиков, участники, удаление писем, отвязка и заявка из письма: раздел 24.

Список переписки

GET /api/v1/mail/threads: фильтры как в разделе «Почта» CRM.

Элемент: uuid, account (uuid, email), subject, snippet, contact (name, email), last_message_at, last_direction (in, out), message_count, unread_count, has_attachments, send_failed, in_inbox, in_sent, lead (number, status, is_open, manager, url или null).

curl -G https://crm.linkodium.com/api/v1/mail/threads \
  -H "X-API-Key: $CRM_API_KEY" \
  --data-urlencode "unread=true" \
  --data-urlencode "limit=50"

Переписка, тело письма, вложения

GET /api/v1/mail/threads/{uuid}: thread, leads (все привязки, текущая с current: true), lead_prefill (поля заявки по умолчанию для «Создать заявку»: title, name, email, phone, message), messages (последние limit писем по возрастанию времени), next_cursor и has_more для более ранних писем. Переписка, объединённая с другой, отдаётся объединённой (redirected_from = запрошенный uuid). Письмо: uuid, direction, from, to, cc, bcc (только у исходящих), reply_to, subject, date, seen, snippet, text (до 20 000 символов, text_truncated), auto (автоматическое письмо: рассылка или автоответ), bounce (отчёт о недоставке), spoof_warning (имя отправителя похоже на другой адрес), auth_fail (почтовый сервис не подтвердил отправителя: DMARC или SPF не прошли), body (state, has_html, url), attachments (uuid, name, mime, size, state, url), send (state: queued, sending, sent, failed, и error у писем из CRM), author (сотрудник, отправивший письмо из CRM).

GET /api/v1/mail/messages/{uuid}/body: text (текст письма до 256 КБ: CRM хранит не больше, более длинный текст обрезан), html (HTML письма, очищенный от скриптов, тот же, что CRM показывает в окне письма; картинки с чужих серверов в нём не загружены, их число в remote_images), html_too_big, state. HTML больше 2 МБ CRM не сохраняет: такое письмо приходит с state: too_big, html: null, html_too_big: true и только текстом. html_too_big: true бывает и у сохранённого HTML больше 5 МБ. Не хватило места в хранилище компании (state: no_space): html: null, html_too_big: false, текст первые 16 КБ. Встроенные картинки письма (логотип, подпись) в html ссылаются на /api/v1/mail/parts/{uuid} (путь без домена): загружайте их тем же ключом, как вложение. Тело ещё не скачано с сервера почты (state: queued): CRM скачивает его первым, повторите запрос через Retry-After секунд.

GET /api/v1/mail/parts/{uuid}: скачанное вложение отдаётся файлом (Content-Disposition: attachment, Range поддерживается). Вложение ещё на сервере почты: CRM ставит его в очередь скачивания и отвечает 202 с part (state: queued) и Retry-After; повторите запрос. Скачать нельзя: 409 ATTACHMENT_UNAVAILABLE с error.state. error.state: error значит, что CRM исчерпала попытки скачать вложение (таймауты, сбои сервера почты): запрос с ?retry=1 ставит скачивание заново, как кнопка «Повторить» у вложения в CRM, и отвечает 202; без retry такое вложение остаётся 409. Значение retry: 1, true, 0 или false, иное 400 VALIDATION_ERROR.

curl -o invoice.pdf https://crm.linkodium.com/api/v1/mail/parts/0f2c1c64-3a9e-4b1d-8c55-6e1f0a2b7d31 \
  -H "X-API-Key: $CRM_API_KEY"

Отправка: POST /api/v1/mail/send

Область mail:send. Письмо ставится в очередь и уходит с сервера почты ящика в течение минуты, как письмо из CRM; копия ложится в «Отправленные» ящика.

У ответа без to и cc получатели как у кнопки «Ответить» («Ответить всем» при reply_all), без subject тема Re: и тема письма. Ответ 201: message (письмо с send.state: queued), thread, duplicate: false, warning (предупреждение о суточном пределе почтового сервиса или null). Повтор с тем же ключом идемпотентности в течение суток: сохранённый первый ответ (201, duplicate: false) с заголовком Idempotent-Replayed: true (раздел 6); позже суток: 200, duplicate: true, то же письмо. В обоих случаях второе письмо не уходит. Ящик не может отправлять: 409 MAIL_ACCOUNT_INACTIVE; квота ящика (100 писем в час с адреса, считаются письма этой компании): 409 SEND_QUOTA; почта приостановлена: 409 SERVICE_PAUSED; заявка не найдена или не видна сотруднику: 404.

curl -X POST https://crm.linkodium.com/api/v1/mail/send \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Idempotency-Key: offer-2026-10-03-128" \
  -F "account=7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -F "to[]=Анна <anna@example.com>" \
  -F "subject=Коммерческое предложение" \
  -F "text=Добрый день! Предложение во вложении." \
  -F "lead=128" \
  -F "files[]=@/tmp/offer.pdf"

Ответ в переписку JSON-ом:

curl -X POST https://crm.linkodium.com/api/v1/mail/send \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"thread": "3b241101-e2bb-4255-8caf-4136c566a962", "text": "Спасибо, счёт оплатим сегодня.", "client_request_id": "reply-5521"}'

Прочитано и привязка к заявке

POST /api/v1/mail/threads/{uuid}/read: без тела все входящие письма переписки становятся прочитанными; {"message": "<uuid письма>", "seen": false} отмечает одно письмо непрочитанным. Отметка общая для всех участников ящика и почтовой программы (флаг на сервере почты). Ответ: thread, touched (сколько писем изменено).

POST /api/v1/mail/threads/{uuid}/lead с {"lead": 128}: переписка относится к заявке, новые письма тоже. Заявка не найдена или не видна сотруднику: 404; номер объединённой заявки ведёт на главную. Ответ: thread, lead.

16. Чаты: /api/v1/chats

Ключ сотрудника с областью chats:read (чтение, «прочитано», файлы) или chats:write (ответы, привязка к заявке). Видны чаты по режиму доступа сотрудника («Права доступа», блок «Чаты»): «все чаты», «все чаты, отвечает ответственный», «только свои и без ответственного» (администраторы видят все). Невидимый чат отвечает 404. У компании нет каналов: 404 на всех адресах.

Шапка переписки, журнал изменений, «Отметить все прочитанными», «Ответ не нужен», стикеры, голосовые, правка и удаление сообщений, телефон в заявку, карточка посетителя и блокировка: раздел 23.

GET /api/v1/chats: filter (all по умолчанию, mine: ответственный за заявку чата сотрудник, awaiting: ждут ответа), q (поиск как в CRM: #номер заявки, телефон, имя или @username; по #номеру и по телефону заявки находятся только чаты, чья заявка видна сотруднику (при видимости «только свои» только его заявки), свой телефон клиента в чате ищется всегда), lead (номер заявки: переписки её клиента), limit, cursor. Чат: uuid, channel (uuid, type: telegram, max, widget, с 11.11.2026 avito, title, status), name, username, phone (телефон клиента; если своего телефона у клиента в чате нет, телефон его заявки, но только если заявка видна сотруднику, иначе null), last_message, last_activity_at, unread, awaiting_reply, blocked, lead (number, status, is_open, manager или null), can_reply, reply_block, reply_block_text, initials, avatar_url (/api/v1/chats/{uuid}/avatar или null), item (объявление чата Авито: title, price строкой или null, url объявления на avito.ru или null; у прочих чатов и пока Авито не прислал объявление null); у канала ещё disabled.

curl -G https://crm.linkodium.com/api/v1/chats \
  -H "X-API-Key: $CRM_API_KEY" \
  --data-urlencode "filter=awaiting"

GET /api/v1/chats/{uuid}/messages: без параметров последние limit (до 100, по умолчанию 50) по возрастанию; before=<uuid сообщения>: более ранние, after=<uuid>: более поздние. Ответ: chat, items, has_more_before, has_more_after. Сообщение: uuid, direction (in, out, system), kind (text, photo, document, voice и другие), text, created_at, lead_number, author, auto (автоответ: greeting, offhours или contact_request; иначе null), external (avito_app: исходящее сообщение продавец написал в приложении Авито, а не в CRM, author тогда null; иначе null), status (received, queued, sent, failed и другие), error, service (у служебного сообщения code и text, иначе null), reply_to (uuid, direction, kind, text, missing), forward (пересланное: from, at), album (общий код у фото одного альбома), files (uuid, kind, name, mime, size, width, height, duration, status, url = /api/v1/chats/files/{uuid}), sticker (uuid, emoji, format), location (lat, lon, live, live_until), venue (lat, lon, title, address), contact_card (name, phone, is_self), edited, deleted, history (прежние тексты изменённого сообщения: text, at, by), phones (телефоны в тексте), unsupported, а также что сотрудник может сделать с сообщением: can_edit, can_delete_at_client, can_retry, can_delete (удаление из CRM, только администратору).

curl -G https://crm.linkodium.com/api/v1/chats/9b2f5a70-1c3d-4e8f-a6b7-0c1d2e3f4a5b/messages \
  -H "X-API-Key: $CRM_API_KEY" \
  --data-urlencode "limit=100"

Ответ клиенту: POST /api/v1/chats/{uuid}/messages

Поля: text (до 10 000 символов), reply_to (uuid сообщения этого чата: цитата), файлы files[] или file (multipart/form-data, до 10, каждый до предела канала, весь запрос вместе не больше 110 МБ, иначе 413 PAYLOAD_TOO_LARGE; место в хранилище компании: 403 QUOTA_EXCEEDED, если его не хватает), client_request_id или Idempotency-Key. Сообщение уходит клиенту от бота компании без подписи сотрудника, как ответ из CRM; ответ 201 с message (status: queued, у виджета сайта сразу sent). Первый ответ клиенту без ответственного делает сотрудника ответственным за заявку (в ленте с пометкой «через API»). Права ответа как в CRM: в режиме «отвечает ответственный» чужому клиенту 403 PERMISSION_DENIED (error.permission: chats.mode); клиент заблокировал бота или канал отключён: 409 CHAT_UNAVAILABLE. В ответе ещё chat (uuid, lead: номер текущей заявки клиента или null). Стикеры и голосовые: раздел 23.

curl -X POST https://crm.linkodium.com/api/v1/chats/9b2f5a70-1c3d-4e8f-a6b7-0c1d2e3f4a5b/messages \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Idempotency-Key: answer-81234" \
  -F "text=Добрый день! Договор во вложении." \
  -F "files[]=@/tmp/contract.pdf"

Прочитано и привязка к заявке

POST /api/v1/chats/{uuid}/read: {"upto": "<uuid сообщения>"} или без тела (до последнего сообщения). Отметка у каждого сотрудника своя. Ответ: unread (непрочитанные этой переписки) и badge (непрочитанные переписки сотрудника, как значок раздела).

POST /api/v1/chats/{uuid}/lead с {"lead": 128}: чат переходит к заявке (видимой сотруднику; номер объединённой ведёт на главную), прошлые сообщения остаются при прежней заявке, в ленты обеих заявок пишутся события. Ответ: chat (null, если после смены заявки сотрудник чат больше не видит), changed, previous_lead (number, status, can_archive).

17. Телефония: POST /api/v1/calls

Универсальный приём звонков от любой АТС. Прослойку между АТС и CRM пишете вы (или берёте готовую), она переводит события АТС в вызовы этого метода. Пример для Novofon и Zadarma в разделе 19.

Модель

Звонок в CRM определяется парой «компания + call_id», где call_id это идентификатор звонка на стороне АТС. Каждое событие звонка (начало, ответ, конец, готовая запись) присылайте отдельным запросом с одним и тем же call_id:

• Первый запрос с новым call_id заводит звонок в ленте заявки.
• Следующие запросы с тем же call_id дописывают поля звонка: итог, длительность, время, запись. Непереданные и пустые поля сохраняют прежние значения.
• Повтор одного и того же запроса ничего не портит. Если не получили ответ, смело отправляйте ещё раз.

Хранить у себя соответствие «звонок АТС -> заявка CRM» не нужно: заявку по номеру клиента находит сама CRM.

Как CRM находит или создаёт заявку

При первом событии звонка (в компании ещё нет звонка с этим call_id):

1. Нужен client_phone, номер клиента. Без него ответ 404 CALL_NOT_FOUND: звонок не заведён и ничего не сохранено. Так штатно выглядит, например, событие готовой записи исходящего звонка, который не сохранялся (см. ниже), или событие, которое пришло раньше начала звонка. Некорректный номер (меньше 7 цифр) в первом событии: 400.
2. CRM ищет активную заявку компании (этап «Новая заявка» или «В работе», не в архиве) с этим номером (российские номера и номера без «+» сравниваются по последним 10 цифрам, номер с кодом другой страны целиком, как в разделе 8; номер короче 10 цифр активную заявку не находит). Для входящего звонка с 10.11.2026 заявка должна быть создана не раньше 30 суток назад, старше не в счёт; исходящий звонок ищет активную заявку без этого ограничения. Нашла: звонок попадает в неё.
3. Не нашла:
   • входящий звонок создаёт новую заявку: телефон клиента, источник source (по умолчанию «Звонок», правило с line ниже), услуга service, ответственный менеджер по умолчанию, а если он не назначен, владелец компании (у ключа сотрудника, который видит только свои заявки, сам сотрудник, ниже). Сотрудники получают уведомление «Новая заявка» по своим настройкам;
   • исходящий звонок создаёт заявку, только если в компании включена настройка Настройки компании -> «Исходящий звонок на номер без заявки создаёт новую заявку». Если выключена (так по умолчанию), звонок не сохраняется, ответ 200 с skipped: true.

Отдельных уведомлений о звонках нет: звонок виден в ленте заявки.

Источник и услуга новой заявки из звонка (с 07.11.2026): поле source (service) запроса, если оно передано; иначе строка номера из поля line в настройках трекинга («Настройки компании» -> «Трекинг», раздел «Телефонные номера», Сквозная аналитика); иначе источник «Звонок» и услуга не задана. Номер line сравнивается по цифрам (8 в начале как 7, выключенные строки не учитываются). Интеграции, которые сами передают source, работают как раньше; ответ звонка не меняется. Если звонок создал новую заявку, CRM ещё ищет клик по этому номеру на сайте за 10 минут до звонка и записывает визит заявки (раздел 10); звонок на рекламный номер без клика связывается с единственным посетителем из рекламы за 20 минут до звонка (Сквозная аналитика).

Ключ сотрудника

Прежний ключ компании работает как описано в этом разделе. Ключ сотрудника передаёт звонки с правами сотрудника:

• Звонок, который попал в заявку, невидимую сотруднику (видимость «только свои», заявка другого менеджера), всё равно записывается в эту заявку, но её номер не раскрывается: ответ 201 или 200 с lead_number: null и hidden: true (created_lead как обычно).
• Звонок должен создать заявку, а у сотрудника нет права «Создавать заявки»: 403 PERMISSION_DENIED с permission: "leads.create" и текстом «Нет права создавать заявки. Обратитесь к администратору компании.». Ничего не сохраняется: ни заявки, ни звонка, ни записи.
• Заявку из звонка по ключу сотрудника, который видит только свои заявки, получает сам сотрудник. Если он видит все заявки компании, заявка уходит менеджеру по умолчанию, а без него владельцу, право «Менять ответственного» для этого не нужно (как у POST /api/v1/leads без manager).
• Запись по ссылке (record_url) к звонку в невидимой сотруднику заявке не принимается: звонок сохранён, в ответе recording: "rejected" и recording_error с кодом PERMISSION_DENIED («Запись не принята: звонок в заявке, которая вам не видна»). Файл записи к такому звонку (раздел 18): 404 CALL_NOT_FOUND.
• События звонка и событие «создана» у заявки из звонка пишутся без автора и без пометки «через API», как у ключа компании.

Для телефонии всей компании выпускайте ключ администратору или сотруднику с видимостью «все заявки» и правом «Создавать заявки»: тогда новые заявки из звонков получает менеджер по умолчанию.

Поля

Словарь status (регистр и разделители не важны: no answer, no_answer, NO-ANSWER одинаковы):

Другое значение показывается в карточке как есть.

Время и часовой пояс

CRM хранит время в UTC и показывает каждому сотруднику в его часовом поясе. Поэтому started_at обязан содержать смещение: 2026-09-28 14:05:00 без смещения можно прочитать по-разному, и в карточке оказалось бы неверное время. Если АТС присылает время без пояса, прослойка должна дописать пояс, в котором работает АТС (обычно он задан в настройках кабинета АТС). Пример в разделе 19.

Запись разговора ссылкой

Если АТС отдаёт запись по ссылке, передайте её в record_url (в том же событии или отдельным запросом с тем же call_id). CRM поставит запись в очередь, скачает её в течение нескольких минут и прикрепит к звонку.

Требования к ссылке:

• схема http или https, порт 80 или 443, длина до 2000 символов;
• доступна из интернета без авторизации (подписанная ссылка АТС подходит). Логин и пароль в самой ссылке (https://user:pass@...) не принимаются;
• ведёт в интернет: IP-адрес в ссылке допустим только публичный (IPv6 только из глобального диапазона 2000::/3), имена внутренней сети (localhost, имя без точки, домены .local, .internal и подобные) не принимаются. Ссылки во внутреннюю сеть CRM не скачивает;
• живёт не меньше нескольких часов: при временной ошибке CRM повторяет скачивание (всего 5 попыток) с растущими паузами примерно в 2, 4, 8 и 16 минут, на все попытки уходит от получаса и дольше. Если АТС позволяет задать срок жизни ссылки, задайте сутки;
• сервер записи присылает начало ответа (заголовки) не позже чем через 60 секунд, в том числе на каждом редиректе, и отдаёт файл целиком не дольше чем за 10 минут. Если в ответе есть заголовок Content-Length, CRM через 30 секунд после начала передачи прикидывает, успеет ли файл докачаться за эти 10 минут, и прерывает попытку, если не успеет; без Content-Length средняя скорость отдачи должна быть не ниже 8 КБ/с. Запись, которая не укладывается в эти пределы ни в одной из 5 попыток, к звонку не прикрепляется;
• формат mp3, wav, ogg, webm, m4a или aac, размер до 200 МБ. Формат CRM определяет по содержимому файла, а не по расширению в ссылке, так что ссылка без расширения (например, .../records/123/download) подходит. Если по ссылке пришёл не аудиофайл (страница ошибки или входа, JSON), это считается временной ошибкой скачивания: CRM повторит попытку, и после 5 неудачных попыток запись к звонку не прикрепляется.

Повтор той же ссылки для того же звонка не ставит вторую загрузку (ответ recording: "duplicate").

Если запись по ссылке принять нельзя, звонок и заявка всё равно сохраняются: ответ обычный (201 или 200), а в нём recording: "rejected" и поле recording_error с причиной:

Ответ recording: "queued" значит только, что ссылка принята в очередь: размер записи CRM узнаёт после скачивания. Если запись не поместилась в оставшееся место хранилища или скачать её не удалось (часть отказов окончательна сразу, остальные после 5 попыток), к звонку она не прикрепляется, и ни в одном ответе API об этом уже не сообщается. Когда запись не поместилась, администраторы компании с подключённым Telegram получают уведомление «Хранилище компании заполнено» (не чаще раза в сутки). Освободите место и пришлите ту же ссылку снова тем же call_id. Если запись важна, держите запас места или загружайте её файлом (раздел 18): там отказ приходит в ответе сразу.

Проверяйте поле recording в ответе: если запись важна, а пришло rejected, сохраните ссылку у себя и повторите позже или загрузите файл методом из раздела 18.

Если ссылки нет, а файл есть, загрузите его методом из раздела 18.

Ответы

Звонок заведён этим запросом, 201 Created:

{ "success": true, "data": { "lead_number": 128, "call_id": "1727517900.1234", "created_lead": true } }

Звонок уже был, поля дописаны, 200 OK:

{ "success": true, "data": { "lead_number": 128, "call_id": "1727517900.1234", "created_lead": false, "recording": "queued" } }

• created_lead: true, если этот запрос создал новую заявку;
• hidden (только ключ сотрудника): true, если звонок записан в заявку, которую сотрудник не видит; lead_number тогда null;
• recording (только если передан record_url): queued поставлена в очередь, duplicate эта ссылка уже была, rejected запись не принята (звонок при этом сохранён);
• recording_error (только при recording: "rejected"): code, message и, для негодной ссылки, details.

Запись не принята, звонок сохранён, 200 OK:

{
  "success": true,
  "data": {
    "lead_number": 128,
    "call_id": "1727517900.1234",
    "created_lead": false,
    "recording": "rejected",
    "recording_error": {
      "code": "VALIDATION_ERROR",
      "message": "Ссылка на запись не принята",
      "details": ["record_url: допустим только порт 80 или 443"]
    }
  }
}

Исходящий звонок на номер без заявки при выключенной настройке, 200 OK:

{ "success": true, "data": { "lead_number": null, "call_id": "out-777", "skipped": true, "reason": "no_lead_for_outgoing" } }

Пример: входящий звонок

Начало звонка:

curl -X POST https://crm.linkodium.com/api/v1/calls \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "call_id": "1727517900.1234",
        "direction": "in",
        "client_phone": "+79991234567",
        "line": "+73422000000",
        "started_at": "2026-09-28T14:05:00+05:00",
        "source": "Реклама Яндекс"
      }'

Конец звонка (тот же call_id):

curl -X POST https://crm.linkodium.com/api/v1/calls \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "call_id": "1727517900.1234", "status": "answered", "duration": 185 }'

Готовая запись:

curl -X POST https://crm.linkodium.com/api/v1/calls \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "call_id": "1727517900.1234", "record_url": "https://records.example-pbx.com/abc123.mp3" }'

Пример: PHP

<?php
function crmCall(array $fields): array
{
    $ch = curl_init('https://crm.linkodium.com/api/v1/calls');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => json_encode($fields, JSON_UNESCAPED_UNICODE),
        CURLOPT_HTTPHEADER     => ['Content-Type: application/json', 'X-API-Key: ' . getenv('CRM_API_KEY')],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 15,
    ]);
    $body = curl_exec($ch);
    return [curl_getinfo($ch, CURLINFO_HTTP_CODE), json_decode((string)$body, true)];
}

[$code, $resp] = crmCall([
    'call_id'      => '1727517900.1234',
    'direction'    => 'in',
    'client_phone' => '+79991234567',
    'started_at'   => (new DateTimeImmutable('now'))->format(DATE_ATOM), // со смещением
]);

18. Запись звонка файлом: POST /api/v1/calls/recording

Для АТС, которые не дают публичную ссылку на запись: прослойка скачивает файл сама и отправляет его в CRM.

• Тело: только multipart/form-data с полями call_id и file. JSON или форма без файла: 400 VALIDATION_ERROR (ссылку на запись передавайте в /api/v1/calls, поле record_url).
• Звонок с этим call_id уже должен быть передан в /api/v1/calls, иначе 404 CALL_NOT_FOUND. По одному файлу CRM заявку не создаёт: в файле нет номера клиента.
• Ключ сотрудника: звонок в заявке, которую сотрудник не видит, отвечает тем же 404 CALL_NOT_FOUND («Звонок с таким call_id не найден: сначала передайте его в /api/v1/calls»), файл не сохраняется. Если заявку передали другому менеджеру во время загрузки, ответ тоже 404, а файл отбрасывается.
• Форматы: mp3, wav, ogg, webm, m4a, aac. CRM проверяет содержимое файла: файл, в котором распознан другой тип (HTML, картинка, архив, документ), отклоняется с ошибкой 400. Если тип по содержимому определить нельзя (так бывает у mp3 без заголовка), решает расширение имени файла из списка выше. Пустой файл: 400.
• Размер: до 100 МБ, больше: 413 PAYLOAD_TOO_LARGE.
• Место в хранилище компании: если его не хватает, 403 QUOTA_EXCEEDED.
• Одновременно с одного IP-адреса: до 8 загрузок, сверх этого 429 RATE_LIMITED с Retry-After.
• Повтор того же файла (то же содержимое) для того же звонка второй записи не создаёт: ответ 200 с duplicate: true и данными ранее принятой записи. Имя файла при этом значения не имеет.
• У одного звонка может быть несколько записей (например, разговор в двух частях или каналы клиента и оператора отдельными файлами). Разные файлы принимаются все, даже с одинаковыми именем и размером. Имена всё же лучше давать разные (call-1727517900.1234-1.mp3, ...-2.mp3): под этим именем запись видят и скачивают менеджеры.
• Если расширение в имени файла не совпадает с форматом, который CRM определила по содержимому, в имени оно заменяется на верное (поле file_name ответа).

Ответ 201 Created:

{
  "success": true,
  "data": {
    "lead_number": 128,
    "call_id": "1727517900.1234",
    "recording": { "id": "5d0c7a4e-8f3b-4f5e-9a51-2b7f0c1d9e20", "file_name": "call.mp3", "size": 482113, "type": "audio/mpeg" }
  }
}

Повтор уже принятого файла, 200 OK:

{
  "success": true,
  "data": {
    "lead_number": 128,
    "call_id": "1727517900.1234",
    "duplicate": true,
    "recording": { "id": "5d0c7a4e-8f3b-4f5e-9a51-2b7f0c1d9e20", "file_name": "call.mp3", "size": 482113, "type": "audio/mpeg" }
  }
}

Пример: curl

curl -X POST https://crm.linkodium.com/api/v1/calls/recording \
  -H "X-API-Key: $CRM_API_KEY" \
  -F "call_id=1727517900.1234" \
  -F "file=@/tmp/call-1727517900.1234.mp3"

Пример: PHP

<?php
$callId = '1727517900.1234';
$part   = 1; // номер части, если АТС режет разговор на несколько файлов

$ch = curl_init('https://crm.linkodium.com/api/v1/calls/recording');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => [
        'call_id' => $callId,
        'file'    => new CURLFile('/tmp/call.mp3', 'audio/mpeg', 'call-' . $callId . '-' . $part . '.mp3'),
    ],
    CURLOPT_HTTPHEADER     => ['X-API-Key: ' . getenv('CRM_API_KEY')],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 120,
]);
$body = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// 201 - принята, 200 - этот файл уже был. 429, 5xx и обрыв связи: повторить позже.
if (!in_array($code, [200, 201], true)) {
    error_log('CRM recording: HTTP ' . $code . ' ' . $body);
}

19. Пример прослойки для Novofon и Zadarma

Novofon и Zadarma сообщают о звонках вебхуками (уведомлениями о событиях АТС) на адрес, который вы указываете в кабинете АТС. Прослойка это небольшой скрипт на вашем сервере: принимает вебхук, переводит его в вызов /api/v1/calls и сразу отвечает АТС.

Соответствие событий

Важно:

• В call_id передавайте pbx_call_id: он одинаков у всех событий одного звонка. call_id_with_rec нужен только для запроса ссылки на запись.
• client_phone передавайте в каждом событии, где номер есть: если первое событие потеряется, звонок заведёт следующее.
• call_start у этих АТС приходит без часового пояса, во времени, заданном в кабинете АТС. Прослойка должна дописать этот пояс (в примере константа PBX_TIMEZONE).
• Ссылку на запись АТС готовит не сразу; Novofon советует запрашивать её примерно через 40 секунд после уведомления. Поэтому прослойка сначала отвечает АТС, а ссылку запрашивает потом, с паузой и повторами (в примере ниже). Если ссылку так и не получили, запишите это в журнал: иначе запись пропадёт молча.
• Ответ 404 CALL_NOT_FOUND на NOTIFY_RECORD штатен для исходящего звонка, если в компании выключена настройка «Исходящий звонок на номер без заявки создаёт новую заявку»: такой звонок не сохранялся, и запись к нему прикладывать некуда. Для входящего звонка тот же ответ значит, что начало и конец звонка до CRM не дошли (например, CRM ответила 429 или 5xx), и запись потеряна. Прослойка не знает направление звонка по NOTIFY_RECORD, поэтому пример пишет в журнал и 404.
• Если в ответе recording: "rejected", запись не принята, хотя звонок сохранён. Причину смотрите в recording_error (раздел 17).

Пример прослойки (PHP)

<?php
// Прослойка АТС -> Linkodium CRM. Адрес этого скрипта укажите в кабинете АТС
// как адрес уведомлений о звонках.

const CRM_URL      = 'https://crm.linkodium.com/api/v1/calls';
const PBX_TIMEZONE = 'Europe/Moscow'; // пояс из настроек кабинета АТС

// Проверка адреса при подключении уведомлений (Novofon, Zadarma).
if (isset($_GET['zd_echo'])) {
    exit(preg_replace('/[^A-Za-z0-9]/', '', (string)$_GET['zd_echo']));
}
// Здесь же стоит проверить подпись уведомления (заголовок Signature)
// по документации АТС: иначе прислать «звонок» сможет кто угодно.

function crmCall(array $fields): void
{
    $ch = curl_init(CRM_URL);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => json_encode(array_filter($fields, fn($v) => $v !== '' && $v !== null),
                                              JSON_UNESCAPED_UNICODE),
        CURLOPT_HTTPHEADER     => ['Content-Type: application/json', 'X-API-Key: ' . getenv('CRM_API_KEY')],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 10,
    ]);
    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $resp = json_decode((string)$body, true);
    if (!in_array($code, [200, 201], true)) {
        // Ответ и тело сохраните в журнал: по ним видно, что не так с запросом.
        // 429, 5xx и обрыв связи стоит повторить позже (раздел 4). 404 на
        // запись исходящего звонка штатен (звонок не сохранялся), на запись
        // входящего значит потерянный звонок: его тоже видно здесь.
        error_log('CRM calls: HTTP ' . $code . ' ' . $body);
    } elseif (($resp['data']['recording'] ?? '') === 'rejected') {
        // Звонок сохранён, запись нет: причина в recording_error (раздел 17).
        error_log('CRM calls: запись не принята ' . json_encode($resp['data']['recording_error'] ?? []));
    }
}

// Время АТС «2026-09-28 14:05:00» -> «2026-09-28T14:05:00+03:00».
function pbxTime(string $raw): string
{
    $dt = DateTimeImmutable::createFromFormat('Y-m-d H:i:s', $raw, new DateTimeZone(PBX_TIMEZONE));
    return $dt ? $dt->format(DATE_ATOM) : '';
}

$p = $_POST;

switch ($p['event'] ?? '') {
    case 'NOTIFY_START':
        crmCall([
            'call_id'      => $p['pbx_call_id'] ?? '',
            'direction'    => 'in',
            'client_phone' => $p['caller_id'] ?? '',
            'line'         => $p['called_did'] ?? '',
            'started_at'   => pbxTime($p['call_start'] ?? ''),
            // Источник по номеру линии: каждой рекламной линии свой.
            'source'       => ['73422000000' => 'Сайт', '79670000000' => 'Реклама'][$p['called_did'] ?? ''] ?? 'Звонок',
        ]);
        break;

    case 'NOTIFY_END':
        crmCall([
            'call_id'      => $p['pbx_call_id'] ?? '',
            'direction'    => 'in',
            'client_phone' => $p['caller_id'] ?? '',
            'line'         => $p['called_did'] ?? '',
            'status'       => $p['disposition'] ?? '',
            'duration'     => (int)($p['duration'] ?? 0),
            'started_at'   => pbxTime($p['call_start'] ?? ''),
        ]);
        break;

    case 'NOTIFY_OUT_START':
        crmCall([
            'call_id'      => $p['pbx_call_id'] ?? '',
            'direction'    => 'out',
            'client_phone' => $p['destination'] ?? '',
            'started_at'   => pbxTime($p['call_start'] ?? ''),
        ]);
        break;

    case 'NOTIFY_OUT_END':
        crmCall([
            'call_id'      => $p['pbx_call_id'] ?? '',
            'direction'    => 'out',
            'client_phone' => $p['destination'] ?? '',
            'line'         => $p['caller_id'] ?? '',
            'status'       => $p['disposition'] ?? '',
            'duration'     => (int)($p['duration'] ?? 0),
            'started_at'   => pbxTime($p['call_start'] ?? ''),
        ]);
        break;

    case 'NOTIFY_RECORD':
        // Ссылку АТС готовит не сразу (Novofon советует ждать около 40 секунд),
        // а АТС ждёт ответа на уведомление. Поэтому сначала отвечаем АТС, потом
        // ждём и запрашиваем ссылку. В боевой прослойке надёжнее очередь задач
        // (cron, supervisor); здесь для краткости пауза после ответа (PHP-FPM).
        header('Content-Type: application/json');
        echo json_encode(['success' => true]);
        if (function_exists('fastcgi_finish_request')) {
            fastcgi_finish_request();
        }
        // Ссылку на запись выдаёт API АТС (метод pbx/record/request, параметр
        // call_id = call_id_with_rec, срок жизни ссылки lifetime). Используйте
        // официальную библиотеку АТС; pbxRecordLink() здесь условная функция.
        $url = '';
        for ($try = 1; $try <= 3 && !$url; $try++) {
            sleep(40);
            $url = pbxRecordLink($p['call_id_with_rec'] ?? '', $p['pbx_call_id'] ?? '');
        }
        if (!$url) {
            error_log('PBX: ссылку на запись не получили, звонок ' . ($p['pbx_call_id'] ?? ''));
        } else {
            crmCall(['call_id' => $p['pbx_call_id'] ?? '', 'record_url' => $url]);
        }
        exit;
}

header('Content-Type: application/json');
echo json_encode(['success' => true]);

Если ссылку на запись получить нельзя, но файл скачать можно, отправьте его методом из раздела 18 с тем же call_id.

20. Переход со старых адресов

Старые адреса /api/lead.add (и /api/leads), /api/lead.call, /api/call.record оставлены только для интеграций, подключённых до выхода API v1, и будут отключены. Новые интеграции подключайте только к v1.

С 14.10.2026 старые адреса не принимают запросы без ключа: такой запрос получает 401 UNAUTHORIZED с текстом «Этот адрес больше не принимает запросы без ключа. Подключайтесь к API v1: …» и ссылкой на этот раздел. Работает только прежний ключ компании (выпущенный до появления ключей сотрудников) в заголовке X-API-Key или Authorization: Bearer: вызов попадает в компанию ключа. Новый ключ компании не выпускается, поэтому новые интеграции подключайте к v1 с ключом сотрудника.

Ключ, который не прошёл проверку, даёт 401 UNAUTHORIZED. Ключ сотрудника старые адреса не принимают: 403 KEY_NOT_ALLOWED, с ним работайте через /api/v1/leads и /api/v1/calls.

Отличия старого /api/call.record от записи ссылкой в v1: этот адрес принимает только запись, поэтому отказ отвечает на весь запрос. Негодная ссылка (требования те же, что в разделе 17): 400 VALIDATION_ERROR с причиной в error.details; хранилище заполнено: 403 QUOTA_EXCEEDED; очередь переполнена: 429 QUEUE_FULL с заголовком Retry-After.

21. Импорт через API

Тот же мастер, что кнопка «Импорт» в списке заявок (Выгрузка и импорт): файл, сопоставление колонок, запуск, шаги, отчёт об ошибках. Область leads:import и право сотрудника «Загружать заявки из файла (импорт)» (по умолчанию у менеджеров выключено). Файл XLSX или CSV до 20 МБ, до 10 000 строк. У сотрудника одновременно идёт один импорт.

Ошибки: 400 VALIDATION_ERROR (файл не разобран, сопоставление без имени, телефона и email), 403 PERMISSION_DENIED (leads.import; leads.reassign у user и column; если право «Загружать заявки из файла» сняли во время импорта, шаг его останавливает), 404 (чужой или удалённый импорт), 409 CONFLICT (у сотрудника уже идёт импорт), 413, 429 RATE_LIMITED с Retry-After. Заявки из импорта отмечены в ленте пометкой via: "import".

Загруженный и завершённый (с отчётом) импорт хранится сутки после последнего изменения, идущий импорт без новых шагов двое суток после последнего шага; потом он удаляется и отвечает 404.

curl -X POST https://crm.linkodium.com/api/v1/leads/import \
  -H "X-API-Key: $CRM_API_KEY" \
  -F "file=@/tmp/leads.xlsx"

curl -X POST https://crm.linkodium.com/api/v1/leads/import/$JOB/start \
  -H "X-API-Key: $CRM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"map": {"0": "name", "1": "phone", "2": "email"}, "duplicates": "append"}'

curl -X POST https://crm.linkodium.com/api/v1/leads/import/$JOB/step \
  -H "X-API-Key: $CRM_API_KEY"

22. Расшифровка звонков

CRM расшифровывает новые записи сама. Через API можно узнать состояние расшифровки и запросить её для записи, которая не расшифрована (полученной до включения расшифровки или неудавшейся), как кнопки «Расшифровать» и «Повторить» в карточке.

uuid записи берётся из recordings[].uuid события call ленты (раздел 12). Запись не найдена или заявка не видна сотруднику: 404. Расшифровка выключена в настройках компании или не настроена: 409 FEATURE_DISABLED. Очередь заполнена: 429 QUEUE_FULL с Retry-After: 60. Готовый текст появляется в ленте через несколько минут; запись длиннее 60 минут не расшифровывается. Запись уходит сервису распознавания речи.

23. Чаты: правка, удаление, стикеры, голосовые

Всё, что сотрудник делает в разделе «Чаты» кроме ответа текстом и файлами (раздел 16). Права те же, что в CRM: видимость по режиму доступа к чатам, ответ по праву ответа, удаление из CRM и блокировка только администратору.

Отказы: не автор сообщения 403 PERMISSION_DENIED (permission: chats.author); нет права ответа (режим «отвечает ответственный», клиент другого сотрудника) 403 PERMISSION_DENIED: у стикера и голосового permission: chats.mode, как у ответа в разделе 16, у прочих адресов раздела chats.reply; окно правки или удаления истекло, сообщение не в том состоянии 409 CONFLICT (error.reason: window, state); у клиента нет заявки 409 (no_lead). Удаление у клиента не требует права ответа: своё сообщение автор убирает и тогда, когда ответ закрыт режимом доступа. При отключённом канале или непринятом токене удаление у клиента невозможно (409 CHAT_UNAVAILABLE), и в MessageDTO can_delete_at_client тогда false.

24. Почта: ящики, участники, удаление

Всё, что сотрудник делает в разделе «Почта» кроме чтения и отправки (раздел 15). Только ящики, где сотрудник участник; действия управления ящиком (участники, отключение, имя отправителя, пароль, серверы) требуют права управления ящиком: 403 PERMISSION_DENIED с permission: mail.manage. Текст в error.message для человека и зависит от действия (например, «Управлять доступом к ящику может участник с правом управления»): проверяйте permission, а не текст. Почта приостановлена: 409 SERVICE_PAUSED. Пароли передаются только в теле, не попадают в ответы и журналы.

Подключение ящика: не больше 10 попыток в час на ключ, кроме пределов сотрудника и компании, как в CRM.

Удаление писем (mail:remove) меняет и сам почтовый ящик: письма уходят в «Корзину» на сервере почты (в своей папке их больше не видят и другие почтовые программы), а корзину провайдер очищает по своим правилам. Если корзины на сервере нет, письмо там остаётся на месте, удалено оно только из CRM. Отключение ящика (disconnect) и выход из него (leave) письма на сервере почты не трогают.

25. Компания, сотрудники, интеграции

Настройки компании, права доступа, сотрудники и приглашения, услуги и быстрые ссылки, API-ключи, Telegram, MAX, виджет и Авито, а также профиль, уведомления, компании сотрудника и обращения в поддержку описаны на отдельной странице: API: компания, сотрудники, интеграции и профиль. Административные адреса доступны только ключу администратора или владельца, области управления компанией и профилем сотрудник выпускает только себе.

Настройки сквозной аналитики (сайты, телефонные номера, Яндекс Метрика, ДАРА, цели конверсий, журналы касаний, визитов и конверсий) администратор меняет через адреса /api/v1/tracking... с областями tracking:read и tracking:write: API компании, раздел «Трекинг». Визит заявки и отчёт по источникам доступны любому сотруднику с leads:read (раздел 10, раздел 9).

Чек-лист «Настройка CRM», список «Начало работы» сотрудника и пример заявки (адреса /api/v1/onboarding...): API компании, раздел «Настройка CRM».

Уход из компании (POST /api/v1/company/leave) без transfer_to отдаёт открытые заявки менеджеру по умолчанию, а если он не назначен, недоступен или уходит сам, владельцу компании; если и владелец недоступен (учётная запись отключена), заявки остаются без ответственного. "transfer_to": "none" оставляет их без ответственного всегда. Ключи, привязанные к самому уходящему или исключённому сотруднику, перестают действовать при любом значении revoke_keys (401); без отзыва они снова заработают, если сотрудника пригласят обратно. PATCH /api/v1/integrations/{uuid}/settings у виджета проверяет обе формы (поля канала и поля виджета) до записи: при ошибке в любой из них ничего не сохраняется.

• Исключение сотрудника (POST /api/v1/members/{uuid}/remove) без transfer_to отдаёт его открытые заявки по правилу ухода: менеджеру по умолчанию, если он работает и это не исключаемый, иначе владельцу, если он работает, иначе заявки остаются без ответственного. Исключение владельца всегда отвечает 403 PERMISSION_DENIED с permission: "company.owner" (раньше с transfer_to, равным ему самому, было 400).
• Ответы исключения {moved, invites_dropped, keys_revoked, default_manager_changed, default_manager} и ухода {left, moved, keys_revoked, default_manager_changed, default_manager}: default_manager_changed равно true, если ушедший был менеджером по умолчанию и им стал получатель его заявок (при "none" владелец компании); default_manager: текущий менеджер по умолчанию {uuid, name} или null.
• PATCH /api/v1/permissions: если права компании дольше 10 секунд сохраняет другой запрос, ответ 409 CONFLICT, ничего не записано; повторите через несколько секунд.
• Обращение в поддержку POST /api/v1/support/requests ({subject, message}): тема до 200 символов, текст до 10 000. Ключ обращения обязателен: заголовок Idempotency-Key или поле client_request_id (1-255 видимых символов ASCII, как в разделе 6; если переданы оба, они должны совпадать), без ключа 400 VALIDATION_ERROR. UUID v4 в любом регистре становится полем request строчными буквами, любой другой ключ превращается в производный UUID. Ответ 202 {request, state, ticket, text, duplicate}. Статус: GET /api/v1/support/requests/{request}, где request взят из ответа; спрашивайте раз в несколько секунд, пока state не станет sent или failed (sending: отправляется; delayed: CRM повторит отправку сама; sent: обращение в поддержке, номер в ticket; failed: отправьте обращение заново с новым ключом). Тот же ключ с другой темой или текстом: 422 IDEMPOTENCY_MISMATCH в течение суток, позже 409 CONFLICT. Не больше 60 обращений в час: 429, Retry-After равен числу секунд до конца часового окна (до 3600). 503 SERVICE_UNAVAILABLE: приём обращений через API закрыт (без Retry-After) или у сотрудника 20 недоставленных обращений либо заполнена общая очередь (Retry-After: 300).

26. ИИ-ассистенты (MCP)

Тот же API доступен ИИ-ассистентам по протоколу MCP (Model Context Protocol) по адресу https://crm.linkodium.com/api/v1/mcp: Claude, ChatGPT, Cursor и другие клиенты ищут заявки, читают переписку и готовят ответы с правами сотрудника. Вход через OAuth 2.1 (приложение само откроет страницу CRM для согласия) или по API-ключу сотрудника в заголовке Authorization: Bearer. Адреса OAuth для клиента: метаданные /.well-known/oauth-protected-resource и /.well-known/oauth-authorization-server, согласие /oauth/authorize/, регистрация клиента POST /api/v1/oauth/register, токены POST /api/v1/oauth/token, отзыв POST /api/v1/oauth/revoke (PKCE S256). MCP (/api/v1/mcp) и /api/v1/oauth/register, /token, /revoke принимают только POST, метаданные /.well-known/... отдаются на GET, страница согласия /oauth/authorize/ открывается в браузере. Все они отвечают своим форматом (JSON-RPC у MCP, ошибки OAuth по RFC 6749), а не форматом раздела 3. Каждое изменение заявки через ассистента видно в ленте с пометкой via: "mcp". Данные посетителя (область visitors:read: IP и браузер, в том числе в тексте событий) ассистенту не отдаются при любом ключе. Подключение, разрешения и список инструментов: Подключение ИИ-ассистентов по MCP.

27. Изменения API

12.11.2026: решение антиспама в ответе приёма, данные Авито в чатах. Прежние запросы и ответы не меняются, добавлены поля.

• POST /api/v1/leads: поле spam_check_wait, в ответе ключ spam_check {state, verdict, live, action, reasons} (раздел 8).
• Чаты (раздел 16): у чата item (объявление Авито), у сообщения external (avito_app: ответ из приложения Авито).
• Документация дополнена по коду, ответы не менялись: остальные поля сообщения чата (auto, service, forward, album, sticker, location, venue, contact_card, размеры файла; раздел 16), отметки письма auto, bounce, spoof_warning, auth_fail и полный объект ящика в GET /api/v1/mail/accounts (раздел 15), допустимые значения spam_check_wait (раздел 8).

11.11.2026: цель «Звонок от 30 с» и канал «Авито». Прежние запросы и ответы не меняются, добавлены значения.

• PATCH /api/v1/tracking/conversions/settings: флаг goals.call_target; у конверсий и визита значение goal: "call_target" (цель crm_call_target, первый входящий звонок заявки с разговором от 30 секунд; API компании, Сквозная аналитика).
• Чаты: channel.type: "avito" (раздел 16), событие created с source: "avito" (раздел 12), канал Авито в GET /api/v1/integrations (API компании; подключается только в кабинете).

10.11.2026: канбан заявок. Прежние запросы и ответы не меняются, добавлен адрес.

• GET /api/v1/leads/board: колонки по этапам со счётчиками и страницами заявок, как вид «Канбан» в CRM (раздел 9).

10.11.2026: антиспам и модули общего кода (Антиспам). Прежние запросы и ответы не меняются, добавлены поля. Повторное обращение (раздел 8) и входящий звонок (раздел 17) подшиваются только к активной заявке, созданной не раньше 30 суток назад; старше: новая заявка.

• POST /api/v1/leads и /api/lead.add: поле ловушки lkt_hp (раздел 8).
• Ключ spam_check в GET одной заявки (раздел 10); событие смены статуса антиспамом с via: "antispam".
• Администратору: модули общего кода в /api/v1/tracking и у сайтов, отметка ключа skip_antispam у любого ключа, компании и сотрудника (API компании).
• Заявка по ключу сотрудника с tracking_token, form_page или landing_page проверяется на спам как заявка по ключу компании (раздел 8).
• MCP: spam_check в ответе get_lead.

10.11.2026: трекинг. Прежние запросы и ответы не меняются, добавлены поле и значения.

• Номера трекинга: поле channel (API компании); у визита и в отчёте новые значения канала maps и other (раздел 9).
• Входящий звонок на рекламный номер получает канал ad и без клика; несколько кликов по номеру от одного посетителя дают точность probable по последнему клику.
• Цель «обращение» не ставится заявке, созданной сразу в «Спаме» или ушедшей в «Спам» до отправки; заявки, созданные импортом, целей не дают.

08.11.2026: новая карточка заявки. Прежние запросы и ответы не меняются, добавлены поля и адреса.

• GET /api/v1/leads/{номер}/history: история клиента (раздел 10).
• POST и DELETE /api/v1/leads/{номер}/comments/{uuid}/pin: закреп комментария (раздел 13); ключ pinned_comment в GET заявки.
• POST /api/v1/leads/{номер}/status принимает amount и comment вместе со статусом (раздел 11).
• Выгрузка XLSX: «Сумма сделки» и маркетинговые колонки; «IP» и «Браузер» только с visitors:read.
• MCP: amount и comment у set_lead_status, pin у add_lead_comment.

07.11.2026: сквозная аналитика (Сквозная аналитика). Прежние запросы и ответы не меняются, добавлены новые поля и адреса.

• Новые области tracking:read и tracking:write (администратор; tracking:write включает tracking:read и выпускается только себе) и адреса /api/v1/tracking... (API компании).
• GET /api/v1/leads/{номер}/visit: визит заявки (раздел 10); GET /api/v1/tracking/report: отчёт «Источники обращений» (раздел 9). Оба с leads:read.
• Заявка: новый ключ amount (сумма сделки, число или null), PATCH /api/v1/leads/{номер} принимает amount (раздел 10). Если ваш код сравнивает набор ключей заявки с закрытым списком, добавьте его.
• POST /api/v1/leads и /api/lead.add: поле tracking_token (раздел 8).
• POST /api/v1/calls: если source или service не переданы, новая заявка берёт их из строки номера line в настройках трекинга, иначе как прежде «Звонок» (раздел 17).

18.10.2026: исправления по аудиту API и уточнения документации по коду.

Изменилось поведение:

• Обработчик запросов не ответил вовремя: вместо HTML-страницы 502 или 504 ответ 503 SERVICE_UNAVAILABLE в JSON с Retry-After: 5 на адресах API, в том числе MCP, OAuth и старых адресах (разделы 3 и 4).
• POST /api/v1/leads: lead (заявка целиком) приходит только ключу с областью leads:read, в том числе у повторного обращения; ключ формы сайта с одной leads:create получает lead: null (раздел 8). Email с кириллицей (info@сайт.рф) принимается при создании и правке заявки и в /api/lead.add.
• POST /api/v1/leads по ключу сотрудника: source события created теперь api (было web), в карточке заявки «Заявка создана через API» вместо «вручную»; такие события, записанные раньше, переписаны на api. Заявка из формы CRM остаётся web, от ИИ-ассистента web с via: mcp (разделы 8 и 12).
• Повторное обращение и поиск заявки звонком: номер с кодом другой страны (записан с «+», код не 7) сравнивается целиком, а не по последним 10 цифрам: +84912345678 больше не находит заявку с +74912345678 (разделы 8 и 17).
• Предел запросов с одного IP-адреса к API v1 поднят: около 100 запросов в секунду, пачка до 1000 разом; прежний предел давал 429 общей прослойке нескольких компаний за одним адресом и синхронизации в несколько потоков, хотя лимит ключа ещё не был исчерпан (раздел 5).
• merge-candidates: телефон через 8 и через +7 находит одну заявку; новая причина отказа у заявки, которую другой сотрудник только что вывел из «Провала»: 409 CONFLICT (раздел 11).
• Лента: started_at звонка всегда в UTC с Z или null (раздел 12); POST /api/v1/calls принимает смещение +0300 и +03 (раздел 17). Повтор DELETE /api/v1/comments/{uuid} тем же ключом: already: true вместо 404 (раздел 13).
• Лента: параметр updated_since и поле updated_at у каждого события; события звонков, дополненные позже, и события, перенесённые объединением, приходят с updated_since как изменённые (раздел 12).
• Тело письма: html_too_big: true и у state: too_big, картинки письма в html ссылаются на /api/v1/mail/parts/{uuid}; GET /api/v1/mail/parts/{uuid}?retry=1 заново скачивает вложение в error (раздел 15).
• Ящик: имя отправителя принимается и полем display_name; удаление писем в ящике без «Корзины» на сервере больше не стирает их там, письмо остаётся в своей папке; display_name, равный нынешнему имени, сменой имени не считается (раздел 24).
• «Создать заявку» из письма (POST /api/v1/mail/threads/{uuid}/lead-create): lead (заявка целиком) приходит только ключу с областью leads:read, иначе null, как у POST /api/v1/leads (раздел 24).
• Импорт: при manager_mode: user поле manager обязательно (пустая строка: без ответственного); в состоянии preview_rows, default_manager и params.manager_mode; шаг отвечает busy: true, пока CRM обрабатывает другие импорты; файл XLSX с паролем получает отказ «Файл защищён паролем»; начатый импорт ждёт продолжения двое суток (раздел 21).
• Звонки: запись по ссылке, которая после скачивания не поместилась в хранилище, к звонку по-прежнему не прикрепляется, но теперь администраторы компании с подключённым Telegram получают уведомление «Хранилище компании заполнено» (раздел 17).
• Чаты: can_delete_at_client: false у отключённого канала и непринятого токена; телефон с +8 (+84...) в POST /api/v1/chats/{uuid}/phone остаётся международным, а не становится +7 (раздел 23).
• Компания (раздел 25): исключение без transfer_to выбирает получателя заявок по правилу ухода из компании, исключение владельца: 403 (раньше 400); ответы исключения и ухода несут default_manager_changed и default_manager; у администратора и владельца chats.mode в правах all; PATCH /api/v1/permissions во время другой правки прав: 409 CONFLICT, ничего не записано; флаги настроек канала принимают и "true", "false". Обращение в поддержку принимает заголовок Idempotency-Key и любой допустимый ключ (раздел 6), Retry-After у 429 равен остатку часового окна.
• ИИ-ассистенты (раздел 26): данные посетителя (visitors:read) ассистенту не отдаются при любом ключе, в том числе IP в тексте событий; send_email пишет на адрес, который оставил клиент или ввёл сотрудник; повторная привязка уже привязанной переписки не пишет событие в ленту.

Документация приведена к коду (поведение прежнее):

• Поиск search идёт и по полю client_needs, и по телефону и email объединённых заявок (раздел 9).
• past_leads в ленте: только прошлые заявки с перепиской в ящиках сотрудника, поле mail_threads_total (раздел 12).
• Почта сотрудника без ящиков: пустые списки вместо 404; тело письма: текст до 256 КБ, HTML больше 2 МБ не хранится (state: too_big), состояние no_space (раздел 15).
• Удаление писем (mail:remove) переносит их и в «Корзину» почтового ящика (разделы 1 и 24).
• Подключение ящика: когда серверы обязательны, присоединение к уже подключённому адресу через 400 CONFIRM_REQUIRED с error.join_confirm; ответы 201 и 200 у «Создать заявку» из письма (раздел 24).
• Импорт без права «Менять ответственного»: ответственный всех заявок сам сотрудник при любом manager_mode (раздел 21).
• 403 QUOTA_EXCEEDED у голосового (раздел 23), 429 QUEUE_FULL у старого /api/call.record, 401 у заблокированной компании и отключённой учётной записи (раздел 4).
• MCP и OAuth: только POST у /api/v1/mcp и /api/v1/oauth/*, метаданные на GET (раздел 26); пустая строка в manager у create_lead (раздел 8); кнопка «Отметить все прочитанными» (разделы 16 и 23).
• Событие «создана» у заявки, созданной звонком, пишется без автора, как события звонков (раздел 1); recording: "queued" значит только, что ссылка принята в очередь (раздел 17).
• email с ошибкой в формате даёт 400 VALIDATION_ERROR, заявка не создаётся (раздел 8); since в ленте отбирает события по времени создания (раздел 12); повтор удаления комментария описан и в разделе 6.
• Компания и поддержка (раздел 25): обращение в поддержку, его ключ, состояния sending, delayed, sent, failed, пределы темы и текста, ответы 422, 409 и 503.

15.10.2026: исправления по аудиту API.

• Список с updated_since не отдаёт правки последних 30 секунд (раздел 9). Раньше заявка, чья запись завершалась позже более свежей правки другой заявки, могла навсегда выпасть из синхронизации по updated_since. Отметка updated_at последней полученной заявки по-прежнему годится для следующего опроса, если запись заявки завершается быстрее 30 секунд (обычный случай); без updated_since список прежний.
• Предпросмотр объединения (dry_run: true, раздел 11, и merge_leads у ИИ-ассистента) без области visitors:read больше не показывает в preview.fill IP и браузер посетителя.
• PATCH /api/v1/integrations/{uuid}/settings у виджета проверяет поля формы виджета до записи (API компании): ошибка в них (400 VALIDATION_ERROR) больше не оставляет сохранёнными поля формы «Канал» из той же правки.
• POST /api/v1/api-keys с сотрудником не из компании: 404 NOT_FOUND с текстом «Сотрудник не найден в компании» (без «Обновите страницу.»).
• В ленте заявки (GET /api/v1/leads/{номер}/events и get_lead_events у ИИ-ассистента) номер другой заявки в previous_lead_number (событие created) и moved_to_lead_number (событие chat) приходит null, если сотрудник ключа эту заявку не видит (раздел 12). Раньше номер приходил всегда, и сотрудник с видимостью «только свои» узнавал номер заявки коллеги, который карточка прячет. Ключ компании видит номера как раньше.
• Если скачивание файла (вложение заявки, запись звонка, файл чата, фото сотрудника) обрывается на стороне хранилища, ответ об ошибке больше не несёт заголовки Content-Length и Content-Range самого файла. Раньше клиент получал короткий ответ об ошибке с длиной файла и ждал недостающие байты до обрыва соединения.
• Ответ на письмо без to и cc (mode: "reply" или "reply_all", раздел 15, и send_email у ИИ-ассистента): имя отправителя длиннее 100 символов в получателях по умолчанию обрезается до 100 символов. Раньше такой ответ получал 400, хотя имя никто не набирал.
• Уход из компании (POST /api/v1/company/leave) без transfer_to: если и менеджер по умолчанию, и владелец недоступны (учётная запись отключена), открытые заявки остаются без ответственного (раздел 25). Раньше уход в таком случае отклонялся с ошибкой «Получатель заявок не состоит в компании».
• Запись разговора ссылкой (раздел 17): формат CRM определяет по содержимому файла, а не по расширению в ссылке, поэтому ссылка без расширения подходит. Ответ не с аудиофайлом (страница ошибки или входа, JSON) считается временной ошибкой скачивания и повторяется, после 5 неудачных попыток запись к звонку не прикрепляется. Раньше такая страница прикреплялась к звонку как запись.
• Документация уточнена по коду: поиск search находит телефон в любом формате записи (раздел 9); в строке получателей письма имя с запятой или адресом пишется в кавычках (раздел 15); поля previous_lead_number и moved_to_lead_number в ленте (раздел 12); ключи самого уходящего или исключённого сотрудника перестают действовать при любом revoke_keys (раздел 1, API компании).
• Документация уточнена по коду: справочник GET /api/v1/managers ключу компании недоступен, ответственного ключ компании указывает email сотрудника (раздел 8); мастер импорта в CRM открывается кнопкой «Импорт» (раздел 21); у отказа управления ящиком признак permission: mail.manage, текст зависит от действия (раздел 24).

14.10.2026: старые адреса без ключа отключены, права сотрудника распространены на почту и телефонию.

• Старые адреса /api/lead.add, /api/leads, /api/lead.call, /api/call.record больше не принимают запросы без ключа: 401 UNAUTHORIZED с текстом, который ведёт на v1 (раздел 20). Прежний ключ компании (X-API-Key или Authorization: Bearer) там работает как раньше, ключ сотрудника получает 403 KEY_NOT_ALLOWED. Если ваша форма или АТС слали запросы на эти адреса без ключа, переведите их на POST /api/v1/leads и POST /api/v1/calls с ключом.
• Новый текст 401 на адресах v1 называет оба пути выпуска ключа: администратор в настройках компании или сотрудник сам себе в профиле (раздел 2).
• mail:read и mail:send стали областями «только себе» (раздел 1): на ключ другого сотрудника не выпускаются (403 PERMISSION_DENIED, permission: "keys.self_only"), а у ключей, выпущенных так раньше, не действуют (403 SCOPE_REQUIRED, в GET /api/v1/me их нет). Текст отказа выпуска теперь с группой области: «Область «Почта: Чтение» сотрудник выпускает только себе в профиле».
• Телефония по ключу сотрудника действует с его правами (раздел 17): звонок в невидимой ему заявке отвечает lead_number: null и hidden: true, запись к такому звонку не принимается (recording_error.code: PERMISSION_DENIED, файл: 404 CALL_NOT_FOUND), без права «Создавать заявки» звонок, который создал бы заявку, получает 403 PERMISSION_DENIED (leads.create), заявку из звонка при видимости «Только свои» получает сам сотрудник, при «Все заявки компании» менеджер по умолчанию (без него владелец) независимо от права «Менять ответственного». Ключи компании работают как раньше.
• Заявка через POST /api/v1/leads по ключу сотрудника теперь присылает уведомление «Новая заявка» и самому сотруднику ключа по его настройкам (раздел 8).
• Ответственный заявки через POST /api/v1/leads по ключу сотрудника зависит от того, какие заявки видит сотрудник (раздел 8): при «Только свои» всегда сам сотрудник, поле manager не учитывается; при «Все заявки компании» без manager менеджер по умолчанию (раньше без права «Менять ответственного» сам сотрудник), с manager указанный сотрудник, другой сотрудник только с правом «Менять ответственного» (без права 403, как раньше). Пустая строка в manager у ключа сотрудника больше не означает «без ответственного». У ИИ-ассистента (create_lead) правила прежние.
• Поле manager принимает email сотрудника вместо uuid в POST /api/v1/leads и PATCH /api/v1/leads/{номер}; ключ компании теперь тоже понимает manager при создании (раздел 8).
• Менеджер по умолчанию не назначен: новые заявки (API, формы сайтов, звонки, почта, импорт, чаты) получает владелец компании, а не остаются без ответственного. GET /api/v1/company по-прежнему показывает в default_manager саму настройку (null, если не назначен).
• Без области visitors:read из текста событий duplicate_request в ленте убрана строка с IP посетителя (раздел 12).
• Чаты при видимости «только свои»: phone чата без своего телефона клиента берётся из заявки только видимой сотруднику, иначе null; поиск q по #номеру и телефону заявки находит только чаты видимых заявок; в карточке посетителя source null у невидимой заявки, mail.opt_out учитывает только отписки в этой компании (разделы 16 и 23).
• Квота отправки писем (100 в час с адреса ящика) и quota ящика считают только письма этой компании (раздел 15).
• Документация уточнена по коду, поведение не менялось: общий предел тела 110 МБ для файлов одного запроса (раздел 5), форма ответа merge с dry_run (раздел 11), поведение updated_since, archived и status (раздел 9), view с lead и contact, повтор письма в течение суток (раздел 15), error.reason у DUPLICATE_FOUND (разделы 4 и 24), неизвестные поля и multipart/form-data только у POST (раздел 3), лимит изменений (раздел 5), ym_client_id длиннее 64 символов (раздел 8), пример прослойки АТС (раздел 19).

09.10.2026: API покрывает всё, что сотрудник делает в кабинете. Прежние адреса, их запросы, ответы и ошибки не изменились; новые поля в прежних ответах только добавлены.

• Новые области выдаются только по выбору при выпуске: прежние ключи их не получают.
• Прежние области открывают и новые адреса своего раздела: например, leads:write отмечает спам, chats:write отправляет стикеры и голосовые, mail:send отвязывает переписку от заявки. Данные посетителя, участники и настройки ящиков, компания и профиль требуют новых областей.
• Области управления компанией и профилем сотрудник выпускает только себе.
• Лента заявки без фильтра types теперь может содержать события типа action и пометку via: mcp. Если ваш код проверяет тип события по закрытому списку, добавьте их.
• Новые адреса: сводка и кандидаты объединения заявок, спам, импорт, расшифровка звонков (разделы 9, 11, 21, 22), чаты и почта (разделы 23 и 24), компания, сотрудники, интеграции и профиль (API компании), MCP (раздел 26).
• Новые поля: author.avatar_url, past_leads и unbound_mail_count в ленте; total списка с with_total=1; ip_address и user_agent заявки (только с visitors:read); поля чата и сообщения (раздел 16); lead_prefill переписки почты; состояние ящика в GET /mail/accounts (servers только с mail:manage); leads и message.thread в ответе отправки письма; badge у отметки чата прочитанным; chat в ответе на сообщение в чат.
• Новые коды ошибок: CONFIRM_REQUIRED, DUPLICATE_FOUND, FEATURE_DISABLED, QUEUE_FULL (раздел 4).