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