Інтеграція системи електронного документообігу в мобільний додаток
Узгодити контракт через мобільний додаток, підписати акт прийому робіт на планшеті прямо на об'єкті, відправити первинні документи в бухгалтерію без паперу. Інтеграція ЕДО в мобільний продукт — це не просто API-запити: електронний підпис, криптографія, юридична значимість документів та специфіка російського нормативного поля.
Екосистема ЕДО в Росії
Основні оператори, з якими доводиться інтегруватися:
| Оператор | API | Акредитація ФНС | Особливості |
|---|---|---|---|
| Діадок (Контур) | REST API | Так | Найпоширеніший, добра документація |
| СФЕРА Кур'єр (СКБ Контур) | REST API | Так | Акцент на логістичні документи |
| 1С-ЕДО | Немає публічного API | Так | Тільки через шлюз 1С |
| Tinkoff ЕДО | REST API | Так | Більш новий, документація розвивається |
| ЕДО Лайт (Тензор, СБІС) | REST API | Так | Інтеграція з екосистемою СБІС |
Для нових проектів частіше вибирають Діадок — найповніший API, велика клієнтська база, добра документація на developer.diadoc.ru.
Електронний підпис: ключовий момент
Юридично значимий ЕДО вимагає кваліфікованого електронного підпису (КЕП) або некваліфікованого (НЕП) залежно від типу документа. Це ключова відмінність від "натиснути кнопку Підписати" в інтерфейсі.
На мобільному пристрої підписання реалізується кількома способами:
1. Хмарний підпис (рекомендується для мобільних). КЕП зберігається в захищеному сховищі оператора ЕДО або центру сертифікації. Додаток запитує підписання через API — користувач підтверджує операцію через SMS-код або push-уведомлення. Закритий ключ ніколи не покидає хмару. Діадок надає хмарний підпис через Контур.Крипто.
Це правильний шлях для мобільних додатків. Зберігання закритого ключа КЕП на мобільному пристрої — юридично ризиковано та технічно складно.
2. Робота через токен/смарт-карту. Підключення USB-токена (Рутокен, eToken) через Lightning/USB-C адаптер — екзотика для мобільних, але буває в промислових сценаріях. Вимагає спеціальних SDK від виробника токена та підтримки MFi.
3. Проста електронна підпис (ПЕП). Для внутрішнього ЕДО (узгодження всередині компанії, яке не вимагає КЕП) — можна обійтися ПЕП, це по суті авторизоване дію користувача в системі, яка логується. Юридична сила нижча, але для внутрішнього обігу достатньо.
Інтеграція з Діадок API
Авторизація — OAuth 2.0 з client credentials або через Контур.ID. Для мобільного додатка використовуємо Authorization Code Flow:
GET https://auth.kontur.ru/api/authorization/v5.7/oauth/login
?client_id={client_id}
&response_type=code
&redirect_uri=myapp://auth/callback
&scope=diadoc
Після отримання code обмінюємо на access_token. Токен живе обмежене час — реалізуємо автоматичне оновлення через refresh_token.
Отримання списку документів:
GET https://diadoc-api.kontur.ru/V3/GetDocuments
?boxId={boxId}&filterCategory=Any.Incoming
Authorization: DiadocAuth ddauth_api_client_id={client_id},ddauth_token={token}
Відповідь — XML або JSON залежно від заголовка Accept. Для мобільного переважніше JSON.
Робота з документами на пристрої
Перегляд PDF. Діадок повертає документи у форматі PDF або TIFF (для формалізованих — XML). На iOS рендеримо PDF через PDFKit (вбудований з iOS 11), TIFF через UIImage. На Android — PdfRenderer або бібліотека AndroidPdfViewer. Для XML формалізованих документів (УПД, рахунок-фактура) потрібен рендеринг через XSLT-шаблон — Діадок надає форми друку через API.
Підписання. При хмарній підписі: POST /V3/PostSignatures з DocumentId та підтвердженням користувача. API повертає статус підписання асинхронно — потрібен polling або вебхук.
Створення вихідного документа. Для неформалізованих: користувач прикріпляє PDF/DOCX з файлової системи (UIDocumentPickerViewController / ACTION_OPEN_DOCUMENT), робимо POST /V3/PostMessagePatch з base64-encoded вмістом файлу та метаданими.
Формалізовані документи (УПД, ТОРГ-12, акти)
Окрема історія. Формалізовані документи — це XML за форматами ФНС (накази ММВ-7-15/820@, ЕД-7-26/736@). Їх не можна просто прикріпити як файл — потрібно генерувати XML з даних за форматом. Діадок надає генератор XML через POST /GenerateTorg12XmlForSeller, POST /GenerateUniversalTransferDocumentXmlForSeller та аналогічні методи.
На мобільному в більшості випадків користувач не створює УПД з нуля — він узгоджує або підписує вже створений документ. Створення формалізованих документів логічніше робити на веб-інтерфейсі або в ERP.
Уведомлення про нові документи
Push при поступленні нового документа на узгодження — ключова фіча для робочого ЕДО-додатка. Діадок підтримує вебхуки (POST /V3/Subscriptions): при новій події система робить POST на ваш endpoint, сервер відправляє FCM/APNs push.
Обробка на мобільному: натиск на пуш відкриває список документів з фільтром "потребує дії".
Офлайн та кешування
Документи кешуємо локально — користувач може переглядати вже завантажені документи без інтернету. Для чутливих даних — шифруємо кеш через iOS Data Protection (клас NSFileProtectionComplete) або Android Keystore + AES-256. Список документів можна зберігати в Core Data / Room з синхронізацією при появі мережі.
Процес внедрення
- Аудит вимог: які типи документів, яка підпис (КЕП/НЕП/ПЕП), який оператор ЕДО вже використовується в компанії
- Вибір методу підписання: хмарна підпис — єдиний розумний варіант для мобільних користувачів без корпоративного MDM
- Прототип інтеграції: тестове окремення ЕДО-оператора, базові запити
- Розробка: авторизація, список документів, перегляд, підписання
- Тестування: юридичні сценарії обов'язково перевіряємо з оператором ЕДО
- Аудит безпеки: зберігання токенів, шифрування кешу, захист від перехоплення
Терміни залежать від складності: перегляд та узгодження без створення документів — 3-4 тижні. Повний цикл з створенням, підписанням та інтеграцією хмарної КЕП — 2-3 місяці. Робота з формалізованими документами додає ще 2-4 тижні.