README

Pipedrive 是一家全球性的以销售为中心的 CRM 和智能收入管理平台，专为小型企业设计。更多详情请访问 www.pipedrive.com。

这是基于 PHP 的 Pipedrive API 包装客户端的官方版本，由 Pipedrive Inc 免费提供，遵循 MIT 许可。它提供了方便访问 Pipedrive API 的方法，允许您操作诸如交易、人员、组织、产品等实体。

⚠️ 从 SDK 的第五版开始，我们已切换到名为 OpenAPI Generator 的开源 SDK 生成器。这使我们能够更好地响应用户对 SDK 可能遇到的问题。

请使用问题页面报告错误或反馈。

安装和使用

要求

PHP 7.4+ 及更高版本。

Composer

composer require pipedrive/pipedrive

手动安装

下载文件并包含 autoload.php

<?php
require_once('/path/to/pipedrive/vendor/autoload.php');

测试

运行单元测试

composer install
composer test

入门指南

请按照安装步骤进行，然后运行以下命令

使用预置的 API 令牌

<?php

use Pipedrive\Configuration;

require_once('/path/to/client/vendor/autoload.php');

// Configure API key authorization: api_key
$config = (new Pipedrive\Configuration())->setApiKey('api_token', 'YOUR_API_KEY');

$apiInstance = new Pipedrive\Api\ActivitiesApi(
// If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
// This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
    $config
);

try {
    $result = $apiInstance->activitiesGet();
    echo '<pre>';
    print_r($result);
    echo '</pre>';
} catch (Exception $e) {
    echo 'Exception when calling ActivitiesApi->activitiesDelete: ', $e->getMessage(), PHP_EOL;
}

?>

使用 OAuth 2.0

为了在 API 客户端中设置身份验证，您需要以下信息

API 客户端可以初始化如下

$oAuthClientId = 'oAuthClientId'; // OAuth 2 Client ID
$oAuthClientSecret = 'oAuthClientSecret'; // OAuth 2 Client Secret
$oAuthRedirectUri = 'https://example.com/oauth/callback'; // OAuth 2 Redirection endpoint or Callback Uri

$config = (new Pipedrive\Configuration());
$config->setClientId($oAuthClientId);
$config->setClientSecret($oAuthClientSecret);
$config->setOauthRedirectUri($oAuthRedirectUri);

$dealsApiInstance = new DealsApi(null, $config);

现在您必须授权客户端。

授权您的客户端

在应用程序可以执行端点调用之前，必须先获取用户授权。SDK 使用 OAuth 2.0 授权 来获取用户同意代表用户执行 API 请求。

1. 获取用户同意

要获取用户同意，您必须将用户重定向到授权页面。当您在 $config 中设置了 clientID 和 OAuthRedirect 时，getAuthorizationPageUrl() 方法将创建授权页面的 URL。

$authUrl = $config->getAuthorizationPageUrl();
header('Location: ' . filter_var($authUrl, FILTER_SANITIZE_URL));

2. 处理 OAuth 服务器响应

用户响应同意请求后，OAuth 2.0 服务器通过将用户重定向到在 Configuration 中指定的重定向 URI 来响应您的应用程序的访问请求。

如果用户批准请求，则授权码将以 code 查询字符串的形式发送

https://example.com/oauth/callback?code=XXXXXXXXXXXXXXXXXXXXXXXXX

如果用户不批准请求，则响应将包含一个 error 查询字符串

https://example.com/oauth/callback?error=access_denied

3. 使用代码授权客户端

服务器收到代码后，可以将其交换为 访问令牌。访问令牌是一个包含用于授权客户端请求和刷新令牌本身的信息的对象。

try {
    $config->authorize($_GET['code']);
} catch (Exception $ex) {
    // handle exception
}

刷新令牌

访问令牌可能在一段时间后过期。要延长其有效期，您必须刷新令牌。

if ($configuration->getExpiresAt() < time()) {
    try {
        $config->refreshToken();
    } catch (Exception $ex) {
        // handle exception
    }
}

如果令牌过期，SDK 将尝试在执行需要身份验证的下一个端点调用之前自动刷新令牌。

存储访问令牌以供重用

建议您存储访问令牌以供重用。

您可以将访问令牌存储在 $_SESSION 全局变量或任何其他持久存储中

// store token
$_SESSION['access_token'] = $config->getAccessToken();

然而，由于 SDK 将在令牌过期时尝试自动刷新令牌，因此建议您注册一个 令牌更新回调 以检测访问令牌的任何更改。

$config->setOAuthTokenUpdateCallback(function ($token) {
    $_SESSION['token'] = $token;
});

令牌更新回调将在授权以及令牌刷新时触发。

从存储的令牌创建客户端

要从存储的访问令牌授权客户端，只需在创建客户端之前在 Configuration 中设置访问令牌以及其他配置参数。

// load token later...
$config->setAccessToken($_SESSION['token']->access_token);

// If you want to set all of the OAuth2 related fields at once from the token gotten from Pipedrive OAuth server
// you can use the updateOAuthRelatedFields() function
$config->updateOAuthRelatedFields($_SESSION['token']);
// This will set the access token, expiresIn, expiresAt, scope and host attributes in the Configuration class
// In order to get automatic access token refreshing, you will still need the client ID, client secret and redirectURI

// Set other configuration, then instantiate client
$activitiesApiInstance = new ActivitiesApi(null, $config);

撤销令牌

当应用程序需要向授权服务器指示用户令牌应被作废时，使用提供 hint 参数值的 revokeToken 方法。

$config = (new Pipedrive\Configuration());
$config->updateOAuthRelatedFields(/* ... */);

设置配置后，只需调用该方法。

// this will revoke all user tokens
$config->revokeToken('refresh_token');

/* OR */

// this will revoke only access token
$config->revokeToken('access_token');

OAuth的完整示例

在这个示例中，index.php 首先检查用户是否有一个访问令牌。如果没有设置，它将用户重定向到 authcallback.php，该文件将获取访问令牌并将用户重定向回 index.php 页面。现在设置了一个访问令牌，index.php 可以使用客户端向服务器发出授权调用。

`index.php`

<?php

use Pipedrive\Api\DealsApi;
use Pipedrive\Configuration;

require_once('../../sdks/php/vendor/autoload.php');

session_start();

$config = (new Pipedrive\Configuration());
$config->setOauthRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/authcallback.php');
$config->setClientSecret('YOUR_CLIENT_SECRET');
$config->setClientId('YOUR_CLIENT_ID');

//$usersApiInstance = new UsersApi(null, $config);
$dealsApiInstance = new DealsApi(null, $config);

// check if a token is available
if (isset($_SESSION['token']) && $_SESSION['token']) {
    // set access token in configuration
    $config->updateOAuthRelatedFields($_SESSION['token']);

    try {
        $dealsResponse = $dealsApiInstance->getDeals();
        echo '<pre>';
        print_r($dealsResponse);
        echo '</pre>';
    } catch (Exception $e) {
        echo 'Exception when trying to get user info', $e, PHP_EOL;
    }
} else {
    header('Location: ' . filter_var($config->getAuthorizationPageUrl(), FILTER_SANITIZE_URL));
}

`authcallback.php`

<?php
require_once('../../sdks/php/vendor/autoload.php');

use Pipedrive\Configuration;

session_start();

$config = (new Pipedrive\Configuration());

$config->setOauthRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/authcallback.php');
$config->setClientSecret('YOUR_CLIENT_SECRET');
$config->setClientId('YOUR_CLIENT_ID');
$config->setAuthorizationPageUrl('https://oauth.pipedrive.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=http%3A%2F%2Flocalhost%3A8081%2Fauthcallback.php');

$config->setOAuthTokenUpdateCallback(function ($token) {
    $_SESSION['token'] = $token;
});

// if authorization code is absent, redirect to authorization page
if (!isset($_GET['code'])) {
    header('Location: ' . filter_var($config->getAuthorizationPageUrl(), FILTER_SANITIZE_URL));
} else {
    try {
        $config->authorize($_GET['code']);

        // resume user activity
        $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/';
        header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
    } catch (Exception $ex) {
        print_r($ex);
    }
}

API端点文档

所有URI相对于 https://api.pipedrive.com/v1

模型文档

授权文档

api_key

类型: API密钥
API密钥参数名称: api_token
位置: URL查询字符串

oauth2

类型: OAuth
流程: accessCode
授权URL: https://oauth.pipedrive.com/oauth/authorize
作用域:
base: 读取授权用户和账户中的货币设置
deals:read: 读取有关交易和相关实体的大多数数据 - 交易字段、产品、关注者、参与者；所有笔记、文件、过滤器、流水线、阶段和统计数据。不包括访问活动（除了与交易相关的最后和下一活动）
deals:full：创建、读取、更新和删除交易、参与者及其关注者；所有文件、笔记和过滤器。还包括对交易字段、管道、阶段和统计信息的读取权限。不包括对活动（除与交易相关的最后和下一个活动外）的访问权限
mail:read：读取邮件线程和消息
mail:full：读取、更新和删除邮件线程。还提供对邮件消息的读取访问权限
activities:read：读取活动及其字段和类型；所有文件和过滤器
activities:full：创建、读取、更新和删除活动及其所有文件和过滤器。还包括对活动字段和类型的读取访问权限
contacts:read：读取有关个人和组织的数据，以及它们的相关字段和关注者；还包括所有笔记、文件和过滤器
contacts:full：创建、读取、更新和删除个人和组织及其关注者；所有笔记、文件和过滤器。还提供对与联系人相关的字段的读取访问权限
products:read：读取产品及其字段、文件、关注者以及与交易连接的产品
products:full：创建、读取、更新和删除产品及其字段；将产品添加到交易中
users:read：读取有关用户（可访问Pipedrive帐户的人）的数据，包括他们的权限、角色和关注者
recents:read：读取帐户中发生的所有最近更改。包括有关活动、活动类型、交易、文件、过滤器、个人、组织、管道、阶段、产品和用户的数据
search:read：在帐户中搜索交易、个人、组织、文件和产品，并查看返回结果的详细信息
admin：允许执行许多在Pipedrive公司帐户中管理员可以执行的操作 - 创建、读取、更新和删除管道及其阶段；交易、个人和组织字段；活动类型；用户和权限等。它还允许应用程序创建webhooks并获取和删除由应用程序创建的webhooks
leads:read：读取有关线索和线索标签的数据
leads:full：创建、读取、更新和删除线索和线索标签
phone-integration：启用高级呼叫集成功能，例如记录通话时长和其他元数据，并在Pipedrive中播放通话录音
goals:read：读取有关所有目标的数据
goals:full：创建、读取、更新和删除目标
video-calls：允许应用程序注册为视频呼叫集成提供商并创建会议链接
messengers-integration：允许应用程序注册为消息传递集成提供商，并允许它们传递传入的消息及其状态

作者

关于本包

此PHP包由OpenAPI Generator项目自动生成

API版本：1.0.0
构建包：org.openapitools.codegen.languages.PhpClientCodegen

christrung / client-php

维护者

详细信息