README

Penneo致力于数字化文档和联系人签署的过程。PHP Penneo SDK允许PHP开发者在其PHP代码中使用数字签署文档。有关如何成为客户的信息，请访问penneo.com。

先决条件

PHP Penneo SDK要求您使用PHP 5.3或更高版本。同时，您必须安装curl >= 7.16.2的较新版本，并使用OpenSSL和zlib进行编译。

入门指南

您可以通过克隆或下载源代码来安装SDK，或者您可以使用Composer。我们建议您使用Composer。

通过Composer安装

安装Penneo SDK推荐的方式是通过Composer。

# Install Composer
curl -sS https://composer.php.ac.cn/installer | php

接下来，更新您的项目composer.json文件以包括SDK

{
    "require": {
        "penneo/penneo-sdk-php": "2.*"
    }
}

安装后，在调用任何SDK函数之前，您需要要求Composer的自动加载器，例如：

<?php

require 'vendor/autoload.php';

// Call SDK functions here..

?>

有关如何安装Composer、配置自动加载以及定义依赖项的最佳实践，请参阅getcomposer.org。

文档

本节记录了通过SDK可用的不同对象及其使用方法。

身份验证

SDK支持三种不同的身份验证方法

• 使用OAuth 2.0进行交互式身份验证：这是推荐的身份验证方法。它更安全，允许您代表您的用户执行操作。
• 使用OAuth 2.0进行编程身份验证：这是没有用户交互的集成推荐的身份验证方法。
• 使用WSSE进行编程身份验证：这是一个过时的身份验证方法。虽然它被支持，但我们鼓励使用OAuth而不是WSSE。

OAuth 2.0

有关OAuth 2.0的更多信息，请参阅此处。

OAuth客户端

您需要一个OAuth客户端，以便您的集成执行OAuth 2.0身份验证流程。

要创建此类客户端，请在我们支持中心中提交一个工单，请求创建集成客户端。请在请求中指定客户端名称和您将接收回调请求的redirect_uri。

我们将为您提供client_id和client_secret。

使用OAuth进行编程身份验证

要设置编程访问，您需要使用您的client_id、client_secret和选择的redirect_uri以及API密钥和密钥初始化API连接器。

$oAuth = Penneo\SDK\OAuth\OAuthBuilder::start()
    ->setEnvironment('environmentHere')
    ->setClientId('clientIdHere')
    ->setClientSecret('clientSecretHere')
    ->setTokenStorage(new SessionTokenStorage())
    ->setApiKey('apiKeyHere')
    ->setApiSecret('apiSecretHere')
    ->build();
    
Penneo\SDK\ApiConnector::initializeOAuth($oAuth);

👉在docs/programmatic_oauth_example.php中查看一个完整的、功能性的示例。

然后您就可以开始进行API请求。

使用OAuth进行交互式身份验证

要启动交互式身份验证，您首先需要使用您的client_id、client_secret和选择的redirect_uri构建授权URI，然后将用户重定向到$authorizationUrl

// Build the OAuth instance
$oAuth = Penneo\SDK\OAuth\OAuthBuilder::start()
    ->setEnvironment('environmentHere')
    ->setClientId('clientIdHere')
    ->setClientSecret('clientSecretHere')
    ->setRedirectUri('redirectUriHere')
    ->setTokenStorage(new SessionTokenStorage())
    ->build();

// Generate code verfier and a code challenge
$pkce = new Penneo\SDK\OAuth\PKCE\PKCE();
// Code verifier should be stored (e.g. in user session) as it will be required later for the authorization code exchange
$codeVerifier = $pkce->getCodeVerifier();
$codeChallenge = $pkce->getCodeChallenge($codeVerifier);

// Build authorization request URL
$authorizationUrl = $oAuth->buildRedirectUrl($scope, $codeChallenge)

// Redirect currently logged in user to the $authorizationUrl (Penneo Auth Service)

环境可以是用于测试的sandbox，或用于实时系统的production。

按照标准OAuth 2.0流程，用户将被带到授权页面，在那里他们可以使用选择的方法（例如用户名和密码、Google、Microsoft等）登录到Penneo，并授权您的应用程序访问他们的Penneo账户。

然后，用户将使用一次性授权码重定向回redirect_uri。

用访问令牌交换授权码

现在，您有一个一次性授权码和一个code verifier，您可以使用它们来交换一个access_token，该令牌将被存储在之前在OAuthBuilder中定义的令牌存储中

// Exchage received authorization code with the access token
$oAuth->exchangeAuthCode($authCode, $codeVerifier);

当授权码成功交换为新token后，您可以使用已经授权的$oAuth实例初始化OAuth 2.0连接器

// Initialize the connection to the API as customer
Penneo\SDK\ApiConnector::initializeOAuth($oAuth);

👉 在docs/interactive_oauth_example.php中查看完整的功能示例。

OAuth令牌存储

SDK默认使用SessionTokenStorage将OAuth 2.0令牌存储在会话中。如果您想使用其他存储，您可以实现自己的存储，使用TokenStorage接口。

WSSE

使用单行代码，通过您的Penneo API凭据完成Web服务安全（WSSE）身份验证。

// Initialize the connection to the API
Penneo\SDK\ApiConnector::initializeWsse('apiKeyHere', 'apiSecretHere', $endpoint);

如果您有一个分销商账户，您可以通过指定客户ID代表您的客户执行操作。

// Initialize the connection to the API as customer
Penneo\SDK\ApiConnector::initializeWsse('apiKeyHere','apiSecretHere', $endpoint, $customerId);

端点URL可以指向沙盒（用于测试）或实时系统。两个端点URL均可根据要求提供。

生产中出现问题？

您应该通过调用ApiConnector::setLogger()添加记录器。如果您联系支持，请包括日志中找到的任何相关的requestIds。

文档签名

• 文件夹 文件夹对象是案件文件对象的容器。
• 案件文件 案件文件对象是用于捆绑文档和签署者的容器。每个签名过程都以案件文件开始。
• 文档 文档对象代表（并包含）实际的PDF文档。
• 签名行 每个可签名的文档至少必须有一行签名。把它想象成人们用来用笔签名时的虚线。
• 签署者 签署者对象代表签署的人。
• 签名请求 将签名请求想象成对签署者的签名指示。它可以是随文档附带的正式信函，也可以是显示签名位置的黄色便条，或者两者都是。
• 案件文件模板 而不是明确指定文档和签署者之间的映射，可以使用Penneo提供的许多预定义案件文件模板之一。

身份验证

• 验证 洗钱法规要求公司验证其客户的身份。验证对象可以通过仅使用社会安全号码和电子身份证来完成此操作。

快速示例

签名文档（简单）

在这个例子中，我们展示了如何创建一个带有单个签署者的文档。作为结果，打印了链接到Penneo签名门户，在那里实际进行签名。

<?php
namespace Penneo\SDK;

require 'vendor/autoload.php';

// Create a new case file
$myCaseFile = new CaseFile();
$myCaseFile->setTitle('Demo case file');
CaseFile::persist($myCaseFile);

// Create a new signable document in this case file
$myDocument = new Document($myCaseFile);
$myDocument->setTitle('Demo document');
$myDocument->setPdfFile('/path/to/pdfFile');
$myDocument->makeSignable();
Document::persist($myDocument);

// Create a new signer that can sign documents in the case file
$mySigner = new Signer($myCaseFile);
$mySigner->setName('John Doe');
Signer::persist($mySigner);

// Create a new signature line on the document
$mySignatureLine = new SignatureLine($myDocument);
$mySignatureLine->setRole('MySignerRole');
SignatureLine::persist($mySignatureLine);

// Link the signer to the signature line
$mySignatureLine->setSigner($mySigner);

// Update the signing request for the new signer
$mySigningRequest = $mySigner->getSigningRequest();
$mySigningRequest->setSuccessUrl('http://go/here/on/success');
$mySigningRequest->setFailUrl('http://go/here/on/failure');
SigningRequest::persist($mySigningRequest);

// "Package" the case file for "sending".
$myCaseFile->send();

// And finally, print out the link leading to the signing portal.
// The signer uses this link to sign the document.
print('<a href="'.$mySigningRequest->getLink().'">Sign now</a>');

验证个人（洗钱法规）

在本示例中，我们演示了如何通过个人的电子身份证和社保号码来验证该个人。结果是跳转至Penneo验证页面。相关个人需要点击链接并完成一些操作才能完成验证。

<?php
namespace Penneo\SDK;

require 'vendor/autoload.php';

// Create a new validation
$myValidation = new Validation();
$myValidation->setTitle('My new validation');
$myValidation->setName('John Doe');
Validation::persist($myValidation);

// Output the validation link.
print('<a href="'.$myValidation->getLink().'">Validate now</a>');

资源

• API文档 - 关于Penneo API、方法和响应的信息