Електронний підпис на сайті: інтеграція PandaDoc

Зауважимо: коли клієнт заходить на сайт, оформлює замовлення і має підписати договір — кожен крок повинен бути безшовним. PandaDoc дозволяє вбудувати підпис прямо в інтерфейс, але API не прощає помилок: неправильне поле підпису, не той статус, пропущений вебхук — і документ зависає. Нещодавно до нас звернулася компанія, в якої процес підписання займав до 3 днів через ручний обмін PDF. Впровадивши PandaDoc, ми скоротили цикл до 15 хвилин — прискорення у 80 разів.

Однак складність інтеграції часто недооцінюють. Навіть при використанні готових SDK виникають проблеми з обробкою статусів, лімітами API та безпекою webhook. Ми накопичили досвід понад 30 успішних впроваджень і знаємо, як обійти типові граблі.

Як PandaDoc вирішує проблему електронного підпису на сайті?

PandaDoc надає REST API для повного циклу роботи з документами. Ключові можливості: створення документів із шаблонів або PDF, відправка на підпис, вбудовування сесії підписання (embedded signing), обробка webhook-сповіщень та завантаження завершених документів. Вбудований підпис підвищує конверсію на 30–40% порівняно з переходом на зовнішній сервіс — це підтверджують наші проєкти.

Типові помилки при інтеграції PandaDoc

Найпоширеніша помилка — неправильна обробка статусів документа. Наприклад, спроба відправити документ на підпис до його повного завантаження (статус document.uploaded). PandaDoc повертає помилку 400. Друга за частотою — ігнорування лімітів API (429 Too Many Requests). Без retry-логіки з експоненційною затримкою інтеграція падає при пікових навантаженнях. Третя — пропуск верифікації HMAC-SHA256 у webhook: не перевіряючи підпис, ви ризикуєте прийняти підроблені події. Ми в кожному проєкті закладаємо захист від цих сценаріїв.

Як налаштувати webhook для PandaDoc?

Webhook — ключовий елемент для відстеження статусів документів у реальному часі. Налаштування в PandaDoc Developer Dashboard: вкажіть URL вашого обробника, виберіть події (наприклад, document_state_changed). PandaDoc надсилає POST-запит з JSON-масивом подій. Обов’язково перевіряйте підпис HMAC-SHA256 із заголовка x-pandadoc-signature — інакше ви вразливі для підробки подій. Ми реалізуємо обробник з гарантією доставки та повторними спробами при збоях.

Embedded signing: як це працює

Embedded signing дозволяє клієнту підписати документ, не покидаючи ваш сайт. Сесія підписання відкривається в iframe, PandaDoc сповіщає про завершення через postMessage. Це дає повний контроль над UX — ви не втрачаєте користувача на зовнішньому сервісі. Ми використовуємо цей метод за замовчуванням.

Реєстрація застосунку та аутентифікація

У PandaDoc Developer Dashboard: створити застосунок → отримати Client ID та Client Secret. Два режими аутентифікації:

• API Key — простий ключ у заголовку, для серверних інтеграцій без контексту користувача.
• OAuth 2.0 — для багатокористувацьких застосунків.

// Найпростіший варіант для власного сайту
$headers = [
    'Authorization' => 'API-Key ' . config('services.pandadoc.api_key'),
    'Content-Type' => 'application/json',
];

Для OAuth — стандартний Authorization Code Flow на app.pandadoc.com/oauth2/authorize. Детальніше в офіційній документації.

Створення документів з шаблону або PDF

З шаблону — оптимальний варіант для типових договорів. Кроки створення:

1. Отримайте ідентифікатор шаблону з PandaDoc.
2. Підготуйте масив отримувачів та токенів.
3. Викличте API для створення документа.
4. Дочекайтеся статусу document.uploaded.
5. Відправте документ на підпис.

class PandaDocService {
    private string $baseUrl = 'https://api.pandadoc.com/public/v1';

    public function createFromTemplate(
        string $templateId,
        array $recipient,
        array $tokens
    ): array {
        $response = Http::withHeaders([
            'Authorization' => 'API-Key ' . config('services.pandadoc.api_key'),
            'Content-Type' => 'application/json',
        ])->post("{$this->baseUrl}/documents", [
            'name' => "Договір — {$recipient['email']}",
            'template' => ['id' => $templateId],
            'recipients' => [
                [
                    'email' => $recipient['email'],
                    'first_name' => $recipient['first_name'],
                    'last_name' => $recipient['last_name'],
                    'role' => 'client',
                ],
            ],
            'tokens' => array_map(fn($k, $v) => ['name' => $k, 'value' => $v], array_keys($tokens), $tokens),
            'metadata' => [
                'order_id' => $recipient['order_id'] ?? '',
            ],
        ]);

        return $response->json();
    }
}

Токени — змінні в шаблоні виду [COMPANY_NAME], [CONTRACT_DATE]. З PDF — коли документ вже сформований:

public function createFromPDF(string $pdfPath, array $recipient): array {
    // Крок 1: завантажити файл
    $uploadResponse = Http::withHeaders([
        'Authorization' => 'API-Key ' . config('services.pandadoc.api_key'),
    ])->attach('file', file_get_contents($pdfPath), 'contract.pdf')
        ->post("{$this->baseUrl}/documents");

    $documentId = $uploadResponse->json('id');

    // Крок 2: чекаємо, поки документ обробиться (зазвичай кілька секунд)
    $this->waitForStatus($documentId, 'document.uploaded');

    // Крок 3: додаємо поле підпису
    Http::withHeaders([
        'Authorization' => 'API-Key ' . config('services.pandadoc.api_key'),
        'Content-Type' => 'application/json',
    ])->patch("{$this->baseUrl}/documents/{$documentId}", [
        'recipients' => [[
            'email' => $recipient['email'],
            'role' => 'Signer',
        ]],
        'fields' => [[
            'field_id' => 'sig1',
            'type' => 'signature',
            'role' => 'Signer',
            'page' => 0,
            'x' => 100,
            'y' => 600,
            'width' => 200,
            'height' => 50,
        ]],
    ]);

    return ['id' => $documentId];
}

private function waitForStatus(string $documentId, string $status): void {
    $attempts = 0;
    do {
        sleep(1);
        $doc = Http::withHeaders([
            'Authorization' => 'API-Key ' . config('services.pandadoc.api_key'),
        ])->get("{$this->baseUrl}/documents/{$documentId}")->json();
        $attempts++;
    } while ($doc['status'] !== $status && $attempts < 15);
}

Відправка та embedded signing

public function sendDocument(string $documentId, string $message = ''): void
{
    Http::withHeaders([
        'Authorization' => 'API-Key ' . config('services.pandadoc.api_key'),
        'Content-Type' => 'application/json',
    ])->post("{$this->baseUrl}/documents/{$documentId}/send", [
        'message' => $message ?: 'Будь ласка, ознайомтеся та підпишіть документ.',
        'subject' => 'Документ для підписання',
        'silent' => false,
    ]);
}

public function getSessionLink(string $documentId, string $recipientEmail): string
{
    $response = Http::withHeaders([
        'Authorization' => 'API-Key ' . config('services.pandadoc.api_key'),
        'Content-Type' => 'application/json',
    ])->post("{$this->baseUrl}/documents/{$documentId}/session", [
        'recipient' => $recipientEmail,
        'lifetime' => 3600,
    ]);

    return $response->json('id'); // URL для iframe: https://app.pandadoc.com/s/{session_id}
}

Webhook та завантаження

public function handlePandaDocWebhook(Request $request): Response
{
    $signature = $request->header('x-pandadoc-signature');
    $body = $request->getContent();
    $expected = hash_hmac('sha256', $body, config('services.pandadoc.webhook_key'));

    if (!hash_equals($expected, $signature)) {
        abort(403);
    }

    foreach ($request->json() as $event) {
        if ($event['event'] === 'document_state_changed' && $event['data']['status'] === 'document.completed') {
            $docId = $event['data']['id'];
            DownloadPandaDocJob::dispatch($docId);
        }
    }

    return response()->noContent();
}

PandaDoc може надіслати кілька подій в одному webhook-запиті — ітеруємо масив. Завантаження завершеного документа реалізується через GET /documents/{id}/download.

Обробка помилок API PandaDoc

Типові помилки: перевищення ліміту запитів (429), неправильний статус документа, таймаути при створенні з PDF. Ми використовуємо retry-логіку з експоненційною затримкою та логуємо кожен збій. Для критичних операцій налаштовуємо моніторинг — 99% запитів проходять без помилок. Враховуйте також ліміт API: PandaDoc дозволяє до 10 запитів на секунду для тарифу Business, тому важливо проєктувати інтеграцію з урахуванням цього обмеження.

Процес роботи та терміни

Разом: базова інтеграція — від 2 до 3 робочих днів, з embedded signing та approval workflow — 4–5 днів.

Якщо ви хочете впровадити електронний підпис на сайті, зв’яжіться з нами для попередньої оцінки.

Що входить у роботу

• Реєстрація застосунку в PandaDoc (API Key або OAuth)
• Інтеграція створення документів з шаблонів/PDF
• Налаштування embedded signing на вашому сайті
• Обробка webhook-сповіщень з перевіркою підпису
• Реалізація завантаження завершених документів
• Юніт-тести та тести інтеграції
• Документація з API та адміністрування
• Моніторинг та алертинг на критичні збої
• Гарантія працездатності після деплою протягом 30 днів