---
title: "Управление агентом по API"
id: "2095"
type: "page"
slug: "api"
published_at: "2026-09-28T16:03:04+00:00"
modified_at: "2026-09-28T16:18:41+00:00"
url: "https://pastukhov.com/agents/crm/docs/api"
markdown_url: "https://pastukhov.com/agents/crm/docs/api.md"
excerpt: "Все изменения в CRM вносятся не через экраны, а программно — по адресам управления, которые…"
---

# Управление агентом по API

[https://pastukhov.com/agents/crm/docs/api.md](https://pastukhov.com/agents/crm/docs/api.md)

Все изменения в CRM вносятся не через экраны, а программно — по адресам управления, которые и есть язык общения с агентом. Это звучит технически, но суть простая: у продукта есть набор команд, которыми агент заводит и правит данные, а интерфейс только показывает результат. Понимать команды наизусть не нужно ни вам, ни агенту: продукт сам рассказывает, что умеет.

## Зачем управление по API

API (программный адрес управления) — это способ делать что-то словами-командами, а не нажатиями. Для продукта это принципиально: именно так агент может выполнить сотни однотипных действий, ничего не перепутав, и именно поэтому интерфейс остаётся лёгким и безопасным. Экран читает, управление пишет — и эти две роли разведены намеренно.

## Два вида доступа

У продукта два разных «пропуска». Первый — обычный вход в интерфейс: он даёт только чтение, и это проверяется на сервере, а не в браузере. Второй — **ключ управления**: только с ним можно менять данные. Ключ передаётся в заголовке запроса, то есть агент каждый раз предъявляет его вместе с командой.

Побочная выгода — честность устройства: даже если человек с браузером очень захочет что-то поправить, у него не получится, потому что его пропуск этого не позволяет. А если ключа нет вовсе, изменения просто запрещены — продукт скажет об этом прямо, а чтение продолжит работать.

## Ключ управления

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

## Справочник, который объясняет сам себя

Главное удобство для агента: по одному адресу он получает полный справочник — что здесь есть, как входить, как устроены списки и ошибки, какие ресурсы доступны и где лежит описание каждого. Там же — краткое руководство с типовыми последовательностями («сначала поищи, потом создавай», «проверь импорт без записи, потом запускай»), таблица кодов ошибок с объяснениями и список ограничений с конкретными числами. Проще говоря: агент, зная только адрес и ключ, дальше разбирается сам — без чтения кода и без инструкций, написанных отдельно и устаревающих.

Ограничения в этом справочнике не выдуманы: числа берутся из самого продукта, поэтому не бывает так, что документация обещает одно, а продукт делает другое.

## Описания ресурсов и структура данных

По каждому разделу есть отдельное описание: какие поля есть, какие значения допустимы, какие адреса вызывать, с примером запроса и ответа на каждый, какие бывают ошибки и с чем этот раздел связан. Отдельно описан общий список видов записей и связей между ними — по нему видно, как устроены данные целиком. Ни одного «секретного» адреса нет: всё, что продукт умеет, описано и совпадает с действительностью.

Если вы завели свои поля или свои объекты, они тоже появляются в описаниях — сразу, без перезапуска. Поэтому агент всегда видит актуальную картину вашей базы, а не типовую из коробки.

## Кто именно изменил

Вместе с командой агент может назвать себя — короткой подписью. Тогда в истории изменения и в записях журнала видно не безликое «служба», а конкретное имя: «агент поддержки», «перенос из старой базы». Если подписи нет, изменение всё равно записано и отнесено к агенту управления. Благодаря этому в любой момент можно понять, чья это правка — человека или конкретного агента.

## Живой поток изменений

Об изменениях продукт сам сообщает тем, кто смотрит на данные: как только агент что-то поправил, открытые экраны это показывают — без перезагрузки страницы. Агенты тоже получают этот сигнал, если им нужно следить за изменениями: например, чтобы не затереть свежую правку человека. То есть человек и агент видят одни и те же события — никто не работает вслепую.

## Публичный приём заявок — отдельно и узко

У приёма заявок с чужих сайтов — особый, очень ограниченный пропуск. Им можно **только создать заявку** и ничего больше: ни прочитать клиентскую базу, ни изменить контакт, ни узнать, что в ней есть. Это сделано специально: ключ приёма неизбежно лежит в коде страницы, и он может попасть не туда, поэтому его возможности сведены к минимуму. Ключ можно заменить в любой момент, и старый сразу перестаёт приниматься. Адрес, по которому принимаются заявки, отвечает одинаково скромно на любой неверный ключ — он ничего не выдаёт о том, что внутри.

## Ограничения и понятные ошибки

Управление работает по понятным правилам, и все они названы прямо. Списки отдаются страницами: по умолчанию по 25 записей, максимум по 100 — так отвечает любой список, поэтому большие выгрузки делаются отдельной операцией выгрузки, а не тянутся одной страницей. У отбора есть разумные пределы: не больше 25 условий и не глубже трёх уровней вложенности — обычно этого хватает с большим запасом. Повторные обращения к приёму заявок ограничены по частоте, а объём заявки — по размеру.

Ответы на ошибки устроены по-человечески, а не «ошибка 500». Неверное значение поля — отказ с перечнем всех проблемных полей и понятной причиной. Неизвестное значение из списка — ответ, в котором перечислены допустимые. Если чего-то нет — ответ говорит, чего именно и с каким номером. А если прав не хватает, ответ объясняет, что нужен ключ управления и где искать описание команд, — то есть не оставляет агента гадать. Все ошибки приходят в одинаковом формате, поэтому их легко и человеку, и программе.

## Что доступно агенту

По управлению доступно всё, что есть в вашей сборке: клиентская база, хронология, качество данных, импорт и выгрузка, свои поля и объекты, а также все включённые надстройки — лиды, сделки, деньги, маркетинг, коммуникации, сервис. Чего нет в вашей сборке, того нет и в справочнике: агент не станет искать несуществующее. Включили надстройку — её возможности появились, выключили — исчезли.

Дальше → [Чат с ИИ-агентом](/agents/crm/docs/agent)

[← Оглавление документации](/agents/crm/docs)