README

SuperOffice Web API 的非官方 PHP SDK

此库提供了一个针对 SuperOffice REST WebAPI 的 PHP SDK，专门针对 CRM Online（SuperOffice Cloud）。

此库的功能目前仅限于项目、预约和文档，但如果您需要，应该很容易将其扩展到其他 SuperOffice 类型 - 只要注意，需要一些工作。

安装

安装此库的推荐方法是使用 Composer，将 superoffice-webapi 包作为依赖项添加到您的应用程序中

composer require softwarepunt/superoffice-webapi

配置

您需要注册为 SuperOffice 开发者，并且必须有一个注册的应用程序来接收必要的客户端凭证。

初始化

在初始化客户端时，您必须传递一个 Config 对象

<?php

use SoftwarePunt\SoWebApi\Client;
use SoftwarePunt\SoWebApi\Config;

$config = new Config();
$config->environment = "sod";
$config->tenantId = "Cust12345";
// ...

$client = new Client($config);

您也可以通过数组设置配置值

<?php

new Config([
    'environment' => "sod",
    'tenantId' => "Cust12345"
    // ...
]);

选项

可用的配置选项

身份验证（OAuth / SuperId）

如果您针对在线 CRM，您必须使用 OAuth 获取 web api 的 BEARER 访问令牌。

本地安装必须使用 BASIC / SOTICKET 身份验证方法（目前此库不支持）。

重定向用户到授权屏幕

设置您的配置后，您可以要求客户端生成 OAuth 授权 URL

<?php 

use SoftwarePunt\SoWebApi\Client;

$client = new Client(/* $config */);
$redirectUrl = $client->getOAuthAuthorizationUrl("optional_state");

这将生成一个类似 https://env-name.superoffice.com/login/common/oauth/authorize?client_id=... 的重定向 URL。

当您将用户重定向到此 URL 时，他们将需要授权您的应用程序并授予对其账户的访问权限。

请求访问令牌

一旦用户授权了您的应用程序，您将收到在配置的 requestUri 上配置的回调请求。

您可以将请求中的 code 参数交换为访问令牌

<?php

$tokenResponse = $client->requestOAuthAccessToken($_GET['code']);

TokenResponse 对象包含以下键

您的应用程序负责存储这些令牌。

刷新访问令牌

您可以使用 refresh_token 生成新的访问令牌，只要用户没有撤销您应用程序的访问权限。

<?php

$tokenResponse = $client->refreshOAuthAccessToken($tokenResponse->refresh_token);

此响应将是一个 TokenResponse 对象，但 refresh_token 设置为 null。

验证 JWT

为了符合 SuperOffice 的要求，您的应用程序应验证每个令牌响应中的 JWT（因此当请求新令牌或刷新令牌时）

<?php

// ... request or refresh access token to get a $tokenResponse
$jwtIsValid = $tokenResponse->validateAndVerifyJwt($config);

if (!$jwtIsValid) {
    // ... something is fishy, bail
}

这将验证令牌（有效发行者，未过期）并验证它是否与配置环境的适当 SuperOffice 证书匹配。

配置访问令牌

在执行任何请求之前，您必须明确设置要使用的访问令牌

<?php

use SoftwarePunt\SoWebApi\Client;

// Optionally pass it directly in the client constructor:
$client = new Client(/* $config */, $tokenResponse->access_token);

// Or set it on an existing client instance:
$client->setAccessToken($tokenResponse->access_token);

租户状态检查

您可以对 租户状态 进行检查以检索有关客户环境的详细信息。您可以使用此信息来确定环境是否可用，并获得 API 请求的负载均衡目标 URL。

"每个租户都有一个状态页面，您可以在其中检查其状态以确保您的应用程序保持稳定并相应地响应。"

<?php

use SoftwarePunt\SoWebApi\Client;

// Authentication is not required, but "tenantId" must be set in your config.
$client = new Client(/* $config */);
$tenantStatus = $client->getTenantStatus();

// If the target environment is offline, do not proceed:
if (!$tenantStatus->IsRunning) die("Tenant offline!");

// Tenant status gives a load-balanced base URL you can set on the client:
$client->setBaseUrl($tenantStatus->Endpoint);

TenantStatus 对象包含以下键

集合

该库暴露了不同的API实体集合，您可以与之交互。每个集合都可以通过客户端实例访问，例如 $client->projects()。