Інтеграція 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.
Готові обговорити ваш проект? Зв'яжіться з нами для детального аудиту системи документообігу. Підберемо оптимальне рішення під ваш бюджет і терміни.