Основные объекты и методы

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

Авторизация

Для доступа к данными системы, как через интерфейсы, так и через API, необходима авторизация под пользователем аккаунта. Вся работа через API также происходит с учетом прав доступа авторизованного пользователя в аккаунте. Все методы могут быть использованы только после авторизации.

Метод API Описание
POST /private/api/auth.php В случае успешной авторизации возвращает идентификатор сессии пользователя, который необходимо использовать при обращении к остальным методам API.

Аккаунт

Через API вы можете получить необходимую информацию по аккаунту: название, оплаченный период, пользователи аккаунта и их права, справочники дополнительных полей контактов и сделок, справочник статусов сделок, справочник типов событий, справочник типов задач и другие параметры аккаунта.

Метод API Описание
GET accounts/current Получение информации по аккаунту в котором произведена авторизация.

Контакт

Одна из основных сущностей системы. Состоит из предустановленного набора полей и дополнительных, создаваемых администратором аккаунта. Каждый контакт может участвовать в одной и более сделке или может быть вообще не связан ни с одной. Каждый контакт может быть прикреплен к одной компании.

E-mail контакта и телефон используются как уникальные идентификаторы в связке с другими системами. К примеру, именно в события контакта попадает информация о совершенных звонках, о e-mail-переписке.

Каждому контакту может быть задан ответственный для разграничения прав доступа между сотрудниками аккаунта.

Метод API Описание
POST contacts/set Метод позволяет добавлять контакты по одному или пакетно, а также обновлять данные по уже существующим контактам.
GET contacts/list Метод для получения списка контактов с возможностью фильтрации и постраничной выборки.
GET contacts/links Метод для получения списка связей между сделками и контактами.

Сделка

Одна из основных сущностей системы. Состоит из предустановленного набора полей и дополнительных, создаваемых администратором аккаунта. Каждая сделка может быть прикреплена к одному и более контакту или не прикреплена ни к одному.

Каждой сделке может быть задан ответственный для разграничения прав доступа между сотрудниками аккаунта.

Сделка обладает статусом, который обозначает положение сделки в жизненном цикле (бизнес-процесс). Он должен быть обязательно присвоен сделке. Список статусов может быть изменен в рамках аккаунта, кроме двух системных конечных статусов.

Метод API Описание
POST leads/set Метод позволяет создавать новые сделки, а также обновлять информацию по уже существующим
GET leads/list Метод который позволяет получить подробную информацию о уже созданных сделках, имеет возможность фильтрации данных и постраничной выборки.
GET contacts/links Метод для получения списка связей между сделками и контактами.

Компания

Полностью аналогична сущности "контакт". Состоит из предустановленного набора полей и дополнительных, создаваемых администратором аккаунта. Каждая компания может участвовать в одной и более сделке или может быть вообще не связана ни с одной.

E-mail и телефон используются как идентификаторы в связке с другими системами

Каждой компании может быть задан ответственный для разграничения прав доступа между сотрудниками аккаунта.

Метод API Описание
POST company/set Метод позволяет добавлять компании по одному или пакетно, а также обновлять данные по уже существующим компаниям.
GET company/list Метод для получения списка компаний с возможностью фильтрации и постраничной выборки.

Покупательv3

Аналогичен сущности "сделка". Состоит из предустановленного набора полей и дополнительных, создаваемых администратором аккаунта. Каждый покупатель может быть прикреплен к одному и более контакту или не прикреплен ни к одному.

Каждому покупателю может быть задан ответственный для разграничения прав доступа между сотрудниками аккаунта.

Покупатель обладает периодом, который обозначает положение покупателя в жизненном цикле (бизнес-процесс). Список периодов может быть изменен в рамках аккаунта, кроме первого и трех конечных системных периодов.

Метод API Описание
POST customers/set Метод позволяет создавать/обновлять/удалять покупателя по одному или пакетно.
GET customers/list Метод для получения списка покупателей с возможностью фильтрации и постраничной выборки.

Транзакцияv3

Транзакция - это сущность которая описывает основные характеристики покупки (дата и сумма). Является дополнением для "покупателя".

Метод API Описание
POST transactions/set Метод позволяет создавать/удалять транзакции по одной или пакетно.
GET transactions/list Метод для получения списка транзакций с возможностью фильтрации.
POST transactions/comment Метод для добавления и изменения комментария существующей транзакции.

Задача

Задача должна обязательно иметь ответственного и дату (число и время). Также задача может быть связана со сделкой или контактом, но не обязательно, она может быть не связана ни с каким объектом. Самая основная сущность системы считается задачи.

Установить результат по закрытой задаче можно, используя метод POST notes/set

Метод API Описание
POST tasks/set Метод позволяет создавать новые задачи, а также обновлять информацию по уже существующим задачам
GET tasks/list Метод для получения списка уже созданных задач, с возможностью фильтрации данных и постраничной выборки.

Событие (примечание)

События представляют возможность добавлять дополнительную структурированную или не структурированную информацию к контакту или сделке. События бывают системные (звонки, СМС-сообщения и т.д.), созданные пользоваталем (примечания, файлы). События в карточках отображаются на ряду с задачами, т.к. не имеют ответственного и не прикреплены к дате.

Зачастую события используются виджетами для добавления дополнительной информации к сделке или контакту, когда не очень удобно использовать кастомные поля. События очень удобно использовать как лог, т.к. они всегда отображаются в хронологическом порядке в ленте и, если ваша информация привязана к дате (хронологии), то желательно использовать именно события.

Метод API Описание
POST notes/set Метод позволяет добавлять события по одному или пакетно, а также обновлять данные по уже существующим событиям.
GET notes/list Метод для получения списка событий с возможностью фильтрации и постраничной выборки.

Дополнительные поля

Метод позволяет создать и удалять дополнительные поля по одному или пакетно. Пользователь не сможет изменить их значения из интерфейса, но сможет фильтровать по ним и просматривать.

Создание и удаление поля также возможно из интерфейса.

Метод API Описание
POST fields/set Метод позволяет добавлять поля по одному или пакетно, а также удалять их.
Работа с кастомными полями В данном разделе вы познакомитесь с структурой заполнения кастомных полей.

Звонок

Звонки представляют возможность добавлять информацию к контакту или компании. События в карточках отображаются на ряду с задачами, т.к. не имеют ответственного и не прикреплены к дате. Если у события звонка есть ссылка на файл записи звонка, то в заметку будет добавлен плеер для проигрывания этой записи.

Метод API Описание
POST calls/add Метод позволяет добавлять звонки по одному или пакетно.

Неразобранное

Новая сущность системы. В состояние Неразобранное попадают все обращения из интеграций: почты, телефонии, форм для сайта, которые ещё не были обработаны пользователем (создана сделка или контакт). Пользователь может принять неразобранное - в данном случае будет создана сделка, а так же, при возможности, контакт и компания, если соответствующая информация есть в заявке, либо отклонить его.

Сейчас API работает в тестовом режиме, для получения доступа необходимо написать на Support@amocrm.ru с просьбой предоставить секретный ключ для использования API неразобранного.

Метод API Описание
GET unsorted/list Метод для получения списка неразобранного с возможностью фильтрации и постраничной выборки.
GET unsorted/get_all_summary Метод для получения аггрегированной информации о принятых и отклонённых заявках.
POST unsorted/accept Метод позволяет переводить из неразобранного в принятые заявки по одной или пакетно.
POST unsorted/decline Метод позволяет переводить из неразобранного в отклонённые заявки по одной или пакетно.
POST unsorted/add Метод позволяет добавлять неразобранное по одному или пакетно.

WebHooks

Каждый аккаунт в amoCRM имеет возможность сообщаться с веб-сервером. Эти "WebHooks" могут быть использованы для обновления информации о сделках в вашем магазине, отправки смс уведомлений или автоматизации ведения сделок. Каждый WebHook может быть настроен для определённой операции и событий. Администратор аккаунта может настроить хуки на странице Настройки->API.
Описание механизма веб-хуков можно найти на этой странице.

Методы для работы с настройками WebHooks аккаунта
Эти методы доступны только администратору аккаунта

Метод API Описание
GET webhooks/list Метод для получения списка WebHooks.
POST webhooks/subscribe Метод позволяет добавлять адреса для отправки WebHooks по одному или пакетно.
POST webhooks/unsubscribe Метод позволяет удалять адреса для отправки WebHooks по одному или пакетно.

Этапы продаж

Этапы продаж – это последовательность шагов, которые проходит потенциальный клиент (лид) по воронке продаж перед покупкой. В amoCRM можно создавать несколько воронок продаж в одном аккаунте и задавать свои этапы для отслеживания хода сделки в каждой воронке.
В amoCRM можно настроить до 10-и воронок в аккаунте. Каждая воронка может содержать до 100 этапов (включая успешный и неуспешный статусы). Настроить воронки и этапы продаж может администратор аккаунт на странице Настройки->Этапы продаж.

Методы для работы с настройками этапов продаж аккаунта
Эти методы доступны только администратору аккаунта

Метод API Описание
GET pipelines/list Метод для получения списка этапов продаж, сгруппированных по воронкам.
POST pipelines/set Метод позволяет добавлять или изменять воронки и этапы продаж по одному или пакетно.
POST pipelines/delete Метод позволяет удалять воронки продаж по одной или пакетно.

Цифровая воронка

Цифровая воронка позволяет настроить выполнение различных действий и автоматически изменять этапы сделок при наступлении определенных событий.
Настроить цифровую воронку может администратор аккаунта на странице сделок, нажав кнопку "Еще" -> Цифровая воронка.
Подробнее о настройке цифровой воронки можно узнать на этой странице.

Периоды покупателейv3

Периоды покупателей – это последовательность шагов, которые проходит потенциальный клиент (покупатель) по воронке покупателей перед покупкой. В amoCRM можно создавать свои периоды для отслеживания хода покупателя.
Воронка покупателей может содержать 10 периодов "до покупки" (включая "недавно купили", "покупка сегодня" и "не купили"). Настроить периоды может администратор аккаунта на странице Digital Pipeline (Цифровая воронка).

Методы для работы с настройками периодов аккаунта
Эти методы доступны только администратору аккаунта

Метод API Описание
GET customers_periods/list Метод для получения списка периодов.
POST customers_periods/set Метод позволяет добавлять, удалять или изменять периоды по одному или пакетно.

Виджеты

Виджет - это архив, содержащий набор файлов, которые будут подключаться в amoCRM всем аккаунтам, включившим виджет. Виджет позволяет получить дополнительный функционал, если необходимо:

  • Отображать дополнительные данные в интерфесах amoCRM. Для виджетов предусмотрены специальные области, где вы можете вывести информацию. Например, вывести статистику обращений по контакту из внутренней системы;
  • Взаимодействовать с пользователем, с введенными им данными. Вы можете подключать JS-скрипты практически в любом интерфейсе системы. Например, можно показывать вслывающую карточку при поступающем звонке;
  • Чтобы администратор аккаунта amoCRM ввел индивидуальные настройки для вашего сервиса. Например, ключ авторизации в вашем API.

Настроить виджеты может администратор аккаунт на странице Настройки->Интеграции.

Методы для работы с виджетами аккаунта
Эти методы доступны только администратору аккаунта

Метод API Описание
GET widgets/list Метод для получения списка виджетов.
POST widgets/set Метод позволяет включать или выключать виджеты по одному или пакетно.

Каталогиv3

Каталоги - это хранилище данных, элементы которого вы можете прикрепить к карточке.

Эти методы доступны только пользователям, у которые есть права на доступ к каталогам.

Метод API Описание
GET catalogs/list Метод для получения списка каталогов.
POST catalogs/set Метод позволяет создавать/переименновывать/удалять каталоги.

Элементы каталоговv3

Элементы каталогов - данные, которые хранятся в каталогах.

Эти методы доступны только пользователям, у которые есть права на доступ к каталогам.

Метод API Описание
GET catalog_elements/list Метод для получения элементов каталогов.
POST catalog_elements/set Метод позволяет создавать/переименновывать/удалять элементы каталогов.

Связиv3

Представленные ниже методы позволяют управлять связями между основными сущностями.

Метод API Описание
GET links/list Метод для получения связей.
POST links/set Метод для привязки/отвязки сущностей.

Элементыv3

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

Метод API Описание
POST elements/sync Метод для управления контактами, покупателями и транзакциями, а также связями между основными сущностями.

Коды ошибок

Распространенные коды ошибок можно найти на этой странице.