שילוב DocuSign: API, חתימה משובצת והגדרת Webhook

שילוב DocuSign עם יישום אינטרנט לחתימה אלקטרונית באתר נתקל לעיתים קרובות בשגיאות OAuth, מחרוזות עיגון שגויות, או webhooks שהוגדרו בצורה לא נכונה. בעיות נפוצות כוללות redirect URIs שגויים, גרסאות SDK מיושנות, ותגי PDF שאינם תואמים. כל זה מוביל לכשלי ריצה ואובדן עסקאות. אנו מתמחים בשילוב API של DocuSign: השלמנו למעלה מ-30 פרויקטים שבהם DocuSign משמש לחתימה על חוזים, מסמכים וחשבוניות. בממוצע, הלקוחות שלנו מקצרים את זמן עיבוד המסמכים ב-40% ומאיצים את סגירת העסקאות פי 3. חתימה משובצת (Embedded signing) דרך API של DocuSign משפרת את שיעור ההשלמה פי 3 בהשוואה לחתימה בדוא"ל, וחוסכת עד $1,500 בחודש בעלויות עיבוד ידני.

למה לבחור ב-DocuSign?

DocuSign הוא המוביל בשוק החתימות האלקטרוניות בארה"ב ובאירופה. הוא תומך בחתימות מחייבות מבחינה משפטית לפי eIDAS (אירופה), UETA/ESIGN (ארה"ב), ובתקנים לאומיים נוספים. לשוק הרוסי: DocuSign מספק חתימה אלקטרונית פשוטה (SES) המוכרת בבית המשפט אם קיים הסכם בין הצדדים—זה מספיק לרוב החוזים המסחריים. לפרטים נוספים, ראו תיעוד DocuSign הרשמי.

איך השילוב עובד?

זרימה טיפוסית:

1. המשתמש ממלא נתונים באתר → לוחץ על "חתום על החוזה"
2. השרת (Backend) יוצר Envelope ב-DocuSign עם המסמך והנמענים
3. המשתמש מועבר ל-DocuSign לחתימה (או מקבל דוא"ל)
4. לאחר החתימה, DocuSign מודיע לאתר דרך webhook
5. השרת מוריד את המסמך החתום ושומר אותו

אנו מיישמים שני תרחישים: שליחת דוא"ל או חתימה משובצת—חתימה ישירות באתר. השוואה:

הגדרת היישום

בפורטל המפתחים של DocuSign: צור Integration Key → הוסף redirect URI → בקש Secret Key. לבדיקות—סביבת Demo חינמית (account-d.docusign.com).

composer require docusign/esign-client 

OAuth: קבלת Token

DocuSign משתמש ב-OAuth 2.0 Authorization Code Grant:

class DocuSignAuthService {
    public function getAuthUrl(): string
    {
        $params = http_build_query([
            'response_type' => 'code',
            'scope' => 'signature',
            'client_id' => config('docusign.integrator_key'),
            'redirect_uri' => config('docusign.redirect_uri'),
        ]);

        return 'https://account-d.docusign.com/oauth/auth?' . $params;
    }

    public function handleCallback(string $code): string
    {
        $response = Http::withBasicAuth(
            config('docusign.integrator_key'),
            config('docusign.client_secret')
        )->asForm()->post('https://account-d.docusign.com/oauth/token', [
            'grant_type' => 'authorization_code',
            'code' => $code,
            'redirect_uri' => config('docusign.redirect_uri'),
        ]);

        return $response->json('access_token');
    }
}

לתרחישים בצד השרת ללא אינטראקציה עם המשתמש—JWT Grant (חשבון שירות).

יצירת Envelope ושליחה לחתימה

class DocuSignEnvelopeService {
    public function createEnvelope( string $accessToken, string $pdfPath, array $signers ): string {
        $config = new \DocuSign\eSign\Configuration();
        $config->setHost(config('docusign.base_url'));
        $config->addDefaultHeader('Authorization', "Bearer {$accessToken}");
        $apiClient = new \DocuSign\eSign\client\ApiClient($config);
        $envelopesApi = new \DocuSign\eSign\Api\EnvelopesApi($apiClient);
        $document = new \DocuSign\eSign\Model\Document([
            'document_base64' => base64_encode(file_get_contents($pdfPath)),
            'name' => 'Договор',
            'file_extension' => 'pdf',
            'document_id' => '1',
        ]);
        $signHere = new \DocuSign\eSign\Model\SignHere([
            'anchor_string' => '/sig1/',
            'anchor_x_offset' => '20',
            'anchor_y_offset' => '-10',
            'anchor_units' => 'pixels',
        ]);
        $recipientList = [];
        foreach ($signers as $i => $signer) {
            $tabs = new \DocuSign\eSign\Model\Tabs(['sign_here_tabs' => [$signHere]]);
            $recipientList[] = new \DocuSign\eSign\Model\Signer([
                'email' => $signer['email'],
                'name' => $signer['name'],
                'recipient_id' => (string)($i + 1),
                'routing_order'=> (string)($i + 1),
                'tabs' => $tabs,
            ]);
        }
        $envelopeDefinition = new \DocuSign\eSign\Model\EnvelopeDefinition([
            'email_subject' => 'Пожалуйста, подпишите документ',
            'documents' => [$document],
            'recipients' => new \DocuSign\eSign\Model\Recipients([
                'signers' => $recipientList,
            ]),
            'status' => 'sent',
        ]);
        $result = $envelopesApi->createEnvelope(
            config('docusign.account_id'),
            $envelopeDefinition
        );
        return $result->getEnvelopeId();
    }
}

חתימה משובצת: חתימה ישירות באתר

במקום הפניה ל-DocuSign—iframe משובץ או הפניה חזרה לאתר:

public function getSigningUrl(string $accessToken, string $envelopeId, array $signer): string {
    $config = new \DocuSign\eSign\Configuration();
    $config->setHost(config('docusign.base_url'));
    $config->addDefaultHeader('Authorization', "Bearer {$accessToken}");
    $apiClient = new \DocuSign\eSign\client\ApiClient($config);
    $envelopesApi = new \DocuSign\eSign\Api\EnvelopesApi($apiClient);
    $viewRequest = new \DocuSign\eSign\Model\RecipientViewRequest([
        'authentication_method' => 'none',
        'client_user_id' => $signer['id'],
        'recipient_id' => '1',
        'return_url' => route('contracts.signed'),
        'user_name' => $signer['name'],
        'email' => $signer['email'],
    ]);
    $result = $envelopesApi->createRecipientView(
        config('docusign.account_id'),
        $envelopeId,
        $viewRequest
    );
    return $result->getUrl();
}

Webhook: הודעה על חתימה

לאחר החתימה, DocuSign שולח XML עם הסטטוס החדש. השרת חייב לעבד את הבקשה, לוודא שהסטטוס הוא composer require docusign/esign-client , ולהתחיל בהורדת המסמך. אנו מגדירים endpoint שמקבל בקשת POST ומוודאים שהוא נגיש מהעולם החיצון. בסביבת ייצור, HTTPS הוא חובה.