Download the PHP package andrei-mireichyk/amocrm-api-library without Composer

amoCRM API Library

В данном пакете представлен API клиент с поддержкой основных сущностей и авторизацией по протоколу OAuth 2.0 в amoCRM.

Оглавление

• Установка
• Начало работы
• Поддерживаемые методы и сервисы
• Обработка ошибок
• Фильтры
• Работа с Custom Fields сущностей
• Работа с тегами сущностей
• Константы
• Примеры

Установка

Установить библиотеку можно с помощью composer:

Начало работы и авторизация

Для начала использования вам необходимо создать объект бибилиотеки:

Так же предоставляется фабрика для создания объектов \AmoCRM\AmoCRM\Client\AmoCRMApiClientFactory. Для ее использования вам нужно реализовать интерфейс \AmoCRM\OAuth\OAuthConfigInterface и \AmoCRM\OAuth\OAuthServiceInterface

Затем необходимо создать объект (\League\OAuth2\Client\Token\AccessToken) Access токена из вашего хранилища токенов и установить его в API клиент.

Также необходимо установить домен аккаунта amoCRM в виде СУБДОМЕН.amocrm.(ru/com).

Вы можете установить функцию-callback на событие обновления Access токена, если хотите дополнительно обрабатывать новый токен (например сохранять его в хранилище токенов):

Отправить пользователя на страницу авторизации можно 2мя способами:

1. Отрисовав кнопку на сайт:

2. Отправив пользователя на страницу авторизации

Для получения Access Token можно использовать следующий код в обработчике, который будет находится по адресу, указаному в redirect_uri

Пример авторизации можно посмотреть в файле examples/get_token.php

Подход к работе с библиотекой

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

Модели и коллекции имеют методы и , методы возвращают представление объекта в виде массива и в виде данных, отправляемых в API.

Также для работы с коллекциями имеют следующие методы:

1. • добавляет модель в конец коллекции.
2. • добавляет модель в начало коллекции.
3. • возвращает массив моделей в коллекции.
4. • получение первой модели в коллекции.
5. • получение последней модели в коллекции.
6. • получение кол-ва элементов в коллекции.
7. • проверяет, что коллекция не пустая.
8. • получение модели по значению ключа.
9. • замена модели по значению ключа.

При работе с библиотекой необходимо не забывать о лимитах API amoCRM. Для оптимальной работы с данными лучше всего создавать/изменять за раз не более 50 сущностей в методах, где есть пакетная обработка.

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

Поддерживаемые методы и сервисы

Библиотека поддерживает большое количество методов API. Методы сгруппированы и объекты-сервисы. Получить объект сервиса можно вызвав необходимый метод у библиотеки, например:

В данный момент доступны следующие сервисы:

Для большинства сервисов есть базовый набор методов:

1. getOne - Получить 1 сущность

   1. id (int|string) - id сущности
   2. with (array) - массив параметров with, которые поддерживает модель сервиса
   3. Результатом выполнения будет модель сущности

2. get Получить несколько сущностей:

   1. filter (BaseEntityFilter) - фильтр для сущности
   2. with (array) - массив параметров with, которые поддерживает модель сервиса
   3. Результатом выполнения будет коллекция сущностей

3. addOne Создать одну сущность:

   1. model (BaseApiModel) - модель создаваемой сущности
   2. Результатом выполнения будет модель сущности

4. add Создать сущности пакетно:

   1. collection (BaseApiCollection) - коллекция моделей создаваемой сущности
   2. Результатом выполнения будет коллекция моделей сущности

5. updateOne Обновить одну сущность:

   1. model (BaseApiModel) - модель создаваемой сущности
   2. Результатом выполнения будет модель сущности

6. update Обновить сущности пакетно:

   1. collection (BaseApiCollection) - коллекция моделей создаваемой сущности
   2. Результатом выполнения будет коллекция моделей сущности
7. syncOne Синхронизировать одну модель с сервером:
   1. model (BaseApiModel) - коллекция моделей создаваемой сущности
   2. with (array) - массив параметров with, которые поддерживает модель сервиса
   3. Результатом выполнения будет коллекция моделей сущности

Не все методы доступны во всех сервисах. В случае их вызова будет выброшены Exception.

Некоторые сервисы имеют специфичные методы, ниже рассмотрим сервисы, которые имеют специфичные методы.

Методы доступные в сервисе :

1. getAuthorizeUrl получение ссылки на авторизация

   1. options (array)
      1. state (string) состояние приложения
   2. Результатом выполнения будет строка с ссылкой на авторизация приложения

2. getAccessTokenByCode получение аксес токена по коду авторизации

   1. code (string) код авторизации
   2. Результатом выполнения будет объект (AccessTokenInterface)

3. getAccessTokenByRefreshToken получение аксес токена по рефреш токену

   1. accessToken (AccessTokenInterface) объект аксес токена
   2. Результатом выполнения будет объект (AccessTokenInterface)

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

   1. domain (string)

5. setAccessTokenRefreshCallback установка callback, который будет вызван при обновлении аксес токена

   1. function (callable)

6. getOAuthButton установка callback, который будет вызван при обновлении аксес токена

   1. options (array)
      1. state (string) состояние приложения
      2. color (string)
      3. title (string)
      4. compact (bool)
      5. class_name (string)
      6. error_callback (string)
      7. mode (string)
   2. Результатом выполнения будет строка с HTML кодом кнопки авторизации
7. exchangeApiKey метод для обмена API ключа на код авторизации
   1. login - email пользователя, для которого обменивается API ключ
   2. apiKey - API ключ пользователя
   3. Код авторизации будет прислан на указанный в настройках приложения redirect_uri

Методы связей доступны в сервисах , , , :

1. link Привязать сущность

   1. model (BaseApiModel) - модель главной сущности
   2. links (LinksCollection|LinkModel) - коллекция или модель связи
   3. Результатом выполнения является коллекция связей (LinksCollection)

2. getLinks Получить связи сущности

   1. model (BaseApiModel) - модель главной сущности
   2. filter (LinksFilter) - фильтр для связей
   3. Результатом выполнения является коллекция связей (LinksCollection)
3. unlink Отвязать сущность
   1. model (BaseApiModel) - модель главной сущности
   2. links (LinksCollection|LinkModel) - коллекция или модель связи
   3. Результатом выполнения является bool значение

Методы удаления доступны в сервисах , , , , , , , :

1. delete

   1. model (BaseApiModel) - модель сущности
   2. Результатом выполнения является bool значение
2. deleteOne
   1. collection (BaseApiCollection) - коллекция моделей сущностей
   2. Результатом выполнения является bool значение

Методы доступные в сервисе :

1. setMode Смена режима покупателей (периодические покупки или сегментация). Если покупатели выключены - то они будут включены.
   1. mode (string) - тип режима (periodicity или segments)
   2. isEnabled (bool) - включен ли функционал покупателей, по-умолчанию - true
   3. Результатом выполнения является строка названия включенного режима или null в случае отключения функционала

Методы доступные в сервисе :

1. getByParentId Получение данных по ID родительской сущности
   1. parentId - ID родительской сущности
   2. filter (BaseEntityFilter) - фильтр
   3. with (array) - массив параметров with, которые поддерживает модель сервиса

Методы доступные в сервисе

1. getCurrent
   1. with (array) - массив параметров with, которые поддерживает модель сервиса
   2. Результатом выполнения является модель AccountModel

Методы доступные в сервисе

1. addOne Создать одну сущность:

   1. model (BaseApiModel) - модель создаваемой сущности
   2. Результатом выполнения будет модель сущности

2. add Создать сущности пакетно:

   1. collection (BaseApiCollection) - коллекция моделей создаваемой сущности
   2. Результатом выполнения будет коллекция моделей сущности

3. link

   1. model (BaseApiModel) - модель неразобранного
   2. body (array) - массив дополнительной информации для привязки
   3. Результатом выполнения будет модель LinkUnsortedModel

4. accept

   1. model (BaseApiModel) - модель неразобранного
   2. body (array) - массив дополнительной информации для принятия
   3. Результатом выполнения будет модель AcceptUnsortedModel

5. decline

   1. model (BaseApiModel) - модель неразобранного
   2. body (array) - массив дополнительной информации для отклонения
   3. Результатом выполнения будет модель DeclineUnsortedModel
6. summary
   1. filter (BaseEntityFilter) - фильтр для сущности
   2. Результатом выполнения будет модель UnsortedSummaryModel

Методы доступные в сервисе

1. subscribe

   1. model (WebhookModel) - модель вебхука
   2. Результатом выполнения является модель WebhookModel
2. unsubscribe
   1. model (WebhookModel) - модель вебхука
   2. Результатом выполнения является bool значение

Методы доступные в сервисе

1. install

   1. model (WidgetModel) - модель виджета
   2. Результатом выполнения является модель WidgetModel
2. uninstall
   1. model (WidgetModel) - модель виджета
   2. Результатом выполнения является модель WidgetModel

Методы доступные в сервисе

1. settings

   1. Результатом выполнения является модель ProductsSettingsModel
2. updateSettings
   1. model (ProductsSettingsModel) - модель виджета
   2. Результатом выполнения является модель ProductsSettingsModel

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

Вызов методов библиотеки может выбрасывать ошибки типа . В данные момент доступны следующие типы ошибок, они все наследуют AmoCRMApiException:

У выброшенных Exception есть следующие методы:

У ошибки типа AmoCRMApiErrorResponseException есть метод , который вернет ошибки валидации входящих данных.

Фильтры

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

Работа с дополнительными полями сущностей

Дополнительные поля доступны у сущностей следующих сервисов:

У моделей, который возвращаются у этих сервисов, поля можно получить через метод . На вызов данного метода возвращается объект или , если значений полей нет.

Внутри коллекции находятся модели значений полей, все модели наследуются от , но зависят от типа поля.

У моделей, наследующих доступны следующие методы:

1. , - получение/установка id поля
2. • получение типа поля
3. , - получение/установка кода поля
4. , - получение/установка названия поля
5. , - получение/установка коллекции значений

Так как некоторые поля могут иметь несколько значений, в свойстве values хранится именно коллекция значений типа . Моделями коллекции являются модели типа .

Схема отношений объектов:

Для разных типов полей мы уже подготовили разные модели и коллекции:

Namespace, в котором находятся модели значения -

Namespace, в котором находятся коллекции моделей значения -

Namespace, в котором находятся модели дополнительных полей -

Пример кода, как создать коллекцию значения полей сущности:

Чтобы удалить значения поля доступен специальный объект .

Передав этот объект, вы зануляете значение поля.

Пример:

Работа с тегами сущностей

Теги доступны как отдельный сервис . При создании данного сервиса, вы указываете тип сущности, с тегами которой вы будете работать. В данный момент доступны:

1. EntityTypesInterface::LEADS,
2. EntityTypesInterface::CONTACTS,
3. EntityTypesInterface::COMPANIES,
4. EntityTypesInterface::CUSTOMERS,

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

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

Пример добавления/изменения тегов у сущности:

или

Для удаления тегов в setTags можно передать в setTags специальный объект \AmoCRM\Collections\NullTagsCollection.

Пример удаления тегов у сущности:

Константы

Основные константы находятся в интерфейсе \AmoCRM\Helpers\EntityTypesInterface.

Также доступны константы в следующих классах/интерфейсах:

1. \AmoCRM\OAuth\AmoCRMOAuth::BUTTON_COLORS - доступные цвета для кнопки на сайт
2. \AmoCRM\Models\Unsorted\BaseUnsortedModel - константы для кодов категорий неразобранного
3. \AmoCRM\Models\CustomFields\BirthdayCustomFieldModel - константы для свойства remind у поля День Рождения
4. \AmoCRM\Models\Interfaces\CallInterface - константы статусов звонков
5. \AmoCRM\EntitiesServices\Interfaces\HasParentEntity - константы для ключей в запросах методов, у которых есть родительский сущность (в данный момент только notes)
6. \AmoCRM\Models\CustomFieldsValues\ValueModels\ItemsCustomFieldValueModel - константы для ключей значения поля Items
7. \AmoCRM\Models\Rights\RightModel - константы, связанные с правами
8. \AmoCRM\Models\AccountModel - константы для аргумента with для сервиса account
9. \AmoCRM\Models\TaskModel - константы для дефолтных типов задач
10. \AmoCRM\Models\NoteType\TargetingNote - константы поддерживаемых внешних сервисов для примечаний о таргетинге (добавляют DP)
11. \AmoCRM\Models\RoleModel - константы для аргумента with для сервиса roles
12. \AmoCRM\Models\Factories\NoteFactory - константы типов примечаний
13. \AmoCRM\Models\NoteType\MessageCashierNote - статусы примечания "Сообщение кассиру"
14. \AmoCRM\Models\LeadModel - константы для аргумента with для сервиса leads
15. \AmoCRM\Filters\Interfaces\HasOrderInterface - константы для сортировки
16. \AmoCRM\Models\EventModel - константы для аргумента with для сервиса events
17. \AmoCRM\Models\CustomFields\CustomFieldModel - константы типов полей
18. \AmoCRM\Models\Customers\CustomerModel - константы для аргумента with для сервиса customers
19. \AmoCRM\Models\ContactModel - константы для аргумента with для сервиса contacts
20. \AmoCRM\Models\CompanyModel - константы для аргумента with для сервиса companies

Работа в случае смены субдомена аккаунта

Одноразовые токены интеграций, расшифровка

Примеры

В рамках данного репозитория имеется папка examples с различными примерами.

Для их работы необходимо добавить в неё файл .env со следующим содержимым, указав ваши значения:

CLIENT_ID="UUID интеграци"
CLIENT_SECRET="Секретный ключ интеграции"
CLIENT_REDIRECT_URI="https://example.com/examples/get_token.php (Важно обратить внимание, что он должен содержать в себе точно тот адрес, который был указан при создании интеграции)"

Затем вы можете поднять локальный сервер командой composer serve. После конфигурацию необходимо перейти в браузере на страницу http://localhost:8181/examples/get_token.php для получения Access Token. Для получения доступа к вашему локальному серверу из вне можно использовать сервис ngrok.io.

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

License

MIT