Интеграция с Documentolog Business

Подписание документов через 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 строк

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 — массив ссылок на файлы (поддерживаемые форматы: docx, doc, xlsx, xls, pptx, ppt, pdf, rar, zip, rtf, tiff, jpeg, jpg, png, gdoc). Длина имени файла без расширения не должна превышать 32 символа
sSetWebhookUrl — URL для получения webhook-уведомлений о статусе документа (отправка, подпись, завершение)
iSendToRecipient — отправить ли документ получателю (1 = да, 0 = нет)
mRecipient — список получателей (можно использовать ИИН, БИН, номер телефона или эл. почту)
mPhonesForSms — массив объектов для отправки SMS-подписей
- enableBMG — использовать ли BMG-сервис для отправки SMS
- phone — номер телефона получателя в формате +X (XXX) XXX-XX-XX
- fio — ФИО получателя
- iin — ИИН получателя
- type — тип отправки (sms)
iRecipientSignatureRequired — требуется ли подпись получателя (1 = да, 0 = нет)
mAvailableSignatureMethodsForRecipient — методы подписи, доступные получателям при открытии документа (eds, egov-qr, adobe-sign, sms)
mAvailableSignatureMethods — методы подписи, доступные отправителю в iframe
sSender — идентификационный номер отправителя (ИИН или БИН)

1.3 Результат запроса

Успешный ответ на запрос будет иметь следующий формат:

8 строк

{

"status": 1,

"data": {

"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",

"scope": "document-create|document-sign|document-show",

"token_type": "Bearer"

}

access_token — токен, который необходимо использовать для доступа к ресурсам. Срок действия — 30 дней
scope — доступные действия с документами
token_type — тип токена, обычно "Bearer"

1.4 Коды ошибок авторизации

При проблемах с авторизацией API возвращает следующие коды ошибок:

Код ошибки	HTTP-статус	Описание и решение
invalid_client	401 Unauthorized	Неверный api-key. Проверьте значение заголовка api-key в личном кабинете.
unauthorized	401 Unauthorized	access_token истёк (срок действия 30 дней) или не передан. Необходимо получить новый токен повторным запросом к oauth/token.
status: 0	200	Логическая ошибка запроса. Подробности в поле message ответа.

1.5 Передача токена в запросах

После получения access_token передавайте его в заголовке Authorization:

1 строка

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

Важно: access_token передаётся только в заголовке Authorization: Bearer. Параметр sParams используется исключительно для встраивания iframe и не является заменой заголовка авторизации.

Часть 2: Встраивание токена в iframe

После получения access token его можно встроить в iframe для дальнейшего использования. Один токен привязан к одному документу.

2.1 URL для встраивания

Используйте следующий URL, подставив полученный access token:

1 строка

https://apibusiness.documentolog.com/external/sign/embedded?sParams={{data.access_token}}

Пример встраивания:

1 строка

Внешний вид iframe для подписания документа

Часть 3: Событие postMessage

3.1 Результат подписи

Когда процесс подписания завершается, iframe отправляет сообщение родительскому окну с помощью функции window.parent.postMessage. Пример сообщения:

6 строк

{

isDocumentolog: true,

type: 'sign',

success: true | false,

signType: 'eds' | 'egov_gr'

}

isDocumentolog — флаг, указывающий на использование системы Documentolog (всегда true)
type — тип события
success — результат подписи
signType — тип подписи, используемый при подписании (например, 'eds')

3.2 Закрытие iframe

При попытке закрытия iframe пользователем, iframe отправляет сообщение родительскому окну с помощью функции window.parent.postMessage. Пример сообщения:

5 строк

{

isDocumentolog: true,

type: 'user-close',

success: false,

}

isDocumentolog — флаг, указывающий на использование системы Documentolog (всегда true)
type — тип события
success — результат подписи

3.3 Документ уже подписан

Если документ для данного токена уже был подписан, iframe немедленно завершает работу и отправляет событие родительскому окну:

5 строк

{

isDocumentolog: true,

type: 'already-signed',

success: true,

}

type — тип события
success — результат подписи

Часть 4: Webhook

4.1 Промежуточные события

В процессе жизненного цикла документа на webhook-адрес приходят промежуточные события.

4 строк

{

"event": "document_sent",

"doc_id": "KZ000000000000000001234567"

}

8 строк

{

"event": "signer_signed"|"signer_declined",

"doc_id": "KZ000000000000000001234567",

"signer": {

"name": "Сейтқали Нұрлан",

"recipient": "000000000000"

}

event — тип события: document_sent — документ отправлен получателям, signer_signed — подписан, signer_declined — отклонён, document_completed — все стороны подписали
doc_id — уникальный идентификатор документа. Совпадает с DOC ID в разделе «Документы». Одинаков во всех событиях одного документа
signer — данные подписанта (присутствует в событиях signer_signed и signer_declined)
- name — ФИО подписанта
- recipient — ИИН, БИН, телефон или эл. почта подписанта

4.2 Завершение документа

Финальное уведомление отправляется на sSetWebhookUrl, когда все участвующие стороны подписали документ:

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 — уникальный идентификатор документа. Совпадает с DOC ID в разделе «Документы». Одинаков во всех событиях одного документа
document — ссылка на документ
download_all_files — ссылка для скачивания всех файлов
download_files — список ссылок для скачивания файлов
download_files_with_eds — список ссылок для скачивания файлов с ЭЦП
download_files_with_eds_ez — список ссылок для скачивания файлов для ezSigner

4.3 Политика доставки (retry)

Система будет переотправлять webhook event с периодичностью: 5, 15, 30, 60, 120, 240, 480, 960, 1440 минут. После последней попытки система пометит event как failed и перестанет переотправлять.

4.4 Время жизни ссылок на файлы

Ссылки из полей download_files, download_files_with_eds и download_files_with_eds_ez, которые приходят в событии document_completed:

Поле	Время жизни ссылки
download_files	Ссылка постоянная, действует пока документ существует в системе.
download_files_with_eds	Ссылка постоянная, действует пока документ существует в системе.
download_all_files	Ссылка постоянная, действует пока документ существует в системе.

Важно: ссылки не открываются в браузере напрямую. При переходе по ссылке браузер запросит логин и пароль — это штатное поведение при отсутствии заголовка авторизации. Для скачивания передавайте тот же access_token, которым создавался документ:

4 строк

curl --location \

'{{ссылка из webhook}}' \

--header 'Authorization: Bearer {{access_token}}' \

--output document.pdf

Через Postman: вкладка Authorization → Bearer Token → вставить токен → Send.

Часть 5: Ограничения и допущения API

Следующие сценарии не поддерживаются через API. Попытка их реализации приведёт к ошибке или неожиданному поведению.

Ограничение	Пояснение
Нельзя создать документ как черновик	Документ немедленно отправляется получателю при вызове create-document. Отложенная отправка через API не предусмотрена.
Отправитель (sSender) обязан быть подписантом	Нельзя отправить документ без подписи со стороны отправителя. Отключить подписание отправителя через API невозможно.
Нельзя настроить очерёдность подписания	API не поддерживает задание порядка, в котором стороны должны подписывать документ. Все участники получают доступ одновременно.
Нельзя отключить подписание со стороны отправителя	Поле mAvailableSignatureMethods всегда применяется к отправителю. Параметра для исключения отправителя из цепочки подписания нет.

Часть 6: Тестовая среда

Публичная тестовая среда отсутствует. Тестирование выполняется в боевой среде с использованием реальных данных.

Рекомендации по тестированию

Используйте тестовые ИИН/БИН из выданных вам учётных записей.
В качестве aAttachments указывайте ссылку на небольшой тестовый PDF файл.
Для sSetWebhookUrl используйте инструменты типа webhook.site для перехвата событий без реального сервера.

Интеграция с Documentolog Business

Подписание документов через API Documentolog

Хотите подключиться к Documentolog?