Подписание документов через API Documentolog
Быстрый запуск и юридическая сила
Документ
Формируется
Подписание
Завершен
Об интеграции
Юридически значимое подписание документов в ваш продукт
Кому подходит данное решение:
Банки и финтех-компании: кредитные договоры, соглашения, дополнительные соглашения и т.п.
B2B SaaS системы: договоры, акты и NDA
Маркетплейсы: акты сверок, договоры с продавцами/покупателями,
Другие типы компаний
Возможности API Documentolog:
Создание документов и отправка их на подпись через запрос к API
Использование юридически значимой инфраструктуры Documentolog
Поддержка нескольких способов подписания: ЭЦП, Egov QR, SMS, Adobe Sign
Встраивание процесс подписания через iframe в ваш интерфейс
Получение результата подписания через Webhook
Описание процесса
Отправка и подписание документа
- Инициатор загружает файл договора в систему — поддерживаются форматы PDF, Word, Excel и другие.
- Инициатор указывает получателя — по номеру телефона, ИИН, БИН или email.
- Инициатор выбирает тип отправки: только просмотр или подписание.
- Инициатор нажимает «Отправить» и при необходимости сам подписывает документ — после чего документ уходит получателю.
- Получатель получает ссылку или уведомление и открывает документ на своём устройстве. Если получатель зарегистрирован в Documentolog Business, документ появится у него в системе автоматически.
- Получатель самостоятельно выбирает удобный способ подписи и подписывает документ.
- Инициатор получает уведомление о подписании и готовый файл
Получатель не подписал документ
Получатель открывает документ на своём устройстве:
- Если получатель решает не подписывать — он нажимает «Отклонить». Инициатор сразу получает уведомление и может связаться с получателем для уточнения причин.
- Если получатель закрыл документ, не приняв решения — ссылка остаётся активной 30 дней. Инициатор видит статус «Не подписан» и может отправить повторное напоминание.
Документация для разработчиков
Данная документация описывает процесс получения access token и его использования для встраивания в iframe.
Это необходимо для работы с документами и их подписания через API
Для начала интеграции нужно пройти регистрацию в системе:
На сайте https://documentolog.com/ перейдите по кнопке "Начать бесплатно" и зарегистрируйтесь в системе Documentolog Business.
Для получения доступа к API Documentolog необходимо приобрести тариф Business. Подробнее: https://documentolog.com/tariffs
После оплаты тарифа перейдите в раздел "Интеграции"
Перейдите по вкладке "API Documentolog"
Часть 1: Получение Access Token
1.1 Запрос Access Token
Для получения access token выполните следующий cURL запрос:
36 строк
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
curl --location 'https://apibusiness.documentolog.com/json/external/oauth/token' \
--header 'api-key: {{api-key}}' \
--header 'Content-Type: application/json' \
--data '{
"aAttachments": [
"https://business.documentolog.com/rct/sample.pdf"
],
"sSetWebhookUrl": "https://your-server.com/webhook",
"iSendToRecipient": 1,
"mRecipient": [
"000000000000"
],
"mPhonesForSms": [
{
"enableBMG": false,
"phone": "+X (XXX) XXX-XX-XX",
"fio": "Simple name",
"iin": "",
"type": "sms"
}
],
"iRecipientSignatureRequired": 1,
"mAvailableSignatureMethodsForRecipient": [
"eds",
"egov-qr",
"adobe-sign",
"sms"
],
"mAvailableSignatureMethods": [
"eds",
"egov-qr",
"adobe-sign",
"sms"
],
"sSender": "000000000000"
}'
1.2 Параметры запроса
Параметры тела запроса:
aAttachments — массив ссылок на файлы, которые нужно подписать
sSetWebhookUrl — URL для получения webhook-уведомления после подписания
iSendToRecipient — флаг отправки документа получателю (1 — отправить)
mRecipient — массив ИИН получателей документа
mPhonesForSms — параметры SMS-подписи для получателей
enableBMG — использовать ли BMG-сервис для отправки SMS
phone — номер телефона получателя в формате +X (XXX) XXX-XX-XX
fio — ФИО получателя
iin — ИИН получателя
type — тип отправки (sms)
iRecipientSignatureRequired — требуется ли подпись от получателя (1 — да)
mAvailableSignatureMethodsForRecipient — доступные методы подписания для получателя
mAvailableSignatureMethods — доступные методы подписания для отправителя
sSender — ИИН отправителя документа
1.3 Результат запроса
В случае успешного запроса вы получите JSON-ответ со статусом и данными токена:
8 строк
01
02
03
04
05
06
07
08
{
"status": 1,
"data": {
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"scope": "document-create|document-sign|document-show",
"token_type": "Bearer"
}
}
access_token — JWT-токен для авторизации iframe
scope — разрешённые операции (создание, подписание, просмотр)
token_type — тип токена (Bearer)
Часть 2: Встраивание токена в iframe
После получения access_token, сформируйте URL для iframe и встройте его в свою страницу.
Сформируйте URL, подставив значение access_token из ответа:
1 строка
01
https://apibusiness.documentolog.com/external/sign/embedded?sParams={{data.access_token}}
Пример встраивания iframe в HTML:
1 строка
01
<iframe src="https://apibusiness.documentolog.com/external/sign/embedded?sParams=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." width="400px" height="600px"></iframe>
Внешний вид iframe для подписания документа
Часть 3: Событие postMessage
3.1 Результат подписания
После подписания документа iframe отправляет событие postMessage с результатом. Подпишитесь на событие message для получения данных:
6 строк
01
02
03
04
05
06
{
isDocumentolog: true,
type: 'sign',
success: true | false,
signType: 'eds' | 'egov_gr'
}
isDocumentolog — флаг принадлежности события к Documentolog
type — тип события
success — результат операции (true — успех, false — ошибка)
signType — метод подписания (eds или egov_gr)
3.2 Закрытие iframe пользователем
Если пользователь закрыл форму подписания без подписи, отправляется отдельное сообщение:
5 строк
01
02
03
04
05
{
isDocumentolog: true,
type: 'user-close',
success: false,
}
isDocumentolog — флаг принадлежности события к Documentolog
type — тип события
success — результат операции (true — успех, false — ошибка)
3.3 Документ уже подписан
Если открываемый в iframe документ уже был подписан, отправляется следующее сообщение:
5 строк
01
02
03
04
05
{
isDocumentolog: true,
type: 'already-signed',
success: true,
}
type — тип события
success — результат операции (true — успех, false — ошибка)
Часть 4: Webhook
4.1 События webhook
В процессе работы с документом на URL, указанный в параметре sSetWebhookUrl, отправляются POST-запросы с информацией о ключевых событиях:
4 строк
01
02
03
04
{
"event": "document_sent",
"doc_id": "KZ000000000000000001234567"
}
8 строк
01
02
03
04
05
06
07
08
{
"event": "signer_signed"|"signer_declined",
"doc_id": "KZ000000000000000001234567",
"signer": {
"name": "Сейтқали Нұрлан",
"recipient": "000000000000"
}
}
event — тип события (document_sent, signer_signed, signer_declined)
doc_id — идентификатор документа
signer — данные подписанта
name — ФИО подписанта
recipient — ИИН подписанта
4.2 Завершение подписания
После завершения подписания документа всеми сторонами на webhook URL отправляется итоговое событие со ссылками на просмотр и скачивание файлов:
24 строк
01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
"event": "document_completed",
"doc_id": "KZ000000000000000001234567",
"document": "https://apibusiness.documentolog.com/external/document/view-document/dcs_universal_type/1234",
"download_all_files": "https://apibusiness.documentolog.com/external/media/download-many?files=4444",
"download_files": [
{
"name": "sample.pdf",
"link": "https://apibusiness.documentolog.com/external/media/download/4444"
}
],
"download_files_with_eds": [
{
"name": "sample.pdf",
"link": "https://apibusiness.documentolog.com/external/media/download-eds/dcs_universal_type/1234/4444"
}
],
"download_files_with_eds_ez": [
{
"name": "sample.pdf",
"link": "https://apibusiness.documentolog.com/external/media/download-eds-ez/dcs_universal_type/1234/4444"
}
]
}
event — тип события (document_completed)
doc_id — идентификатор документа
document — ссылка на просмотр документа
download_all_files — ссылка на скачивание всех файлов одним архивом
download_files — список файлов для скачивания
download_files_with_eds — список файлов с прикреплёнными ЭЦП-подписями
download_files_with_eds_ez — список файлов с ЭЦП-подписями в формате Ez