Download the PHP package dedomorozoff/amocrm-api-php-v4 without Composer

amoCRM API PHP Wrapper (частично переделан для 4 версии api)

❗❗❗ Частично измененная версия библиотеки под 4 версию API.

• Изменены часть классов получения объектов сущностей, добавлен метод PATCH для редактирования уже существующей сущности.

• Добавлен класс DatabaseStorage для хранения токенов в базе данных.

  Для хранения токенов в базе данных требуется запустить файл migration.php или самостоятельно создать таблицу с названием tokens и с полями token_domain(VARCHAR), token_json(JSON), token_integration_code(VARCHAR). token_integration_code - уникальный идентификационный код интеграции, создан для того чтобы было возможно определять интеграции созданные на одном и то же домене. Сохранение и загрузка токенов в базу данных:

Простая обертка на PHP7+ для работы с REST API amoCRM v2 (версии 2) с авторизацией по протоколу oAuth 2.0 или по API-ключу пользователя, поддержкой AJAX-запросов к frontend-методам, троттлингом запросов к API, блокировкой одновременного обновления одной сущности и логированием запросов/ответов к API в файл.

Данная библиотека была создана для удовлетворения новых требований amoCRM, предъявляемых к публичным интеграциям:

Публичные интеграции должны использовать механизм авторизации oAuth 2.0, использование механизма API ключей не допускается. Требование с февраля 2020 года.

С 1 июля 2020 г. информация о API-ключе пользователя стала недоступна в интерфейсе amoCRM.

В настоящее время актуальной версией является REST API amoCRM v4 (версия 4) (запросы к API отправляются на /api/v4/).

Документация по REST API amoCRM v2

Документация по REST API v2 теперь недоступна на русскоязычной версии сайта amoCRM. На англоязычной версии сайта эта документация перенесена в раздел API V2 GENERAL METHODS.

Архив документации по REST API amoCRM v2 в формате HTML вынесен в самостоятельный репозиторий.
Ниже приведены ссылки на отдельные HTML-файлы этого архива:

• Аккаунт
• Авторизация
• Компании
• Контакты
• Сделки
• События
• Задачи
• Списки
• Элементы списков
• Неразобранное
• Webhooks
• Покупатели
• Дополнительные поля
• Виджеты
• Товары
• Воронки и этапы продаж
• Логирование звонков
• Уведомление о звонке
• Коды ошибок
• Ограничения и рекомендации

Содержание

• Требования
• Установка
• Авторизация
  • Авторизация по протоколу oAuth 2.0 (актуальный метод)
    • Первичная авторизация и обмен кода авторизации на access токен и refresh токен
    • Последующие авторизации
    • Хранение access и refresh токенов
      • Интерфейс TokenStorageInterface
      • Класс FileStorage
      • Использование собственного класса для сохранения токенов
    • Проверка наличия первичной авторизации
  • Авторизация по API-ключу пользователя (устаревший метод)
  • Одновременная авторизация в нескольких аккаунтах amoCRM
• Параметры настройки
• Работа с сущностями amoCRM
  • Список методов и констант моделей
    • Базовый класс моделей AmoObject
    • Класс AmoContact - модель контакта
    • Класс AmoCompany - модель компании
    • Класс AmoLead - модель сделки
    • Класс AmoTask - модель задачи
    • Класс AmoNote - модель события (примечания)
    • Класс AmoCatalog - модель списка (каталога)
    • Класс AmoCatalogElement - модель элемента списка (каталога)
    • Класс AmoIncomingLead - базовая модель заявки из неразобранного
      • Общие методы для работы с заявками из неразобранного
      • Класс AmoIncomingLeadForm - модель заявки из неразобранного при добавлении из веб-формы
      • Класс AmoIncomingLeadSip - модель заявки из неразобранного с типом входящий звонок
  • Методы для загрузки сущностей
  • Методы для пакетного сохранения сущностей
  • Методы для пакетного удаления сущностей
  • Методы для webhooks
  • Методы для неразобранного
  • Дополнительные методы
• Блокировка одновременного обновления одной сущности
• Троттлинг запросов к API
• Отладочный режим и логирование
• Обработка ошибок
• Примеры
  • Работа с контактами
  • Работа с компаниями
  • Работа со сделками
  • Работа с событиями
  • Работа с задачами
  • Работа со списками (каталогами)
  • Работа с элементами списков (каталогов)
  • Работа с webhooks
  • Работа с заявками из неразобранного
  • Поддержка AJAX-запросов к frontend-методам
  • Работа с несколькими поддоменами
  • Отладка и логирование
• UML-диаграмма классов
• Автор
• Лицензия

Требования

• PHP >= 7.0.
• Произвольный автозагрузчик классов, реализующий стандарт PSR-4.

Установка

Установка через composer:

или путем добавления:

в секцию require файла composer.json.

Авторизация

Авторизация по протоколу oAuth 2.0 (актуальный метод)

• static AmoAPI::oAuth2(string $subdomain, string $clientId, string $clientSecret, string $redirectUri, string $authCode = null) :array
  • $subdomain - поддомен или полный домен amoCRM;
  • $clientId - ID интеграции;
  • $clientSecret - секрет интеграции;
  • $redirectUri - URI перенаправления;
  • $authCode - код авторизации (временный ключ) для обмена на access токен и refresh токен.

Первичная авторизация и обмен кода авторизации на access токен и refresh токен

При первичной авторизации производится обмен кода авторизации authCode на access токен и refresh токен, которые сохраняются в хранилище токенов вместе с переданными значениями $clientId, $clientSecret и $redirectUri.

Последующие авторизации

После первичного обмена кода авторизации на access токен и refresh токен, при последующих авторизациях, достаточно передать только $subdomain - поддомен или полный домен amoCRM.

Получение нового access токена и refresh токена по истечении срока действия access токена происходит автоматически, когда на запрос к API amoCRM приходит ответ с HTTP-статусом 401 Unauthorized.

Хранение access и refresh токенов

Сохранение и загрузка токенов выполняется с помощью классов, реализующих интерфейс \AmoCRM\TokenStorage\TokenStorageInterface.

Интерфейс TokenStorageInterface

В интерфейсе \AmoCRM\TokenStorage\TokenStorageInterface определены три метода:

• save(array $tokens, string $domain) :void Сохраняет параметры авторизации и токены.
  • $tokens - ассоциативный массив параметров авторизации и токенов:
    [ 'access_token' => '...', 'refresh_token' => '...', 'client_id' => '...', 'client_secret' => '...', 'redirect_uri'=> '...' ];
  • $domain - полный домен amoCRM (например, testsubdomain.amocrm.ru).
• load(string $domain) :?array Загружает параметры авторизации и токены и возвращает их. Метод должен возвращать null, когда нет сохраненных токенов.
  • $domain - полный домен amoCRM.
• hasTokens(string $domain) :bool Проверяет существуют ли токены для заданного домена amoCRM, то есть была ли выполнена первичная авторизация.
  • $domain - полный домен amoCRM.

Класс FileStorage

По умолчанию для сохранения и загрузки токенов используется класс \AmoCRM\TokenStorage\FileStorage, реализующий интерфейс \AmoCRM\TokenStorage\TokenStorageInterface. Класс хранит токены в JSON-файлах, с именами, соответствующими именам доменов amoCRM (например, testsubdomain.amocrm.ru.json).

В параметрах, передаваемых конструктору класса, можно указать каталог для хранения файлов токенов:

• __construct(string $storageFolder = '') Конструктор класса.
  • $storageFolder - каталог для хранения файлов токенов. Может быть задан абсолютный путь или путь относительно текущего рабочего каталога. Если передана пустая строка, то создается каталог по умолчанию - 'tokens'.

При возникновении ошибок выбрасывается исключение класса \AmoCRM\TokenStorage\TokenStorageException.

Использование собственного класса для сохранения токенов

Пример использования собственного класса для сохранения токенов в базе данных:

Пример класса \AmoCRM\TokenStorage\DatabaseStorage:

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

Чтобы проверить, происходила ли первичная авторизация для нужного поддомена amoCRM, можно воспользоваться методом hasTokens() интерфейса \AmoCRM\TokenStorage\TokenStorageInterface:

Авторизация по API-ключу пользователя (устаревший метод)

С 1 июля 2020 г. информация о API-ключе пользователя стала недоступна в интерфейсе amoCRM.

• static AmoAPI::oauth(string $login, string $hash, string $subdomain) :array
  • $login - логин пользователя;
  • $hash - API-ключ пользователя;
  • $subdomain - поддомен или полный домен amoCRM.

Пример авторизации по API-ключу пользователя.

Одновременная авторизация в нескольких аккаунтах amoCRM

Библиотека позволяет одновременно работать с несколькими поддоменами (аккаунтами) amoCRM. Для этого необходимо последовательно выполнить авторизацию в каждом их поддоменов.

Параметры настройки

Все параметры настройки библиотеки устанавливаются через статические свойства класса AmoAPI.

Работа с сущностями amoCRM

Работа с сущностями amoCRM строится с помощью:

• методов классов-моделей:
  • AmoContact - модель контакта;
  • AmoCompany - модель компании;
  • AmoLead - модель сделки;
  • AmoNote - модель события (примечания);
  • AmoTask - модель задачи;
  • AmoCatalog - модель списка (каталога);
  • AmoCatalogElement - модель элемента списка (каталога);
  • AmoIncomingLead - абстрактная базовая модель заявки из неразобранного;
  • AmoIncomingLeadForm - модель заявки из неразобранного при добавлении заявки из веб-формы;
  • AmoIncomingLeadSip - модель заявки из неразобранного с типом входящий звонок.
• дополнительных статических методов класса AmoAPI;
• параметров моделей, доступных через публичные свойства объектов классов-моделей.

Список методов и констант моделей

Базовый класс моделей AmoObject

Абстрактный базовый класс всех моделей - AmoObject содержит следующие общие методы:

• __construct(array $params = [], string $subdomain = null) Создает новый объект модели и заполняет ее.
  • $params - параметры модели;
  • $subdomain - поддомен или полный домен amoCRM. Если null, то используется поддомен последней авторизации.
• fillById(int|string $id, array $params = []) :AmoObject Заполняет модель данными по ID сущности.
  • $id - ID сущности;
  • $params - дополнительные параметры, передаваемые в GET-запросе к amoCRM.
• getParams() :array Возвращает все параметры модели.
• getCustomFields(array|int $ids) :array Возвращает дополнительные поля по ID полей.
  • $ids - ID поля или массив ID полей.
• getCustomFieldValueById(int $id, bool $returnFirst = true, string $returnValue = 'value') Возвращает значение дополнительного поля по ID поля.
  • $i - ID поля;
  • $returnFirst - вернуть только первое значение из списка значений;
  • $returnValue - имя параметра, значение которого возвращается (value, enum, subtype).
• setCustomFields(array $params) :AmoObject Устанавливает значения дополнительных полей.
  • $params - массив значений дополнительных полей.
• addTags(array|string $tags) :AmoObject Добавляет теги.
  • $tags - тег или массив тегов.
• delTags(array|string $tags) :AmoObject Удаляет теги.
  • $tags - тег или массив тегов.
• save(bool $returnResponse = false) Сохраняет объект модели в amoCRM и возвращает ID сущности.
  • $returnResponse - вернуть ответ сервера вместо ID сущности.

Константы, определяющие типы привязываемых сущностей:

• CONTACT_TYPE = 1 - контакт;
• LEAD_TYPE = 2 - сделка;
• COMPANY_TYPE = 3 - компания;
• TASK_TYPE = 4 - задача;
• CUSTOMER_TYPE = 12 - покупатель.

Класс AmoContact - модель контакта

• addLeads(array|int $id) Привязывает сделки по ID.
• addCustomers(array|int $id) Привязывает покупателей по ID.
• addCompany(int $id) Привязывает компанию по ID.
• getPhone() Возвращает первый телефон контакта.
• getEmail() Возвращает первый e-mail контакта.

Класс AmoCompany - модель компании

• addLeads(array|int $id) Привязывает сделки по ID.
• addContacts(array|int $id) Привязывает контакты по ID.
• addCustomers(array|int $id) Привязывает покупателей по ID.
• getPhone() Возвращает первый телефон компании.
• getEmail() Возвращает первый e-mail компании.

Класс AmoLead - модель сделки

⚠   Для заявок из неразобранного существуют специальные методы.

• addContacts(array|int $id) Привязывает контакты по ID контакта(ов) (не более 40 контактов у одной сделки).
• removeContacts(array|int $id) Отвязывает контакты по ID контакта(ов).
• addCompany(int $id) Привязывает компанию по ID компании.
• removeCompany(int $id) Отвязывает компанию по ID компании.
• setCatalogElements(array $catalogElements) Устанавливает элементы списков (каталогов) по ID списков.

Класс AmoTask - модель задачи

• addContact(int $id) Привязывает контакт по ID.
• addLead(int $id) Привязывает сделку по ID.

Константы класса, определяющие типы задач:

• CALL_TASKTYPE = 1 - звонок;
• MEET_TASKTYPE = 2 - встреча;
• MAIL_TASKTYPE = 3 - написать письмо.

Класс AmoNote - модель события (примечания)

Константы класса, определяющие типы событий:

• LEAD_CREATED_NOTETYPE = 1 - создание сделки;
• CONTACT_CREATED_NOTETYPE = 2 - создание контакта;
• LEAD_STATUS_CHANGED_NOTETYPE = 3 - изменение статуса сделки;
• COMMON_NOTETYPE = 4 - обычное примечание;
• COMPANY_CREATED_NOTETYPE = 12 - создание компании;
• TASK_RESULT_NOTETYPE = 13 результат по задаче;
• SYSTEM_NOTETYPE = 25 - системное сообщение;
• SMS_IN_NOTETYPE = 102 - входящее SMS сообщение;
• SMS_OUT_NOTETYPE = 103 - исходящее SMS сообщение.

Класс AmoCatalog - модель списка (каталога)

Класс AmoCatalog не имеет собственных специфических методов.

Класс AmoCatalogElement - модель элемента списка (каталога)

Класс AmoCatalogElement не имеет собственных специфических методов.

Класс AmoIncomingLead - базовая модель заявки из неразобранного

Работа с заявками из неразобранного существенно отличается от работы с другими сущностями amoCRM.
Согласно официальной документации:

Изначально неразобранное было в отдельном хранилище и являлось отдельной сущностью именно поэтому до сих пор в интерфейсах amoCRM и в API есть особенности которые отличают поведение сделки в статусе Неразобранное от сделок в других статусах.

⚠   Поэтому для моделей заявок из неразобранного не работают следующие методы класса AmoObject:

• fillById();
• getCustomFields();
• getCustomFieldValueById();
• setCustomFields();
• addTags();
• delTags();
• AmoAPI::saveObjects();
• AmoAPI::saveObjectsWithLimit().

Общие методы для работы с заявками из неразобранного

Абстрактный базовый класс модели заявки из неразобранного - AmoIncomingLead содержит следующие методы:

• fillByUid(int|string $uid, array $params = []) :AmoObject Заполняет модель заявки данными по UID заявки.
  • $uid - UID сущности;
  • $params - дополнительные параметры, передаваемые в GET-запросе к amoCRM.
• setIncomingLeadInfo(array $params) :AmoIncomingLead Устанавливает параметры заявки из неразобранного.
  • $params - параметры неразобранного.
• addIncomingLead(AmoLead|array $lead) :AmoIncomingLeadSip Добавляет параметры сделки.
  • $lead - объект класса AmoLead или массив параметров сделки.
• addIncomingContact(AmoContact|array $contact) :AmoIncomingLead Добавляет параметры контакта.
  • $contact - объект класса AmoContact или массив параметров контакта.
• addIncomingCompany(AmoCompany|array $company) :AmoIncomingLead Добавляет параметры компании.
  • $company - объект класса AmoCompany или массив параметров компании.
• save(bool $returnResponse = false) Добавляет новую заявку в неразобранное и возвращает массив, содержащий UID заявки.
  • $returnResponse - вернуть ответ сервера вместо UID.

Статические методы для пакетного добавления заявок в amoCRM, а также для принятия или отклонения неразобранных заявок находятся в классе AmoAPI.

Класс AmoIncomingLeadForm - модель заявки из неразобранного при добавлении из веб-формы

Дочерний класс AmoIncomingLeadForm не имеет собственных специфических методов.

Класс AmoIncomingLeadSip - модель заявки из неразобранного с типом входящий звонок

Дочерний класс AmoIncomingLeadSip не имеет собственных специфических методов.

Методы для загрузки сущностей

Класс AmoAPI содержит следующие общие статические методы для загрузки сущностей:

• static getAll<Entities> (array $params, bool $returnResponse = false, string $subdomain = null) :\Generator Загружает ВСЕ сущности заданного типа <Entities> c возможностью фильтрации.
  Возвращает объект типа \Generator для последующей выборки параметров сущностей.
  • <Entities>:
    • Contacts
    • Companies
    • Leads
    • Tasks
    • Notes
    • CatalogElements
    • IncomingLeads
  • $params - параметры фильтрации;
  • $returnResponse - возвращать полный ответ сервера amoCRM вместо массива параметров сущностей;
  • $subdomain - поддомен или полный домен amoCRM. Если null, то используется поддомен последней выполненной авторизации.
• static get<Entities>(array $params, bool $returnResponse = false, string $subdomain = null) :?array
  Загружает сущности заданного типа <Entities> c возможностью фильтрации и постраничной выборки.
  Возвращает массив параметров сущностей для заполнения моделей или null.
  • <Entities>:
    • Contacts
    • Companies
    • Leads
    • Tasks
    • Notes
    • Webhooks
    • Widgets
    • IncomingLeads
    • IncomingLeadsSummary
    • Pipelines
    • Catalogs
    • CatalogElements
  • $params - параметры фильтрации и постраничной выборки;
  • $returnResponse - возвращать полный ответ сервера amoCRM вместо массива параметров сущностей;
  • $subdomain - поддомен или полный домен amoCRM. Если null, то используется поддомен последней выполненной авторизации.

Методы для пакетного сохранения сущностей

Класс AmoAPI содержит статические методы для пакетного сохранения (добавления или обновления) за один запрос до 500 сущностей различного типа для одного поддомена amoCRM.

Согласно официальной документации:

Максимальное кол-во создаваемых/изменяем сущностей не более 500, для более оптимальной работы интеграции и избежания ошибок, рекомендуется не более 250. В случае получения 504 ошибки рекомендуется уменьшить количество передаваемых сущностей в запросе и повторить запрос.

• static saveObjects(array $amoObjects, bool $returnResponses = false, string $subdomain = null) :array
  Добавляет или обновляет сущности в amoCRM. Возвращает массив параметров сущностей.
  • $amoObjects Массив объектов классов-моделей (не более 500 объектов одного типа): AmoContact, AmoCompany,...;
  • $returnResponses - возвращать массив ответов сервера amoCRM вместо массива параметров сущностей;
  • $subdomain - поддомен или полный домен amoCRM. Если null, то используется поддомен последней выполненной авторизации.
• static saveObjectsWithLimit(array $amoObjects, bool $returnResponses = false, string $subdomain = null, $limit = 250) :array
  Добавляет или обновляет сущности в amoCRM с ограничением на число сущностей в одном запросе к API. Возвращает массив параметров сущностей.
  • $amoObjects Массив объектов классов-моделей: AmoContact, AmoCompany,...;
  • $returnResponses - возвращать массив ответов сервера amoCRM вместо массива параметров сущностей;
  • $subdomain - поддомен или полный домен amoCRM. Если null, то используется поддомен последней выполненной авторизации;
  • $limit - максимальное число сущностей в одном запросе к API.

Методы для пакетного удаления сущностей

Класс AmoAPI содержит статический метод для пакетного удаления списков и элементов списков:

• static delteObjects(array $amoObjects, bool $returnResponses = false, string $subdomain = null) :array
  Удаляет сущности в amoCRM. Возвращает пустой массив параметров сущностей.
  • $amoObjects Массив объектов классов-моделей: AmoCatalog или AmoCatalogElement;
  • $returnResponses - возвращать массив ответов сервера amoCRM вместо пустого массива параметров сущностей;
  • $subdomain - поддомен или полный домен amoCRM. Если null, то используется поддомен последней выполненной авторизации.

Методы для webhooks

Класс AmoAPI содержит статические методы для добавления и удаления webhooks:

• static addWebhooks(array $params, bool $returnResponse = false, string $subdomain = null) :array
  Добавляет один webhook или несколько webhooks (не более 100).
  • params - параметры webhook или массив параметров webhooks;
  • $returnResponse - возвращать массив ответов сервера amoCRM вместо массива параметров webhook;
  • $subdomain - поддомен или полный домен amoCRM. Если null, то используется поддомен последней выполненной авторизации.
• static deleteWebhooks(array $params, bool $returnResponse = false, string $subdomain = null) :array
  Удаляет один webhook или несколько webhooks (не более 100).
  • params - параметры webhook или массив параметров webhooks;
  • $returnResponse - возвращать массив ответов сервера amoCRM вместо массива параметров webhook;
  • $subdomain - поддомен или полный домен amoCRM. Если null, то используется поддомен последней выполненной авторизации.

Методы для неразобранного

Класс AmoAPI содержит следующие статические методы для работы с заявками из неразобранного:

• static saveIncomingObjects(AmoIncomingLeadForm|AmoIncomingLeadSip|array $amoObjects, bool $returnResponses = false, string $subdomain = null) :array
  Пакетно добавляет заявки в неразобранное. Возвращает массив параметров UID неразобранного.
  • $amoObjects - объект классов-моделей AmoIncomingLeadForm или AmoIncomingLeadSip или массив этих объектов;
  • $returnResponses - возвращать массив ответов сервера amoCRM вместо массива UID;
  • $subdomain - поддомен или полный домен amoCRM. Если null, то используется поддомен последней выполненной авторизации.
• static saveIncomingObjectsWithLimit(AmoIncomingLeadForm|AmoIncomingLeadSip|array $amoObjects, bool $returnResponses = false, string $subdomain = null, $limit = 250) :array
  Пакетно добавляет заявки в неразобранное с ограничением на число заявок в одном запросе к API. Возвращает массив UID неразобранного.
  • $amoObjects - объект классов-моделей AmoIncomingLeadForm или AmoIncomingLeadSip или массив этих объектов;
  • $returnResponses - возвращать массив ответов сервера amoCRM вместо массива UID;
  • $subdomain - поддомен или полный домен amoCRM. Если null, то используется поддомен последней выполненной авторизации;
  • $limit - максимальное число заявок в одном запросе к API.
• static acceptIncomingLeads(array $params, bool $returnResponse = false, $subdomain = null) :array Принимает неразобранные заявки.
  • params - параметры заявок;
  • $returnResponse - возвращать ответ сервера amoCRM вместо массива параметров принятой заявки;
  • $subdomain - поддомен или полный домен amoCRM. Если null, то используется поддомен последней выполненной авторизации.
• static declineIncomingLeads(array $params, bool $returnResponse = false, $subdomain = null) :array Отклоняет неразобранные заявки.
  • params - параметры заявок;
  • $returnResponse - возвращать ответ сервера amoCRM вместо массива параметров отклоненной заявки;
  • $subdomain - поддомен или полный домен amoCRM. Если null, то используется поддомен последней выполненной авторизации.

Дополнительные методы

Дополнительные статические методы класса AmoAPI:

• static getAccount(string $with = '', string $subdomain = null) :array
  Возвращает информацию об аккаунте amoCRM.
  • $with - Разделенный запятыми список возвращаемых дополнительных параметров аккаунта, включающий:
    • custom_fields - дополнительные поля сущностей;
    • users - пользователи;
    • pipelines - воронки;
    • groups - группы пользователей;
    • note_types - типы событий (примечаний);
    • task_types - типы задач.
  • $subdomain - поддомен или полный домен amoCRM. Если null, то используется поддомен последней выполненной авторизации.
• static getAccountDomain(string $subdomain = null) :array
  Возвращает информацию о домене аккаунта amoCRM при авторизации по протоколу oAuth2.0.
  • $subdomain - поддомен или полный домен amoCRM. Если null, то используется поддомен последней выполненной авторизации.
• static getLastResponse(bool $unescapeUnicode = true) :?string
  Возвращает последний ответ сервера amoCRM в сыром виде.
  • $unescapeUnicode - Декодировать символы UTF-8 \uXXXX в ответе сервера.
• static request(string $query, string $type = 'GET', array $params = [], string $subdomain = null) :?array Позволяет выполнить RAW запрос к API amoCRM.
  • $query - путь в URL запроса;
  • $type - метод запроса 'GET', 'POST' или 'AJAX';
  • $params - параметры запроса;
  • $subdomain - поддомен или полный домен amoCRM. Если null, то используется поддомен последней авторизации.
• static getAmoDomain(string $subdomain) :string
  Возвращает полное имя домена amoCRM.
  • $subdomain - поддомен или полный домен amoCRM.

Блокировка одновременного обновления одной сущности

При одновременном обновлении одной и той же сущности (сделки, контакта, компании и т.д. с одинаковым ID) в разных процессах или потоках исполнения в API amoCRM может возникать ошибка "Last modified date is older than in database" из-за передаваемого вместе с запросом на обновление значения updated_at сущностей.

Для предотвращения возникновения данной ошибки в методе save() реализован механизм блокировки одновременного обновления одной сущности. До окончания обновления сущности в первом по времени запущенном процессе (потоке исполнения), то есть до получения ответа от API amoCRM, другие процессы, конкурирующие за обновление той же сущности, приостанавливаются и предпринимают повторные попытки выполнить обновление сущности каждые AmoAPI::$lockEntityTimeout секунд с максимально допустимым числом попыток AmoAPI::$lockEntityAttempts.

Троттлинг запросов к API

Для предотвращения превышения максимально допустимого числа запросов к API amoCRM (не более 7 запросов в секунду) в рамках одного процесса или потока исполнения в библиотеке реализован простой алгоритм троттлинга запросов, основанный на вычислении времени, прошедшего с момента отправки последнего запроса к API, и приостановке процесса до истечения 1/AmoAPI::$throttle секунд.

Отладочный режим и логирование

При включении отладочного режима AmoAPI::$debug = true информация о каждом запросе/ответе к API amoCRM выводится в STDOUT.

Для логирования каждого запроса/ответа к API amoCRM может быть использован произвольный класс-логгер, реализующий стандарт PSR-3, или простейший класс-логгер AmoAPIDebugLogger. Объект класса-логгера устанавливается в свойстве AmoAPI::$debugLogger. Логирование выполняется независимо от состояния отладочного режима AmoAPI::$debug. При каждом запросе/ответе к API в классе-логгере вызывается метод debug().

В конструктор класса AmoAPIDebugLogger может быть передано имя лог-файла:

• __construct(string $logFile = 'logs/debug.log')
  • $logFile - лог-файл.

Обработка ошибок

При возникновении ошибок выбрасывается исключение с объектом класса \AmoCRM\AmoAPIException.
Класс-исключение AmoAPIException содержит следующие вспомогательные методы:

• getErrors() :array Возвращает массив сообщений об ошибках (errors) из ответа сервера amoCRM;
• getItems() :array Возвращает массив параметров сущностей (items) из ответа сервера amoCRM.

Примеры

Работа с контактами

Работа с компаниями

Работа со сделками

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

Работа с событиями

Работа с задачами

Работа со списками (каталогами)

Работа с элементами списков (каталогов)

Работа с webhooks

Работа с заявками из неразобранного

Работа с заявками из неразобранного существенно отличается от работы с другими сущностями amoCRM.
Согласно официальной документации:

Изначально неразобранное было в отдельном хранилище и являлось отдельной сущностью именно поэтому до сих пор в интерфейсах amoCRM и в API есть особенности которые отличают поведение сделки в статусе Неразобранное от сделок в других статусах.

Пример работы с заявками из неразобранного при добавлении из веб-формы.

Поддержка AJAX-запросов к frontend-методам

Метод \AmoCRM\AmoAPI::request() позволяет выполнять AJAX-запросы к frontend-методам.

`

Пример ответа (фрагмент):

Работа с несколькими поддоменами

Отладка и логирование

UML-диаграмма классов

Автор

© 2019-2021 andrey-tech

Лицензия

Данная библиотека распространяется на условиях лицензии MIT.