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

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

PandaDoc відрізняється від DocuSign та SignNow тим, що це не просто сервіс підпису, а повноцінна платформа для роботи з документами: створення з шаблонів, змінні, approval workflows, платіжні блоки всередині документа, аналітика відкриттів. REST API охоплює весь цикл від створення до архівування.

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

У 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.

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

PandaDoc підтримує шаблони — це зручніше, ніж кожен раз завантажувати PDF:

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);
}

Відправка на підпис

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, // true — не відправляти email, тільки посилання
    ]);
}

Embedded signing через session link

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'); // це session ID, не URL напрямку
    // URL для iframe: https://app.pandadoc.com/s/{session_id}
}

Остаточна URL для iframe: https://app.pandadoc.com/s/{session_id}. PandaDoc відправляє postMessage при завершенні підписання.

Webhook

// Реєстрація в налаштуваннях PandaDoc: Settings → API → Webhooks → Add endpoint

public function handlePandaDocWebhook(Request $request): Response
{
    // PandaDoc підписує через HMAC-SHA256, ключ з налаштувань
    $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-запиті — ітеруємо масив.

Скачування та зберігання

public function download(string $documentId, string $savePath): void
{
    $response = Http::withHeaders([
        'Authorization' => 'API-Key ' . config('services.pandadoc.api_key'),
    ])->get("{$this->baseUrl}/documents/{$documentId}/download");

    file_put_contents($savePath, $response->body());
}

Що відрізняє PandaDoc

Шаблони з брендингом (логотип, кольори, стиль), pricing tables прямо в документі (клієнт бачить суму та підписує), approval workflows (документ проходить внутрішнє узгодження до відправки клієнту), вбудована аналітика перегляду (коли відкрили, скільки часу на кожній сторінці). Це робить PandaDoc підходящим для комерційних пропозицій та договорів з ціноутворенням, а не тільки для типових бланків.

Терміни

Базова інтеграція (шаблон → створення → відправка → webhook → скачування): 2–3 робочих дні. З embedded signing, токенами з CRM та approval workflow: 4–5 робочих днів.