Как настроить уведомления из систем документооборота (СЭД) с помощью API

Системы электронного документооборота (СЭД) отлично справляются со своей задачей, избавляя вас от расходов на бумагу, упрощая управление документами и сокращая время на согласования. Минус у них один, но серьезный: их эффективность полностью зависит от того, как быстро пользователь узнает о любых изменениях. Пропущенное уведомление о новых документах, согласованиях или дедлайнах способно дезорганизовать любой бизнес-процесс.

Эту задачу можно решить. API-интеграция с использованием Exolve API, автоматизирует отправку уведомлений через SMS. Это исключает задержки, снижает риски ошибок и повышает надежность системы. Осталось понять, как это можно сделать, чем мы и займемся в нашей статье.

Архитектура интеграции Exolve API с СЭД

Интеграция Exolve API с системами электронного документооборота (СЭД) требует четкого понимания технических аспектов. Схематично это выглядит так:

Рассмотрим все поближе, включая варианты кода, инструменты и рекомендации по настройке.

Общая схема взаимодействия СЭД и Exolve API

Коммуникация строится на основе RESTful API. СЭД отсылает HTTP-запросы к Exolve API при наступлении событий (например, создание документа или изменение статуса). Exolve API обрабатывает запросы и отправляет уведомления через SMS, email или мессенджеры.

Варианты интеграции

Всегда есть несколько способов получения результата. Остановимся на тех, что чаще всего используются.

1. Вызов API напрямую из системы документооборота.

Если СЭД поддерживает HTTP-запросы, можно настроить прямой вызов Exolve API. На Python это будет выглядеть так:

import requests url = "https://api.exolve.ru/v1/send" api_key = "ваш_api_ключ" payload = {     "phone": "+79123456789",  # Номер телефона получателя     "text": "Новый документ требует вашего внимания.",  # Текст уведомления     "channel": "sms"  # Канал отправки (sms, email, telegram) } headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) if response.status_code == 200: print("Уведомление отправлено!") else: print("Ошибка:", response.json())

Рекомендации:

• Используйте библиотеку requests для работы с HTTP-запросами.

• Храните API-ключи в переменных окружения или секретных хранилищах (например, AWS Secrets Manager).

• Логируйте ответы API для отслеживания ошибок.

2. Использование промежуточного сервера для маршрутизации уведомлений.

Если СЭД не поддерживает прямую интеграцию, настройте промежуточный сервер. Например, на базе Node.js:

const express = require('express'); const axios = require('axios'); const app = express(); app.use(express.json()); const EXOLVE_API_URL = "https://api.exolve.ru/v1/send"; const API_KEY = "ваш_api_ключ"; app.post('/notify', async (req, res) => { const { phone, text, channel } = req.body; try {     const response = await axios.post(EXOLVE_API_URL, {         phone,         text,         channel     }, {         headers: {             'Authorization': `Bearer ${API_KEY}`,             'Content-Type': 'application/json'         }     });     res.status(200).json({ success: true, data: response.data }); } catch (error) {     res.status(500).json({ success: false, error: error.message }); } }); app.listen(3000, () => { console.log('Сервер запущен на порту 3000'); });

Рекомендации:

• Используйте Express.js для создания легковесного сервера.

• Добавьте middleware для валидации входящих данных (например, express-validator).

• Настройте мониторинг сервера с помощью инструментов вроде Prometheus или Grafana.

Поток данных: от события в СЭД до доставки уведомления пользователю

В итоге, движение информации будет выглядеть таким образом:

1.   Событие в СЭД: например, создание нового документа. СЭД генерирует событие и передает данные (ID документа, тип события, получателя) в API или промежуточный сервер.

2.   Передача данных в Exolve API: данные передаются в формате JSON. Пример запроса:

{ "phone": "+79123456789", "text": "Документ №123 требует вашего согласования.", "channel": "sms" }

3.   Exolve API обрабатывает запрос и отправляет уведомление через выбранный канал. Exolve API возвращает статус доставки. Пример ответа:

{ "status": "success", "message_id": "12345" }

Рекомендации:

• Настройте обработку ошибок (например, повторную отправку при сбое).

• Используйте очереди (RabbitMQ, Kafka) для асинхронной обработки запросов.

• Логируйте все этапы для упрощения отладки.

Настройка и работа с Exolve API

Для успешной интеграции Exolve API с СЭД важно правильно настроить доступ, изучить формат запросов и научиться обрабатывать ответы. Рассмотрим ключевые аспекты работы с API.

Получаем API-ключи и настраиваем доступ

1. Зарегистрируйтесь в МТС Exolve и после подтверждения учетной записи получите доступ к личному кабинету.

2. В личном кабинете найдите раздел «API-ключи» и сформируйте собственный ключ, он будет выглядеть примерно так: sk_1234567890abcdef.

3. Убедитесь, что ваш сервер или приложение имеют доступ к API Exolve. Для этого: разрешите IP-адреса вашего сервера в личном кабинете Exolve и используйте HTTPS для всех запросов к API.

Формат запросов

Способов, которыми система извещает пользователей о случившихся изменениях, не так много: SMS, звонок с голосовым сообщением на заданный номер телефона или ответ на запрос самого пользователя. Разберемся, как это сделать.

1. Как отправлять SMS-уведомления о новых документах.

Пример запроса на отправку SMS:

import requests url = "https://api.exolve.ru/v1/send" api_key = "ваш_api_ключ" payload = {     "phone": "+79123456789",  # Номер получателя     "text": "Новый документ №123 требует вашего внимания.",  # Текст SMS     "channel": "sms"  # Канал отправки } headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) if response.status_code == 200: print("SMS отправлено!") else: print("Ошибка:", response.json())

Рекомендации:

• Убедитесь, что текст SMS не превышает лимит символов (как правило, это 160 для латиницы, 70 для кириллицы).

• Для часто отправляемых сообщений пользуйтесь шаблонами.

2. Голосовые звонки с важными сообщениями.

Пример запроса на отправку голосового сообщения:

payload = {     "phone": "+79123456789",     "text": "Внимание! Документ №123 требует срочного согласования.", "channel": "voice"  # Канал отправки } response = requests.post(url, json=payload, headers=headers) if response.status_code == 200:     print("Голосовое сообщение отправлено!") else: print("Ошибка:", response.json())

Рекомендации:

• Используйте короткие и четкие тексты для голосовых сообщений.

• Проверьте качество синтеза речи в тестовом режиме.

3. Проверка статуса доставки.

Пример запроса для проверки статуса:

message_id = "12345"  # ID сообщения, полученное при отправке status_url = f"https://api.exolve.ru/v1/status/{message_id}" response = requests.get(status_url, headers=headers) if response.status_code == 200: status_data = response.json() print("Статус доставки:", status_data["status"]) else: print("Ошибка:", response.json())

Рекомендации:

• Регулярно проверяйте статус важных уведомлений.

• Настройте уведомления о неудачных попытках доставки.

Разбор ответов API и обработка ошибок

МТС Exolve – надежная платформа, но от ошибок никто не застрахован, так что лучше заранее подготовиться к такой ситуации.

Пример успешного ответа:

{     "status": "success",     "message_id": "12345" }

Пример ошибки:

{ "status": "error", "code": 400, "message": "Неверный формат номера телефона." }

Обработка ошибок:

Пример кода для обработки ошибок:

if response.status_code == 200: print("Успешно:", response.json()) elif response.status_code == 400: print("Ошибка запроса:", response.json()["message"]) elif response.status_code == 401: print("Ошибка авторизации: проверьте API-ключ.") else: print("Неизвестная ошибка:", response.status_code)

Рекомендации:

• Логируйте все ошибки для последующего анализа.

• Используйте библиотеки для автоматического повторения запросов при временных сбоях (например, retrying в Python).

• Настройте мониторинг ошибок с помощью инструментов вроде Sentry или ELK Stack.

Интеграция с различными СЭД

Один из китов, на которых строится успешная интеграция Exolve API с системами электронного документооборота (СЭД) – способ вызова API. Он зависит от того, что может и умеет конкретная СЭД. Рассмотрим поближе основные подходы, включая встроенные механизмы, использование скриптов и интеграцию через сторонние сервисы.

Способы вызова API в популярных СЭД

Есть три надежных, проверенных практикой способа коммуникации API и СЭД: через механизмы самой СЭД, через скрипты и через сторонний сервер.

Через встроенные механизмы (например, веб-хуки, REST-запросы)

Многие современные СЭД поддерживают встроенные механизмы для интеграции с внешними API, такие как веб-хуки или REST-запросы.

Пример настройки веб-хука в СЭД:

1. В настройках СЭД найдите раздел «Интеграции» или «Веб-хуки».

2. Укажите URL-адрес Exolve API (https://api.exolve.ru/v1/send) и метод POST.

3. Настройте триггеры (например, «Создание документа» или «Изменение статуса»).

4. Передавайте данные в формате JSON. Пример тела запроса:

{     "phone": "+79123456789",     "text": "Документ №123 требует вашего внимания.",     "channel": "sms" }

Рекомендации:

• Убедитесь, что СЭД поддерживает HTTPS для безопасной передачи данных.

• Настройте логирование всех исходящих запросов для отладки.

Использование скриптов (Python, JavaScript, PowerShell) для отправки уведомлений

Если СЭД не поддерживает встроенные механизмы интеграции, можно использовать скрипты для отправки уведомлений. Здесь самые распространенные варианты.

Пример на Python:

import requests def send_notification(phone, text): url = "https://api.exolve.ru/v1/send" api_key = "ваш_api_ключ" payload = {     "phone": phone,     "text": text,     "channel": "sms"     } headers = {     "Authorization": f"Bearer {api_key}",     "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) return response.json() # Пример вызова функции send_notification("+79123456789", "Новый документ №456 требует согласования.")

Пример на JavaScript (Node.js):

const axios = require('axios'); async function sendNotification(phone, text) { const url = "https://api.exolve.ru/v1/send"; const apiKey = "ваш_api_ключ"; const payload = {     phone,     text,     channel: "sms" }; const headers = {     "Authorization": `Bearer ${apiKey}`,     "Content-Type": "application/json" }; try {     const response = await axios.post(url, payload, { headers });     console.log("Уведомление отправлено:", response.data);     } catch (error) {     console.error("Ошибка:", error.response.data); } } // Пример вызова функции sendNotification("+79123456789", "Документ №789 требует вашего внимания.");

Пример на PowerShell:

$url = "https://api.exolve.ru/v1/send" $apiKey = "ваш_api_ключ" $headers = @{ "Authorization" = "Bearer $apiKey" "Content-Type" = "application/json" } $body = @{ "phone" = "+79123456789" "text" = "Документ №101 требует согласования." "channel" = "sms" } | ConvertTo-Json $response = Invoke-RestMethod -Uri $url -Method Post -Headers $headers -Body $body Write-Output $response

Рекомендации:

• Используйте скрипты для автоматизации рутинных задач.

• Храните API-ключи в защищенных хранилищах (например, AWS Secrets Manager или HashiCorp Vault).

Интеграция через сторонний сервер или микросервис

Если СЭД не поддерживает прямую интеграцию или требуется дополнительная обработка данных, можно использовать промежуточный сервер или микросервис.

Пример архитектуры:

1. СЭД отправляет данные о событиях на промежуточный сервер (например, через веб-хук или файловый обмен).

2. Промежуточный сервер обрабатывает данные (фильтрует, форматирует) и передает их в Exolve API.

3. Exolve API отправляет уведомления пользователям.

Пример настройки микросервиса на Node.js:

const express = require('express'); const axios = require('axios'); const app = express(); app.use(express.json()); const EXOLVE_API_URL = "https://api.exolve.ru/v1/send"; const API_KEY = "ваш_api_ключ"; app.post('/notify', async (req, res) => { const { phone, text, channel } = req.body; try {     const response = await axios.post(EXOLVE_API_URL, {         phone,         text,         channel     }, {         headers: {             'Authorization': `Bearer ${API_KEY}`,             'Content-Type': 'application/json'         }         });     res.status(200).json({ success: true, data: response.data }); } catch (error) {     res.status(500).json({ success: false, error: error.message }); } }); app.listen(3000, () => { console.log('Сервер запущен на порту 3000'); });

Рекомендации:

• Используйте Docker для контейнеризации микросервиса.

• Настройте балансировку нагрузки и мониторинг (например, с помощью Kubernetes и Prometheus).

Практический пример

Приведем пример пошаговой настройки уведомлений через Exolve API. Сценарий: при поступлении документа на согласование в СЭД, система отправляет SMS-уведомление ответственному лицу.

Конфигурация СЭД для отслеживания событий

Шаги:

1. В СЭД найдите событие, связанное с поступлением документа на согласование. Например, это может быть изменение статуса документа на «Требует согласования».

2. В настройках СЭД создайте триггер, который срабатывает при изменении статуса документа. Укажите, что триггер должен отправлять HTTP-запрос на внешний URL (например, на ваш промежуточный сервер или напрямую в Exolve API).

3. Настройте передачу данных в формате JSON. Пример данных:

{ "document_id": "12345", "document_name": "Договор поставки", "recipient_phone": "+79123456789", "status": "Требует согласования" }

Написание кода для вызова Exolve API

Пример кода на Python:

import requests import logging # Настройка логирования logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s') def send_notification(phone, text): url = "https://api.exolve.ru/v1/send" api_key = "ваш_api_ключ" payload = {     "phone": phone,     "text": text,     "channel": "sms"     } headers = {     "Authorization": f"Bearer {api_key}",     "Content-Type": "application/json" } try:     response = requests.post(url, json=payload, headers=headers)         response.raise_for_status()  # Проверка на ошибки HTTP     logging.info(f"Уведомление отправлено: {response.json()}") except requests.exceptions.RequestException as e:     logging.error(f"Ошибка при отправке уведомления: {e}") # Пример обработки события из СЭД def handle_document_event(event_data): document_id = event_data["document_id"] document_name = event_data["document_name"] recipient_phone = event_data["recipient_phone"] status = event_data["status"] # Формирование текста уведомления text = f"Документ '{document_name}' (ID: {document_id}) требует вашего согласования. Статус: {status}."   # Отправка уведомления send_notification(recipient_phone, text) # Пример данных события event_data = { "document_id": "12345", "document_name": "Договор поставки", "recipient_phone": "+79123456789", "status": "Требует согласования" } # Обработка события handle_document_event(event_data)

Обратите внимание на несколько моментов:

• send_notification: Функция для отправки SMS через Exolve API.

• handle_document_event: Функция для обработки события из СЭД и формирования текста уведомления.

• Логирование используется для отслеживания успешных отправок и ошибок.

Логирование и отладка работы

Настройка логирования:

1. Добавьте в код настройку для записи логов в файл:

logging.basicConfig( level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s', filename='exolve_integration.log' )

2. Пример логов

Успешная отправка:

2023-10-15 12:34:56 - INFO - Уведомление отправлено: {'status': 'success', 'message_id': '12345'}

Ошибка:

2023-10-15 12:35:10 - ERROR - Ошибка при отправке уведомления: 400 Client Error: Bad Request for url: https://api.exolve.ru/v1/send

Отладка:

1. Используйте инструменты вроде Postman или cURL для тестирования запросов к Exolve API. Пример cURL:

curl -X POST https://api.exolve.ru/v1/send \ -H "Authorization: Bearer ваш_api_ключ" \ -H "Content-Type: application/json" \ -d '{     "phone": "+79123456789",     "text": "Тестовое уведомление",     "channel": "sms" }'

2. Настройте уведомления об ошибках (например, через Sentry или Telegram-бота) и регулярно проверяйте логи для выявления проблем.

Использование Exolve API для автоматизации уведомлений в СЭД заметно облегчает рутину в работе с документами. Пользователи быстрее получают информацию, риск упустить что-то важное становится несущественным. В статье мы подробно рассказали, что и как можно сделать. Обратите внимание на рекомендации – мы поскользнулись на многих таких «подводных камушках» и все зафиксировали, чтобы вам было проще повторить этот путь.

При желании в будущем можно шире использовать те возможности, что дает интеграция: добавить отчеты по доставке уведомлений для анализа эффективности; повысить надежность, реализовав мультимодальные уведомления (SMS, email, голосовые сообщения), или даже интегрировать чат-боты (Telegram, WhatsApp) для двустороннего взаимодействия с пользователями.