README

This package provides an easy-to-use Laravel integration with eSignatures.io, allowing you to send, manage, and track contracts programmatically.

Features

Send contracts using eSignatures.io templates.
Use custom PDFs for signing without templates.
Manage signers (add, update, delete).
Handle webhooks for real-time contract updates.
Withdraw contracts.
List and copy templates.
Logging support for debugging and monitoring.

Installation

Install the package via Composer:

composer require kirchevsky/laravel-esignatures

Publish the configuration (optional):

php artisan vendor:publish --tag=esignatures-config

Add your eSignatures.io API token to the .env file:
```
ESIGNATURES_TOKEN=your-secret-token
```

Usage

Basic Initialization

Create an instance of the module:

use YourNamespace\ESignatures\ESignatures;

$eSignatures = new ESignatures(env('ESIGNATURES_TOKEN'));

Sending a Contract with a Template

$response = $eSignatures->sendContract([
    'template_id' => 'template-id',
    'signers' => [
        [
            'name' => 'John Doe',
            'email' => 'john@example.com',
            'mobile' => '+1234567890',
        ],
    ],
    'title' => 'Contract Title',
    'metadata' => 'custom-metadata',
]);

if ($response['status'] === 'queued') {
    echo "Contract sent successfully!";
}

Fetching Contract Details

$contract = $eSignatures->getContract('contract-id');
echo "Contract Title: " . $contract['data']['contract']['title'];

Withdrawing a Contract

$response = $eSignatures->withdrawContract('contract-id');
if ($response['status'] === 'queued') {
    echo "Contract withdrawn successfully!";
}

Managing Signers

Add a Signer:

$response = $eSignatures->addSigner('contract-id', [
    'name' => 'New Signer',
    'email' => 'new@example.com',
    'mobile' => '+1234567890',
]);

Update a Signer:

$response = $eSignatures->updateSigner('contract-id', 'signer-id', [
    'name' => 'Updated Signer',
    'email' => 'updated@example.com',
]);

Delete a Signer:

$response = $eSignatures->deleteSigner('contract-id', 'signer-id');

Webhook Handling

Handle webhook notifications from eSignatures.io:

Add a route in your web.php:

Route::post('/webhook/esignatures', [WebhookController::class, 'handle']);

Create the WebhookController:

use Illuminate\Http\Request;
use YourNamespace\ESignatures\ESignatures;

class WebhookController extends Controller
{
    public function handle(Request $request)
    {
        $eSignatures = new ESignatures(env('ESIGNATURES_TOKEN'));
        $eSignatures->handleWebhook(function ($payload) {
            // Process the webhook payload
            Log::info('Webhook received', $payload);
        });
    }
}

Advanced Usage

List Templates

$templates = $eSignatures->listTemplates();
foreach ($templates['data'] as $template) {
    echo "Template ID: {$template['template_id']}, Name: {$template['template_name']}\n";
}

Copy a Template

$response = $eSignatures->copyTemplate('template-id', [
    'title' => 'New Template',
    'placeholder_fields' => [
        [
            'api_key' => 'field-key',
            'value' => 'Field Value',
        ],
    ],
]);

Debugging & Logging

If you want to log API requests and responses, pass a PSR-3 logger (like Laravel's Log facade) during initialization:

use Illuminate\Support\Facades\Log;

$eSignatures = new ESignatures(env('ESIGNATURES_TOKEN'), Log::channel('stack'));

Contributing

Fork the repository.
Create a new branch (git checkout -b feature-name).
Make your changes.
Commit your changes (git commit -am 'Add new feature').
Push to the branch (git push origin feature-name).
Open a Pull Request.

License

This package is open-sourced software licensed under the MIT license.

Support

If you encounter any issues or have questions, feel free to open an issue on GitHub.

kirchevsky / laravel-esignatures

Maintainers

Details