Интеграция DocuSign с веб-приложением часто сталкивается с ошибками OAuth, неверными anchor-строками или неправильной настройкой webhook. Типичные проблемы — неверно настроенные redirect URI, устаревшие версии SDK и несовпадение тегов в PDF. Всё это приводит к сбоям в рантайме и срыву сделок. Мы специализируемся на таких интеграциях: за время работы реализовали более 30 проектов, где DocuSign используется для подписания договоров, актов и счетов. В среднем наши клиенты сокращают время на обработку документов на 40% и ускоряют закрытие сделок в 3 раза.
Почему стоит выбрать DocuSign?
DocuSign — лидер рынка электронных подписей в США и Европе. Поддерживает юридически обязывающие подписи по стандартам eIDAS (Европа), UETA/ESIGN (США), и ряду национальных стандартов. Для российского рынка важно: DocuSign даёт простую электронную подпись (ПЭП), которая признаётся в суде при наличии соглашения сторон — для большинства коммерческих договоров этого достаточно. Официальная документация DocuSign.
Как устроена интеграция?
Типовой флоу:
- На сайте пользователь заполняет данные → нажимает «Подписать договор»
- Бэкенд создаёт Envelope (конверт) в DocuSign с документом и получателями
- Пользователь перенаправляется на DocuSign для подписания (или получает email)
- После подписания DocuSign уведомляет сайт через webhook
- Бэкенд скачивает подписанный документ и сохраняет
Мы реализуем два сценария: отправка по email или embedded signing — подпись прямо на сайте. Сравнение:
| Критерий | Email-подпись | Embedded signing |
|---|---|---|
| Взаимодействие | Пользователь уходит на DocuSign | Подпись в iframe на вашем сайте |
| Контроль UX | Минимальный | Полный (дизайн, редирект) |
| Процент завершения | ~70% | ~95% (в 3 раза меньше отказов) |
| Скорость внедрения | 2-3 дня | 4-5 дней |
Настройка приложения
В 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.
Готовы обсудить ваш проект? Свяжитесь с нами для детального аудита системы документооборота. Подберём оптимальное решение под ваш бюджет и сроки.