חתימה אלקטרונית באתר שלך: אינטגרציית PandaDoc

חתימה אלקטרונית באתר שלך: שילוב PandaDoc

תארו לעצמכם: לקוח מבקר באתר שלכם, מבצע הזמנה, וצריך לחתום על חוזה—כל שלב חייב להיות חלק. PandaDoc מאפשרת להטמיע את החתימה ישירות בממשק, אבל ה-API לא סולח על טעויות: שדה חתימה שגוי, סטטוס לא נכון, webhook שהוחמץ—והמסמך נתקע. לאחרונה פנתה אלינו חברה שתהליך החתימה אצלה ארך עד 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). ללא לוגיקת ניסיון חוזר עם backoff אקספוננציאלי, האינטגרציה נכשלת בעומס שיא. השלישית היא דילוג על אימות HMAC-SHA256 ב-webhooks: אי-אימות החתימה מסכן בקבלת אירועים מזויפים. בכל פרויקט, אנו כוללים הגנה מפני תרחישים אלה.

כיצד להגדיר Webhook עבור PandaDoc

Webhooks הם המפתח למעקב בזמן אמת אחר סטטוס המסמך. בלוח המפתחים של PandaDoc: ציינו את כתובת ה-handler שלכם, בחרו אירועים (לדוגמה, document_state_changed). PandaDoc שולחת בקשת POST עם מערך JSON של אירועים. תמיד אמתו את חתימת ה-HMAC-SHA256 מה-header x-pandadoc-signature—אחרת אתם חשופים לזיוף אירועים. אנו מיישמים handler עם אספקה מובטחת וניסיונות חוזרים במקרה של כשל.

חתימה מוטמעת: איך זה עובד

חתימה מוטמעת מאפשרת ללקוח לחתום על המסמך מבלי לעזוב את האתר שלכם. סשן החתימה נפתח ב-iframe; PandaDoc מודיעה על השלמה דרך postMessage. זה נותן לכם שליטה מלאה על חוויית המשתמש—אתם לא מאבדים את המשתמש לשירות חיצוני. אנו משתמשים בשיטה זו כברירת מחדל.

רישום אפליקציה ואימות

בלוח המפתחים של PandaDoc: צרו אפליקציה → קבלו Client ID ו-Client Secret. שני מצבי אימות:

• API Key — מפתח פשוט ב-header, לאינטגרציות צד-שרת ללא הקשר משתמש.
• OAuth 2.0 — עבור יישומים מרובי משתמשים.

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

עבור OAuth — תהליך Authorization Code Flow סטנדרטי ב-// Самый простой вариант для собственного сайта $headers = [ 'Authorization' => 'API-Key ' . config('services.pandadoc.api_key'), 'Content-Type' => 'application/json', ]; . פרטים בתיעוד הרשמי.

יצירת מסמכים מתבנית או PDF

שימוש בתבנית הוא אופטימלי עבור חוזים סטנדרטיים. שלבי היצירה:

1. קבלו את מזהה התבנית מ-PandaDoc.
2. הכינו מערך של נמענים ו-tokens.
3. קראו ל-API ליצירת המסמך.
4. חכו לסטטוס app.pandadoc.com/oauth2/authorize.
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();
    }
}

Tokens הם משתנים בתבנית כמו document.uploaded, 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(); } } . מ-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,
    ]);
}

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 אחת—עברו על המערך. הורדת מסמך שהושלם מיושמת דרך [COMPANY_NAME].

טיפול בשגיאות API של PandaDoc

שגיאות אופייניות: חריגה ממגבלת קצב (429), סטטוס מסמך לא חוקי, timeouts בעת יצירה מ-PDF. אנו משתמשים בלוגיקת ניסיון חוזר עם backoff אקספוננציאלי ורושמים כל כשל. עבור פעולות קריטיות, אנו מגדירים ניטור—99% מהבקשות עוברות ללא שגיאות. כמו כן, קחו בחשבון את מגבלת ה-API: PandaDoc מאפשרת עד 10 בקשות בשנייה עבור תוכנית Business, אז תכננו את האינטגרציה בהתאם.

תהליך ולוח זמנים

סה"כ: אינטגרציה בסיסית — בין 2 ל-3 ימי עבודה, עם חתימה מוטמעת ותהליך אישור — 4–5 ימים.

אם אתם רוצים להטמיע חתימה אלקטרונית באתר שלכם, צרו קשר להערכה מקדימה.

מה כלול

• רישום אפליקציה ב-PandaDoc (API Key או OAuth)
• אינטגרציה ליצירת מסמכים מתבניות/PDF
• הגדרת חתימה מוטמעת באתר שלכם
• טיפול בהודעות webhook עם אימות חתימה
• יישום הורדת מסמכים שהושלמו
• בדיקות יחידה ובדיקות אינטגרציה
• תיעוד API וניהול
• ניטור והתראות על כשלים קריטיים
• אחריות ל-30 יום לאחר הפריסה