aazalan/amocrm-api-php-v4

用于与 amoCRM v2 API 进行交互的简单封装，支持通过 oAuth 2.0 协议或用户 API 密钥进行授权，支持 AJAX 请求到前端方法，请求节流，阻止同时更新单个实体，并将请求/响应日志到文件。

维护者

详细信息

github.com/aazalan/amocrm-api-php-v4

主页

源代码

安装: 45

依赖者: 0

建议者: 0

安全: 0

星标: 0

关注者: 0

分支: 12

dev-master 2023-10-13 06:34 UTC

Requires

Requires (Dev)

MIT 95f0fe81a4e880a0058dbf6e0d9dc59a57c7780f

loggingapioauth2ajaxthrottlingcrmamoCRMapi-wrapper

This package is auto-updated.

Last update: 2024-09-13 08:26:44 UTC

README

❗❗❗ 部分修改的库，适用于 API 的第 4 版。

  • 修改了部分获取实体对象的类，添加了用于编辑现有实体的 PATCH 方法。

  • 添加了 DatabaseStorage 类，用于在数据库中存储令牌。

    要在数据库中存储令牌，需要运行 migration.php 文件或自行创建一个名为 tokens 的表，包含以下字段：token_domain(VARCHAR)，token_json(JSON)，token_integration_code(VARCHAR)。token_integration_code 是一个唯一的集成识别码，用于区分在同一域名上创建的集成。在数据库中保存和加载令牌

AmoAPI::$tokenStorage = new DatabaseStorage(
[
  'host' => 'хост',
  'port' => 'порт',
  'db' => 'название базы данных',
  'user' => 'имя пользователя',
  'password' => 'пароль'
],
$integrationCode);

amoCRM logo

Latest Stable Version Total Downloads GitHub stars GitHub forks GitHub watchers License

PHP7+ 的简单封装，用于操作 REST API amoCRM v2 (版本 2)，支持通过 oAuth 2.0 协议或用户 API 密钥进行授权，支持 AJAX 请求到前端方法，API 请求节流，阻止同时更新单个实体，并将请求/响应日志到文件。

该库是为了满足 amoCRM 对公共集成提出的新要求而创建的

公共集成必须使用 oAuth 2.0 授权机制，不允许使用 API 密钥机制。自 2020 年 2 月起的要求。

自 2020 年 7 月 1 日起，用户 API 密钥信息在 amoCRM 界面中不再可用。

目前，有效的版本是 REST API amoCRM v4 (版本 4)（API 请求发送到 /api/v4/）。

REST API amoCRM v2 文档

REST API v2 文档现在在 amoCRM 的俄语版本网站上不可用。在英文版本网站上，此文档已移至 API V2 GENERAL METHODS 部分。

REST API amoCRM v2 文档的 HTML 格式存档已移至单独的 存储库。
以下是该存档的单独 HTML 文件链接

目录

要求

  • PHP >= 7.0.
  • 实现 PSR-4 标准的任意自动加载类。

安装

通过 composer 安装

$ composer require andrey-tech/amocrm-api-php:"^2.7"

或通过添加以下内容

"andrey-tech/amocrm-api-php": "^2.7"

到 composer.json 文件的 require 部分。

授权

通过 OAuth 2.0 协议进行授权（当前方法）

  • static AmoAPI::oAuth2(string $subdomain, string $clientId, string $clientSecret, string $redirectUri, string $authCode = null) :array
    • $subdomain - amoCRM 的子域或完整域名；
    • $clientId - 集成 ID；
    • $clientSecret - 集成密钥；
    • $redirectUri - 重定向 URI；
    • $authCode - 授权码（临时密钥），用于交换 access token 和 refresh token。

初始授权和交换授权代码以获取 access 令牌和 refresh 令牌

在首次授权时，将授权码 authCode 交换为 access token 和 refresh token，这些 token 与 $clientId、$clientSecret 和 $redirectUri 一起保存在令牌存储中。

use AmoCRM\{AmoAPI, AmoAPIException};
use AmoCRM\TokenStorage\TokenStorageException;

try {
    // Параметры авторизации по протоколу oAuth 2.0
    $clientId     = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee';
    $clientSecret = 'TFPoaG2A5hp3G3o6opCL8eC9v92Mm0fKQWEHBDwIjedCmVliT4kI3XQcjOOP1s';
    $authCode     = 'eee60208cc09e3ae3506d667228038345b6578a11d4862094655f630074c8c6ed87a9d804d49b5880e';
    $redirectUri  = 'https://www.example.com/oauth2/';
    $subdomain    = 'testsubdomain';

    // Первичная авторизация
    AmoAPI::oAuth2($subdomain, $clientId, $clientSecret, $redirectUri, $authCode);

    // Получение информации об аккаунте вместе с пользователями и группами
    print_r(AmoAPI::getAccount($with = 'users,groups'));

} catch (AmoAPIException $e) {
    printf('Ошибка авторизации (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
} catch (TokenStorageException $e) {
    printf('Ошибка обработки токенов (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

后续授权

在首次将授权码交换为 access token 和 refresh token 后，后续的授权只需要传递 $subdomain - amoCRM 的子域或完整域名。

use AmoCRM\{AmoAPI, AmoAPIException};
use AmoCRM\TokenStorage\TokenStorageException;

try {

    // Последующие авторизации
    $subdomain = 'testsubdomain';
    AmoAPI::oAuth2($subdomain);

    // Получение информации об аккаунте
    print_r(AmoAPI::getAccount());

} catch (AmoAPIException $e) {
    printf('Ошибка авторизации (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
} catch (TokenStorageException $e) {
    printf('Ошибка обработки токенов (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

当 access token 过期时，会自动获取新的 access token 和 refresh token，当 API 请求收到 HTTP 状态码 401 Unauthorized 的响应时。

存储 access 和 refresh 令牌

使用实现 \AmoCRM\TokenStorage\TokenStorageInterface 接口的类来保存和加载令牌。

TokenStorageInterface 接口

\AmoCRM\TokenStorage\TokenStorageInterface 接口中定义了三个方法

  • save(array $tokens, string $domain) :void 保存授权参数和令牌。
    • $tokens - 授权参数和令牌的关联数组
      [ 'access_token' => '...', 'refresh_token' => '...', 'client_id' => '...', 'client_secret' => '...', 'redirect_uri'=> '...' ];
    • $domain - amoCRM 的完整域名（例如，testsubdomain.amocrm.ru）。
  • load(string $domain) :?array 加载授权参数和令牌并返回它们。当没有保存的令牌时，方法应该返回 null。
    • $domain - amoCRM 的完整域名。
  • hasTokens(string $domain) :bool 检查是否存在给定 amoCRM 域名的令牌，即是否已执行首次授权。
    • $domain - amoCRM 的完整域名。

FileStorage 类

默认情况下，保存和加载令牌使用的是实现接口 \AmoCRM\TokenStorage\TokenStorageInterface 的类 \AmoCRM\TokenStorage\FileStorage。该类将令牌存储在 JSON 文件中，文件名与 amoCRM 的域名对应（例如，testsubdomain.amocrm.ru.json）。

可以在传递给类构造函数的参数中指定存储令牌的目录。

  • __construct(string $storageFolder = '') 类构造函数。
    • $storageFolder - 存储令牌文件的目录。可以是绝对路径或相对于当前工作目录的路径。如果传递空字符串，则创建默认目录 - 'tokens'。

在发生错误时，会抛出 \AmoCRM\TokenStorage\TokenStorageException 类的异常。

使用自定义类保存令牌

示例：使用自定义类在数据库中保存令牌。

use AmoCRM\{AmoAPI, AmoAPIException};
use AmoCRM\TokenStorage\DatabaseStorage;

try {
    // Параметры авторизации по протоколу oAuth 2.0
    $clientId     = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee';
    $clientSecret = 'TFPoaG2A5hp3G3o6opCL8eC9v92Mm0fKQWEHBDwIjedCmVliT4kI3XQcjOOP1s';
    $authCode     = 'eee60208cc09e3ae3506d667228038345b6578a11d4862094655f630074c8c6ed87a9d804d49b5880e';
    $redirectUri  = 'https://www.example.com/oauth2/';
    $subdomain    = 'testsubdomain';

    // Устанавливаем объект класса, обеспечивающего сохранение токенов
    AmoAPI::$tokenStorage = new DatabaseStorage();

    // Авторизация
    AmoAPI::oAuth2($subdomain, $clientId, $clientSecret, $redirectUri, $authCode);

    // Получение информации об аккаунте
    print_r(AmoAPI::getAccount());

} catch (AmoAPIException $e) {
    printf('Ошибка авторизации (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

示例类 \AmoCRM\TokenStorage\DatabaseStorage

<?php
namespace AmoCRM\TokenStorage;

class DatabaseStorage implements TokenStorageInterface
{
    /**
     * Сохраняет токены
     * @param  array  $tokens Токены для сохранения
     * @param  string $domain Полный домен amoCRM
     * @return void
     */
    public function save(array $tokens, string $domain)
    {
        // Здесь токены сохраняются в базе данных
    }

    /**
     * Загружает токены
     * @param  string $domain Полный домен amoCRM
     * @return array|null
     */
    public function load(string $domain)
    {
        // Здесь токены извлекаются из базы данных
    }

    /**
     * Проверяет: существуют ли токены для заданного домена amoCRM,
     * то есть была ли выполнена первичная авторизация
     * @param  string  $domain Полный домен amoCRM
     * @return boolean
     */
    public function hasTokens(string $domain) :bool
    {
        // Здесь проверяется наличие токенов в базе данных
    }
}

检查初始授权

要检查是否已对所需 amoCRM 子域进行初次授权，可以使用接口 \AmoCRM\TokenStorage\TokenStorageInterface 的 hasTokens() 方法。

use AmoCRM\{AmoAPI, AmoAPIException};
use AmoCRM\TokenStorage\{FileStorage, TokenStorageException};

try {

    // Параметры авторизации по протоколу oAuth 2.0
    $clientId     = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee';
    $clientSecret = 'TFPoaG2A5hp3G3o6opCL8eC9v92Mm0fKQWEHBDwIjedCmVliT4kI3XQcjOOP1s';
    $authCode     = 'eee60208cc09e3ae3506d667228038345b6578a11d4862094655f630074c8c6ed87a9d804d49b5880e';
    $redirectUri  = 'https://www.example.com/oauth2/';
    $subdomain    = 'testsubdomain';

    AmoAPI::$tokenStorage = new FileStorage();

    $domain = AmoAPI::getAmoDomain($subdomain);
    $isFirstAuth = ! AmoAPI::$tokenStorage->hasTokens($domain);

    if ($isFirstAuth) {
        // Первичная авторизация
        AmoAPI::oAuth2($subdomain, $clientId, $clientSecret, $redirectUri, $authCode);
    } else {
        // Последующие авторизации
        AmoAPI::oAuth2($subdomain);
    }

} catch (AmoAPIException $e) {
    printf('Ошибка авторизации (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
} catch (TokenStorageException $e) {
    printf('Ошибка обработки токенов (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

使用用户 API 密钥进行授权（已过时的方法）

自 2020 年 7 月 1 日起，用户 API 密钥信息在 amoCRM 界面中不再可用。

  • static AmoAPI::oauth(string $login, string $hash, string $subdomain) :array
    • $login - 用户登录名；
    • $hash - 用户 API 密钥；
    • $subdomain - amoCRM 的子域或完整域名。

示例：使用用户 API 密钥进行授权。

use \AmoCRM\{AmoAPI, AmoAPIException};

try {
    // Параметры авторизации по API-ключу пользователя
    $login     = 'login@example.com';
    $hash      = 'TFPoaG2A5hp3G3o6opCL8eC9v92Mm0fKQWEHBDwIjedCmVliT4kI3XQcjOOP1s';
    $subdomain = 'testsubdomain';

    // Авторизация
    AmoAPI::auth($login, $hash, $subdomain);

    // Получение информации об аккаунте
    print_r(AmoAPI::getAccount());

} catch (AmoAPIException $e) {
    printf('Ошибка авторизации (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

在多个 amoCRM 账户中同时授权

该库允许同时与多个 amoCRM 子域（账户）交互。为此，需要在每个子域中依次执行授权。

use AmoCRM\{AmoAPI, AmoAPIException};

try {
    // Авторизация в поддомене 1
    AmoAPI::oAuth2($subdomain1, $clientId1, $clientSecret1, $redirectUri1, $authCode1);

    // Авторизация в поддомене 2
    AmoAPI::auth($login2, $hash2, $subdomain2);

    //...

    // Авторизация в поддомене N
    AmoAPI::oAuth2($subdomainN, $clientIdN, $clientSecretN, $redirectUriN, $authCodeN);

} catch (AmoAPIException $e) {
    printf('Ошибка авторизации (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

配置参数

通过类 AmoAPI 的静态属性设置库的所有配置参数。

处理 amoCRM 实体

使用类-模型的方法构建与 amoCRM 实体的交互。

  • 类-模型的方法
    • AmoContact - 联系人模型；
    • AmoCompany - 公司模型；
    • AmoLead - 交易模型；
    • AmoNote - 事件（备注）模型；
    • AmoTask - 任务模型；
    • AmoCatalog - 列表（目录）模型；
    • AmoCatalogElement - 列表（目录）元素模型；
    • AmoIncomingLead - 未解析的抽象基本申报模型；
    • AmoIncomingLeadForm - 在添加来自网页表单的申报时，从未解析的申报中提取的模型；
    • AmoIncomingLeadSip - 类型为传入电话通话的未解析申报模型。
  • 通过类 AmoAPI 的额外静态方法；
  • 通过类-模型对象的公共属性访问模型的可用参数。

方法和模型常量列表

模型的基本类 AmoObject

所有模型的基础抽象类 AmoObject 包含以下公共方法

  • __construct(array $params = [], string $subdomain = null) 创建新的模型对象并填充它。
    • $params - 模型参数；
    • $subdomain - 子域或完整域名。如果为 null，则使用上次授权的子域。
  • fillById(int|string $id, array $params = []) :AmoObject 根据实体 ID 填充模型数据。
    • $id - 实体 ID；
    • $params - 在向 amoCRM 发送 GET 请求时传递的额外参数。
  • getParams() :array 返回模型的所有参数。
  • getCustomFields(array|int $ids) :array 根据字段 ID 返回额外字段。
    • $ids - 字段 ID 或字段 ID 数组。
  • getCustomFieldValueById(int $id, bool $returnFirst = true, string $returnValue = 'value') 根据字段 ID 返回额外字段值。
    • $i - 字段 ID；
    • $returnFirst - 仅返回列表中的第一个值；
    • $returnValue - 返回参数名称的值（value、enum、subtype）。
  • setCustomFields(array $params) :AmoObject 设置额外字段值。
    • $params - 额外字段值数组。
  • addTags(array|string $tags) :AmoObject 添加标签。
    • $tags - 标签或标签数组。
  • delTags(array|string $tags) :AmoObject 删除标签。
    • $tags - 标签或标签数组。
  • save(bool $returnResponse = false) 将模型对象保存到 amoCRM 并返回实体 ID。
    • $returnResponse - 返回服务器响应而不是实体 ID。

定义关联实体类型的常量

  • CONTACT_TYPE = 1 - 联系人；
  • LEAD_TYPE = 2 - 交易；
  • COMPANY_TYPE = 3 - 公司；
  • TASK_TYPE = 4 - 任务；
  • CUSTOMER_TYPE = 12 - 顾客。

AmoContact 类 - 联系人模型

  • addLeads(array|int $id) 通过 ID 关联交易。
  • addCustomers(array|int $id) 通过 ID 关联顾客。
  • addCompany(int $id) 通过 ID 关联公司。
  • getPhone() 返回联系人的第一个电话。
  • getEmail() 返回联系人的第一个电子邮件。

AmoCompany 类 - 公司模型

  • addLeads(array|int $id) 通过 ID 关联交易。
  • addContacts(array|int $id) 通过 ID 关联联系人。
  • addCustomers(array|int $id) 通过 ID 关联顾客。
  • getPhone() 返回公司的第一个电话。
  • getEmail() 返回公司的第一个电子邮件。

AmoLead 类 - 交易模型

⚠   对于来自“未整理”的请求，存在特殊方法。

  • addContacts(array|int $id) 通过联系人 ID（一个交易最多 40 个联系人）关联联系人。
  • removeContacts(array|int $id) 通过联系人 ID 解关联联系人。
  • addCompany(int $id) 通过公司 ID 关联公司。
  • removeCompany(int $id) 通过公司 ID 解关联公司。
  • setCatalogElements(array $catalogElements) 通过列表 ID 设置列表（目录）元素。

类 AmoTask - 任务模型

  • addContact(int $id) 通过 ID 关联联系人。
  • addLead(int $id) 通过 ID 关联交易。

定义任务类型的类常量

  • CALL_TASKTYPE = 1 - 电话；
  • MEET_TASKTYPE = 2 - 会议；
  • MAIL_TASKTYPE = 3 - 发送邮件。

类 AmoNote - 事件模型（备注）

定义事件类型的类常量

  • LEAD_CREATED_NOTETYPE = 1 - 创建交易；
  • CONTACT_CREATED_NOTETYPE = 2 - 创建联系人；
  • LEAD_STATUS_CHANGED_NOTETYPE = 3 - 交易状态变更；
  • COMMON_NOTETYPE = 4 - 普通备注；
  • COMPANY_CREATED_NOTETYPE = 12 - 创建公司；
  • TASK_RESULT_NOTETYPE = 13 - 任务结果；
  • SYSTEM_NOTETYPE = 25 - 系统消息；
  • SMS_IN_NOTETYPE = 102 - 进入 SMS 消息；
  • SMS_OUT_NOTETYPE = 103 - 离开 SMS 消息。

类 AmoCatalog - 列表模型（目录）

AmoCatalog 类没有自己的特定方法。

类 AmoCatalogElement - 列表元素模型（目录）

AmoCatalogElement 类没有自己的特定方法。

类 AmoIncomingLead - 未处理申请的基本模型

处理来自“未整理”的请求与处理 amoCRM 中其他实体的请求有显著区别。
根据官方文档

最初，“未整理”是单独存储的，并且是一个独立的实体，因此至今在 amoCRM 的接口和 API 中还有一些特性，这些特性区分了“未整理”状态下的交易与其他状态下的交易。

⚠   因此，对于来自“未整理”的模型，以下 AmoObject 类方法不适用

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

处理未处理申请的通用方法

抽象基本类模型来自“未整理” - AmoIncomingLead 包含以下方法

  • fillByUid(int|string $uid, array $params = []) :AmoObject 使用请求 UID 的数据填充请求模型。
    • $uid - 实体 UID；
    • $params - 在向 amoCRM 发送 GET 请求时传递的额外参数。
  • setIncomingLeadInfo(array $params) :AmoIncomingLead 设置“未整理”请求的参数。
    • $params - “未整理”参数。
  • addIncomingLead(AmoLead|array $lead) :AmoIncomingLeadSip 添加交易参数。
    • $lead - AmoLead 类对象或交易参数数组。
  • addIncomingContact(AmoContact|array $contact) :AmoIncomingLead 添加联系人参数。
    • $contact - AmoContact 类对象或联系人参数数组。
  • addIncomingCompany(AmoCompany|array $company) :AmoIncomingLead 添加公司参数。
    • $company - AmoCompany 类的实例或公司参数数组。
  • save(bool $returnResponse = false) 将新的申请添加到未解析中，并返回包含申请 UID 的数组。
    • $returnResponse - 返回服务器响应而不是 UID。

用于批量添加申请到 amoCRM 以及接受或拒绝未解析申请的静态方法位于 AmoAPI 类中。

类 AmoIncomingLeadForm - 从网页表单添加的未处理申请模型

AmoIncomingLeadForm 子类没有自己的特定方法。

类 AmoIncomingLeadSip - 类型为来电的未处理申请模型

AmoIncomingLeadSip 子类没有自己的特定方法。

加载实体的方法

AmoAPI 类包含以下用于加载实体的通用静态方法

  • static getAll<Entities> (array $params, bool $returnResponse = false, string $subdomain = null) :\Generator 加载指定类型 <Entities> 的所有实体，支持过滤。
    返回一个 \Generator 对象，用于后续提取实体参数。
    • <Entities>:
      • Contacts
      • Companies
      • Leads
      • Tasks
      • Notes
      • CatalogElements
      • IncomingLeads
    • $params - 过滤参数；
    • $returnResponse - 返回 amoCRM 服务器完整响应而不是实体参数数组；
    • $subdomain - amoCRM 的子域名或完整域名。如果为 null，则使用最后一个授权的子域名。
  • static get<Entities>(array $params, bool $returnResponse = false, string $subdomain = null) :?array
    加载指定类型 <Entities> 的实体，支持过滤和分页。
    返回实体参数数组用于填充模型或 null。
    • <Entities>:
      • Contacts
      • Companies
      • Leads
      • Tasks
      • Notes
      • Webhooks
      • Widgets
      • IncomingLeads
      • IncomingLeadsSummary
      • Pipelines
      • Catalogs
      • CatalogElements
    • $params - 过滤和分页参数；
    • $returnResponse - 返回 amoCRM 服务器完整响应而不是实体参数数组；
    • $subdomain - amoCRM 的子域名或完整域名。如果为 null，则使用最后一个授权的子域名。

批量保存实体的方法

AmoAPI 类包含静态方法，用于批量保存（添加或更新）最多 500 个不同类型的实体，针对单个 amoCRM 子域名。

根据 官方文档

建议创建或修改的实体数量不超过 500，为了集成更高效以及避免错误，建议不超过 250。在遇到 504 错误时，建议减少请求中实体数量并重试。

  • static saveObjects(array $amoObjects, bool $returnResponses = false, string $subdomain = null) :array
    在 amoCRM 中添加或更新实体。返回实体参数数组。
    • $amoObjects 是模型类对象的数组（每种类型的对象不超过 500 个）：AmoContact、AmoCompany 等；
    • $returnResponses - 返回 amoCRM 服务器响应数组而不是实体参数数组；
    • $subdomain - amoCRM 的子域名或完整域名。如果为 null，则使用最后一个授权的子域名。
  • static saveObjectsWithLimit(array $amoObjects, bool $returnResponses = false, string $subdomain = null, $limit = 250) :array
    在 amoCRM 中添加或更新实体，限制单个 API 请求中的实体数量。返回实体参数数组。
    • $amoObjects 是模型类对象的数组：AmoContact、AmoCompany 等；
    • $returnResponses - 返回 amoCRM 服务器响应数组而不是实体参数数组；
    • $subdomain - amoCRM 的子域名或完整域名。如果为 null，则使用最后一个授权的子域名；
    • $limit - 单个 API 请求中的最大实体数量。

批量删除实体的方法

AmoAPI 类包含用于批量删除列表和列表元素的静态方法

  • static delteObjects(array $amoObjects, bool $returnResponses = false, string $subdomain = null) :array
    在 amoCRM 中删除实体。返回空实体参数数组。
    • $amoObjects 是模型类对象的数组：AmoCatalog 或 AmoCatalogElement；
    • $returnResponses - 返回 amoCRM 服务器响应数组而不是空实体参数数组；
    • $subdomain - amoCRM 的子域名或完整域名。如果为 null，则使用最后一个授权的子域名。

webhooks 的方法

AmoAPI 类包含用于添加和删除 webhooks 的静态方法

  • static addWebhooks(array $params, bool $returnResponse = false, string $subdomain = null) :array
    添加一个 webhook 或多个 webhook（不超过 100 个）。
    • params - webhook 参数或 webhook 参数数组；
    • $returnResponse - 返回 amoCRM 服务器响应数组而不是 webhook 参数数组；
    • $subdomain - amoCRM 的子域名或完整域名。如果为 null，则使用最后一个授权的子域名。
  • static deleteWebhooks(array $params, bool $returnResponse = false, string $subdomain = null) :array
    删除一个或多个webhook（不超过100个）。
    • params - webhook 参数或 webhook 参数数组；
    • $returnResponse - 返回 amoCRM 服务器响应数组而不是 webhook 参数数组；
    • $subdomain - amoCRM 的子域名或完整域名。如果为 null，则使用最后一个授权的子域名。

未处理的方法

AmoAPI类包含以下静态方法，用于处理未解析的请求：

  • static saveIncomingObjects(AmoIncomingLeadForm|AmoIncomingLeadSip|array $amoObjects, bool $returnResponses = false, string $subdomain = null) :array
    批量添加请求到未解析。返回未解析的UID参数数组。
    • $amoObjects - AmoIncomingLeadForm或AmoIncomingLeadSip类对象或这些对象的数组；
    • $returnResponses - 返回amoCRM服务器的响应数组，而不是UID数组；
    • $subdomain - amoCRM 的子域名或完整域名。如果为 null，则使用最后一个授权的子域名。
  • static saveIncomingObjectsWithLimit(AmoIncomingLeadForm|AmoIncomingLeadSip|array $amoObjects, bool $returnResponses = false, string $subdomain = null, $limit = 250) :array
    批量添加请求到未解析，每个API请求限制请求的数目。返回未解析的UID数组。
    • $amoObjects - AmoIncomingLeadForm或AmoIncomingLeadSip类对象或这些对象的数组；
    • $returnResponses - 返回amoCRM服务器的响应数组，而不是UID数组；
    • $subdomain - amoCRM 的子域名或完整域名。如果为 null，则使用最后一个授权的子域名；
    • $limit - 每个API请求的最大请求数；
  • static acceptIncomingLeads(array $params, bool $returnResponse = false, $subdomain = null) :array
    • params - 请求参数；
    • $returnResponse - 返回amoCRM服务器的响应，而不是接收到的请求参数数组；
    • $subdomain - amoCRM 的子域名或完整域名。如果为 null，则使用最后一个授权的子域名。
  • static declineIncomingLeads(array $params, bool $returnResponse = false, $subdomain = null) :array
    • params - 请求参数；
    • $returnResponse - 返回amoCRM服务器的响应，而不是拒绝的请求参数数组；
    • $subdomain - amoCRM 的子域名或完整域名。如果为 null，则使用最后一个授权的子域名。

附加方法

AmoAPI类的其他静态方法

  • static getAccount(string $with = '', string $subdomain = null) :array
    返回amoCRM账户信息。
    • $with - 返回账户的附加参数列表，包括：
      • custom_fields - 实体的额外字段；
      • users - 用户；
      • pipelines - 流程；
      • groups - 用户组；
      • note_types - 事件类型（备注）；
      • task_types - 任务类型。
    • $subdomain - amoCRM 的子域名或完整域名。如果为 null，则使用最后一个授权的子域名。
  • static getAccountDomain(string $subdomain = null) :array
    在通过oAuth2.0协议认证时，返回amoCRM账户域的信息。
    • $subdomain - amoCRM 的子域名或完整域名。如果为 null，则使用最后一个授权的子域名。
  • static getLastResponse(bool $unescapeUnicode = true) :?string
    以原始形式返回amoCRM服务器的最后响应。
    • $unescapeUnicode - 解码服务器响应中的UTF-8 \uXXXX字符。
  • static request(string $query, string $type = 'GET', array $params = [], string $subdomain = null) :?array
    • $query - 请求URL的路径；
    • $type - 请求方法 'GET', 'POST' 或 'AJAX'；
    • $params - 请求参数；
    • $subdomain - 子域或完整域名。如果为 null，则使用上次授权的子域。
  • static getAmoDomain(string $subdomain) :string
    返回amoCRM的完整域名。
    • $subdomain - amoCRM 的子域或完整域名。

防止单个实体同时更新

在API amoCRM中，当在API的不同进程或执行流中同时更新具有相同ID的同一实体（交易、联系人、公司等）时，可能会因为请求更新时随请求一起传递的实体值updated_at而出现错误"Last modified date is older than in database"。

为防止出现此类错误，在save()方法中实现了阻止同时更新同一实体的机制。在第一个启动的进程（执行流）更新实体完成之前，即收到amoCRM API的响应之前，其他竞争更新同一实体的进程将暂停，并每AmoAPI::$lockEntityTimeout秒尝试重复更新实体，最大尝试次数为AmoAPI::$lockEntityAttempts。

对 API 请求进行节流

为防止在单个进程或执行流中超出对amoCRM API的最大请求次数（每秒不超过7个请求），在库中实现了一个简单的请求节流算法，该算法基于计算自上次发送API请求以来经过的时间，并在1/AmoAPI::$throttle秒内暂停进程。

调试模式和日志记录

当启用调试模式AmoAPI::$debug = true时，API amoCRM的每个请求/响应信息都将输出到STDOUT。

为了记录每个API请求/响应，amoCRM可以使用实现PSR-3标准的任意日志类，或者简单的日志类AmoAPIDebugLogger。日志类对象通过属性AmoAPI::$debugLogger设置。日志记录独立于调试模式AmoAPI::$debug的状态。每次向API请求/响应时，在日志类中调用debug()方法。

AmoAPIDebugLogger类的构造函数可以传递日志文件名

  • __construct(string $logFile = 'logs/debug.log')
    • $logFile - 日志文件。

错误处理

在发生错误时，会抛出一个包含\AmoCRM\AmoAPIException类对象的异常。
AmoAPIException异常类包含以下辅助方法

  • getErrors() :array 返回amoCRM服务器响应的错误消息数组（errors）;
  • getItems() :array 返回amoCRM服务器响应的实体参数数组（items）。

示例

处理联系人

use AmoCRM\{AmoAPI, AmoContact, AmoAPIException};

try {
    // Авторизация
    $subdomain = 'testsubdomain';
    AmoAPI::oAuth2($subdomain);

    // Загрузка ВСЕХ контактов с возможностью фильтрации
    $generator = AmoAPI::getAllContacts([
        'query' => 'Ганс'
    ]);
    foreach ($generator as $items) {
        foreach ($items as $item) {
            print_r($item);
        }
    }

    // Загрузка контактов с возможностью фильтрации и постраничной выборки
    $items = AmoAPI::getContacts([
        'limit_rows'   => 100,
        'limit_offset' => 1000
    ]);
    foreach ($items as $item) {
        print_r($item);
    }

    // -------------------------------------------------------------------------

    // Создание нового контакта
    $contact1 = new AmoContact([
        'name'                => 'Ганс-Дитрих Геншер',
        'responsible_user_id' => 12345678
    ]);

    // Установка дополнительных полей
    $contact1->setCustomFields([
        '6532343' => 41,
        '123456' => [[
            'value' => '+79451112233',
            'enum'  => 'WORK'
        ]],
        '123467' => [[
            'value' => 'hans@example.com',
            'enum'  => 'WORK'
        ]]
    ]);

    // Сохранение контакта и получение его ID
    $contact1Id = $contact1->save();

    // Обновление существующего контакта и получение ответа сервера amoCRM
    $contact2 = new AmoContact([
        'id'         => 12300344,
        'name'       => 'Улоф Йоаким Пальме'
    ]);
    $contact2->first_name = 'Улоф';
    $contact2->last_name  = 'Пальме';
    print_r($contact1->save($returnResponse = true));

    // Пакетное добавление и/или обновление контактов
    $items = AmoAPI::saveObjects([ $contact1, $contact2 ]);
    foreach ($items as $item) {
        print_r($item);
    }

    // -------------------------------------------------------------------------

    // Заполнение модели контакта по ID контакта
    $contact3 = new AmoContact();
    $contact3->fillById(12345679);

    // Получение всех дополнительных полей контакта
    print_r($contact3->custom_fields);

    // Получение всех параметров контакта из модели
    print_r($contact3->getParams());

    // Получение дополнительных полей контакта по ID полей
    print_r($contact3->getCustomFields([ 123456, 123467 ]));    

    // Получение первого значения дополнительного поля контакта по ID поля
    print_r($contact3->getCustomFieldValueById(155114));

    // Получение всех значений дополнительного поля контакта по ID поля
    print_r($contact3->getCustomFieldValueById(155116, $returnFirst = false));

    // Получение первого ENUM дополнительного поля контакта по ID поля
    print_r($contact3->getCustomFieldValueById(155116, $returnFirst = true, $returnValue = 'enum'));

    // Получение всех ENUM дополнительного поля контакта по ID поля
    print_r($contact3->getCustomFieldValueById(155116, $returnFirst = false, $returnValue = 'enum'));

    // -------------------------------------------------------------------------

    // Привязка сделок к контакту по ID сделок
    $contact3->addLeads([ 12380925, 12364352 ]);

    // Привязка покупателей к контакту по ID покупателей
    $contact3->addCustomers([ 1237374, 1239658 ]);

    // Добавление тегов к контакту
    $contact3->addTags([ 'сотрудник', 'стажер' ]);

    // Удаление тегов контакта
    $contact3->delTags('курьер');

    // Сохранение контакта
    $contact3->save();

    // -------------------------------------------------------------------------

    $items = AmoAPI::getContacts([
        'responsible_user_id' => 12373452
    ]);

    // Пакетная привязка сделки к контактам
    $contacts = [];
    foreach ($items as $item) {
        $contacts[] = (new AmoContact($item))->addLeads(12380925);
    }

    // Пакетное сохранение контактов
    AmoAPI::saveObjects($contacts);

} catch (AmoAPIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

处理公司

use AmoCRM\{AmoAPI, AmoCompany, AmoAPIException};

try {
    // Авторизация
    $subdomain = 'testsubdomain';
    AmoAPI::oAuth2($subdomain);

    // Загрузка ВСЕХ компаний с возможностью фильтрации
    $generator = AmoAPI::getAllCompanies([
        'query'        => 'OOO',
        'limit_offset' => 12000        
    ]);
    foreach ($generator as $items) {
        foreach ($items as $item) {
            print_r($item);
        }
    }

    // Загрузка компаний с возможностью фильтрации и постраничной выборки
    $items = AmoAPI::getCompanies([
        'responsible_user_id' => 12357492,
        'limit_rows'          => 250,
        'limit_offset'        => 1000
    ]);
    foreach ($items as $item) {
        print_r($item);
    }

    // -------------------------------------------------------------------------

    // Создание новой компании
    $company1 = new AmoCompany([
        'name'                => 'ООО МММ',
        'responsible_user_id' => 12358394,
    ]);

    // Установка дополнительных полей
    $company1->setCustomFields([
        '2390423' => 'Город Москва',
        '123456' => [[
            'value' => '+79457778899',
            'enum'  => 'WORK'
        ]],
        '123467' => [[
            'value' => 'mmm@example.com',
            'enum'  => 'WORK'
        ]]
    ]);

    // Привязка контакта
    $company1->addContacts(12375435);

    // Привязка сделки
    $company1->addLeads(12349693);

    // Привязка покупателя
    $company1->addCustomers(1237374);

    // Добавление тега
    $company1->addTags('Акционер');

    // Сохранение компании и получение ее ID
    $companyId = $company1->save();

    // Обновление существующей компании и получение ответа сервера amoCRM
    $company2 = new AmoCompany([
        'id'         => 12375435,
        'created_by' => 12396034,
        'name'       => 'ООО Рога и Копыта',
    ]);
    $response = $company2->save($returnResponse = true);

    // Пакетное добавление и/или обновление компаний
    $items = AmoAPI::saveObjects([ $company1, $company2 ]);
    foreach ($items as $item) {
        print_r($item);
    }

    // -------------------------------------------------------------------------

    // Заполнение модели компании по ID
    $company3 = new AmoCompany();
    $company3->fillById(12375435);

    // Получение всех параметров компании из модели
    print_r($company3->getParams());

    // Получение дополнительных полей компании по ID полей
    print_r($company3->getCustomFields([ 123456, 123467, 2390423 ]));    

    // Получение первого значения дополнительного поля компании по ID поля
    print_r($company3->getCustomFieldValueById(2390423));

    // Получение всех значений дополнительного поля компании по ID поля
    print_r($company3->getCustomFieldValueById(2390423, $returnFirst = false));

    // Получение первого subtype дополнительного поля компании по ID поля
    print_r($company3->getCustomFieldValueById(2390423, $returnFirst = true, $returnValue = 'subtype'));

    // Получение первого ENUM дополнительного поля компании по ID поля
    print_r($company3->getCustomFieldValueById(2390423, $returnFirst = true, $returnValue = 'enum'));

    // -------------------------------------------------------------------------

    $items = AmoAPI::getCompanies([
        'responsible_user_id' => 12358394
    ]);

    // Пакетная привязка сделки к компаниям
    $companies = [];
    foreach ($items as $item) {
        $companies[] = (new AmoCompany($item))->addLeads([ 12380925 ]);
    }

    // Пакетное сохранение компаний
    AmoAPI::saveObjects($companies);

} catch (AmoAPIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

处理交易

处理未解析的请求与处理交易有很大不同。对于它们，使用特殊方法。

use AmoCRM\{AmoAPI, AmoLead, AmoAPIException};

try {
    // Авторизация
    $subdomain = 'testsubdomain';
    AmoAPI::oAuth2($subdomain);

    // Загрузка ВСЕХ сделок с возможностью фильтрации
    $generator = AmoAPI::getAllLeads([
        'responsible_user_id' => 12357492
    ]);
    foreach ($generator as $items) {
        foreach ($items as $item) {
            print_r($item);
        }
    }

    // Загрузка сделок с возможностью фильтрации и постраничной выборки
    $items = AmoAPI::getLeads([
        'limit_rows'          => 250,
        'limit_offset'        => 2000
    ]);
    foreach ($items as $item) {
        print_r($item);
    }

    // -------------------------------------------------------------------------

    // Создание новой сделки
    $lead1 = new AmoLead([
        'name'                => 'Заказ № 964023',
        'responsible_user_id' => 12358394,
        'pipeline'            => [ 'id' => 45232121 ],
        'status_id'           => 142,
        'sale'                => 15000
   ]);

    // Установка дополнительных полей
    $lead1->setCustomFields([
        '3434323' => 'Акционерное общество',
        '3434327' => [ 1121, 1122, 1123 ]
    ]);

    // Привязка контакта
    $lead1->addContacts(12375435);

    // Привязка компании
    $lead1->addCompany(12364643);

    // Установка элементов списка
    $lead1->setCatalogElements([
        93492 => [
            9898 => 10,
            9899 => 5
        ]
    ]);

    // Добавление тега
    $lead1->addTags('Акционер');

    // Сохранение сделки и получение ее ID
    $leadId = $lead1->save();

    // Обновление существующей компании и получение ответа сервера amoCRM
    $lead2 = new AmoLead([
        'id'         => 123057838,
        'sale'       => 175000
    ]);
    $response = $lead2->save($returnResponse = true);

    // Пакетное добавление и/или обновление сделок
    $items = AmoAPI::saveObjects([ $lead1, $lead2 ]);
    foreach ($items as $item) {
        print_r($item);
    }

    // -------------------------------------------------------------------------

    // Заполнение модели сделки по ID
    $lead3 = new AmoLead();
    $lead3->fillById(12328958);

    // Отвязка контакта от сделки
    $lead3->removeContacts(12345678);

    // Отвязка компании от сделки
    $lead3->removeCompany(12345671);

    // Получение параметров сделки из модели
    print_r($lead3->getParams());

    // Получение дополнительных полей сделки по ID полей
    print_r($lead3->getCustomFields([ 123456, 123467, 2390423 ]));    

    // Получение первого значения дополнительного поля сделки по ID поля
    print_r($lead3->getCustomFieldValueById(2390423));

    // Получение всех значений дополнительного поля сделки по ID поля
    print_r($lead3->getCustomFieldValueById(2390423, $returnFirst = false));

    // Получение всех ENUM дополнительного поля сделки по ID поля
    print_r($lead3->getCustomFieldValueById(2390423, $returnFirst = true, $returnValue = 'enum'));

    // -------------------------------------------------------------------------

    $leads = AmoAPI::getLeads([
        'responsible_user_id' => 12358394
    ]);

    // Пакетная привязка компании к сделкам
    $leads = [];
    foreach ($items as $item) {
        $leads[] = (new AmoLead($item))->addCompany(12380925);
    }

    // Пакетное сохранение сделок
    AmoAPI::saveObjects($leads);

} catch (AmoAPIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

处理事件

use AmoCRM\{AmoAPI, AmoNote, AmoAPIException};

try {
    // Авторизация
    $subdomain = 'testsubdomain';
    AmoAPI::oAuth2($subdomain);

    // Загрузка ВСЕХ событий, привязанных к сделкам, с возможностью фильтрации
    $generator = AmoAPI::getAllNotes([
        'type'       => 'lead',
        'note_type'  => AmoNote::COMMON_NOTETYPE
    ]);
    foreach ($generator as $items) {
        foreach ($items as $item) {
            print_r($item);
        }
    }

    // Загрузка событий, привязанных к контактам, с возможностью фильтрации и постраничной выборки
    $items = AmoAPI::getLeads([
        'type'           => 'contact',
        'limit_rows'     => 250,
        'limit_offset'   => 2000
    ]);
    foreach ($items as $item) {
        print_r($item);
    }

    // -------------------------------------------------------------------------
    
    // Создание нового события типа "обычное примечание", привязанного к сделке
    $note = new AmoNote([
        'element_id'   => 12328687,
        'note_type'    => AmoNote::COMMON_NOTETYPE,
        'element_type' => AmoNOTE::LEAD_TYPE,
        'text'         => 'Текст примечания к сделке'
    ]);

    // Сохранение события и получение его ID
    $noteId = $note->save();

    // Обновление существующего события
    $note2 = new AmoNote([
        'id'   => 12300958,
        'text' => 'Обновленный текст события'
    ]);

    // Заполнение модели события по ID и изменение текста события
    $note3 = new AmoNote();
    $note3->fillById(12347842);
    $note3->text = 'Новый тест события';

    // Получение параметров события из модели
    print_r($note3->getParams());

    // Пакетное сохранение событий
    AmoAPI::saveObjects([ $note2, $note3 ]);

} catch (AmoAPIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

处理任务

use AmoCRM\{AmoAPI, AmoTask, AmoAPIException};

try {
    // Авторизация
    $subdomain = 'testsubdomain';
    AmoAPI::oAuth2($subdomain);

    // Загрузка ВСЕХ задач, привязанных к сделкам, с возможностью фильтрации
    $generator = AmoAPI::getAllTasks([
        'type'   => 'lead',
        'filter' => [
            'task_type' => [ AmoTask::CALL_TASKTYPE, AmoTask::MAIL_TASKTYPE ]
        ]
    ]);
    foreach ($generator as $items) {
        foreach ($items as $item) {
            print_r($item);
        }
    }

    // Загрузка задач, с возможностью фильтрации и постраничной выборки
    $items = AmoAPI::getTasks([
        'responsible_user_id' => 12381202,
        'limit_rows'          => 100,
        'limit_offset'        => 800
    ]);
    foreach ($items as $item) {
        print_r($item);
    }

    // -------------------------------------------------------------------------

    // Создание новой задачи типа "написать письмо", привязанной к контакту
    $task = new AmoTask([
        'task_type'        => AmoTASK::MAIL_TASKTYPE,
        'element_type'     => AmoTask::CONTACT_TYPE,
        'element_id'       => 12367433,
        'text'             => 'Необходимо написать письмо',
        'complete_till_at' => 1508706000
    ]);

    // Сохранение задачи и получение её ID
    $taskId = $task->save();

    // Обновление существующей задачи
    $task2 = new AmoTask([
        'id'   => 12311954,
        'text' => 'Обновленный текст задачи'
    ]);

    // Привязка сделки к задаче по ID
    $task2->addLead(12389536);

    // Заполнение модели задачи по ID и изменение текста задачи
    $task3 = new AmoTask();
    $task3->fillById(12327872);
    $task3->text = 'Новый тест события';

    // Получение параметров задачи из модели
    print_r($task3->getParams());

    // Пакетное сохранение задач
    AmoAPI::saveObjects([ $task2, $task3 ]);

} catch (AmoAPIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

处理列表（目录）

use AmoCRM\{AmoAPI, AmoCatalog, AmoAPIException};

try {
    // Авторизация
    $subdomain = 'testsubdomain';
    AmoAPI::oAuth2($subdomain);

    // Загрузка перечня списков с возможностью фильтрации
    $items = AmoAPI::getCatalogs();
    foreach ($items as $item) {
        print_r($item);
    }

    // Создание нового списка
    $catalog = new AmoCatalog([
        'name' => 'Товары на складе'
    ]);

    // Сохранение списка и получение его ID
    $catalogId = $catalog->save();

    // Обновление существующего списка
    $catalog2 = new AmoCatalog([
        'id'   => 7185,
        'name' => 'Не товары'
    ]);

    // Заполнение модели списка по ID и изменение названия списка 
    $catalog3 = new AmoCatalog();
    $catalog3->fillById(7187);
    $catalog3->name = 'Актуальные товары';

    // Получение параметров списка из модели
    print_r($catalog3->getParams());

    // Пакетное сохранение списков
    AmoAPI::saveObjects([ $catalog2, $catalog3 ]);

    // Пакетное удаление списков
    AmoAPI::deleteObjects([ $catalog2, $catalog3 ]);

} catch (AmoAPIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

处理列表元素（目录）

use AmoCRM\{AmoAPI, AmoCatalogElement, AmoAPIException};

try {
    // Авторизация
    $subdomain = 'testsubdomain';
    AmoAPI::oAuth2($subdomain);

    // Загрузка ВСЕХ элементов заданного списка с возможностью фильтрации
    $generator = AmoAPI::getAllCatalogElements([
        'catalog_id' => 4422,
        'term'   => 'Маркер'
    ]);
    foreach ($generator as $items) {
        foreach ($items as $item) {
            print_r($item);
        }
    }

    // Загрузка элементов заданного списка с фильтрацией с постраничной выборкой
    $items = AmoAPI::getCatalogElements([
        'catalog_id' => 4422,
        'term'       => 'Фломастер',
        'page'       => 21
    ]);
    foreach ($items as $item) {
        print_r($item);
    }

    // -------------------------------------------------------------------------

    // Создание нового элемента каталога
    $element = new AmoCatalogElement([
        'catalog_id' => 4422,
        'name'       => 'Ручка гелевая'
    ]);

    // Установка дополнительных полей
    $element->setCustomFields([
        '20423' => 'Артикул 14567323',
        '24233' => 120
    ]);

    // Сохранение элемента списка и получение его ID
    $elementId = $element->save();

    // Обновление существующего элемента списка
    $element2 = new AmoCatalogElement([
        'id'   => 12312312,
        'text' => 'Ручка перьевая'
    ]);

    // Заполнение модели элемента списка по ID и изменение имени элемента
    $element3 = new AmoCatalogElement();
    $element3->fillById(12398096);
    $element3->name = 'Карандаш';

    // Получение параметров элемента списка из модели
    print_r($element3->getParams());

    // Пакетное сохранение элементов
    AmoAPI::saveObjects([ $element2, $element3 ]);

    // Пакетное удаление элементов
    AmoAPI::deleteObjects([ $element2, $element3 ]);

} catch (AmoAPIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

处理 webhooks

use AmoCRM\{AmoAPI, AmoAPIException};

try {

    // Авторизация
    $subdomain = 'subdomain';
    AmoAPI::oAuth2($subdomain);

    // Получаем список установленных webhooks
    $webhooks = AmoAPI::getWebhooks();
    print_r($webhooks);

    // Добавляем webhook
    AmoAPI::addWebhooks([
        'url'    => 'https://example.com/webhook/',
        'events' => [ 'add_lead' ]
    ]);

    // Удаляем webhook
    AmoAPI::deleteWebhooks([
        'url'    => 'https://example.com/webhook/',
        'events' => [ 'add_lead' ]
    ]);

    // Добавляем несколько webhooks
    AmoAPI::addWebhooks([
        [
            'url'    => 'https://example1.com/webhook/',
            'events' => [ 'add_lead' ]
        ],
        [
            'url'    => 'https://example2.com/webhook/',
            'events' => [ 'update_lead' ]
        ]
    ]);

    // Удаляем несколько webhooks
    AmoAPI::deleteWebhooks([
        [
            'url'    => 'https://example1.com/webhook/',
            'events' => [ 'add_lead' ]
        ],
        [
            'url'    => 'https://example2.com/webhook/',
            'events' => [ 'update_lead' ]
        ]
    ]);

} catch (AmoAPIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

处理未处理的申请

处理来自“未整理”的请求与处理 amoCRM 中其他实体的请求有显著区别。
根据官方文档

最初，“未整理”是单独存储的，并且是一个独立的实体，因此至今在 amoCRM 的接口和 API 中还有一些特性，这些特性区分了“未整理”状态下的交易与其他状态下的交易。

以下是在从网页表单添加时处理未解析请求的示例。

use AmoCRM\{AmoAPI, AmoLead, AmoContact, AmoIncomingLeadForm, AmoAPIException};

try {

    // Авторизация
    $subdomain = 'testsubdomain';
    AmoAPI::oAuth2($subdomain);

    // Создаем новую заявку в неразобранном при добавлении из веб-формы
    $incomingLead = new AmoIncomingLeadForm();

    // Устанавливаем обязательные параметры 
    $incomingLead->setIncomingLeadInfo([
        'form_id'   => 1,
        'form_page' => 'https://www.example.com',
        'form_name' => 'Home page form'
    ]);

    // Добавляем параметры сделки
    $lead = new AmoLead([
        'name' => 'Новая заявка с сайта'
    ]);
    $lead->setCustomFields([ 25475362 => '#1543252' ]);
    $incomingLead->addIncomingLead($lead);

    // Добавляем параметры контакта
    $contact = new AmoContact([
       'name' => 'Ганс-Дитрих Геншер'
    ]);
    $contact->setCustomFields([
        255114 => [[
            'value' => '+10349654820',
            'enum'  => 'WORK'
        ]],
        255116 => [[
            'value' => 'hans@example.com',
            'enum'  => 'WORK'
       ]]
    ]);
    $incomingLead->addIncomingContact($contact);

    // Добавляем параметры компании
    $incomingLead->addIncomingCompany([
        'name' => 'Freie Demokratische Partei'
    ]);

    // Сохраняем заявку
    AmoAPI::saveIncomingObjects($incomingLead);

    // ------------------------------------------------------------------------

    // Получаем заявку из неразобранного по UID
    $uid = 'f03c796fb5455667e648dd0ec9755fc9680bc3775ac76a540753d249d455';
    $incomingLead2 = new AmoIncomingLeadForm();
    $incomingLead2->fillByUid($uid);
    print_r($incomingLead2->getParams());

    // Загрузка ВСЕХ заявок из неразобранного с фильтрацией по категории
    $generator = AmoAPI::getAllIncomingLeads([
        'categories'   => [ 'forms' ]
    ]);
    foreach ($generator as $items) {
        foreach ($items as $item) {
            print_r($item);
        }
    }

    // ------------------------------------------------------------------------

    // Принимаем заявки из неразобранного
    AmoAPI::acceptIncomingLeads([
        'accept' => [
            'f03c796fb5455667e648dd0ec9755fc9680bc3775ac76a540753d249d455',
            'a12c723fb54556676e6487d0e89795fc9080bc3975ac86a548752302d478',
        ],
        'user_id'   => 13752426,
        'status_id' => 142
    ]);

    // Отклоняем заявки из неразобранного
    AmoAPI::declineIncomingLeads([
      'decline' => [ 'e21c796dfb5sd566de648ccb80ec546a4d25e4baecbd343actf0b3ed4363c4' ],
      'user_id' => 13752426
    ]);

} catch (AmoAPIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

支持 AJAX 请求到前端方法

\AmoCRM\AmoAPI::request()方法允许执行针对前端方法的AJAX请求。

use AmoCRM\{AmoAPI, AmoAPIException};

try {

    // Авторизация
    $subdomain = 'testsubdomain';
    AmoAPI::oAuth2($subdomain);

    $params = [
        'filter' => [
            'cf'=> [
                '681165'=> [
                    'from' => '30.03.2022',
                    'to' => '30.03.2022'
                ]
            ],
        ],
        'useFilter' => 'y',
        'element_type' => 1,
        'json' => 1,
        'page' => 1
    ];

    $data = AmoAPI::request('/ajax/contacts/list', 'AJAX', $params);

    print_r($data);    

} catch (AmoAPIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

示例响应（片段）

{
    "response": {
        "url": "\/contacts\/list\/contacts\/",
        "items": [
            {
                "id": 68207643,
                "tags": {
                    "items": []
                },
                "url": "\/contacts\/detail\/68207643",
                "element_type": 1,
                "entity": "contact",
                "is_deleted": false,
                "rights": {
                    "contacts": {
                        "edit": true
                    },
                    "companies": {
                        "edit": true
                    }
                },
                "class_name": "",
                "name": {
                    "text": "Звонок от 79521111111",
                    "url": "\/contacts\/detail\/68207643"
                },
                "company_name": {
                    "name": "",
                    "url": "#"
                },
                "manager": "Иван Петров",
                "date_create": "Сегодня 11:30",
                "creator": "Робот",
                "date_modified": "Сегодня 11:31",
                "modified_by": "Робот",
                "date_of_nearest_task": {
                    "date": 1652641199,
                    "failed": false
                },
                "custom_fields": [
                    {
                        "id": "72797",
                        "name": "Телефон",
                        "values": [
                            {
                                "enum": "112761",
                                "value": "+7 952 111-11-11"
                            }
                        ]
                    }
                ],
...

处理多个子域

use AmoCRM\{AmoAPI, AmoCompany, AmoAPIException};

try {
    // Авторизация в поддомене 1
    // ...
    AmoAPI::oAuth2($subdomain1, $clientId1, $clientSecret1, $redirectUri1, $authCode1);

    // Авторизация в поддомене 2
    // ...
    AmoAPI::oAuth2($subdomain2, $clientId2, $clientSecret2, $redirectUri2, $authCode2);

    // Загрузка компаний из поддомена 1
    $items1 = AmoAPI::getCompanies([
        'responsible_user_id' => 12357492
    ], $subdomain1);

    // Загрузка всех компаний из поддомена 2
    $generator2 = AmoAPI::getAllCompanies([
        'query' => 'OOO'
    ], $subdomain2);

    // Создание новой компании для поддомена 1
    $company1 = new AmoCompany([
        'name' => 'ООО Абракадабра',
    ], $subdomain1);

    // Обновление существующей компании для поддомена 1
    $company2 = new AmoCompany([], $subdomain1);
    $company2->fillById(12389423);
    $company2->name = 'OOO Розенталь';

    // Пакетное сохранение компаний для поддомена 1
    AmoAPI::saveObjects([ $company1, $company2 ], $subomain1);

} catch (AmoAPIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

调试和日志记录

use AmoCRM\{AmoAPI, AmoAPIDebugLogger, AmoAPIException};

try {
    // Включение вывода запросов/ответов к API в STDOUT
    AmoAPI::$debug = true;

    // Включение логирования запросов/ответов к API в файл
    AmoAPI::$debugLogger = new AmoAPIDebugLogger($logFile = 'logs/debug_amocrm_api.log');

    // Авторизация
    $subdomain = 'testsubdomain';
    AmoAPI::oAuth2($subdomain);

} catch (AmoAPIException $e) {
    printf('Ошибка (%d): %s' . PHP_EOL, $e->getCode(), $e->getMessage());
}

类 UML 图

amoCRM API class diagram UML

作者

© 2019-2021 andrey-tech

许可证

本库根据MIT许可证分发。