PHPackages                             andrei-mireichyk/amocrm-api-library - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. andrei-mireichyk/amocrm-api-library

ActiveLibrary[Authentication & Authorization](/categories/authentication)

andrei-mireichyk/amocrm-api-library
===================================

amoCRM API Client

0.3.11(5y ago)016MITPHPPHP >=7.1

Since May 20Pushed 5y agoCompare

[ Source](https://github.com/AndreiMireichyk/amocrm-api-php)[ Packagist](https://packagist.org/packages/andrei-mireichyk/amocrm-api-library)[ RSS](/packages/andrei-mireichyk-amocrm-api-library/feed)WikiDiscussions master Synced today

READMEChangelog (1)Dependencies (9)Versions (25)Used By (0)

[![amoCRM API Library](.github/logo.png?raw=true)](.github/logo.png?raw=true)

amoCRM API Library
==================

[](#amocrm-api-library)

[![Latest Version](https://camo.githubusercontent.com/aacba822522da46cf22410750dea0840b47c472e1cd5a925e0227642c1f1a39c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f72656c656173652f616d6f63726d2f616d6f63726d2d6170692d706870)](https://github.com/amocrm/amocrm-api-php/releases)[![Build Status](https://camo.githubusercontent.com/475bb003473371c313ba278f987b550fc7401f76b2304317ab87185ec4ae8946/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f616d6f63726d2f616d6f63726d2d6170692d706870)](https://travis-ci.org/github/amocrm/amocrm-api-php/)[![Total Downloads](https://camo.githubusercontent.com/75eb50c81c7b618ae6de7490a65e1dc35b045fbd9f9d811c95fc132cb589cad6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f616d6f63726d2f616d6f63726d2d6170692d6c6962726172792e737667)](https://packagist.org/packages/amocrm/amocrm-api-library)

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

Оглавление
----------

[](#оглавление)

- [Установка](#%D1%83%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B0)
- [Начало работы](#%D0%BD%D0%B0%D1%87%D0%B0%D0%BB%D0%BE-%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D1%8B-%D0%B8-%D0%B0%D0%B2%D1%82%D0%BE%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F)
- [Поддерживаемые методы и сервисы](#%D0%BF%D0%BE%D0%B4%D0%B4%D0%B5%D1%80%D0%B6%D0%B8%D0%B2%D0%B0%D0%B5%D0%BC%D1%8B%D0%B5-%D0%BC%D0%B5%D1%82%D0%BE%D0%B4%D1%8B-%D0%B8-%D1%81%D0%B5%D1%80%D0%B2%D0%B8%D1%81%D1%8B)
- [Обработка ошибок](#%D0%BF%D0%BE%D0%B4%D0%B4%D0%B5%D1%80%D0%B6%D0%B8%D0%B2%D0%B0%D0%B5%D0%BC%D1%8B%D0%B5-%D0%BC%D0%B5%D1%82%D0%BE%D0%B4%D1%8B-%D0%B8-%D1%81%D0%B5%D1%80%D0%B2%D0%B8%D1%81%D1%8B)
- [Фильтры](#%D0%A4%D0%B8%D0%BB%D1%8C%D1%82%D1%80%D1%8B)
- [Работа с Custom Fields сущностей](#%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B0-%D1%81-%D0%B4%D0%BE%D0%BF%D0%BE%D0%BB%D0%BD%D0%B8%D1%82%D0%B5%D0%BB%D1%8C%D0%BD%D1%8B%D0%BC%D0%B8-%D0%BF%D0%BE%D0%BB%D1%8F%D0%BC%D0%B8-%D1%81%D1%83%D1%89%D0%BD%D0%BE%D1%81%D1%82%D0%B5%D0%B9)
- [Работа с тегами сущностей](#%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B0-%D1%81-%D1%82%D0%B5%D0%B3%D0%B0%D0%BC%D0%B8-%D1%81%D1%83%D1%89%D0%BD%D0%BE%D1%81%D1%82%D0%B5%D0%B9)
- [Константы](#%D0%BA%D0%BE%D0%BD%D1%81%D1%82%D0%B0%D0%BD%D1%82%D1%8B)
- [Примеры](#%D0%BF%D1%80%D0%B8%D0%BC%D0%B5%D1%80%D1%8B)

Установка
---------

[](#установка)

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

```
composer require amocrm/amocrm-api-library

```

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

[](#начало-работы-и-авторизация)

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

```
$apiClient = new \AmoCRM\Client\AmoCRMApiClient($clientId, $clientSecret, $redirectUri);
```

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

```
$apiClientFactory = new \AmoCRM\AmoCRM\Client\AmoCRMApiClientFactory($oAuthConfig, $oAuthService);
$apiClient = $apiClientFactory->make();
```

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

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

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

```
$apiClient->setAccessToken($accessToken)
        ->setAccountBaseDomain($accessToken->getValues()['baseDomain'])
        ->onAccessTokenRefresh(
            function (\League\OAuth2\Client\Token\AccessTokenInterface $accessToken, string $baseDomain) {
                saveToken(
                    [
                        'accessToken' => $accessToken->getToken(),
                        'refreshToken' => $accessToken->getRefreshToken(),
                        'expires' => $accessToken->getExpires(),
                        'baseDomain' => $baseDomain,
                    ]
                );
            });
```

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

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

```
$apiClient->getOAuthClient()->getOAuthButton(
            [
                'title' => 'Установить интеграцию',
                'compact' => true,
                'class_name' => 'className',
                'color' => 'default',
                'error_callback' => 'handleOauthError',
                'state' => $state,
            ]
        );
```

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

```
$authorizationUrl = $apiClient->getOAuthClient()->getAuthorizeUrl([
            'state' => $state,
            'mode' => 'post_message', //post_message - редирект произойдет в открытом окне, popup - редирект произойдет в окне родителе
        ]);

header('Location: ' . $authorizationUrl);
```

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

```
$accessToken = $apiClient->getOAuthClient()->getAccessTokenByCode($_GET['code']);
```

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

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

[](#подход-к-работе-с-библиотекой)

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

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

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

1. `add(BaseApiModel $model): self` - добавляет модель в конец коллекции.
2. `prepend(BaseApiModel $value): self` - добавляет модель в начало коллекции.
3. `all(): array` - возвращает массив моделей в коллекции.
4. `first(): ?BaseApiModel` - получение первой модели в коллекции.
5. `last(): ?BaseApiModel` - получение последней модели в коллекции.
6. `count(): int` - получение кол-ва элементов в коллекции.
7. `isEmpty(): bool` - проверяет, что коллекция не пустая.
8. `getBy($key, $value): ?BaseApiModel` - получение модели по значению ключа.
9. `replaceBy($key, $value, BaseApiModel $replacement): void` - замена модели по значению ключа.

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

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

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

[](#поддерживаемые-методы-и-сервисы)

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

```
$leadsService = $apiClient->leads();
```

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

СервисЦель сервисаnotesПримечание сущностиtagsТеги сущностейtasksЗадачиleadsСделкиcontactsКонтактыcompaniesКомпанииcatalogsКаталогиcatalogElementsЭлементы каталоговcustomFieldsПользовательские поляcustomFieldGroupsГруппы пользовательских полейaccountИнформация об аккаунтеrolesРоли пользователейusersРоли юзеровcustomersSegmentsСегменты покупателейeventsСписок событийwebhooksВебхукиunsortedНеразобранноеpipelinesВоронки сделокstatusesСтатусы сделокwidgetsВиджетыlossReasonПричины отказаtransactionsПокупки покупателейcustomersПокупателиcustomersStatusesСегменты покупателяcallsЗвонкиproductsТоварыshortLinksКороткие ссылкиgetOAuthClientoAuth сервисgetRequestГолый запросы#### Для большинства сервисов есть базовый набор методов:

[](#для-большинства-сервисов-есть-базовый-набор-методов)

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

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

    ```
    getOne($id, array $with => []);
    ```
2. get Получить несколько сущностей:

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

    ```
    get(BaseEntityFilter $filter = null, array $with = []);
    ```
3. addOne Создать одну сущность:

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

    ```
    addOne(BaseApiModel $model);
    ```
4. add Создать сущности пакетно:

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

    ```
    add(BaseApiCollection $collection);
    ```
5. updateOne Обновить одну сущность:

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

    ```
    updateOne(BaseApiModel $model);
    ```
6. update Обновить сущности пакетно:

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

    ```
    update(BaseApiCollection $collection);
    ```
7. syncOne Синхронизировать одну модель с сервером:

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

    ```
    syncOne(BaseApiModel $model, $with = []);
    ```

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

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

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

[](#методы-доступные-в-сервисе-getoauthclient)

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

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

    ```
    getAuthorizeUrl(array $options = []);
    ```
2. getAccessTokenByCode получение аксес токена по коду авторизации

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

    ```
    getAccessTokenByCode(string $code);
    ```
3. getAccessTokenByRefreshToken получение аксес токена по рефреш токену

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

    ```
    getAccessTokenByRefreshToken(AccessTokenInterface $accessToken);
    ```
4. setBaseDomain установка базового домена, куда будут отправляться запросы необходимые для работы с токенами

    1. domain (string)

    ```
    setBaseDomain(string $domain);
    ```
5. setAccessTokenRefreshCallback установка callback, который будет вызван при обновлении аксес токена

    1. function (callable)

    ```
    setAccessTokenRefreshCallback(callable $function);
    ```
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 кодом кнопки авторизации

    ```
    getOAuthButton(array $options = []);
    ```
7. exchangeApiKey метод для обмена API ключа на код авторизации

    1. login - email пользователя, для которого обменивается API ключ
    2. apiKey - API ключ пользователя
    3. Код авторизации будет прислан на указанный в настройках приложения redirect\_uri

    ```
    exchangeApiKey(string $login, string $apiKey);
    ```

#### Методы связей доступны в сервисах `leads`, `contacts`, `companies`, `customers`:

[](#методы-связей-доступны-в-сервисах-leads-contacts-companies-customers)

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

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

    ```
    link(BaseApiModel $model, $linkedEntities);
    ```
2. getLinks Получить связи сущности

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

    ```
    getLinks(BaseApiModel $model, LinksFilter $filter);
    ```
3. unlink Отвязать сущность

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

    ```
    unlink(BaseApiModel $model, $linkedEntities);
    ```

#### Методы удаления доступны в сервисах `transactions`, `lossReasons`, `statuses`, `pipelines`, `customFields`, `customFieldsGroups`, `roles`, `customersStatuses`:

[](#методы-удаления-доступны-в-сервисах-transactions-lossreasons-statuses-pipelines-customfields-customfieldsgroups-roles-customersstatuses)

1. delete

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

    ```
    deleteOne(BaseApiModel $model);
    ```
2. deleteOne

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

    ```
    deleteOne(BaseApiModel $model);
    ```

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

[](#методы-доступные-в-сервисе-customers)

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

    ```
    setMode(string $mode, bool $isEnabled = true);
    ```

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

[](#методы-доступные-в-сервисе-notes)

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

    ```
    getByParentId(int $parentId, BaseEntityFilter $filter = null, array $with = []);
    ```

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

[](#методы-доступные-в-сервисе-account)

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

    ```
    getCurrent(array $with = []);
    ```

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

[](#методы-доступные-в-сервисе-unsorted)

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

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

    ```
    addOne(BaseApiModel $model);
    ```
2. add Создать сущности пакетно:

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

    ```
    add(BaseApiCollection $collection);
    ```
3. link

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

    ```
    link(BaseApiModel $unsortedModel, $body = []);
    ```
4. accept

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

    ```
    accept(BaseApiModel $unsortedModel, $body = []);
    ```
5. decline

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

    ```
    decline(BaseApiModel $unsortedModel, $body = []);
    ```
6. summary

    1. filter (BaseEntityFilter) - фильтр для сущности
    2. Результатом выполнения будет модель UnsortedSummaryModel

    ```
    summary(BaseEntityFilter $filter);
    ```

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

[](#методы-доступные-в-сервисе-webhooks)

1. subscribe

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

    ```
    subscribe(WebhookModel $webhookModel);
    ```
2. unsubscribe

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

    ```
    unsubscribe(WebhookModel $webhookModel);
    ```

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

[](#методы-доступные-в-сервисе-widgets)

1. install

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

    ```
    install(WidgetModel $widgetModel);
    ```
2. uninstall

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

    ```
    uninstall(WidgetModel $widgetModel);
    ```

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

[](#методы-доступные-в-сервисе-products)

1. settings

    1. Результатом выполнения является модель ProductsSettingsModel

    ```
    settings();
    ```
2. updateSettings

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

    ```
    updateSettings(ProductsSettingsModel $productsSettings);
    ```

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

[](#обработка-ошибок)

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

ТипУсловияAmoCRM\\Exceptions\\AmoCRMApiConnectExceptionExceptionПодключение к серверу не было выполненоAmoCRM\\Exceptions\\AmoCRMApiErrorResponseExceptionСервер вернул ошибку на выполняемый запросAmoCRM\\Exceptions\\AmoCRMApiHttpClientExceptionПроизошла ошибка http клиентаAmoCRM\\Exceptions\\AmoCRMApiNoContentExceptionСервер вернул код 204 без результата, ничего страшного не произошло, просто нет данных на ваш запросAmoCRM\\Exceptions\\AmoCRMApiTooManyRedirectsExceptionСлишком много редиректов (в нормальном режиме не выкидывается)AmoCRM\\Exceptions\\AmoCRMoAuthApiExceptionОшибка в oAuth клиентеAmoCRM\\Exceptions\\BadTypeExceptionПередан не верный тип данныхAmoCRM\\Exceptions\\InvalidArgumentExceptionПередан не верный аргументAmoCRM\\Exceptions\\NotAvailableForActionExceptionМетод не доступен для вызоваAmoCRM\\Exceptions\\AmoCRMApiPageNotAvailableExceptionВыбрасывается в случае запроса следующей или предыдущей страницы коллекции, когда страница отстутвуетУ выброшенных Exception есть следующие методы:

1. `getErrorCode()`
2. `getTitle()`
3. `getLastRequestInfo()`
4. `getDescription()`

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

Фильтры
-------

[](#фильтры)

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

СервисФильтрОсобенностиПоддерживает ли сортировку?`catalogElements``\AmoCRM\Filters\CatalogElementsFilter`Доступен в ограниченном виде, в будущих версиях будет расширен❌`companies``\AmoCRM\Filters\CompaniesFilter`Доступен только на аккаунтах, которые подключены к тестированию функционала фильтрации по API✅`contacts``\AmoCRM\Filters\ContactsFilter`Доступен только на аккаунтах, которые подключены к тестированию функционала фильтрации по API✅`customers``\AmoCRM\Filters\CustomersFilter`Доступен только на аккаунтах, которые подключены к тестированию функционала фильтрации по API✅`leads``\AmoCRM\Filters\LeadsFilter`Доступен только на аккаунтах, которые подключены к тестированию функционала фильтрации по API✅`events``\AmoCRM\Filters\EventsFilter`Фильтр для списка событий❌`leads`, `contacts`, `customers`, `companies``\AmoCRM\Filters\LinksFilter`Фильтр для получения связей для метода \\AmoCRM\\EntitiesServices\\HasLinkMethodInterface::getLinks❌`notes``\AmoCRM\Filters\NotesFilter`Фильтра для \\AmoCRM\\EntitiesServices\\EntityNotes::get✅`tags``\AmoCRM\Filters\TagsFilter`Фильтр для \\AmoCRM\\EntitiesServices\\EntityTags::get❌`tasks``\AmoCRM\Filters\TasksFilter`Фильтр для метода \\AmoCRM\\EntitiesServices\\Tasks::get✅`unsorted``\AmoCRM\Filters\UnsortedFilter`Фильтр для метода \\AmoCRM\\EntitiesServices\\Unsorted::get✅`unsorted``\AmoCRM\Filters\UnsortedSummaryFilter`Фильтр для метода \\AmoCRM\\EntitiesServices\\Unsorted::summary❌`webhooks``\AmoCRM\Filters\WebhooksFilter`Фильтр для метода получения хуков❌Работа с дополнительными полями сущностей
-----------------------------------------

[](#работа-с-дополнительными-полями-сущностей)

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

1. `leads`
2. `contacts`
3. `companies`
4. `customers`
5. `catalogElements`
6. `segments`

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

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

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

1. `getFieldId`, `setFieldId` - получение/установка id поля
2. `getFieldType` - получение типа поля
3. `getFieldCode`, `setFieldCode` - получение/установка кода поля
4. `getFieldName`, `setFieldName` - получение/установка названия поля
5. `getValues`, `setValues` - получение/установка коллекции значений

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

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

[](#схема-отношений-объектов)

`CustomFieldsValuesCollection 1  n BaseCustomFieldValuesModel``BaseCustomFieldValuesModel::getValues() 1  1 BaseCustomFieldValueCollection``BaseCustomFieldValueCollection 1  n BaseCustomFieldValueModel`

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

[](#для-разных-типов-полей-мы-уже-подготовили-разные-модели-и-коллекции)

Namespace, в котором находятся модели значения - `\AmoCRM\Models\CustomFieldsValues\ValueModels`

Namespace, в котором находятся коллекции моделей значения - `\AmoCRM\Models\CustomFieldsValues\ValueCollections`

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

Тип поляМодель значенияКоллекция моделей значенийМодель доп поляКонтактСделкаКомпанияПокупательКаталогСегментТекстTextCustomFieldValueModelTextCustomFieldValueCollectionTextCustomFieldValuesModel✅✅✅✅✅✅ЧислоNumericCustomFieldValueModelNumericCustomFieldValueCollectionNumericCustomFieldValuesModel✅✅✅✅✅✅ФлагCheckboxCustomFieldValueModelCheckboxCustomFieldValueCollectionCheckboxCustomFieldValuesModel✅✅✅✅✅✅СписокSelectCustomFieldValueModelSelectCustomFieldValueCollectionSelectCustomFieldValuesModel✅✅✅✅✅✅МультисписокMultiselectCustomFieldValueModelMultiselectCustomFieldValueCollectionMultiSelectCustomFieldValuesModel✅✅✅✅✅✅МультитекстMultitextCustomFieldValueModelMultitextCustomFieldValueCollectionMultitextCustomFieldValuesModel✅❌❌❌❌❌ДатаDateCustomFieldValueModelDateCustomFieldValueCollectionDateCustomFieldValuesModel✅✅✅✅✅✅СсылкаUrlCustomFieldValueModelUrlCustomFieldValueCollectionUrlCustomFieldValuesModel✅✅✅✅✅✅Дата и времяDateTimeCustomFieldValueModelDateTimeCustomFieldValueCollectionDateTimeCustomFieldValuesModel✅✅✅✅✅✅Текстовая областьTextareaCustomFieldValueModelTextareaCustomFieldValueCollectionTextareaCustomFieldValuesModel✅✅✅✅✅✅ПереключательRadiobuttonCustomFieldValueModelRadiobuttonCustomFieldValueCollectionRadiobuttonCustomFieldValuesModel✅✅✅✅✅✅Короткий адресStreetAddressCustomFieldValueModelStreetAddressCustomFieldValueCollectionStreetAddressCustomFieldValuesModel✅✅✅✅✅✅АдресSmartAddressCustomFieldValueModelSmartAddressCustomFieldValueCollectionSmartAddressCustomFieldValuesModel✅✅✅❌❌❌День рожденияBirthdayCustomFieldValueModelBirthdayCustomFieldValueCollectionBirthdayCustomFieldValuesModel✅✅✅❌❌❌Юр. лицоLegalEntityCustomFieldValueModelLegalEntityCustomFieldValueCollectionLegalEntityCustomFieldValuesModel✅✅✅❌❌❌ЦенаPriceCustomFieldValueModelPriceCustomFieldValueCollectionPriceCustomFieldValuesModel❌❌❌❌✅❌КатегорияCategoryCustomFieldValueModelCategoryCustomFieldValueCollectionCategoryCustomFieldValuesModel❌❌❌❌✅❌ПредметыItemsCustomFieldValueModelItemsCustomFieldValueCollectionItemsCustomFieldValuesModel❌❌❌❌✅❌Пример кода, как создать коллекцию значения полей сущности:

```
//Создадим модель сущности
$lead = new LeadModel();
$lead->setId(1);
//Создадим коллекцию полей сущности
$leadCustomFieldsValues = new CustomFieldsValuesCollection();
//Создадим модель значений поля типа текст
$textCustomFieldValuesModel = new TextCustomFieldValuesModel();
//Укажем ID поля
$textCustomFieldValuesModel->setFieldId(123);
//Добавим значения
$textCustomFieldValuesModel->setValues(
    (new TextCustomFieldValueCollection())
        ->add((new TextCustomFieldValueModel())->setValue('Текст'))
);
//Добавим значение в коллекцию полей сущности
$leadCustomFieldsValues->add($textCustomFieldValuesModel);
//Установим сущности эти поля
$lead->setCustomFieldsValues($leadCustomFieldsValues);
```

Чтобы удалить значения поля доступен специальный объект `\AmoCRM\Models\CustomFieldsValues\ValueCollections\NullCustomFieldValueCollection`.

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

Пример:

```
//Создадим модель сущности
$lead = new LeadModel();
$lead->setId(1);
//Создадим коллекцию полей сущности
$leadCustomFieldsValues = new CustomFieldsValuesCollection();
//Создадим модель значений поля типа текст
$textCustomFieldValuesModel = new TextCustomFieldValuesModel();
//Укажем ID поля
$textCustomFieldValuesModel->setFieldId(123);
//Обнулим значения
$textCustomFieldValuesModel->setValues(
    (new NullCustomFieldValueCollection())
);
//Добавим значение в коллекцию полей сущности
$leadCustomFieldsValues->add($textCustomFieldValuesModel);
//Установим сущности эти поля
$lead->setCustomFieldsValues($leadCustomFieldsValues);
```

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

[](#работа-с-тегами-сущностей)

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

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

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

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

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

```
//Создадим модель сущности
$lead = new LeadModel();
$lead->setId(1);
//Создадим коллекцию тегов с тегами и установим их в сущности
$lead->setTags((new TagsCollection())
    ->add(
        (new TagModel())
            ->setName('тег')
    )->add(
        (new TagModel())
            ->setId(123123)
    )
);
```

или

```
//Создадим модель сущности
$lead = new LeadModel();
$lead->setId(1);
//Создадим коллекцию тегов с тегами и установим их в сущности
$lead->setTags(
    TagsCollection::fromArray([
        [
            'name' => 'тег',
        ],
        [
            'id' => 123,
        ],
    ])
);
```

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

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

```
//Создадим модель сущности
$lead = new LeadModel();
$lead->setId(1);
//Удалим теги
$lead->setTags((new 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`

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

[](#работа-в-случае-смены-субдомена-аккаунта)

```
/**
 * Получим модель с информацией о домене аккаунта по access_token
 * Подробнее: @see AccountDomainModel
 *
 * Запрос уходит на www.amocrm.ru/oauth2/account/subdomain
 * С Authorization: Bearer {access_token}
 * curl 'https://www.amocrm.ru/oauth2/account/subdomain' -H 'Authorization: Bearer {access_token}'
 *
 * @example examples/get_account_subdomain.php
 */
$accountDomain = $apiClient->getOAuthClient()
        ->getAccountDomain($accessToken);

// Возьмём из полученной модели текущий subdomain аккаунта и засетим наш апи клиент
$apiClient->setAccountBaseDomain($accountDomain->getSubdomain());
// ... дальше продолжаем работу с апи клиентом
```

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

[](#одноразовые-токены-интеграций-расшифровка)

```
// Как пример, получим заголовки с реквеста
// И получим нужный нам X-Auth-Token
$token = $_SERVER['HTTP_X_AUTH_TOKEN'];

/**
 * Одноразовый токен для интеграций, для того чтобы его получить используйте
 * метод this.$authorizedAjax() в своей интеграции
 * Подробнее: @link https://www.amocrm.ru/developers/content/web_sdk/mechanics
 *
 * Данный токен должен передаваться в заголовках вместе с запросом на ваш удаленный сервер
 * X-Auth-Token: {disposable_token}
 * Время жизни токена: 30 минут
 *
 * Расшифруем пришедший токен и получим модель с информацией
 * Подробнее: @see DisposableTokenModel
 * @example examples/parse_disposable_token.php
 */
$disposableTokenModel = $apiClient->getOAuthClient()
    ->parseDisposableToken($token);
```

Примеры
-------

[](#примеры)

В рамках данного репозитория имеется папка 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
-------

[](#license)

MIT

###  Health Score

24

—

LowBetter than 32% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 86.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~5 days

Total

21

Last Release

2067d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/8efe53293545348581877dbdd2008ccd49b84d7dc21ad73b57b3cf242f3cbc0c?d=identicon)[AndreiMireichyk](/maintainers/AndreiMireichyk)

---

Top Contributors

[![bessudnov](https://avatars.githubusercontent.com/u/5815770?v=4)](https://github.com/bessudnov "bessudnov (182 commits)")[![noweasily](https://avatars.githubusercontent.com/u/16639415?v=4)](https://github.com/noweasily "noweasily (14 commits)")[![lmcsu](https://avatars.githubusercontent.com/u/34189985?v=4)](https://github.com/lmcsu "lmcsu (3 commits)")[![AndreiMireichyk](https://avatars.githubusercontent.com/u/39955122?v=4)](https://github.com/AndreiMireichyk "AndreiMireichyk (3 commits)")[![constantable](https://avatars.githubusercontent.com/u/11844178?v=4)](https://github.com/constantable "constantable (2 commits)")[![soul-rise](https://avatars.githubusercontent.com/u/1153194?v=4)](https://github.com/soul-rise "soul-rise (2 commits)")[![bigperson](https://avatars.githubusercontent.com/u/4757391?v=4)](https://github.com/bigperson "bigperson (2 commits)")[![ub-3](https://avatars.githubusercontent.com/u/47298830?v=4)](https://github.com/ub-3 "ub-3 (1 commits)")[![m4tlch](https://avatars.githubusercontent.com/u/3687188?v=4)](https://github.com/m4tlch "m4tlch (1 commits)")[![olapsema](https://avatars.githubusercontent.com/u/13793736?v=4)](https://github.com/olapsema "olapsema (1 commits)")

---

Tags

clientoauth2authorizationauthorisationapi clientamoCRMamocrm api

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/andrei-mireichyk-amocrm-api-library/health.svg)

```
[![Health](https://phpackages.com/badges/andrei-mireichyk-amocrm-api-library/health.svg)](https://phpackages.com/packages/andrei-mireichyk-amocrm-api-library)
```

###  Alternatives

[amocrm/amocrm-api-library

amoCRM API Client

182728.5k6](/packages/amocrm-amocrm-api-library)[patrickbussmann/oauth2-apple

Sign in with Apple OAuth 2.0 Client Provider for The PHP League OAuth2-Client

1132.5M6](/packages/patrickbussmann-oauth2-apple)[amocrm/oauth2-amocrm

amoCRM OAuth 2.0 Client Provider for The PHP League OAuth2-Client

25874.7k5](/packages/amocrm-oauth2-amocrm)[mollie/oauth2-mollie-php

Mollie Provider for OAuth 2.0 Client

251.7M1](/packages/mollie-oauth2-mollie-php)[omines/oauth2-gitlab

GitLab OAuth 2.0 Client Provider for The PHP League OAuth2-Client

36721.5k13](/packages/omines-oauth2-gitlab)[salla/ouath2-merchant

Salla OAuth 2.0 Client Provider for The PHP League OAuth2-Client

21117.6k1](/packages/salla-ouath2-merchant)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)