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

Быстрый запуск и юридическая сила

Документ

Формируется

Подписание

Завершен

Об интеграцииЮридически значимое подписание документов в ваш продукт
Кому подходит данное решение:
  • Банки и финтех-компании: кредитные договоры, соглашения, дополнительные соглашения и т.п.
  • B2B SaaS системы: договоры, акты и NDA
  • Маркетплейсы: акты сверок, договоры с продавцами/покупателями
  • Другие типы компаний
Возможности API Documentolog:
  • Создание документов и отправка их на подпись через запрос к API
  • Использование юридически значимой инфраструктуры Documentolog
  • Поддержка нескольких способов подписания: ЭЦП, Egov QR, SMS, Adobe Sign
  • Встраивание процесса подписания через iframe в ваш интерфейс
  • Получение результата подписания через Webhook
Описание процесса
Отправка и подписание документа
  1. Инициатор загружает файл договора в систему — поддерживаются форматы PDF, Word, Excel и другие.
  2. Инициатор указывает получателя — по номеру телефона, ИИН, БИН или email.
  3. Инициатор выбирает тип отправки: только просмотр или подписание.
  4. Инициатор нажимает «Отправить» и при необходимости сам подписывает документ — после чего документ уходит получателю.
  5. Получатель получает ссылку или уведомление и открывает документ на своём устройстве. Если получатель зарегистрирован в Documentolog Business, документ появится у него в системе автоматически.
  6. Получатель самостоятельно выбирает удобный способ подписи и подписывает документ.
  7. Инициатор получает уведомление о подписании и готовый файл
Получатель не подписал документ

Получатель открывает документ на своём устройстве:

  1. Если получатель решает не подписывать — он нажимает «Отклонить». Инициатор сразу получает уведомление и может связаться с получателем для уточнения причин.
  2. Если получатель закрыл документ, не приняв решения — ссылка остаётся активной 30 дней. Инициатор видит статус «Не подписан» и может отправить повторное напоминание.
Документация для разработчиковДанная документация описывает процесс получения access token и его использования для встраивания в iframe.
Это необходимо для работы с документами и их подписания через API
Для начала интеграции нужно пройти регистрацию в системе:
  1. На сайте https://documentolog.com/ перейдите по кнопке "Начать бесплатно" и зарегистрируйтесь в системе Documentolog Business.
  2. Для получения доступа к API Documentolog необходимо приобрести тариф Business. Подробнее: https://documentolog.com/tariffs
  3. После оплаты тарифа перейдите в раздел "Интеграции"
  4. Перейдите по вкладке "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 — массив ссылок на файлы (поддерживаемые форматы: 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 строк

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 — токен, который необходимо использовать для доступа к ресурсам. Срок действия — 30 дней
  • scope — доступные действия с документами
  • token_type — тип токена, обычно "Bearer"

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

При проблемах с авторизацией API возвращает следующие коды ошибок:
Код ошибкиHTTP-статусОписание и решение
invalid_client401 UnauthorizedНеверный api-key. Проверьте значение заголовка api-key в личном кабинете.
unauthorized401 Unauthorizedaccess_token истёк (срок действия 30 дней) или не передан. Необходимо получить новый токен повторным запросом к oauth/token.
status: 0200Логическая ошибка запроса. Подробности в поле 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 строка

01

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

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

1 строка

01

<iframe src="https://apibusiness.documentolog.com/external/sign/embedded?sParams=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." width="400px" height="600px"></iframe>

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

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

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

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

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

6 строк

01

02

03

04

05

06

{

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 строк

01

02

03

04

05

{

isDocumentolog: true,

type: 'user-close',

success: false,

}

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

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

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

5 строк

01

02

03

04

05

{

isDocumentolog: true,

type: 'already-signed',

success: true,

}

  • type — тип события
  • success — результат подписи
Часть 4: Webhook

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

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

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

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

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

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 — уникальный идентификатор документа. Совпадает с 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 строк

01

02

03

04

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 для перехвата событий без реального сервера.