PHPackages                             amocrm/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. amocrm/amocrm-api-library

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

amocrm/amocrm-api-library
=========================

amoCRM API Client

1.17.0(2d ago)185798.9k↓41.1%124[117 issues](https://github.com/amocrm/amocrm-api-php/issues)[8 PRs](https://github.com/amocrm/amocrm-api-php/pulls)6MITPHPPHP >=7.1 || >=8.0CI failing

Since May 20Pushed 1mo ago10 watchersCompare

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

READMEChangelog (10)Dependencies (22)Versions (98)Used By (6)

[![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/cef38cbbaba471eeef2890c1e7b73c3af8efcc47ff0be14ca12c83de4a1f2759/68747470733a2f2f6170702e7472617669732d63692e636f6d2f616d6f63726d2f616d6f63726d2d6170692d7068702e7376673f6272616e63683d6d6173746572)](https://app.travis-ci.com/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. Для работы библиотеки требуется PHP версии не ниже 7.1.

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

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

- [Установка](#%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%B0%D0%B2%D1%82%D0%BE%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F-%D1%81-%D0%B4%D0%BE%D0%BB%D0%B3%D0%BE%D0%B6%D0%B8%D0%B2%D1%83%D1%89%D0%B8%D0%BC-%D1%82%D0%BE%D0%BA%D0%B5%D0%BD%D0%BE%D0%BC)
- [Подход к работе с библиотекой](#%D0%BF%D0%BE%D0%B4%D1%85%D0%BE%D0%B4-%D0%BA-%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B5-%D1%81-%D0%B1%D0%B8%D0%B1%D0%BB%D0%B8%D0%BE%D1%82%D0%B5%D0%BA%D0%BE%D0%B9)
- [Поддерживаемые методы и сервисы](#%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%BE%D0%B1%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%BA%D0%B0-%D0%BE%D1%88%D0%B8%D0%B1%D0%BE%D0%BA)
- [Фильтры](#%D1%84%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%BE%D1%81%D0%BE%D0%B1%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8-%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D1%8B-%D1%81-%D0%B8%D1%81%D1%82%D0%BE%D1%87%D0%BD%D0%B8%D0%BA%D0%B0%D0%BC%D0%B8)
- [Константы](#%D0%BA%D0%BE%D0%BD%D1%81%D1%82%D0%B0%D0%BD%D1%82%D1%8B)
- [Работа в случае смены субдомена аккаунта](#%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B0-%D0%B2-%D1%81%D0%BB%D1%83%D1%87%D0%B0%D0%B5-%D1%81%D0%BC%D0%B5%D0%BD%D1%8B-%D1%81%D1%83%D0%B1%D0%B4%D0%BE%D0%BC%D0%B5%D0%BD%D0%B0-%D0%B0%D0%BA%D0%BA%D0%B0%D1%83%D0%BD%D1%82%D0%B0)
- [Одноразовые токены интеграций, расшифровка](#%D0%BE%D0%B4%D0%BD%D0%BE%D1%80%D0%B0%D0%B7%D0%BE%D0%B2%D1%8B%D0%B5-%D1%82%D0%BE%D0%BA%D0%B5%D0%BD%D1%8B-%D0%B8%D0%BD%D1%82%D0%B5%D0%B3%D1%80%D0%B0%D1%86%D0%B8%D0%B9-%D1%80%D0%B0%D1%81%D1%88%D0%B8%D1%84%D1%80%D0%BE%D0%B2%D0%BA%D0%B0)
- [Работа с валютами](#%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B0-%D1%81-%D0%B2%D0%B0%D0%BB%D1%8E%D1%82%D0%B0%D0%BC%D0%B8)
- [Примеры](#%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\Client\AmoCRMApiClientFactory`. Для ее использования вам нужно реализовать интерфейс `\AmoCRM\OAuth\OAuthConfigInterface` и `\AmoCRM\OAuth\OAuthServiceInterface`

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

При использовании фабрики вам не нужно устанавливать callback onAccessTokenRefresh, при обновлении токена будет вызван метод saveOAuthToken из $oAuthService (\\AmoCRM\\OAuth\\OAuthServiceInterface).

Затем необходимо создать объект (`\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

### Авторизация с правами конкретного пользователя аккаунта

[](#авторизация-с-правами-конкретного-пользователя-аккаунта)

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

Для авторизации под пользователем аккаунта - необходимо задать ID пользователя у объекта типа `\AmoCRM\Client\AmoCRMApiClient`. Метод вернет новый объект с установленным контекстом.

```
$apiClient = new \AmoCRM\Client\AmoCRMApiClient($clientId, $clientSecret, $redirectUri);
$apiClientWithContext = $apiClient->withContextUserId(123);
```

### Установка кастомного User Agent

[](#установка-кастомного-user-agent)

Начиная с версии 1.5.0 появилась возможность указать свой User Agent для запросов с библиотекой.

```
$apiClient = new \AmoCRM\Client\AmoCRMApiClient($clientId, $clientSecret, $redirectUri);
$apiClient = $apiClient->setUserAgnet('App Name');
```

### Установка кастомного callback-обработчика ответа от сервера

[](#установка-кастомного-callback-обработчика-ответа-от-сервера)

Начиная с версии 1.9.0 появилась возможность устанавливать callback-обработчик ответа от сервера.

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

Если нет необходимости в отработке стандартной логики обработки ответа, то callback должен возвращать true

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

$this->apiClient
     ->setCheckHttpStatusCallback(
         function (ResponseInterface $response, $decodedBody) {
             if ($response->getStatusCode() === 204) {
                 return true;
             }

             $this->logger->info('Response: ', $decodedBody);
         }
     );
```

Авторизация с долгоживущим токеном
----------------------------------

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

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

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

```
$apiClient = new \AmoCRM\Client\AmoCRMApiClient();
```

После этого нужно создать объект `AmoCRM\Client\LongLivedAccessToken`, который будет использоваться с запросами в API.

```
$longLivedAccessToken = new LongLivedAccessToken($accessToken);
```

Затем нужно установить токен и адресс аккаунта в объект библиотеки:

```
$apiClient->setAccessToken($longLivedAccessToken)
    ->setAccountBaseDomain('example.amocrm.ru');
```

После этих простых шагов, вы сможете делать запросы в amoCRM до тех пор, пока токен не истечет или его не отзовут. В случае отзыва или истечения токена - при выполнении запроса - упадет ошибка с http кодом 401.

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

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

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

Модели и коллекции имеют методы `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` - замена модели по значению ключа.
10. `removeBy($key, $value): int` - удаление моделей по значению ключа, возвращает количество удаленных моделей.
11. `removeFirstBy($key, $value): bool` - удаление первой модели по значению ключа, возвращает true если модель была удалена.
12. `chunk(int $size): array` - разделение коллекции на массив состоящий из коллекций определенной длины.
13. `pluck(string $column): array` - получение массива значений моделей коллекции по названию свойства.

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

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

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

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

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

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

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

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

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

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.

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

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

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

1. addComplex Создать сделки пакетно со связанным контакт и компанией через [комплексный метод](https://www.amocrm.ru/developers/content/crm_platform/leads-api#leads-complex-add) с поддержкой [контроля дублей](https://www.amocrm.ru/developers/content/crm_platform/duplication-control)
    1. collection (LeadsCollection) - коллекция моделей создаваемой сущности
    2. Результатом выполнения будет новая коллекция созданных сущностей

    ```
    addComplex(LeadsCollection $collection);
    ```
2. addOneComplex Создать одну сделку со связанным контакт и компанией через [комплексный метод](https://www.amocrm.ru/developers/content/crm_platform/leads-api#leads-complex-add) с поддержкой [контроля дублей](https://www.amocrm.ru/developers/content/crm_platform/duplication-control)
    1. collection (LeadsCollection) - коллекция моделей создаваемой сущности
    2. Результатом выполнения будет новая модель созданной сделки

    ```
    addOneComplex(LeadModel $model);
    ```

Подробнее про использование метода комплексного создания смотрите в [примере](examples/leads_complex_actions.php)

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

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

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

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

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

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

    ```
    getAccessTokenByCode(string $code);
    ```
3. getAccessTokenByRefreshToken получение access токена по refresh токену

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

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

    1. domain (string)

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

    1. function (callable)

    ```
    setAccessTokenRefreshCallback(callable $function);
    ```
6. getOAuthButton установка callback, который будет вызван при обновлении access токена

    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`, `entityFiles`, `files`:

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

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);
    ```

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

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

1. earnPoints Начисляет бонусные баллы покупателю

    1. model (BonusPointsActionModel) - модель в которой Id покупателя и количество баллов для начисления
    2. Результатом выполнения является обновленное количество бонусных баллов покупателя или null в случае если произошла ошибка

    ```
    earnPoints(BonusPointsActionModel $bonusPointsActionModel)
    ```
2. redeemPoints Списывает бонусные баллы покупателя

    1. model (BonusPointsActionModel) - модель в которой Id покупателя и количество баллов для списания
    2. Результатом выполнения является обновленное количество бонусных баллов покупателя или null в случае если произошла ошибка

    ```
    redeemPoints(BonusPointsActionModel $bonusPointsActionModel)
    ```

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

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

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);
    ```

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

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

1. close
    1. model (TalkCloseActionModel) - модель для закрытия беседы
    2. Результатом выполнения - является закрытие беседы или запуск NPS-бота для последующего закрытия беседы

    ```
    close(TalkCloseActionModel $closeAction)
    ```

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

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

1. uploadOne
    1. model (FileUploadModel) - модель файла для загрузки
    2. Результатом выполнения является модель FileModel

    ```
    uploadOne(FileUploadModel $model);
    ```

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

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

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

    ```
    getOne($id, array $with => []);
    ```
2. get - получить несколько сущностей:
    1. filter (BaseEntityFilter) - фильтр для сущности
    2. with (array) - массив параметров with, которые поддерживает модель сервиса
    3. Результатом выполнения будет коллекция `WebsiteButtonsCollection` из сущностей `WebsiteButtonModel`

    ```
    get(?BaseEntityFilter $filter = null, array $with = []);
    ```
3. createAsync - добавить источник типа "кнопка на сайт"
    1. model (WebsiteButtonCreateRequestModel) - модель со свойствами:
        1. pipelineId (int) - id воронки
        2. trustedWebsites (array) - список доверенных адресов на которых будет размещена "кнопка на сайт". Например amocrm.ru,
        3. isUsedInApp (true|false) - true, если кнопка встраивается в приложение, а не на сайт
    2. Результатом выполнения будет модель `WebsiteButtonCreateResponseModel`

    ```
    createAsync(WebsiteButtonCreateRequestModel $model);
    ```
4. updateAsync - добавить дополнительные доверенные адреса
    1. model (WebsiteButtonUpdateRequestModel) - модель со свойствами:
        1. sourceId (int) - id источника
        2. trustedWebsitesToAdd (array) - список доверенных адресов на которых будет размещена "кнопка на сайт"
    2. Результатом выполнения будет модель `WebsiteButtonModel`

    ```
    updateAsync(WebsiteButtonUpdateRequestModel $model);
    ```
5. addOnlineChatAsync - добавить канал связи "Онлайн-чат" к кнопке на сайт
    1. sourceId - id источника
    2. Результатом выполнения будет void значение

    ```
    addOnlineChatAsync(int $sourceId);
    ```

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

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

Вызов методов библиотеки может выбрасывать ошибки типа `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Выбрасывается в случае запроса следующей или предыдущей страницы коллекции, когда страница отсутствуетAmoCRM\\Exceptions\\AmoCRMMissedTokenExceptionНе установлен Access Token для выполнения запросаУ выброшенных 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✅`customFields``\AmoCRM\Filters\CustomFieldsFilter`Фильтр для метода получения дополнительных полей `\AmoCRM\EntitiesServices\CustomFields::get`❌`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`Фильтр для метода получения хуков❌`files``\AmoCRM\Filters\FilesFilter`Фильтр для метода получения файлов `\AmoCRM\EntitiesServices\Files::get`❌`sources``\AmoCRM\Filters\SourcesFilter`Фильтр для метода получения источников `\AmoCRM\EntitiesServices\Sources::get`❌`chatTemplates``\AmoCRM\Filters\Chats\TemplatesFilter`Фильтр для метода получения шаблонов чатов `\AmoCRM\EntitiesServices\Chats\Templates::get`❌Сервисы, где необходима постраничная навигация`\AmoCRM\Filters\PagesFilter`Фильтр, который подходит для любого сервиса, где есть постраничная навигация❌Работа с дополнительными полями сущностей
-----------------------------------------

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

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

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❌❌❌❌✅❌МеткаTrackingDataCustomFieldValueModelTrackingDataCustomFieldValueCollectionTrackingDataCustomFieldValuesModel❌✅❌❌❌❌Связь с другим элементомLinkedEntityCustomFieldValueModelLinkedEntityCustomFieldValueCollectionLinkedEntityCustomFieldValuesModel❌❌❌❌✅❌ДенежноеMonetaryCustomFieldModelMonetaryCustomFieldValueCollectionMonetaryCustomFieldValuesModel✅✅✅✅❌❌Каталоги и спискиChainedListCustomFieldModelChainedListCustomFieldValueCollectionChainedListCustomFieldValuesModel❌✅❌✅❌❌ФайлFileCustomFieldModelFileCustomFieldValueCollectionFileCustomFieldValuesModel✅✅✅✅❌❌ПлательщикPayerCustomFieldModelPayerCustomFieldValueCollectionPayerCustomFieldValuesModel❌❌❌❌✅ (только счета-покупки)❌ПоставщикSupplierCustomFieldModelSupplierCustomFieldValueCollectionSupplierCustomFieldValuesModel❌❌❌❌✅ (только счета-покупки)❌Пример кода, как создать коллекцию значения полей сущности:

```
//Создадим модель сущности
$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()));
```

Особенности работы с источниками
--------------------------------

[](#особенности-работы-с-источниками)

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

При добавлении источника обязательными полями являются `external_id`, `name` интеграция может создать в аккаунте не более 50 активных источников на аккаунт. При удалении источника, к примеру, со значением `external_id: 'sales'`и при повторном создании с тем же `external_id` crm может вернуть `id` раннее удаленного источника. Поэтому не стоит на стороне интеграции формировать первичный ключ из поля `id`.

Чтобы источник отображался в кнопке whatsapp CRM Plugin необходимо указать поле источника `services` с таким содержимым:

```
 [
   {
      "type": "whatsapp",
      "pages": [
         {
            "id": "",
            "name": "My WhatsApp",
            "link": ""
         }
      ]
   }
]
```

Чтобы правильно сформировать поле `services` можно воспользоваться моделью `\AmoCRM\Collections\Sources\SourceServicesCollection`

### Источник по-умолчанию

[](#источник-по-умолчанию)

Источник по-умолчанию (с полем `default=true`) может быть только один или отсутствовать совсем. При отсутствии источника по-умолчанию в сделках будет указан источник АПИ-интеграция с названием интеграции (как при создании неразобранного через АПИ).

Чтобы сменить источник по-умолчанию, достаточно нужному источнику проставить поле `default=true`, у предыдущего источника поле default будет выставлено в `default=false`. Но при удалении источника по-умолчанию интеграция сама должна указать новый источник по-умолчанию.

### Миграция интеграции на множественные источники (для интеграций с чатами)

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

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

К примеру исходное состояние: Есть аккаунт с подключенной интеграцией с чатами, эта интеграция поддерживает только 1 источник. На данный момент нам не важно как была установлена интеграция: через DP или маркетплейс.

Интеграция начинает внедрение поддержки множественных источников, логически разобьем на этапы:

**1 этап**Интеграция умеет работать с АПИ источниками (но не отправляет и не принимает источник в сообщениях amojo). Добавляет источник по-умолчанию, который логически соответствует источнику, использовавшемуся когда не было поддержки нескольких источников. Теперь crm будет присылать в сообщениях `external_id` этого источника для всех чатов которые явно не закреплены за конкретным источником.

**2 этап**Интеграция умеет работать с источниками и при отправке сообщений от клиента (при создании чата) указывает `external_id`Все чаты с новыми сообщениями становятся размеченными по источнику.

Так же интеграция теперь обрабатывает источник и учитывает его при отправке сообщения от менеджера, в том числе при начале чата с клиентом (опция "написать первым").

**3 этап**Интеграция позволяет администратору аккаунта добавить (через интеграцию) второй и последующие источники. Вся переписка числится за каким-то источником

**Важный момент**Источник по-умолчанию не привязывается к чатам, если его явно не передавали с сообщениями и тогда при смене источника по-умолчанию чат без разметки будет "числиться" за новым источником

Константы
---------

[](#константы)

Основные константы находятся в интерфейсе `\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`
21. `\AmoCRM\Models\CatalogElementModel` - константы для аргумента with для сервиса `catalogElements`
22. `\AmoCRM\Enum\InvoicesCustomFieldsEnums` - константы для работы с полями каталога счетов (с версии 0.12 константы статусов переехали в \\AmoCRM\\Enum\\Invoices\\BillStatusEnumCode)
23. `\AmoCRM\Enum\Chats\Templates\Buttons\ButtonsEnums` - типы кнопок шаблонов чатов
24. `\AmoCRM\Enum\Sources\SourceServiceTypeEnum` - типы сервисов для источников
25. `\AmoCRM\Enum\Tags\TagColorsEnum` - возможные цвета для тегов
26. `\AmoCRM\Enum\Invoices\BillStatusEnumCode` - предустановленные статусы для Счетов/Покупок
27. `\AmoCRM\Enum\SuppliersCustomFieldsEnums` - константы для свойств поля поставщик

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

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

```
/**
 * Получим модель с информацией о домене аккаунта по 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
 */
use AmoCRM\Models\AccountDomainModel;$accountDomain = $apiClient->getOAuthClient()
        ->getAccountDomain($accessToken);

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

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

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

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

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

    var_dump($disposableTokenModel->toArray());
} catch (DisposableTokenExpiredException $e) {
    // Время жизни токена истекло
    printError($e);
    die;
} catch (DisposableTokenInvalidDestinationException $e) {
    // Не прошёл проверку на адресата токена
    printError($e);
    die;
} catch (DisposableTokenVerificationFailedException $e) {
    // Токен не прошел проверку подписи
    printError($e);
    die;
}
```

Также вы можете распарсить и модель одноразового токена для Salesbot/Marketingbot. Для этого необходимо сделать вызов метода `parseBotDisposableToken`:

```
use AmoCRM\Models\BotDisposableTokenModel;$token = 'XXX';
try {
    /**
     * Одноразовый токен для ботов, его вы можете получить, сделав вызов widget_request в виджете в боте
     * Подробнее: @link https://www.amocrm.ru/developers/content/digital_pipeline/salesbot#handler-widget_request
     *
     * Данный токен содержит в себе информацию об аккаунте и о сущности, с которой работает бот
     * Для продолжения бота необходимо сделать запрос на метод, который был получен в теле хука
     * Подробнее: @link https://www.amocrm.ru/developers/content/crm_platform/widgets-api#widget-continue
     *
     * Расшифруем пришедший токен и получим модель с информацией
     * Подробнее: @see BotDisposableTokenModel
     */
    $botDisposableTokenModel = $apiClient->getOAuthClient()
        ->parseBotDisposableToken($token);

    var_dump($botDisposableTokenModel->toArray());
} catch (DisposableTokenExpiredException $e) {
    // Время жизни токена истекло
    printError($e);
    die;
} catch (DisposableTokenInvalidDestinationException $e) {
    // Не прошёл проверку на адресата токена
    printError($e);
    die;
} catch (DisposableTokenVerificationFailedException $e) {
    // Токен не прошел проверку подписи
    printError($e);
    die;
}
```

Работа с валютами
-----------------

[](#работа-с-валютами)

```
/** @var AmoCRMApiClient $apiClient */

# Получим сервис для работы с валютами
$service = $apiClient->currencies();

# Получение списка валют
try {
    $collection = $service->get();
    var_dump($collection);
} catch (AmoCRMApiException $e) {
    printError($e);
    die;
}

# Получение списка валют с фильтром
$filter = new CurrenciesFilter();
$filter->setLimit(50);
$filter->setPage(2);

try {
    $collection = $service->get($filter);
    var_dump($collection);
} catch (AmoCRMApiException $e) {
    printError($e);
    die;
}
```

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

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

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

Работа с Issues
---------------

[](#работа-с-issues)

Если вы столкнулись с проблемой при работе с библиотекой, вы можете составить Issue, который будет рассмотрен при первой возможности.

При составлении, детально опишите проблему, приложите примеры кода, а также ответы на запросы из `getLastRequestInfo`.

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

Также могут быть рассмотрены пожелания по улучшению библиотеки.

Вы можете предложить свои исправления/изменения исходного кода библиотеки, посредством создания Issue с описанием, а также Pull request с упоминанием Issue в комментарии к нему. Они будут рассмотрены и будут приняты или отклонены. Некоторые Pull Request могут остаться без ответа и действия, в случае, если правки потенциально жизнеспособны, но в данный момент не являются ключевыми для проекта.

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

License
-------

[](#license)

MIT

###  Health Score

66

—

FairBetter than 99% of packages

Maintenance81

Actively maintained with recent releases

Popularity58

Moderate usage in the ecosystem

Community38

Small or concentrated contributor base

Maturity77

Established project with proven stability

 Bus Factor1

Top contributor holds 71% 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 ~24 days

Recently: every ~90 days

Total

91

Last Release

2d ago

Major Versions

0.13.0 → 1.0.02023-05-15

PHP version history (2 changes)0.1PHP >=7.1

0.9.0PHP >=7.1 || >=8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/492988105724b8150ec53dc63c199cb094ee0ec702119896a5efcd1e6b88b2e4?d=identicon)[bessudnov](/maintainers/bessudnov)

---

Top Contributors

[![bessudnov](https://avatars.githubusercontent.com/u/5815770?v=4)](https://github.com/bessudnov "bessudnov (439 commits)")[![noweasily](https://avatars.githubusercontent.com/u/16639415?v=4)](https://github.com/noweasily "noweasily (32 commits)")[![olapsema](https://avatars.githubusercontent.com/u/13793736?v=4)](https://github.com/olapsema "olapsema (24 commits)")[![makeroi](https://avatars.githubusercontent.com/u/72909976?v=4)](https://github.com/makeroi "makeroi (15 commits)")[![bmoiseenko](https://avatars.githubusercontent.com/u/113043126?v=4)](https://github.com/bmoiseenko "bmoiseenko (14 commits)")[![vadimkorchagin](https://avatars.githubusercontent.com/u/157621493?v=4)](https://github.com/vadimkorchagin "vadimkorchagin (11 commits)")[![max-kut](https://avatars.githubusercontent.com/u/12911259?v=4)](https://github.com/max-kut "max-kut (11 commits)")[![nzhirkovAMO](https://avatars.githubusercontent.com/u/137226071?v=4)](https://github.com/nzhirkovAMO "nzhirkovAMO (7 commits)")[![Sawered](https://avatars.githubusercontent.com/u/804711?v=4)](https://github.com/Sawered "Sawered (7 commits)")[![constantable](https://avatars.githubusercontent.com/u/11844178?v=4)](https://github.com/constantable "constantable (6 commits)")[![oauth-enjoyer](https://avatars.githubusercontent.com/u/233246011?v=4)](https://github.com/oauth-enjoyer "oauth-enjoyer (5 commits)")[![RuslanSamburov](https://avatars.githubusercontent.com/u/62927663?v=4)](https://github.com/RuslanSamburov "RuslanSamburov (5 commits)")[![epavlyuchenkov](https://avatars.githubusercontent.com/u/176288531?v=4)](https://github.com/epavlyuchenkov "epavlyuchenkov (4 commits)")[![Mirarori](https://avatars.githubusercontent.com/u/161659364?v=4)](https://github.com/Mirarori "Mirarori (4 commits)")[![SevakTorosyan](https://avatars.githubusercontent.com/u/39670623?v=4)](https://github.com/SevakTorosyan "SevakTorosyan (3 commits)")[![lmcsu](https://avatars.githubusercontent.com/u/34189985?v=4)](https://github.com/lmcsu "lmcsu (3 commits)")[![spervuhina-amocrm](https://avatars.githubusercontent.com/u/255911498?v=4)](https://github.com/spervuhina-amocrm "spervuhina-amocrm (3 commits)")[![fcritic](https://avatars.githubusercontent.com/u/113447533?v=4)](https://github.com/fcritic "fcritic (3 commits)")[![amodmax](https://avatars.githubusercontent.com/u/121236365?v=4)](https://github.com/amodmax "amodmax (2 commits)")[![bigperson](https://avatars.githubusercontent.com/u/4757391?v=4)](https://github.com/bigperson "bigperson (2 commits)")

---

Tags

clientoauth2authorizationauthorisationapi clientamoCRMamocrm api

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

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

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

###  Alternatives

[laravel/framework

The Laravel Framework.

34.8k543.8M20.0k](/packages/laravel-framework)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.6M571](/packages/shopware-core)[shopware/platform

The Shopware e-commerce core

3.4k1.5M3](/packages/shopware-platform)[league/oauth2-server

A lightweight and powerful OAuth 2.0 authorization and resource server library with support for all the core specification grants. This library will allow you to secure your API with OAuth and allow your applications users to approve apps that want to access their data from your API.

6.7k147.0M289](/packages/league-oauth2-server)[patrickbussmann/oauth2-apple

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

1152.8M12](/packages/patrickbussmann-oauth2-apple)[bitrix24/b24phpsdk

An official PHP library for the Bitrix24 REST API

10244.2k5](/packages/bitrix24-b24phpsdk)

PHPackages © 2026

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