README

Pipedrive是一个面向全球的小型企业的以销售为核心的CRM和智能收入管理平台。有关更多详情，请访问www.pipedrive.com。

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

⚠️ SDK的第五个版本中，我们迁移到了一个开源SDK生成器OpenAPI Generator。这使我们能够更好地应对您可能遇到的SDK问题。

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

安装和使用

需求

PHP 7.4+及以后版本。

Composer

composer require davramenko/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->getActivities();
    echo '<pre>';
    print_r($result);
    echo '</pre>';
} catch (Exception $e) {
    echo 'Exception when calling ActivitiesApi->getActivities: ', $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 deals data', $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: 创建、读取、更新和删除产品及其字段；将产品添加到交易中
projects:read: 读取项目及其字段、任务和项目模板
projects: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

davramenko / pipedrive

维护者

详细信息