livevasiliy/amocrm-api-library

amoCRM API 客户端

维护者

详细信息

github.com/livevasiliy/amocrm-api-php

源代码

安装: 8

依赖: 0

建议者: 0

安全性: 0

星标: 0

关注者: 1

分支: 108

1.0.5 2022-03-07 20:38 UTC

Requires

Requires (Dev)

MIT 7dd0c5894e7b92ac36047ec62df43515a5430713

authorizationclientoauth2authorisationapi clientamoCRMamocrm api

This package is auto-updated.

Last update: 2024-09-08 02:16:59 UTC

README

amoCRM API Library

amoCRM API 库

Latest Version Build Status Total Downloads

此存储库是旧版 PHP 的官方存储库的分支

如果您使用的是更新版本，请使用 官方存储库

此包提供了 amoCRM 的 API 客户端，支持主要实体和 OAuth 2.0 协议的授权。使用此库需要 PHP 版本 5.6 或更高。

目录

安装

可以使用 composer 安装此库

composer require livevasiliy/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，当更新令牌时，会自动调用 $oAuthService 的 saveOAuthToken 方法 (\AmoCRM\OAuth\OAuthServiceInterface)。

然后您需要从您的令牌存储中创建一个 Access 令牌对象 (\League\OAuth2\Client\Token\AccessToken) 并将其设置在 API 客户端中。

还需要设置 amoCRM 账户的域，格式为 СУБДОМЕН.amocrm.(ru/com)。

您可以为 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,
                    ]
                );
            });

可以通过两种方式发送用户到授权页面

  1. 绘制按钮到网站
$apiClient->getOAuthClient()->getOAuthButton(
            [
                'title' => 'Установить интеграцию',
                'compact' => true,
                'class_name' => 'className',
                'color' => 'default',
                'error_callback' => 'handleOauthError',
                'state' => $state,
            ]
        );
  1. 发送用户到授权页面
$authorizationUrl = $apiClient->getOAuthClient()->getAuthorizeUrl([
            'state' => $state,
            'mode' => 'post_message', //post_message - редирект произойдет в открытом окне, popup - редирект произойдет в окне родителе
        ]);

header('Location: ' . $authorizationUrl);

您可以在位于 redirect_uri 所指定地址的处理程序中使用以下代码来获取 Access Token

$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 - 根据键值替换模型。
  10. removeBy($key, $value): int - 根据键值删除模型，返回删除的模型数量。
  11. removeFirstBy($key, $value): bool - 根据键值删除第一个模型，如果模型被删除则返回 true。
  12. chunk(int $size): array - 将集合分割成指定长度的数组。
  13. pluck(string $column): array - 根据属性名称获取模型集合的值数组。

在使用库时，必须注意amoCRM API的限制。为了优化数据处理，最好在具有批量处理的方法中一次创建/修改不超过50个实体。

不要忘记错误处理，以及不要忘记存储令牌的安全性。 令牌泄露可能导致失去对账户的访问权限。

支持的方法和服务

该库支持大量API方法。方法被分组在服务对象中。可以通过调用库中的必要方法来获取服务对象，例如

$leadsService = $apiClient->leads();

目前可用的服务如下

大多数服务都有基本方法集

  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 = []);

并非所有方法都在所有服务中都可用。调用它们将抛出异常。

某些服务具有特定方法，以下将讨论具有特定方法的服务的示例。

在leads服务中可用的方法

  1. addComplex 通过复合方法批量创建交易，支持重复控制
    1. collection (LeadsCollection) - 创建的实体模型集合
    2. 执行结果将是新创建的实体集合
    addComplex(LeadsCollection $collection);
  2. addOneComplex 通过复合方法创建一个交易，支持重复控制
    1. collection (LeadsCollection) - 创建的实体模型集合
    2. 执行结果将是新创建的交易模型
    addOneComplex(LeadModel $model);

有关使用复合创建方法的详细信息，请参阅示例

在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 通过refresh令牌获取access令牌

    1. accessToken (AccessTokenInterface) access令牌对象
    2. 执行结果将是AccessTokenInterface对象
    getAccessTokenByRefreshToken(AccessTokenInterface $accessToken);

  4. setBaseDomain 设置基本域名，其中将发送请求以处理令牌

    1. domain (string)
    setBaseDomain(string $domain);

  5. setAccessTokenRefreshCallback 设置在更新access令牌时将调用的回调

    1. function (callable)
    setAccessTokenRefreshCallback(callable $function);

  6. getOAuthButton 设置在更新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 - 用户的电子邮件，为其交换API密钥
    2. apiKey - 用户的API密钥
    3. 授权代码将发送到应用程序设置中的redirect_uri
    exchangeApiKey(string $login, string $apiKey);

关系方法可在以下服务中使用：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. 执行结果是布尔值
    unlink(BaseApiModel $model, $linkedEntities);

删除方法可在以下服务中使用：transactions、lossReasons、statuses、pipelines、customFields、customFieldsGroups、roles、customersStatuses

  1. delete

    1. model (BaseApiModel) - 实体模型
    2. 执行结果是布尔值
    deleteOne(BaseApiModel $model);

  2. deleteOne

    1. collection (BaseApiCollection) - 实体模型集合
    2. 执行结果是布尔值
    deleteOne(BaseApiModel $model);

在 customers 服务中可用的方法

  1. setMode 更改购买者模式（周期性购买或分段）。如果购买者已关闭，则将其打开。
    1. mode (string) - 模式类型（periodicity 或 segments）
    2. isEnabled (bool) - 是否启用购买者功能，默认为 true
    3. 执行结果是启用的模式名称字符串或 null（如果禁用功能）
    setMode(string $mode, bool $isEnabled = true);

在 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 服务中可用的方法

  1. getByParentId 通过父实体 ID 获取数据
    1. parentId - 父实体 ID
    2. filter (BaseEntityFilter) - 过滤器
    3. with (array) - with参数数组，该参数被服务模型支持
    getByParentId(int $parentId, BaseEntityFilter $filter = null, array $with = []);

在 account 服务中可用的方法

  1. getCurrent
    1. with (array) - with参数数组，该参数被服务模型支持
    2. 执行结果是 AccountModel 模型
    getCurrent(array $with = []);

在 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 服务中可用的方法

  1. subscribe

    1. model (WebhookModel) - 脚本钩子模型
    2. 执行结果是 WebhookModel 模型
    subscribe(WebhookModel $webhookModel);

  2. unsubscribe

    1. model (WebhookModel) - 脚本钩子模型
    2. 执行结果是布尔值
    unsubscribe(WebhookModel $webhookModel);

在 widgets 服务中可用的方法

  1. install

    1. model (WidgetModel) - 视图模型
    2. 执行结果是 WidgetModel 模型
    install(WidgetModel $widgetModel);

  2. uninstall

    1. model (WidgetModel) - 视图模型
    2. 执行结果是 WidgetModel 模型
    uninstall(WidgetModel $widgetModel);

在 products 服务中可用的方法

  1. settings

    1. 执行结果是 ProductsSettingsModel 模型
    settings();

  2. updateSettings

    1. model (ProductsSettingsModel) - 视图模型
    2. 执行结果是 ProductsSettingsModel 模型
    updateSettings(ProductsSettingsModel $productsSettings);

在 talks 服务中可用的方法

  1. close
    1. model (TalkCloseActionModel) - 关闭对话模型
    2. 执行结果是关闭对话或启动 NPS-机器人以后续关闭对话
    close(TalkCloseActionModel $closeAction)

错误处理

调用库方法可能会抛出 AmoCRMApiException 类型的错误。目前，可用的错误类型如下，它们都继承自 AmoCRMApiException

抛出的异常有以下方法

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

类型为 AmoCRMApiErrorResponseException 的错误有 getValidationErrors() 方法，它将返回输入数据验证的错误。

过滤器

目前库支持以下服务的过滤器

处理实体额外字段

以下服务的实体具有额外字段

  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

对于不同类型的字段，我们已准备不同的模型和集合

包含模型值的命名空间 - \AmoCRM\Models\CustomFieldsValues\ValueModels

包含模型值集合的命名空间 - \AmoCRM\Models\CustomFieldsValues\ValueCollections

包含额外字段模型的命名空间 - \AmoCRM\Models\CustomFieldsValues

创建实体字段值集合的代码示例

//Создадим модель сущности
$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 中传递特殊对象 \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 插件的按钮中显示，需要指定来源字段的 services 内容

 [
   {
      "type": "whatsapp",
      "pages": [
         {
            "id": "<идентификатор или номер телефона>",
            "name": "My WhatsApp",
            "link": "<номер телефона>"
         }
      ]
   }
]

要正确形成 services 字段，可以使用模型 \AmoCRM\Collections\Sources\SourceServicesCollection

默认来源

默认来源（具有 default=true 字段）只能有一个，或者根本不存在。如果没有默认来源，则交易中将显示 API 集成来源，其名称为集成名称（如通过 API 创建未解构的）。

要更改默认来源，只需将所需来源的 default 字段设置为 true，而之前的来源的 default 字段将被设置为 false。但是，在删除默认来源时，集成本身应指定新的默认来源。

集成迁移到多个来源（用于聊天集成）

默认来源可以在集成迁移到多个来源时使用，尤其是如果集成支持写入第一选项。

例如，原始状态
存在一个已连接到聊天的账户，该集成只支持1个来源。目前对我们来说，集成是通过DP还是市场平台安装的并不重要。

集成开始支持多个来源，我们将逻辑上将其分为几个阶段。

1阶段
集成可以处理API来源（但不发送和接收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 - 用于生日字段提醒属性的常量
  4. \AmoCRM\Models\Interfaces\CallInterface - 电话状态常量
  5. \AmoCRM\EntitiesServices\Interfaces\HasParentEntity - 具有父实体（目前只有笔记）的方法请求键的常量
  6. \AmoCRM\Models\CustomFieldsValues\ValueModels\ItemsCustomFieldValueModel - Items字段值的键常量
  7. \AmoCRM\Models\Rights\RightModel - 与权限相关的常量
  8. \AmoCRM\Models\AccountModel - 服务account的with参数的常量
  9. \AmoCRM\Models\TaskModel - 默认任务类型的常量
  10. \AmoCRM\Models\NoteType\TargetingNote - 支持的用于目标说明的外部服务常量（添加DP）
  11. \AmoCRM\Models\RoleModel - 服务roles的with参数的常量
  12. \AmoCRM\Models\Factories\NoteFactory - 备注类型常量
  13. \AmoCRM\Models\NoteType\MessageCashierNote - “消息给收银员”备注的状态
  14. \AmoCRM\Models\LeadModel - 服务leads的with参数的常量
  15. \AmoCRM\Filters\Interfaces\HasOrderInterface - 排序常量
  16. \AmoCRM\Models\EventModel - 服务events的with参数的常量
  17. \AmoCRM\Models\CustomFields\CustomFieldModel - 字段类型常量
  18. \AmoCRM\Models\Customers\CustomerModel - 服务customers的with参数的常量
  19. \AmoCRM\Models\ContactModel - 服务contacts的with参数的常量
  20. \AmoCRM\Models\CompanyModel - 服务companies的with参数的常量
  21. \AmoCRM\Models\CatalogElementModel - 服务catalogElements的with参数的常量
  22. \AmoCRM\Enum\InvoicesCustomFieldsEnums - 用于工作目录账单字段的常量
  23. \AmoCRM\Enum\Chats\Templates\Buttons\ButtonsEnums - 聊天模板按钮的类型
  24. \AmoCRM\Enum\Sources\SourceServiceTypeEnum - 来源服务的类型

处理账户子域更改的情况

/**
 * Получим модель с информацией о домене аккаунта по 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'];

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方法。

$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;
}

示例

在当前存储库中有一个名为examples的文件夹，其中包含各种示例。

要使用它们，需要在该文件夹中添加一个包含以下内容的.env文件，并指定您的值

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

然后，可以使用命令composer serve启动本地服务器。配置后，需要在浏览器中转到https://:8181/examples/get_token.php页面以获取访问令牌。要访问外部本地服务器，可以使用ngrok.io服务。

登录后，您可以通过浏览器访问示例来检查其功能。需要注意的是，为了确保示例能够正常运行，您需要检查其中实体ID的正确性。

处理问题

如果在使用库的过程中遇到问题，您可以提交一个Issue，它将在有机会时被处理。

在提交时，请详细描述问题，并附上代码示例以及getLastRequestInfo的响应。

请勿在示例中包含不应公开的重要数据。

也可以考虑对库进行改进的愿望。

您可以通过创建一个包含描述的Issue以及提及该Issue的Pull request来提出对库源代码的修复/更改。它们将被审查，并可能被接受或拒绝。一些Pull Request可能不会得到回应或采取行动，如果修改潜在可行，但当前不是项目的关键。

如果您遇到了amoCRM功能的问题，请通过账户中的聊天联系技术支持。

许可证

MIT