API интеграция Documentolog — электронный документооборот в ваших инструментах

Инструкция по использованию открытого API Documentolog

Documentolog предоставляет открытое API для интеграции с различными системами, что позволяет автоматизировать процессы, такие как подписание и отправка документов.

Для использования API, необходимо зарегистрироваться в системе Documentolog и получить API-ключ

Шаг 1: Регистрация в системе

На сайте https://documentolog.com/ перейдите по кнопке “Начать бесплатно” и зарегистрируйтесь в системе Documentolog.
Для получения доступа к API Documentolog необходимо приобрести тариф Start+ или Business. Подробнее: https://documentolog.com/tariffs
После оплаты тарифа перейдите в раздел «Моя организация»
Перейдите по вкладке «Настройки»
Откройте раздел «Интеграции»

Шаг 2: Получение API-ключа

Скопируйте ваш API-ключ либо создайте новый

Сохраните ключ в безопасном месте, так как он будет использоваться для аутентификации ваших запросов.

Шаг 3: Получение Access Token для встраивания в iframe

Access Token необходим для работы с документами и их подписания через API

Часть 1: Получение Access Token

1.1 Запрос Access Token:

Для получения Access Token выполните следующий c URL запрос:

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/icons/android-icon-192x192.png"
    ],
    "sSetWebhookUrl": "https://apibusiness.documentolog.com/external/test/webhook",
    "iSendToRecipient": 1,
    "mRecipient": [
        "000000000000"
    ],
    "iRecipientSignatureRequired": 1,
    "mAvailableSignatureMethodsForRecipient": [
        "eds",
        "egov-qr"
    ],
    "mAvailableSignatureMethods": [
        "eds",
        "egov-qr"
    ],
    "sSender": "000000000000"
}'

1.2 Параметры запроса:

aAttachments: Массив ссылок на файлы (поддерживаемые форматы: docx, doc, xlsx, xls, pptx, ppt, pdf, rar, zip, rtf, tiff, jpeg, jpg, png, gdoc).
sSetWebhookUrl: URL для получения результатов после подписания.
iSendToRecipient: Отправить ли документ получателю (1 = да, 0 = нет).
mRecipient: Список получателей (можно использовать ИИН, БИН или эл. почту).
iRecipientSignatureRequired: Требуется ли подпись получателя (1 = да, 0 = нет).
mAvailableSignatureMethodsForRecipient: Методы подписи для получателя (например, eds, egov-qr).
mAvailableSignatureMethods: Методы подписи для отправителя (например, eds, egov-qr).
sSender: Идентификационный номер отправителя.

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

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

{
    "status": 1,
    "data": {
        "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "scope": "document-create|document-sign|document-show",
        "token_type": "Bearer"
    }
}

Access_token: Токен, который необходимо использовать для доступа к ресурсам.
scope: Доступные действия с документами.
token_type: Тип токена, обычно "Bearer".

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

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

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

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

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

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

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

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

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

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

{
	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. Вот пример сообщения:

{
	isDocumentolog: true,
	type: 'user-close',
	success: false,
}

isDocumentolog: Флаг, указывающий на использование системы Documentolog (всегда true).
type: Тип события.
success: Результат подписи.

Часть 4: Webhook

На указанный в поле sWebhook будет отправлено сообщение после подписание документа:

{
    "content": {
        "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": "android-icon-192x192.png",
                "link": "https://apibusiness.documentolog.com/external/media/download/4444"
            }
        ],
        "download_files_with_eds": [
            {
                "name": "android-icon-192x192.png",
                "link": "https://apibusiness.documentolog.com/external/media/download-eds/dcs_universal_type/1234/4444"
            }
        ],
        "download_files_with_eds_ez": [
            {
                "name": "android-icon-192x192.png",
                "link": "https://apibusiness.documentolog.com/external/media/download-eds-ez/dcs_universal_type/1234/4444"
            }
        ]
    }
}

Инструкция по использованию открытого API Documentolog

Any questions left?