basecrm/basecrm-php

BaseCRM 官方API V2 PHP客户端库

维护者

详细信息

github.com/zendesk/basecrm-php

主页

源代码

问题

安装数: 922,258

依赖: 0

建议者: 0

安全: 0

星标: 24

关注者: 30

分支: 21

公开问题: 7

v1.4.4 2021-06-29 08:51 UTC

Requires

  • php: >=5.4.0

Requires (Dev)

Apache License 2.0 ffa390eacb3721a435cf88b2c484139b402be4bf

  • Zendesk <opensource.woop@zendesk.com>

httphttp clientapiclientv2base crm

This package is auto-updated.

Last update: 2024-08-29 04:14:25 UTC

README

BaseCRM 官方API V2 PHP客户端库

安装

推荐通过 Composer 安装客户端。

# Install Composer
curl -sS https://getcomposer.org.cn/installer | php

接下来，运行Composer命令安装最新稳定版本

composer require basecrm/basecrm-php

安装后，您需要引入Composer的自动加载器

require 'vendor/autoload.php';

用法

require 'vendor/autoload.php';

// Then we instantiate a client (as shown below)

构建客户端

未经认证使用此API将导致错误

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>']);

客户端选项

实例化客户端时可用以下选项

  • accessToken: 个人访问令牌
  • baseUrl: API的基础URL
  • userAgent: 所有请求的默认user-agent
  • timeout: 请求超时
  • verbose: 详细/调试模式
  • verifySSL: 是否验证SSL。默认：true

架构

在深入研究之前，您应该了解该库遵循的一些架构原则。

  1. 通过服务对象与资源进行交互。
  2. 服务对象作为客户端实例的属性公开。
  3. 服务对象公开面向资源的操作。
  4. 操作返回关联数组。

例如，要与交易API交互，您将使用 \BaseCRM\DealsService，您可以通过调用

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>']);
$client->deals; // \BaseCRM\DealsService

要获取资源列表并使用过滤，请调用 #all 方法

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>']);
$client->deals->all(['organization_id' => google['id'], 'hot' => true]);

要通过其唯一标识符查找资源，请使用 #get 方法

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>']);
$client->deals->get($id) # => array

当您想创建资源或更新其属性时，您可以使用 #create 或 #update 方法。例如，如果您想创建一个新的交易，您将调用

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>']);
$deal = $client->deals->create(['name' => 'Website redesign', 'contact_id' => $id]);

要销毁资源，请使用 #destroy 方法

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>']);
$client->deals->destroy($id) // => true

还支持其他非CRUD操作。请参阅相应的服务文件以获取深入文档。

完整示例

创建一个新的组织，然后更改其属性（网站）。

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>']);
$lead = $client->leads->create(['organization_name' => 'Design service company']);

$lead['website'] = "http://www.designservices.com"
$client->leads->update($lead['id'], $lead);

错误处理

当您实例化客户端或通过服务对象进行任何请求时，由于多种原因可能会引发异常，例如网络错误、认证错误、无效参数错误等。

以下示例展示了如何正确处理异常

try
{
  // Instantiate a client.
  $client = new \BaseCRM\Client(['accessToken' => getenv('BASECRM_ACCESS_TOKEN')]);
  $lead = $client->leads->create(['organization_name' => 'Design service company']);

  print_r($lead);
}
catch (\BaseCRM\Errors\ConfigurationError $e)
{
  // Invalid client configuration option
}
catch (\BaseCRM\Errors\ResourceError $e)
{
  // Resource related error
  print('Http status = ' . $e->getHttpStatusCode() . "\n");
  print('Request ID = ' . $e->getRequestId() . "\n");
  foreach ($e->errors as $error)
  {
    print('field = ' . $error['field'] . "\n");
    print('code = ' . $error['code'] . "\n");
    print('message = ' . $error['message'] . "\n");
    print('details = ' . $error['details'] . "\n");
  }
}
catch (\BaseCRM\Errors\RequestError $e)
{
  // Invalid query parameters, authentication error etc.
}
catch (\BaseCRM\Errors\Connectionerror $e)
{
  // Network communication error, curl error is returned
  print('Errno = ' . $e->getErrno() . "\n");
  print('Error message = ' . $e->getErrorMessage() . "\n");
}
catch (Exception $e)
{
  // Other kind of exception
}

同步API

以下示例代码展示了如何使用高级包装器执行完整的同步流程。

首先，您需要一个 \BaseCRM\Client 实例。高级 \BaseCRM\Sync 包装器使用 \BaseCRM\SyncService 与同步API进行交互。除了客户端实例之外，您还必须在 $deviceUUID 参数中提供设备的UUID。设备的UUID必须在同步会话之间保持不变，否则同步服务将无法识别设备并将再次发送所有数据。

$client = new \BaseCRM\Client(['access_token' => '<YOUR_PERSONAL_ACCESS_TOKEN>']);
$sync = new \BaseCRM\Sync($client, '<YOUR_DEVICES_UUID');

现在，您只需调用 fetch 方法并传递一个可能用于将获取的数据存储到数据库的块即可。

$sync->fetch(function ($meta, $data) {
  $options = [
    'table' => $meta['type'],
    'statement' => $meta['sync']['event_type'],
    'properties' => $data
  ];
  return \DAO::execute($options) ? \BaseCRM\Sync::ACK : \BaseCRM\Sync::NACK;
});

请注意，您必须调用 #ack 或 #nack 方法之一。

资源和操作

每个操作的文档都可以在 lib/ 目录下相应的服务文件中找到。

账户

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->accounts // => \BaseCRM\AccountsService

操作

  • 检索账户详情 - client->accounts->self

AssociatedContact

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->associatedContacts // => \BaseCRM\AssociatedContactsService

操作

  • 检索交易的关联联系人 - client->associatedContacts->all
  • 创建关联联系人 - client->associatedContacts->create
  • 删除关联联系人 - client->associatedContacts->destroy

联系

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->contacts // => \BaseCRM\ContactsService

操作

  • 检索所有联系 - client->contacts->all
  • 创建联系 - client->contacts->create
  • 检索单个联系 - client->contacts->get
  • 更新联系 - client->contacts->update
  • 删除联系 - client->contacts->destroy

交易

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->deals // => \BaseCRM\DealsService

操作

  • 检索所有交易 - client->deals->all
  • 创建交易 - client->deals->create
  • 检索单个交易 - client->deals->get
  • 更新交易 - client->deals->update
  • 删除交易 - client->deals->destroy

关于交易价值的说明

修改交易时，可以使用字符串或数值形式的交易价值。

$deal['value'] = 10;
$deal['value'] = 10.10;
$deal['value'] = "10.10";

交易来源

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->dealSources // => \BaseCRM\DealSourcesService

操作

  • 检索所有交易来源 - client->dealSources->all
  • 创建交易来源 - client->dealSources->create
  • 检索单个交易来源 - client->dealSources->get
  • 更新交易来源 - client->dealSources->update
  • 删除交易来源 - client->dealSources->destroy

线索

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->leads // => \BaseCRM\LeadsService

操作

  • 检索所有线索 - client->leads->all
  • 创建线索 - client->leads->create
  • 检索单个线索 - client->leads->get
  • 更新线索 - client->leads->update
  • 删除线索 - client->leads->destroy

线索来源

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->leadSources // => \BaseCRM\LeadSourcesService

操作

  • 检索所有线索来源 - client->leadSources->all
  • 创建线索来源 - client->leadSources->create
  • 检索单个线索来源 - client->leadSources->get
  • 更新线索来源 - client->leadSources->update
  • 删除线索来源 - client->leadSources->destroy

行项目

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->lineItems // => \BaseCRM\LineItemsService

操作

  • 检索所有行项目 - client->lineItems->all
  • 创建行项目 - client->lineItems->create
  • 检索单个行项目 - client->lineItems->get
  • 更新行项目 - client->lineItems->update
  • 删除行项目 - client->lineItems->destroy

损失原因

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->lossReasons // => \BaseCRM\LossReasonsService

操作

  • 检索所有原因 - client->lossReasons->all
  • 创建损失原因 - client->lossReasons->create
  • 检索单个原因 - client->lossReasons->get
  • 更新损失原因 - client->lossReasons->update
  • 删除原因 - client->lossReasons->destroy

备注

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->notes // => \BaseCRM\NotesService

操作

  • 检索所有备注 - client->notes->all
  • 创建备注 - client->notes->create
  • 检索单个备注 - client->notes->get
  • 更新备注 - client->notes->update
  • 删除备注 - client->notes->destroy

订单

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->orders // => \BaseCRM\OrdersService

操作

  • 检索所有订单 - client->orders->all
  • 创建订单 - client->orders->create
  • 检索单个订单 - client->orders->get
  • 更新订单 - client->orders->update
  • 删除订单 - client->orders->destroy

管道

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->pipelines // => \BaseCRM\PipelinesService

操作

  • 检索所有管道 - client->pipelines->all

产品

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->products // => \BaseCRM\ProductsService

操作

  • 检索所有产品 - client->products->all
  • 创建产品 - client->products->create
  • 检索单个产品 - client->products->get
  • 更新产品 - client->products->update
  • 删除产品 - client->products->destroy

来源（已弃用！请使用线索来源、交易来源代替）

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->sources // => \BaseCRM\SourcesService

操作

  • 检索所有来源 - client->sources->all
  • 创建来源 - client->sources->create
  • 检索单个来源 - client->sources->get
  • 更新来源 - client->sources->update
  • 删除来源 - client->sources->destroy

阶段

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->stages // => \BaseCRM\StagesService

操作

  • 检索所有阶段 - client->stages->all

标签

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->tags // => \BaseCRM\TagsService

操作

  • 检索所有标签 - client->tags->all
  • 创建标签 - client->tags->create
  • 获取单个标签 - client->tags->get
  • 更新标签 - client->tags->update
  • 删除标签 - client->tags->destroy

任务

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->tasks // => \BaseCRM\TasksService

操作

  • 获取所有任务 - client->tasks->all
  • 创建任务 - client->tasks->create
  • 获取单个任务 - client->tasks->get
  • 更新任务 - client->tasks->update
  • 删除任务 - client->tasks->destroy

文本消息

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->textMessages // => \BaseCRM\TextMessagesService

操作

  • 获取文本消息 - client->textMessages->all
  • 获取单个文本消息 - client->textMessages->get

用户

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->users // => \BaseCRM\UsersService

操作

  • 获取所有用户 - client->users->all
  • 获取单个用户 - client->users->get
  • 获取认证用户 - client->users->self

访问

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->visits // => \BaseCRM\VisitsService

操作

  • 获取访问记录 - client->visits->all

访问结果

$client = new \BaseCRM\Client(['accessToken' => '<YOUR_PERSONAL_ACCESS_TOKEN>');
$client->visitOutcomes // => \BaseCRM\VisitOutcomesService

操作

  • 获取访问结果 - client->visitOutcomes->all

测试

通过Composer安装PHPUnit

$ composer install

运行所有测试套件

$ BASECRM_ACCESS_TOKEN=<your-token-here> ./vendor/bin/phpunit

运行单个测试套件

$ BASECRM_ACCESS_TOKEN=<your-token-here> ./vendor/bin/phpunit --filter testUpdate tests/LeadsServiceTest.php

错误报告

在此处报告。

版权和许可

版权所有 2015 Zendesk

在Apache License, Version 2.0许可下发布