Интеграция электронной подписи DocuSign на сайт

Интеграция DocuSign с веб-приложением часто сталкивается с ошибками OAuth, неверными anchor-строками или неправильной настройкой webhook. Типичные проблемы — неверно настроенные redirect URI, устаревшие версии SDK и несовпадение тегов в PDF. Всё это приводит к сбоям в рантайме и срыву сделок. Мы специализируемся на таких интеграциях: за время работы реализовали более 30 проектов, где DocuSign используется для подписания договоров, актов и счетов. В среднем наши клиенты сокращают время на обработку документов на 40% и ускоряют закрытие сделок в 3 раза.

Почему стоит выбрать DocuSign?

DocuSign — лидер рынка электронных подписей в США и Европе. Поддерживает юридически обязывающие подписи по стандартам eIDAS (Европа), UETA/ESIGN (США), и ряду национальных стандартов. Для российского рынка важно: DocuSign даёт простую электронную подпись (ПЭП), которая признаётся в суде при наличии соглашения сторон — для большинства коммерческих договоров этого достаточно. Официальная документация DocuSign.

Как устроена интеграция?

Типовой флоу:

1. На сайте пользователь заполняет данные → нажимает «Подписать договор»
2. Бэкенд создаёт Envelope (конверт) в DocuSign с документом и получателями
3. Пользователь перенаправляется на DocuSign для подписания (или получает email)
4. После подписания DocuSign уведомляет сайт через webhook
5. Бэкенд скачивает подписанный документ и сохраняет

Мы реализуем два сценария: отправка по email или embedded signing — подпись прямо на сайте. Сравнение:

Настройка приложения

В DocuSign Developer Portal: создать Integration Key → добавить redirect URI → запросить Secret Key. Для тестирования — бесплатная Demo среда (account-d.docusign.com).

composer require docusign/esign-client 

OAuth: получение токена

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 (сервис-аккаунт).

Создание конверта и отправка на подпись

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

Embedded signing: подпись прямо на сайте

Вместо перехода на 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 с новым статусом. Сервер должен обработать запрос, проверить, что статус Completed, и запустить загрузку документа. Мы настраиваем эндпоинт, который принимает POST-запросы, и гарантируем, что он доступен внешнему миру. В Production обязательно используем HTTPS.

Какие подводные камни при интеграции?

Наиболее частые ошибки:

• Ошибка OAuth: неверный redirect URI или scope. Убедитесь, что в настройках приложения указан точный URI, включая протокол и порт.
• Несовпадение anchor-строк: если документ PDF не содержит указанной anchor-строки, DocuSign выдаст ошибку. Используйте теги вида /sig1/ внутри исходного документа.
• Потеря webhook: при тестировании обязательно проверяйте, что сервер доступен из внешней сети (не localhost) и что DocuSign может отправить запрос. На Production используйте HTTPS.

Если вы столкнётесь с этими проблемами — наша команда поможет их оперативно решить.

Что входит в нашу работу?

• Анализ бизнес-процессов и выбор оптимального сценария (email/embedded)
• Настройка приложения DocuSign (Integration Key, Secret, Redirect URI)
• Разработка API-интеграции: создание Envelope, управление подписанием
• Интеграция webhook для автоматического обновления статуса
• Embedded signing: встраивание iframe с кастомными настройками
• Тестирование в Demo-среде и переключение на Production
• Документация по эксплуатации (инструкция для администратора)
• Обучение сотрудников работе с новой системой

Гарантируем стабильную работу и своевременную поддержку после запуска. Свяжитесь с нами — обсудим ваш проект и подберём оптимальное решение.

Наш опыт и результаты

Мы — команда с опытом в интеграции DocuSign API. Выполнили более 30 проектов для компаний из сферы финтеха, логистики и ритейла. Один из клиентов — платформа для аренды коммерческой недвижимости — сократила время подписания договора с 3 дней до 2 часов, а затраты на курьерскую доставку документов упали на 80%. Другой проект — интернет-магазин B2B — увеличил скорость обработки заказов на 60% благодаря автоматическому подписанию счета на оплату. Средняя экономия времени на документообороте составляет 40%, а конверсия закрытия сделок растёт в 3 раза.

Хотите такие же результаты? Получите консультацию — оценим вашу систему и предложим план внедрения.

Сроки

Базовая интеграция (создание конверта + отправка email подписанту + webhook): 2–3 рабочих дня. Embedded signing с полным флоу внутри сайта и автоматическим скачиванием документа: 4–5 рабочих дней. В оценку входит регистрация приложения DocuSign, тестирование в Demo-среде и переключение на Production.

Готовы обсудить ваш проект? Свяжитесь с нами для детального аудита системы документооборота. Подберём оптимальное решение под ваш бюджет и сроки.