Электронная подпись на сайте: интеграция 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 дней