### Initialize DigiSign Client

Source: https://context7.com/digitalcz/digisign/llms.txt

Initialize the DigiSign client with basic or advanced options. Advanced setup allows custom HTTP clients, caching, and sandbox mode.

```php
use DigitalCz\DigiSign\DigiSign;
use DigitalCz\DigiSign\Auth\ApiKeyCredentials;
use DigitalCz\DigiSign\DigiSignClient;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;
use Symfony\Component\HttpClient\Psr18Client;

// Minimal setup via constructor options
$dgs = new DigiSign([
    'access_key' => 'your-access-key',
    'secret_key' => 'your-secret-key',
]);

// Full setup with custom HTTP client, caching, and sandbox mode
$dgs = new DigiSign([
    'access_key'          => 'your-access-key',
    'secret_key'          => 'your-secret-key',
    'http_client'         => new Psr18Client(),
    'cache'               => new Psr16Cache(new FilesystemAdapter()),
    'sandbox'             => true,               // use https://api.staging.digisign.org
    'signature_tolerance' => 60,                 // webhook signature max age in seconds
]);

// Or configure step by step
$dgs = new DigiSign();
$dgs->setCredentials(new ApiKeyCredentials('your-access-key', 'your-secret-key'));
$dgs->setClient(new DigiSignClient(new Psr18Client()));
$dgs->useSandbox(true);
```

--------------------------------

### Install DigiSign via Composer

Source: https://github.com/digitalcz/digisign/blob/2.x/README.md

Use Composer to install the DigiSign library. This is the standard method for adding the library to your PHP project.

```bash
$ composer require digitalcz/digisign
```

--------------------------------

### Configure DigiSign in Symfony

Source: https://github.com/digitalcz/digisign/blob/2.x/README.md

Example configuration for the DigiSign client within a Symfony application using YAML. This demonstrates how to inject access and secret keys, and optionally other services like cache and HTTP client.

```yaml
services:
  DigitalCz\DigiSign\DigiSign:
    $options:
      # minimal config
      access_key: '%digisign.accessKey%'
      secret_key: '%digisign.secretKey%'

      # other options
      cache: '@psr16.cache'
      http_client: '@psr18.http_client'
      sandbox: true # use sandbox API
```

--------------------------------

### Manage Account Settings and Administration

Source: https://context7.com/digitalcz/digisign/llms.txt

This snippet covers fetching account information, updating settings with error handling, listing users, creating API keys, retrieving statistics, and getting billing information. Be mindful of validation errors when updating settings.

```php
use DigitalCz\DigiSign\DigiSign;
use DigitalCz\DigiSign\Exception\BadRequestException;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);

// Fetch current account info
$account = $dgs->account()->get();
echo "Account: {$account->name}\n";

// Update account settings with validation error handling
try {
    $dgs->account()->settings()->update([
        'defaultSenderEmail' => 'noreply@company.com',
        'shortName'          => 'CompanyCo',
    ]);
} catch (BadRequestException $e) {
    $violations = $e->getViolations();
    if ($violations !== null) {
        foreach ($violations->toArray() as $field => $messages) {
            echo "Validation error on '{$field}': " . implode(', ', $messages) . "\n";
        }
    }
}

// List account users
$users = $dgs->account()->users()->list();

// Create a new API key
$apiKey = $dgs->account()->apiKeys()->create(['name' => 'CI/CD Pipeline Key']);
echo "New API Key: {$apiKey->accessKey} / {$apiKey->secretKey}\n";

// Retrieve account statistics
$stats = $dgs->account()->statistics(['from' => '2024-01-01', 'to' => '2024-12-31']);

// Get billing info
$billing = $dgs->account()->billing();
```

--------------------------------

### Configure DigiSign with Constructor Options

Source: https://github.com/digitalcz/digisign/blob/2.x/README.md

Instantiate the DigiSign client using an array of options for authentication and other settings. Supports API keys directly or via a Credentials instance.

```php
use DigitalCz\DigiSign\Auth\ApiKeyCredentials;
use DigitalCz\DigiSign\DigiSign;

// Via constructor options
$dgs = new DigiSign([
    'access_key' => '...', 
    'secret_key' => '...'
]);

// Or via methods
$dgs = new DigiSign();
$dgs->setCredentials(new ApiKeyCredentials('...', '...'));
```

--------------------------------

### Create and Send an Envelope

Source: https://github.com/digitalcz/digisign/blob/2.x/README.md

Demonstrates the process of creating an envelope, adding recipients, uploading a document, attaching a signature tag, and finally sending the envelope for signing. Requires prior DigiSign client instantiation.

```php
$dgs = new DigitalCz\DigiSign\DigiSign(['access_key' => '...', 'secret_key' => '...']);

$envelopes = $dgs->envelopes();

$envelope = $envelopes->create([
    'emailSubject' => 'Please sign',
    'emailBody' => 'Hello James, please sign these documents.',
    'senderName' => 'John Smith',
    'senderEmail' => 'john.smith@example.com'
]);

$recipient = $envelopes->recipients($envelope)->create([
    'role' => 'signer',
    'name' => 'James Brown',
    'email' => 'james42@example.com',
    'mobile' => '+420775300500',
]);

$stream = DigitalCz\DigiSign\Stream\FileStream::open('path/to/document.pdf');
$file = $dgs->files()->upload($stream);

$document = $envelopes->documents($envelope)->create([
    'name' => 'Contract',
    'file' => $file->self()
]);

$tag = $envelopes->tags($envelope)->create([
    'type' => 'signature',
    'document' => $document,
    'recipient' => $recipient,
    'page' => 1,
    'xPosition' => 200,
    'yPosition' => 340
]);

$envelopes->send($envelope->id());
```

--------------------------------

### Configure DigiSign with Methods

Source: https://github.com/digitalcz/digisign/blob/2.x/README.md

Configure the DigiSign client by setting various options using dedicated methods. This includes setting a custom HTTP client, authentication credentials, cache, sandbox mode, API base URL, and signature tolerance.

```php
use DigitalCz\DigiSign\Auth\Token;
use DigitalCz\DigiSign\Auth\TokenCredentials;
use DigitalCz\DigiSign\DigiSign;
use DigitalCz\DigiSign\DigiSignClient;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;
use Symfony\Component\HttpClient\Psr18Client;

$dgs = new DigiSign();
// To set your own PSR-18 HTTP Client, if not provided Psr18ClientDiscovery is used
$dgs->setClient(new DigiSignClient(new Psr18Client()));
// If you already have the auth-token, i can use TokenCredentials
$dgs->setCredentials(new TokenCredentials(new Token('...', 123)));
// Cache will be used to store auth-token, so it can be reused in later requests
$dgs->setCache(new Psr16Cache(new FilesystemAdapter()));
// Use sandbox API (https://api.staging.digisign.org)
$dgs->useSandbox(true);
// Overwrite API base
$dgs->setApiBase('https://example.com/api');
// Set maximum age of webhook request to one minute
$dgs->setSignatureTolerance(60);
```

--------------------------------

### Create and Manage Bulk Signature Jobs

Source: https://context7.com/digitalcz/digisign/llms.txt

Use this to create, send, resend, and list bulk signature jobs. Ensure the DigiSign client is initialized with access and secret keys.

```php
use DigitalCz\DigiSign\DigiSign;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);

// Create a bulk signature job
$bulk = $dgs->bulkSignature()->create([
    'name'      => 'Bulk Q4 Contracts',
    'signer'    => '/api/account/users/user-id',
    'documents' => [
        '/api/files/file1-id',
        '/api/files/file2-id',
    ],
]);

// Send the bulk signature request
$dgs->bulkSignature()->send($bulk->id());

// Resend if signer did not respond
$dgs->bulkSignature()->resend($bulk->id());

// List existing bulk signature jobs
$list = $dgs->bulkSignature()->list(['status' => ['in' => ['pending']]]);
foreach ($list->items as $item) {
    echo "{$item->id}: {$item->status}\n";
}
```

--------------------------------

### Create and Send an Envelope

Source: https://context7.com/digitalcz/digisign/llms.txt

This snippet demonstrates the complete process of creating an envelope, adding recipients and documents, placing signature tags, and sending the envelope to trigger recipient notifications. Ensure you have the DigiSign client initialized with your access and secret keys.

```php
use DigitalCz\DigiSign\DigiSign;
use DigitalCz\DigiSign\Stream\FileStream;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);
$envelopes = $dgs->envelopes();

// 1. Create the envelope
$envelope = $envelopes->create([
    'emailSubject' => 'Please sign the contract',
    'emailBody'    => 'Hello James, please sign the attached document.',
    'senderName'   => 'John Smith',
    'senderEmail'  => 'john.smith@example.com',
]);

// 2. Add a signer recipient
$recipient = $envelopes->recipients($envelope)->create([
    'role'   => 'signer',
    'name'   => 'James Brown',
    'email'  => 'james42@example.com',
    'mobile' => '+420775300500',
]);

// 3. Upload a PDF file and attach it as an envelope document
$file     = $dgs->files()->upload(FileStream::open('/path/to/contract.pdf'));
$document = $envelopes->documents($envelope)->create([
    'name' => 'Contract',
    'file' => $file,     // Resource instance is automatically converted to IRI
]);

// 4. Place a signature tag at position (200, 340) on page 1
$tag = $envelopes->tags($envelope)->create([
    'type'      => 'signature',
    'document'  => $document,
    'recipient' => $recipient,
    'page'      => 1,
    'xPosition' => 200,
    'yPosition' => 340,
]);

// 5. Send the envelope (triggers email delivery to recipient)
$envelopes->send($envelope->id());
echo "Envelope {$envelope->id()} sent successfully\n";

```

--------------------------------

### Run PHPUnit Tests

Source: https://github.com/digitalcz/digisign/blob/2.x/README.md

Executes the unit tests using PHPUnit. This command is used to verify the correctness of the library's components.

```bash
$ composer tests
```

--------------------------------

### Create and Attach Labels to Envelopes

Source: https://context7.com/digitalcz/digisign/llms.txt

Organize envelopes by creating labels with names and colors, and then attaching them to specific envelopes. You can also list labels attached to an envelope.

```php
use DigitalCz\DigiSign\DigiSign;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);

// Create a label
$label = $dgs->labels()->create(['name' => 'HR Contracts', 'color' => '#ff5500']);

// Attach label to an envelope
$dgs->envelopes()->labels('envelope-id')->create(['label' => $label->self()]);

// List labels on an envelope
$attachedLabels = $dgs->envelopes()->labels('envelope-id')->list();
```

--------------------------------

### Configure API Key Credentials

Source: https://context7.com/digitalcz/digisign/llms.txt

Configure API key credentials for authentication. This can be done with or without caching for token reuse.

```php
use DigitalCz\DigiSign\Auth\ApiKeyCredentials;
use DigitalCz\DigiSign\Auth\CachedCredentials;
use DigitalCz\DigiSign\DigiSign;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;

// Without caching — fetches a new token on every script run
$dgs = new DigiSign();
$dgs->setCredentials(new ApiKeyCredentials('my-access-key', 'my-secret-key'));

// With caching — reuses token across requests until it expires
$cache = new Psr16Cache(new FilesystemAdapter('/tmp/digisign-cache'));
$credentials = new ApiKeyCredentials('my-access-key', 'my-secret-key');
$dgs->setCredentials(new CachedCredentials($credentials, $cache));

// Equivalent shorthand using constructor option
$dgs = new DigiSign([
    'access_key' => 'my-access-key',
    'secret_key' => 'my-secret-key',
    'cache'      => new Psr16Cache(new FilesystemAdapter()),
]);
```

--------------------------------

### Run All Checks

Source: https://github.com/digitalcz/digisign/blob/2.x/README.md

Executes all defined checks, including code style, static analysis, and unit tests. This is a comprehensive command for verifying code quality.

```bash
$ composer checks
```

--------------------------------

### Configure DigiSign as Symfony Service

Source: https://context7.com/digitalcz/digisign/llms.txt

Configure the DigiSign client as a Symfony service using YAML. This allows dependency injection and easier management within a Symfony application.

```yaml
# config/services.yaml
services:
  DigitalCz\DigiSign\DigiSign:
    $options:
      access_key: '%env(DIGISIGN_ACCESS_KEY)%'
      secret_key: '%env(DIGISIGN_SECRET_KEY)%'
      cache:       '@psr16.cache'
      http_client: '@psr18.http_client'
      sandbox:     false
```

--------------------------------

### Upload a PDF File

Source: https://context7.com/digitalcz/digisign/llms.txt

Upload a local PDF file to DigiSign storage. The returned File resource's IRI is used to reference the file in subsequent operations. You can also download file content.

```php
use DigitalCz\DigiSign\DigiSign;
use DigitalCz\DigiSign\Stream\FileStream;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);

// Upload a local PDF
$file = $dgs->files()->upload(FileStream::open('/path/to/contract.pdf'));
echo $file->self();   // e.g. /api/files/abc123
echo $file->id;       // abc123

// Download file content back
$fileResponse = $dgs->files()->content($file->id());
file_put_contents('/tmp/downloaded.pdf', $fileResponse->getFile()->getHandle());
```

--------------------------------

### Create and Send a Delivery Request

Source: https://context7.com/digitalcz/digisign/llms.txt

Use this to send documents for receipt-acknowledgment delivery without requiring a signature. Ensure the file path is correctly configured.

```php
use DigitalCz\DigiSign\DigiSign;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);

$delivery = $dgs->deliveries()->create([
    'emailSubject' => 'Your invoice',
    'emailBody'    => 'Please find your invoice attached.',
    'senderName'   => 'Billing Department',
    'senderEmail'  => 'billing@company.com',
]);

$dgs->deliveries()->recipients($delivery)->create([
    'name'  => 'Customer A',
    'email' => 'customer@example.com',
]);

$dgs->deliveries()->documents($delivery)->create([
    'name' => 'Invoice',
    'file' => '/api/files/invoice-file-id',
]);

$dgs->deliveries()->send($delivery->id());
```

--------------------------------

### Fix Code Style and Run All Checks

Source: https://github.com/digitalcz/digisign/blob/2.x/CONTRIBUTING.md

Use these composer commands to maintain code style consistency and execute all project checks.

```bash
$ composer csfix    # fix codestyle
```

```bash
$ composer checks   # run all checks
```

--------------------------------

### Envelope Templates

Source: https://context7.com/digitalcz/digisign/llms.txt

Create and manage envelope templates for repeated signing workflows. Use a template to instantly create a pre-configured envelope.

```APIDOC
## Envelope Templates — Reusable Templates

Create and manage envelope templates for repeated signing workflows. Use a template to instantly create a pre-configured envelope.

```php
use DigitalCz\DigiSign\DigiSign;

$dgs       = new DigiSign(['access_key' => '...', 'secret_key' => '...']);
$templates = $dgs->envelopeTemplates();

// Create a template
$template = $templates->create([
    'name'         => 'Standard NDA',
    'emailSubject' => 'Please sign the NDA',
    'emailBody'    => 'Hi {{recipientName}}, please review and sign the attached NDA.',
]);

// Add a document, recipient, and tag to the template (same API as envelopes)
$templates->documents($template)->create(['name' => 'NDA Document', 'file' => '/api/files/xyz']);
$templates->recipients($template)->create(['role' => 'signer', 'name' => 'Template Signer']);

// Instantiate the template into a ready-to-send envelope
$envelope = $templates->use($template);
echo "New envelope from template: {$envelope->id()}\n";

// Clone an existing template
$copy = $templates->clone($template);
```
```

--------------------------------

### Manage Envelope Templates

Source: https://context7.com/digitalcz/digisign/llms.txt

Create and manage reusable envelope templates for consistent signing workflows. Supports creating templates, adding documents and recipients, instantiating templates into envelopes, and cloning existing templates.

```php
use DigitalCz\DigiSign\DigiSign;

$dgs       = new DigiSign(['access_key' => '...', 'secret_key' => '...']);
$templates = $dgs->envelopeTemplates();

// Create a template
$template = $templates->create([
    'name'         => 'Standard NDA',
    'emailSubject' => 'Please sign the NDA',
    'emailBody'    => 'Hi {{recipientName}}, please review and sign the attached NDA.',
]);

// Add a document, recipient, and tag to the template (same API as envelopes)
$templates->documents($template)->create(['name' => 'NDA Document', 'file' => '/api/files/xyz']);
$templates->recipients($template)->create(['role' => 'signer', 'name' => 'Template Signer']);

// Instantiate the template into a ready-to-send envelope
$envelope = $templates->use($template);
echo "New envelope from template: {$envelope->id()}\n";

// Clone an existing template
$copy = $templates->clone($template);
```

--------------------------------

### Manage Identity Verification Requests

Source: https://context7.com/digitalcz/digisign/llms.txt

This snippet demonstrates how to list pending identifications, download selfie images, and approve or deny verification requests. Remember to replace 'identification-id' with the actual ID.

```php
use DigitalCz\DigiSign\DigiSign;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);

// List all identifications
$list = $dgs->identifications()->list(['status' => ['in' => ['pending']]]);

foreach ($list->items as $identification) {
    echo "{$identification->id}: {$identification->status}\n";

    // Download selfie image
    $selfie = $dgs->identifications()->selfie($identification->id());
    file_put_contents("/tmp/selfie_{$identification->id()}.jpg", $selfie->getFile()->getHandle());

    // Approve or deny
    if ($identification->status === 'pending') {
        $dgs->identifications()->approve($identification->id());
        // or deny:
        // $dgs->identifications()->deny($identification->id(), ['reason' => 'Documents unclear']);
    }
}

// Download identification protocol PDF
$protocol = $dgs->identifications()->protocol('identification-id');
$protocol->save('/tmp/protocol.pdf');
```

--------------------------------

### Account - Settings and Administration

Source: https://context7.com/digitalcz/digisign/llms.txt

Read and update account settings, manage users, API keys, brandings, certificates, and retrieve statistics or billing information. This section covers administrative tasks for your DigiSign account.

```APIDOC
## Account — Settings and Administration

Read and update account settings, manage users, API keys, brandings, certificates, and retrieve statistics or billing information.

```php
use DigitalCz\DigiSign\DigiSign;
use DigitalCz\DigiSign\Exception\BadRequestException;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);

// Fetch current account info
$account = $dgs->account()->get();
echo "Account: {$account->name}\n";

// Update account settings with validation error handling
try {
    $dgs->account()->settings()->update([
        'defaultSenderEmail' => 'noreply@company.com',
        'shortName'          => 'CompanyCo',
    ]);
} catch (BadRequestException $e) {
    $violations = $e->getViolations();
    if ($violations !== null) {
        foreach ($violations->toArray() as $field => $messages) {
            echo "Validation error on '{$field}': " . implode(', ', $messages) . "\n";
        }
    }
}

// List account users
$users = $dgs->account()->users()->list();

// Create a new API key
$apiKey = $dgs->account()->apiKeys()->create(['name' => 'CI/CD Pipeline Key']);
echo "New API Key: {$apiKey->accessKey} / {$apiKey->secretKey}\n";

// Retrieve account statistics
$stats = $dgs->account()->statistics(['from' => '2024-01-01', 'to' => '2024-12-31']);

// Get billing info
$billing = $dgs->account()->billing();
```
```

--------------------------------

### Run CodeSniffer

Source: https://github.com/digitalcz/digisign/blob/2.x/README.md

Executes PHP_CodeSniffer to check the code against defined coding standards. This command helps in maintaining a consistent code style across the project.

```bash
$ composer cs
```

--------------------------------

### Download Completed Documents and Audit Log

Source: https://context7.com/digitalcz/digisign/llms.txt

Download signed documents from a completed envelope. You can download a single document, all documents as a ZIP archive, or just the audit log. The `save()` method is used to store the downloaded content.

```php
use DigitalCz\DigiSign\DigiSign;

$dgs        = new DigiSign(['access_key' => '...', 'secret_key' => '...']);
$envelopeId = 'abc-envelope-id';
$documentId = 'xyz-document-id';

// Download a single document as PDF
$fileResponse = $dgs->envelopes()->documents($envelopeId)->download($documentId);
$fileResponse->save('/tmp/signed_contract.pdf');

// Download all envelope documents as a ZIP (separate files)
$zipResponse = $dgs->envelopes()->download($envelopeId, ['output' => 'separate']);
$zipResponse->save('/tmp/');                           // saved using Content-Disposition filename
echo $zipResponse->getFile()->getFilename() . "\n";   // e.g. envelope_abc.zip

// Download the audit log only
$logResponse = $dgs->envelopes()->download($envelopeId, ['output' => 'only_log']);
file_put_contents('/tmp/audit_log.pdf', $logResponse->getFile()->getHandle());

```

--------------------------------

### Webhooks - Register and Validate

Source: https://context7.com/digitalcz/digisign/llms.txt

Register webhook endpoints to receive real-time event notifications and validate incoming webhook signature headers using HMAC-SHA256. This section covers setting up webhooks and verifying their authenticity.

```APIDOC
## Webhooks — Register and Validate

Register webhook endpoints to receive real-time event notifications, and validate incoming webhook signature headers using HMAC-SHA256.

```php
use DigitalCz\DigiSign\DigiSign;
use DigitalCz\DigiSign\Exception\InvalidSignatureException;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);

// Register a webhook
$webhook = $dgs->webhooks()->create([
    'url'    => 'https://myapp.com/webhooks/digisign',
    'events' => ['envelope.completed', 'envelope.signed', 'envelope.cancelled'],
]);
echo "Webhook secret: {$webhook->secret}\n";

// Test the webhook (triggers a test ping to the URL)
$dgs->webhooks()->test($webhook->id());

// ---- In your webhook receiver endpoint (e.g. POST /webhooks/digisign) ----
$header  = $_SERVER['HTTP_SIGNATURE'] ?? '';    // e.g. t=1631618784,s=105fdb...
$payload = file_get_contents('php://input');
$secret  = 'your-webhook-secret';

try {
    $dgs = new DigiSign();
    $dgs->setSignatureTolerance(300);           // reject requests older than 5 minutes
    $dgs->validateSignature($payload, $header, $secret);

    $event = json_decode($payload, true);
    // Process $event['type'], $event['data'] ...
    http_response_code(200);
} catch (InvalidSignatureException $e) {
    http_response_code(400);
    echo "Invalid signature: " . $e->getMessage();
}
```
```

--------------------------------

### Run Code Style Fixer

Source: https://github.com/digitalcz/digisign/blob/2.x/README.md

Executes the code style fixer to ensure code adheres to project standards. This command is part of the testing suite.

```bash
$ composer csfix
```

--------------------------------

### List Envelopes with Filtering and Pagination

Source: https://context7.com/digitalcz/digisign/llms.txt

Retrieve a paginated and filtered list of envelopes using the `list()` method. You can filter by status, search by subject, and sort the results. The `itemsPerPage` and `page` parameters control pagination.

```php
use DigitalCz\DigiSign\DigiSign;
use DigitalCz\DigiSign\Resource\Envelope;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);

$list = $dgs->envelopes()->list([
    'status'       => ['in' => ['draft', 'sent']],       // status filter
    'emailSubject' => ['contains' => 'Contract'],         // subject search
    'order'        => ['createdAt' => 'DESC'],            // sort descending
    'itemsPerPage' => 20,
    'page'         => 1,
]);

echo "Total: {$list->totalItems}\n";

/** @var Envelope $envelope */
foreach ($list->items as $envelope) {
    echo sprintf(
        "[%s] %s — %s\n",
        $envelope->status,
        $envelope->id,
        $envelope->emailSubject,
    );
}

```

--------------------------------

### Run PHPStan Static Analysis

Source: https://github.com/digitalcz/digisign/blob/2.x/README.md

Executes PHPStan for static analysis to detect potential bugs and type errors in the code. This helps in maintaining code quality and preventing runtime issues.

```bash
$ composer phpstan
```

--------------------------------

### Envelopes — Create and Send

Source: https://context7.com/digitalcz/digisign/llms.txt

This operation allows you to create a new envelope, add recipients and documents, place signature tags, and then send the envelope to initiate the signing process. It is the core workflow for requesting digital signatures.

```APIDOC
## Envelopes — Create and Send

Create an envelope, add recipients and documents, place signature tags, then send it. This is the core workflow for requesting digital signatures.

```php
use DigitalCz\DigiSign\DigiSign;
use DigitalCz\DigiSign\Stream\FileStream;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);
$envelopes = $dgs->envelopes();

// 1. Create the envelope
$envelope = $envelopes->create([
    'emailSubject' => 'Please sign the contract',
    'emailBody'    => 'Hello James, please sign the attached document.',
    'senderName'   => 'John Smith',
    'senderEmail'  => 'john.smith@example.com',
]);

// 2. Add a signer recipient
$recipient = $envelopes->recipients($envelope)->create([
    'role'   => 'signer',
    'name'   => 'James Brown',
    'email'  => 'james42@example.com',
    'mobile' => '+420775300500',
]);

// 3. Upload a PDF file and attach it as an envelope document
$file     = $dgs->files()->upload(FileStream::open('/path/to/contract.pdf'));
$document = $envelopes->documents($envelope)->create([
    'name' => 'Contract',
    'file' => $file,     // Resource instance is automatically converted to IRI
]);

// 4. Place a signature tag at position (200, 340) on page 1
$tag = $envelopes->tags($envelope)->create([
    'type'      => 'signature',
    'document'  => $document,
    'recipient' => $recipient,
    'page'      => 1,
    'xPosition' => 200,
    'yPosition' => 340,
]);

// 5. Send the envelope (triggers email delivery to recipient)
$envelopes->send($envelope->id());
echo "Envelope {$envelope->id()} sent successfully\n";
```
```

--------------------------------

### Envelopes — List with Filtering and Pagination

Source: https://context7.com/digitalcz/digisign/llms.txt

Retrieve a paginated and filtered list of envelopes using the `list()` method. You can filter by status, search by email subject, and sort the results.

```APIDOC
## Envelopes — List with Filtering and Pagination

Retrieve a paginated, filtered list of envelopes using the `list()` method with query parameters.

```php
use DigitalCz\DigiSign\DigiSign;
use DigitalCz\DigiSign\Resource\Envelope;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);

$list = $dgs->envelopes()->list([
    'status'       => ['in' => ['draft', 'sent']],       // status filter
    'emailSubject' => ['contains' => 'Contract'],         // subject search
    'order'        => ['createdAt' => 'DESC'],            // sort descending
    'itemsPerPage' => 20,
    'page'         => 1,
]);

echo "Total: {$list->totalItems}\n";

/** @var Envelope $envelope */
foreach ($list->items as $envelope) {
    echo sprintf(
        "[%s] %s — %s\n",
        $envelope->status,
        $envelope->id,
        $envelope->emailSubject,
    );
}
```
```

--------------------------------

### Bulk Signatures

Source: https://context7.com/digitalcz/digisign/llms.txt

Create, send, resend, and list bulk signature jobs. Bulk signatures allow a single signer to sign documents for multiple subjects at once.

```APIDOC
## Bulk Signatures — Signing Portal

Create and manage bulk signature requests, which allow a single signer to sign documents for multiple subjects at once.

```php
use DigitalCz\DigiSign\DigiSign;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);

// Create a bulk signature job
$bulk = $dgs->bulkSignature()->create([
    'name'      => 'Bulk Q4 Contracts',
    'signer'    => '/api/account/users/user-id',
    'documents' => [
        '/api/files/file1-id',
        '/api/files/file2-id',
    ],
]);

// Send the bulk signature request
$dgs->bulkSignature()->send($bulk->id());

// Resend if signer did not respond
$dgs->bulkSignature()->resend($bulk->id());

// List existing bulk signature jobs
$list = $dgs->bulkSignature()->list(['status' => ['in' => ['pending']]]);
foreach ($list->items as $item) {
    echo "{$item->id}: {$item->status}\n";
}
```
```

--------------------------------

### Error Handling

Source: https://context7.com/digitalcz/digisign/llms.txt

All HTTP error responses are thrown as typed exceptions that extend `ResponseException`. Inspect violation details from `BadRequestException` for form-validation failures.

```APIDOC
## Error Handling — Exception Types

All HTTP error responses are thrown as typed exceptions that extend `ResponseException`. Inspect violation details from `BadRequestException` for form-validation failures.

```php
use DigitalCz\DigiSign\DigiSign;
use DigitalCz\DigiSign\Exception\BadRequestException;
use DigitalCz\DigiSign\Exception\UnauthorizedException;
use DigitalCz\DigiSign\Exception\NotFoundException;
use DigitalCz\DigiSign\Exception\ForbiddenException;
use DigitalCz\DigiSign\Exception\ServerException;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);

try {
    $envelope = $dgs->envelopes()->get('non-existent-id');
} catch (NotFoundException $e) {
    echo "Not found: " . $e->getMessage() . "\n";
    // HTTP 404
} catch (UnauthorizedException $e) {
    echo "Unauthorized: " . $e->getMessage() . "\n";
    // HTTP 401 — bad credentials
} catch (ForbiddenException $e) {
    echo "Forbidden: " . $e->getMessage() . "\n";
    // HTTP 403
} catch (BadRequestException $e) {
    // HTTP 400 — includes field-level violation details
    $violations = $e->getViolations();
    if ($violations !== null) {
        foreach ($violations->toArray() as $field => $errors) {
            echo "Field '{$field}': " . implode('; ', $errors) . "\n";
        }
    }
} catch (ServerException $e) {
    echo "Server error (5xx): " . $e->getMessage() . "\n";
}
```
```

--------------------------------

### Register and Validate Webhooks

Source: https://context7.com/digitalcz/digisign/llms.txt

This code shows how to register a webhook endpoint for receiving event notifications and how to validate incoming webhook signatures using HMAC-SHA256. Ensure your webhook secret is kept secure.

```php
use DigitalCz\DigiSign\DigiSign;
use DigitalCz\DigiSign\Exception\InvalidSignatureException;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);

// Register a webhook
$webhook = $dgs->webhooks()->create([
    'url'    => 'https://myapp.com/webhooks/digisign',
    'events' => ['envelope.completed', 'envelope.signed', 'envelope.cancelled'],
]);
echo "Webhook secret: {$webhook->secret}\n";

// Test the webhook (triggers a test ping to the URL)
$dgs->webhooks()->test($webhook->id());

// ---- In your webhook receiver endpoint (e.g. POST /webhooks/digisign) ----
$header  = $_SERVER['HTTP_SIGNATURE'] ?? '';    // e.g. t=1631618784,s=105fdb...
$payload = file_get_contents('php://input');
$secret  = 'your-webhook-secret';

try {
    $dgs = new DigiSign();
    $dgs->setSignatureTolerance(300);           // reject requests older than 5 minutes
    $dgs->validateSignature($payload, $header, $secret);

    $event = json_decode($payload, true);
    // Process $event['type'], $event['data'] ...
    http_response_code(200);
} catch (InvalidSignatureException $e) {
    http_response_code(400);
    echo "Invalid signature: " . $e->getMessage();
}
```

--------------------------------

### Perform Additional Envelope Actions

Source: https://context7.com/digitalcz/digisign/llms.txt

This snippet covers various lifecycle actions for envelopes, including cancelling, resending notifications, cloning, discarding drafts, and generating embedded signing URLs. Ensure the envelope ID is valid for the action you intend to perform.

```php
use DigitalCz\DigiSign\DigiSign;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);
$id  = 'abc-envelope-id';

// Cancel a sent envelope
$dgs->envelopes()->cancel($id, ['reason' => 'Cancelled by sender']);

// Resend notification emails to all pending recipients
$dgs->envelopes()->resend($id);

// Clone an envelope (creates a new draft copy)
$cloned = $dgs->envelopes()->clone($id);
echo "Cloned envelope: {$cloned->id()}\n";

// Generate an embedded signing URL for a recipient
$embed = $dgs->envelopes()->embedSigning($id, ['recipient' => '/api/envelopes/abc/recipients/rec1']);
echo "Signing URL: {$embed->url}\n";

// Get envelope count statistics
$count = $dgs->envelopes()->count();

// Discard a draft
$dgs->envelopes()->discard($id);

```

--------------------------------

### Labels

Source: https://context7.com/digitalcz/digisign/llms.txt

Create and attach labels to envelopes for organizational grouping and filtering. Labels can be created with a name and color, and then attached to specific envelopes.

```APIDOC
## Labels — Organize Envelopes

Create and attach labels to envelopes for organizational grouping and filtering.

```php
use DigitalCz\DigiSign\DigiSign;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);

// Create a label
$label = $dgs->labels()->create(['name' => 'HR Contracts', 'color' => '#ff5500']);

// Attach label to an envelope
$dgs->envelopes()->labels('envelope-id')->create(['label' => $label->self()]);

// List labels on an envelope
$attachedLabels = $dgs->envelopes()->labels('envelope-id')->list();
```
```

--------------------------------

### Envelopes — Additional Actions

Source: https://context7.com/digitalcz/digisign/llms.txt

Perform various lifecycle actions on envelopes, including canceling, resending notifications, cloning, discarding, anonymizing, restoring, generating embedded signing URLs, and retrieving envelope counts.

```APIDOC
## Envelopes — Additional Actions

Perform lifecycle actions on envelopes: cancel, resend, clone, discard, anonymize, restore, embed, or start/finish corrections.

```php
use DigitalCz\DigiSign\DigiSign;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);
$id  = 'abc-envelope-id';

// Cancel a sent envelope
$dgs->envelopes()->cancel($id, ['reason' => 'Cancelled by sender']);

// Resend notification emails to all pending recipients
$dgs->envelopes()->resend($id);

// Clone an envelope (creates a new draft copy)
$cloned = $dgs->envelopes()->clone($id);
echo "Cloned envelope: {$cloned->id()}\n";

// Generate an embedded signing URL for a recipient
$embed = $dgs->envelopes()->embedSigning($id, ['recipient' => '/api/envelopes/abc/recipients/rec1']);
echo "Signing URL: {$embed->url}\n";

// Get envelope count statistics
$count = $dgs->envelopes()->count();

// Discard a draft
$dgs->envelopes()->discard($id);
```
```

--------------------------------

### Envelope Tags

Source: https://context7.com/digitalcz/digisign/llms.txt

Create, update, and manage signature and form-field tags on envelope documents, and fill tag values programmatically.

```APIDOC
## Envelope Tags — Signature Placement

Create, update, and manage signature and form-field tags on envelope documents, and fill tag values programmatically.

```php
use DigitalCz\DigiSign\DigiSign;

$dgs      = new DigiSign(['access_key' => '...', 'secret_key' => '...']);
$envelope = $dgs->envelopes()->get('abc-envelope-id');
$tags     = $dgs->envelopes()->tags($envelope);

// Create a signature tag
$sigTag = $tags->create([
    'type'      => 'signature',
    'document'  => '/api/envelopes/abc/documents/doc1',
    'recipient' => '/api/envelopes/abc/recipients/rec1',
    'page'      => 1,
    'xPosition' => 150,
    'yPosition' => 600,
    'width'     => 200,
    'height'    => 60,
]);

// Create a text input tag pre-filled with a value
$textTag = $tags->create([
    'type'        => 'text',
    'placeholder' => 'contract_date',
    'document'    => '/api/envelopes/abc/documents/doc1',
    'recipient'   => '/api/envelopes/abc/recipients/rec1',
    'page'        => 1,
    'xPosition'   => 100,
    'yPosition'   => 500,
]);

// Bulk update tag values by tag IRI
$tags->updateValues([
    '/api/envelopes/abc/tags/' . $textTag->id() => '2024-12-31',
]);

// Access tags by placeholder name
$byPlaceholder = $tags->byPlaceholder()->get('contract_date');
```
```

--------------------------------

### Envelopes — Download Completed Documents

Source: https://context7.com/digitalcz/digisign/llms.txt

Download signed documents from a completed envelope. You can download individual documents as PDFs, all documents as a ZIP archive, or retrieve the audit log.

```APIDOC
## Envelopes — Download Completed Documents

Download signed documents from a completed envelope, either individually or as a ZIP archive, or retrieve the audit log.

```php
use DigitalCz\DigiSign\DigiSign;

$dgs        = new DigiSign(['access_key' => '...', 'secret_key' => '...']);
$envelopeId = 'abc-envelope-id';
$documentId = 'xyz-document-id';

// Download a single document as PDF
$fileResponse = $dgs->envelopes()->documents($envelopeId)->download($documentId);
$fileResponse->save('/tmp/signed_contract.pdf');

// Download all envelope documents as a ZIP (separate files)
$zipResponse = $dgs->envelopes()->download($envelopeId, ['output' => 'separate']);
$zipResponse->save('/tmp/');                           // saved using Content-Disposition filename
echo $zipResponse->getFile()->getFilename() . "\n";   // e.g. envelope_abc.zip

// Download the audit log only
$logResponse = $dgs->envelopes()->download($envelopeId, ['output' => 'only_log']);
file_put_contents('/tmp/audit_log.pdf', $logResponse->getFile()->getHandle());
```
```

--------------------------------

### Handle API Errors with Typed Exceptions

Source: https://context7.com/digitalcz/digisign/llms.txt

Catch specific exceptions like NotFoundException, UnauthorizedException, BadRequestException, ForbiddenException, and ServerException to handle different HTTP error responses. BadRequestException provides field-level violation details.

```php
use DigitalCz\DigiSign\DigiSign;
use DigitalCz\DigiSign\Exception\BadRequestException;
use DigitalCz\DigiSign\Exception\UnauthorizedException;
use DigitalCz\DigiSign\Exception\NotFoundException;
use DigitalCz\DigiSign\Exception\ForbiddenException;
use DigitalCz\DigiSign\Exception\ServerException;

$dgs = new DigiSign(['access_key' => '...', 'secret_key' => '...']);

try {
    $envelope = $dgs->envelopes()->get('non-existent-id');
} catch (NotFoundException $e) {
    echo "Not found: " . $e->getMessage() . "\n";
    // HTTP 404
} catch (UnauthorizedException $e) {
    echo "Unauthorized: " . $e->getMessage() . "\n";
    // HTTP 401 — bad credentials
} catch (ForbiddenException $e) {
    echo "Forbidden: " . $e->getMessage() . "\n";
    // HTTP 403
} catch (BadRequestException $e) {
    // HTTP 400 — includes field-level violation details
    $violations = $e->getViolations();
    if ($violations !== null) {
        foreach ($violations->toArray() as $field => $errors) {
            echo "Field '{$field}': " . implode('; ', $errors) . "\n";
        }
    }
} catch (ServerException $e) {
    echo "Server error (5xx): " . $e->getMessage() . "\n";
}
```

--------------------------------

### Batch Sendings

Source: https://context7.com/digitalcz/digisign/llms.txt

Use batch sendings to send the same envelope to many recipients in one operation, track per-item status, and retrieve statistics.

```APIDOC
## Batch Sendings — Send to Multiple Recipients

Use batch sendings to send the same envelope to many recipients in one operation, track per-item status, and retrieve statistics.

```php
use DigitalCz\DigiSign\DigiSign;

$dgs   = new DigiSign(['access_key' => '...', 'secret_key' => '...']);
$batch = $dgs->batchSendings();

// Create a batch sending
$batchSending = $batch->create([
    'name'     => 'Q4 Contract Batch',
    'template' => '/api/envelope-templates/template-id',
]);

// Add items (individual recipients) to the batch
$batch->items($batchSending)->create([
    'recipients' => [
        ['name' => 'Carol', 'email' => 'carol@example.com'],
    ],
]);
$batch->items($batchSending)->create([
    'recipients' => [
        ['name' => 'Dave', 'email' => 'dave@example.com'],
    ],
]);

// Send the entire batch
$batch->send($batchSending);

// Retrieve statistics after sending
$stats = $batch->stats($batchSending);
echo "Total: {$stats->total}, Sent: {$stats->sent}, Signed: {$stats->signed}\n";
```
```

--------------------------------

### Manage Batch Sendings

Source: https://context7.com/digitalcz/digisign/llms.txt

Send the same envelope to multiple recipients in a single operation and track their status. Supports creating batch sendings, adding individual recipients, sending the batch, and retrieving statistics.

```php
use DigitalCz\DigiSign\DigiSign;

$dgs   = new DigiSign(['access_key' => '...', 'secret_key' => '...']);
$batch = $dgs->batchSendings();

// Create a batch sending
$batchSending = $batch->create([
    'name'     => 'Q4 Contract Batch',
    'template' => '/api/envelope-templates/template-id',
]);

// Add items (individual recipients) to the batch
$batch->items($batchSending)->create([
    'recipients' => [
        ['name' => 'Carol', 'email' => 'carol@example.com'],
    ],
]);
$batch->items($batchSending)->create([
    'recipients' => [
        ['name' => 'Dave', 'email' => 'dave@example.com'],
    ],
]);

// Send the entire batch
$batch->send($batchSending);

// Retrieve statistics after sending
$stats = $batch->stats($batchSending);
echo "Total: {$stats->total}, Sent: {$stats->sent}, Signed: {$stats->signed}\n";
```