retech / sign-me
Celest Sign me SDK
Requires
- php: ^8.1
- symfony/http-client: ^7.0
This package is auto-updated.
Last update: 2024-10-23 03:51:35 UTC
README
Handle your SignMe-requests in a human-digestible way. The goal is to make it feel like working with local models.
SignMe is a signature service targeted at integrators, rather than a pure UI-solution like most competitors.
Status: Private BETA. Please do not use in production yet
Example
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();
Installation
composer require retech/sign-me
Usage
This package is a one-stop solution for all your remote signMe needs. It's functionality can be divided into three categories:
pure API
In order to use the public REST-API, method-wrappers simplify your calls. All of these methods return the result as assoc-array on success and throw the Exception Retech\Celest\SignMe\Exceptions\ConnectionException when things go wrong.
authenticate
The method establishes authentication using the environment variables SIGN_ME_CLIENT_ID and SIGN_ME_API_KEY. Alternatively, you can pass in your clientId & ApiKey directly.
$client = new SignMeClient(); $client->authenticate();
get
Execute GET-calls against the base-uri https://sign.celest.services/api/
$myDocument = $client->get('documents/123-123-123-1231-123123123');
post
Execute POST-calls against the base-uri https://sign.celest.services/api/
$myReference = 'user-123-345-523-93645' $newSignatory = $client->post('signature/123-123-123-1231-123123123', [ 'signerHash' => $myReference, 'signerEmail' => 'john.doe@email.com' ]);
put
Execute PUT-calls against the base-uri https://sign.celest.services/api/
$webHookUrl = 'https://webhook.your-domain.com?mydocId=1023' $updatedDoc = $client->put('documents/123-123-123-1231-123123123', [ 'webhookUrl' => $webHookUrl ]);
delete
Execute DELETE-calls against the base-uri https://sign.celest.services/api/
$success = $client->delete('documents/123-123-123-1231-123123123');
Easy Objects (OO)
Other than managing your transactions and company-settings, the use-case of the signMe API is predictable enough to make your day-to-day life easier with our object oriented interaction possibilities.
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
Currently accepts PDF & DOCX only
$myDocument = $client->uploadDocument('Mike\'s car sale', __DIR__ . '/file.php'); // Document (see Entities)
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
Lastly, let's have a quick look at the webhook validation tool included in this package
$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); ... }
Support
Before the official release, no public support is provided.
License
MIT