README

以人类可消化的方式处理SignMe请求。目标是使其感觉就像与本地模型一起工作。

SignMe 是一个针对集成商的签名服务，而不是像大多数竞争对手那样是一个纯UI解决方案。

状态：私有测试版。请勿在生产环境中使用

示例

use Retech\Celest\SignMe\SignMeClient;

$sdk = (new SignMeClient())->authenticate();

// create a new document to sign
$newDocument = $sdk->uploadDocument('SDK upload','path/contracts/max-hunter-lease-agreement.pdf');

// add Signatory
$signatoryMax = $newDocument->addSignatory('my-reference-c9d9b8b8', 'Max Hunter', 'm.hunter@example.com');

// create field on page 4
$signatureField = $signatoryMax->addField('Please sign here', 4);

// move field in position using percentages
$signatureField->setX(53.3);
$signatureField->setY(40);

// you can set width/height as well
$signatureField->setHeight(7);

// send changes to API
$signatureField->update();

// and then some pseudo-code to get the picture
$email = new MyEmailClientWrapper();
$email->to('Max Hunter', 'm.hunter@example.com');
$email->body('Hi Max. Please sign this: ' . $signatoryMax->getSignatureLink());
$email->send();

安装

composer require retech/sign-me

用法

此包是满足您所有远程signMe需求的一站式解决方案。其功能可以分为三个类别

api
简单对象
webhook读取器

纯API

为了使用公共REST-API，方法包装器简化了您的调用。所有这些方法在成功时返回关联数组，并在出错时抛出异常 Retech\Celest\SignMe\Exceptions\ConnectionException。

authenticate

此方法使用环境变量 SIGN_ME_CLIENT_ID 和 SIGN_ME_API_KEY 建立身份验证。或者，您可以直接传递您的clientId & ApiKey。

$client = new SignMeClient();
$client->authenticate();

get

对基本uri https://sign.celest.services/api/ 执行GET调用

$myDocument = $client->get('documents/123-123-123-1231-123123123');

post

对基本uri https://sign.celest.services/api/ 执行POST调用

$myReference = 'user-123-345-523-93645'
$newSignatory = $client->post('signature/123-123-123-1231-123123123', [
    'signerHash' => $myReference,
    'signerEmail' => 'john.doe@email.com'
]);

put

对基本uri https://sign.celest.services/api/ 执行PUT调用

$webHookUrl = 'https://webhook.your-domain.com?mydocId=1023'
$updatedDoc = $client->put('documents/123-123-123-1231-123123123', [
    'webhookUrl' => $webHookUrl
]);

delete

对基本uri https://sign.celest.services/api/ 执行DELETE调用

$success = $client->delete('documents/123-123-123-1231-123123123');

简单对象（OO）

除了管理您的交易和公司设置之外，signMe API的使用案例足够可预测，足以通过我们的面向对象交互可能性使您日常工作更轻松。

getDocuments

$documents = $client->getDocuments();
$totalPages = $documents['pages']; // e.g. 3
$allDocumentCount = $documents['total'] // e.g. 127
$newestDocument = $documents[documents][0] // Document (see Entities)

getDocument

$myDocument = $client->getDocument('d3373e45-f7bd-43dc-b48e-db5bca1a5493'); // Document (see Entities)

uploadDocument

目前仅接受PDF & DOCX

$myDocument = $client->uploadDocument('Mike\'s car sale', __DIR__ . '/file.php'); // Document (see Entities)

实体

Document

getDownloadUrl(): null|string
getDownloadUrl(): null|string
getFinalInstructions(): null|string
setFinalInstructions(finalInstructions: null|string): void
getWebhookUrl(): null|string
setWebhookUrl(webhookUrl: null|string): void
getSlug(): string
getName(): string
getRequesterHash(): string
getFields(): array
getSignatures(): array
getSignature(signerHash: string): null|Signature
addSignatory(signerHash: string, [signerName: null|string = null], [signerEmail: null|string = null]): Signature
update(): Document

Signature

fields: array = [...]
documentSlug: string
getSignerHash(): string
getSignerName(): null|string
getSignerEmail(): null|string
getIp(): null|string
getSignedAt(): DateTimeImmutable|null
isSigned(): bool
setSignerName(signerName: null|string): void
setSignerEmail(signerEmail: null|string): void
addField(label: string, [page: int = 1], [type: string = 'signature']): Field
getSignatureLink(): string

Field

setType(type: string): void
setSignerHash(signerHash: string): void
setPage(page: int): void
setX(x: float): void
setY(y: float): void
setWidth(width: float): void
setHeight(height: float): void
setLabel(label: null|string): void
getLabel(): null|string
getHeight(): float
getWidth(): float
getY(): float
getX(): float
getPage(): int
getSignerHash(): string
getType(): string
update(): Field
delete(): void

Webhook Reader

最后，让我们快速查看此包中包含的webhook验证工具

$webHook = new Retech\Celest\SignMe\WebHookValidator($mySignatureSecret);
try{
    $webHook->validate();
} catch (WebhookValidationException $e){
    // malicious!! 
}

// readonly properties (available after validate() or parse())

$event = $webHook->event; // Retech\Celest\SignMe\Enums\Event e.g Event::UPDATE
$entity = $webHook->entity; // Retech\Celest\SignMe\Enums\Entity e.g. Entity::DOCUMENT
$slug = $webHook->slug;

// payload
$payload = $webHook->parse();

if($webHook->entity === Entity::DOCUMENT && $payload->isCompleted()){
    // all signatures are valid
} elseif ($webHook->entity === Entity::DOCUMENT) {
    // apparently some signatures are outstanding
    $signatures = $payload->getSignatures(); // e.g. [['ip' => null, 'time' => null, 'signerHash' => '123-123-123-k']]
    ...
    // or let's get the doc
    $sdk = (new SignMeClient())->authenticate();
    $document = $sdk->getDocument($webHook->slug);
    ...
    
}

支持

在正式发布之前，不提供公开支持。

许可证

MIT

retech / sign-me

维护者

详情