Расширяйте возможности с API

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

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

Также вы можете воспользоваться консолью и пробовать работать с API и тестировать запросы через независимый сервис.

Что такое виджет?

Если вам необходимо просто обмениваться данными между amoCRM и внешней системой, то вы можете использовать REST API. Через него вы можете удаленно получать, добавлять и обновлять данные в amoCRM.

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

Виджет - это набор настроек, JS и PHP-файлов, которые могут быть подключены в любой аккаунт amoCRM, через включение виджета клиентом.

Примеры использования виджетов из жизни:

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

Словарь amoCRM

Термин Значение
Виджет/ Add-on Дополнение к системе, которое может быть включено и настроено пользователем для своего аккаунта с целью расширения функций amoCRM. Может содержать JS-файл, файл настроек, php-файл, изображения, используемые в работе дополнения.
Языки/Локализация amoCRM переведена на два языка: английский (amocrm.com) и русский (amocrm.ru). Вы можете публиковать виджеты на обоих языках явно указав это в манифесте. Не забудьте также сделать перевод и учесть формат времени
Манифест Файл, загружаемый вместе с виджетом, содержащий описание и настройки виджета
Настройки виджета При установке некоторые виджеты требуют ввода настроек, к примеру, название аккаунта во внешней системе, параметры авторизации в ней, настройки полей и т.д.
Аккаунт Учетная запись компании в amoCRM, имеющая собственные платежные реквизиты, биллинговую информацию, собственные данные и список пользователей, которым разрешен доступ к этим данным. Каждый аккаунт имеет свой субдомен в системе, например, company.amocrm.ru

Общие правила работы с API

Все общение с API происходит в зашифрованном виде по протоколу SSL. Это значит что все ссылки к API должны содержать протокол HTTPS. Особенно важно помнить это при обращении через JS, если вы обращаетесь к каким-то сторонним ресурсам, к примеру, обращаетесь к WEB-сокету. Внутри системы пользователь всегда находится в защищенном соединении и попытка обратится к HTTP картинке будет заблокирована или браузер пользователя выдаст ему предупреждение.

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

Все запросы необходимо производить не на общий домен http://www.amocrm.ru, а на точный адрес вашего аккаунта, например, https://company.amocrm.ru или https://example.amocrm.ru.

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

В случае превышения количества запросов - будет возвращаться ошибка HTTP 429, при многократном нарушении ограничений, аккаунт блокируется и на любой запрос в API будет возвращаться ошибка HTTP 403

В случае окончания подписки, доступ к данным через API будет закрыт через 30 дней после окончания подписки. В ответ на запросы сервер будет возвращать HTTP код 402.

Поддерживаемые протоколы

Для работы с нашим API необходима поддержка одного из следующих криптографических протоколов: TLS 1.1, TLS 1.2
Рекомендуемой версией является TLS 1.2

Начиная с 16.11.2016 мы полностью отказываемся от поддержки протокола SSLv3, в связи с тем, что данный протокол считается уязвивым.

Библиотека cURL поддерживает протокол TLS 1.1/1.2, начиная с версии 7.34.0. В параметрах сеанса cURL можно явно указать версию протокола:

  1. $curl=curl_init(); #Сохраняем дескриптор сеанса cURL
  2. curl_setopt($curl, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1_2);