Интеграция мобильного ЭДО с облачной подписью и Диадок API

Представьте: водитель доставки получает на Android-планшет акт выполненных работ, подписывает его за 15 секунд, и документ сразу уходит в бухгалтерию. Без сканера, без бумаги, без курьера. Так работает мобильный ЭДО. Но за этой простотой скрывается сложная интеграция: API, криптография, юридическая значимость. Мы делаем так, чтобы ваш электронный документооборот работал на мобильных устройствах без сюрпризов — с облачной подписью, push-уведомлениями и безопасным кэшированием.

Интеграция СЭД в мобильное приложение — это не про «прикрутить API». Это про выбор оператора, тип подписи, формат документов и регуляторные требования. Наш опыт: более 50 интеграций с Диадок, СФЕРА, 1С-ЭДО. Разберём ключевые моменты.

Как облачная подпись упрощает юридически значимый ЭДО?

Юридически значимый ЭДО требует квалифицированной электронной подписи (КЭП) или неквалифицированной (НЭП) в зависимости от типа документа. Это ключевое отличие от «нажать кнопку Подписать» в интерфейсе. На мобильном устройстве подписание реализуется несколькими способами.

Облачная подпись (рекомендуется для мобильных). КЭП хранится в защищённом хранилище оператора ЭДО или удостоверяющего центра. Приложение запрашивает подписание через API — пользователь подтверждает операцию через SMS-код или push-уведомление. Закрытый ключ никогда не покидает облако. Диадок предоставляет облачную подпись через Контур.Крипто. Этот подход в 10 раз безопаснее хранения КЭП на устройстве — риск утечки ключа минимален.

Работа через токен/смарт-карту. Подключение USB-токена (Рутокен, eToken) через Lightning/USB-C адаптер — экзотика для мобильных, но бывает в промышленных сценариях. Требует специальных SDK от производителя токена и поддержки MFi.

Простая электронная подпись (ПЭП). Для внутреннего ЭДО (согласование внутри компании, не требующее КЭП) можно обойтись ПЭП — это по сути авторизованное действие пользователя в системе, которое логируется. Юридическая сила ниже, но для внутреннего оборота достаточно.

Как устроена интеграция с Диадок 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 с синхронизацией при появлении сети.

Что входит в работу по интеграции?

Мы предоставляем интеграцию под ключ с передачей всей документации и доступами. Вот что вы получаете:

• Аудит требований и выбор оператора ЭДО под ваш сценарий.
• Реализация авторизации (OAuth 2.0) и списка документов.
• Просмотр PDF/TIFF/XML формализованных документов.
• Подписание через облачную подпись или ПЭП.
• Push-уведомления при поступлении новых документов.
• Кэширование с шифрованием (AES-256) для офлайн-доступа.
• Документация и обучение команды.
• Пост-релизная поддержка на 3 месяца.

Как мы внедряем ЭДО: процесс и сроки

1. Аудит требований: какие типы документов, какая подпись (КЭП/НЭП/ПЭП), какой оператор ЭДО уже используется в компании.
2. Выбор метода подписания: облачная подпись — единственный разумный вариант для мобильных пользователей без корпоративного MDM.
3. Прототип интеграции: тестовая среда Диадока / другого оператора, базовые запросы.
4. Разработка: авторизация, список документов, просмотр, подписание.
5. Тестирование: юридические сценарии обязательно проверяем с оператором ЭДО.
6. Аудит безопасности: хранение токенов, шифрование кэша, защита от перехвата.

Сроки зависят от сложности: просмотр и согласование без создания документов — 3–4 недели. Полный цикл с созданием, подписанием и интеграцией облачной КЭП — 2–3 месяца. Работа с формализованными документами добавляет ещё 2–4 недели.

Типичные ошибки при интеграции ЭДО:

• Не учитывать обязательность КЭП для внешних контрагентов — внутренний ПЭП не подойдёт.
• Хранить закрытый ключ на устройстве без шифрования — риск компрометации.
• Игнорировать форматы ФНС для формализованных документов — штрафы и отказ оператора.
• Забывать про автообновление токена — пользователь будет часто переавторизовываться.
• Не кэшировать документы — пользователь не сможет работать офлайн.

Кейс: логистическая компания

Интегрировали ЭДО для логистической компании: 1500 документов в день, подписание актов на Android-планшетах водителями. Выбрали облачную подпись через Диадок, реализовали авторизацию по Контур.ID, push-уведомления при поступлении документов. Просмотр PDF через WebView, подписание — по кнопке с подтверждением SMS. Время от открытия до подписания — 15 секунд. До внедрения — 3 дня на бумагу. Сокращение сроков согласования — в 17 280 раз быстрее. Экономия на операционных затратах — до 60%.

Какие операторы ЭДО доступны для интеграции?

Для новых проектов чаще выбираем Диадок — наиболее полный API, большая клиентская база.

Когда нужна квалифицированная подпись?

Согласно Федеральному закону №63-ФЗ, для внешнего оборота с контрагентами обязательна КЭП. Внутренние согласования могут обходиться ПЭП. Облачная подпись решает проблему безопасности: вы получаете юридическую значимость без риска утери ключа. Федеральный закон №63-ФЗ «Об электронной подписи» регулирует виды подписей и их применение.

Свяжитесь с нами для бесплатной консультации по выбору оператора и оценке проекта — мы подберём оптимальное решение под ваш бизнес. Закажите demo-версию, чтобы увидеть интеграцию в действии.

Интеграция API в мобильное приложение: с чего начать

Запрос уходит, ответ не приходит, timeout — 30 секунд. Пользователь смотрит на спиннер. Сети нет — мобильная карта в метро. Или сеть есть, но сервер вернул 200 с HTML-страницей ошибки вместо JSON — и приложение крашит при JSONDecoder.decode(). Мы видим такие кейсы на каждом втором проекте. Поэтому интеграция API в мобильное приложение — это не просто вызов endpoint'а, а проектирование надёжного сетевого слоя: обработка ошибок, кэширование, offline-режим, certificate pinning. Закажите аудит текущего сетевого слоя — оценим проект за 1 день.

Почему стандартные библиотеки недостаточны? URLSession и OkHttp предоставляют базовый HTTP-клиент, но для production нужны retry с exponential backoff, валидация статус-кодов, типизированная десериализация и мониторинг состояния сети. Без этого приложение теряет данные и пользователей. Мы уже 5 лет занимаемся мобильной разработкой и реализовали более 30 проектов с интеграцией API на iOS, Android и Flutter — от стартапов до enterprise-решений.

Как выбрать протокол для интеграции API?

REST остаётся стандартом для большинства проектов. Но когда на экране профиля нужно 5 полей из 40, GraphQL исключает over-fetching и сокращает трафик на 30–60%. gRPC оправдан при тысячах запросов в минуту (trading, IoT) — бинарная сериализация в 3–5 раз быстрее JSON. WebSocket — единственный выбор для real-time без polling (сообщения, уведомления).

Пример из практики: для финтех-приложения мы заменили REST (40 полей) на GraphQL — размер ответа сократился с 12 КБ до 2,5 КБ, время рендера экрана упало на 70%. Экономия трафика составила около 15 000 ₽ в месяц при 100 000 активных пользователей.

Как обеспечить надёжность соединения и offline-first

Пользователи теряют сеть в метро, лифте, тоннеле. Мобильное приложение обязано работать без интернета — хотя бы в read-only режиме. Мы внедряем паттерн offline-first:

1. При открытии экрана сначала показываем данные из локального кеша (Core Data / Room).
2. Параллельно выполняем сетевой запрос, обновляем UI после ответа.
3. Если сеть недоступна — показываем кешированные данные и метку «нет соединения».
4. При восстановлении сети автоматически синхронизируем изменения.

Для кэширования HTTP-ответов используем URLCache (iOS) и OkHttp Cache (Android) с поддержкой Cache-Control. Для структурированных данных — SwiftData / Room. NWPathMonitor / ConnectivityManager.NetworkCallback отслеживают состояние сети и триггерят обновление.

REST и выбор клиентской библиотеки

Alamofire (iOS) — де-факто стандарт для Swift-проектов. Поверх URLSession добавляет request chaining, response validation, automatic retry, certificate pinning через ServerTrustManager. AF.request() с .validate() возвращает ошибку для любого статус-кода вне 200–299. Без .validate() Alamofire считает 404 и 500 успешными ответами. С Swift Concurrency — async-версия через serializingDecodable.

Retrofit (Android) — аннотационный HTTP-клиент поверх OkHttp. Интерфейс с аннотациями компилируется в реализацию. @GET, @POST, @Path, @Query, @Body — декларативное описание API. OkHttp под капотом: connection pooling, transparent gzip, HTTP/2 multiplex. HttpLoggingInterceptor — логирование в debug-сборке. Authenticator — автоматический refresh токена при 401.

Ktor (KMM/Flutter) — мультиплатформенный HTTP-клиент. На iOS работает через Darwin engine (URLSession), на Android — через OkHttp. Единый код для обеих платформ при KMM-архитектуре.

GraphQL: когда REST не справляется

REST возвращает фиксированную структуру. Экран профиля требует name, avatar, email — сервер отдаёт 40 полей. Over-fetching. GraphQL решает это: клиент запрашивает ровно нужные поля. Это критично для мобайла, где трафик и время парсинга — реальные ограничения. Apollo iOS и Apollo Kotlin генерируют типизированные классы по схеме: schema.graphql + query-файлы → строгие типы на этапе компиляции. Subscriptions через WebSocket — real-time без polling. Ограничение: GraphQL сложнее кешировать на уровне HTTP. Apollo использует нормализованный in-memory кеш InMemoryNormalizedCache — запросы с пересекающимися данными обновляют кеш без дублирования. Apollo GraphQL Documentation

WebSocket: real-time без лишнего трафика

Polling (setInterval каждые 5 секунд) — трата батареи и трафика. WebSocket — постоянное двунаправленное соединение. iOS: URLSessionWebSocketTask (нативный, iOS 13+). Android: OkHttp WebSocket. Обязательная обработка reconnect: при onFailure — экспоненциальный backoff (1с → 2с → 4с → 8с → максимум 60с). Socket.IO — надстройка с автоматическим reconnect, но для новых проектов предпочтительнее нативный WebSocket (меньше зависимостей).

gRPC: для высоконагруженных сервисов

gRPC с protobuf — бинарная сериализация: меньше размер, быстрее парсинг. grpc-swift для iOS, grpc-kotlin для Android. Protobuf-схема компилируется в типизированные классы. Streaming (server-side, client-side, bidirectional) — нативная возможность. Порог применения: высокая частота запросов (trading, IoT) или критичная latency. Для обычного CRUD REST проще в дебаге и мониторинге.

Certificate Pinning и безопасность

Корпоративный proxy может перехватить HTTPS через подмену сертификата. Certificate pinning предотвращает это: приложение принимает только конкретный сертификат или публичный ключ. Alamofire: ServerTrustManager с PinnedCertificatesTrustEvaluator. OkHttp: CertificatePinner с SHA-256 хешем. Операционная сложность: при ротации сертификата старые версии приложения перестают работать. Решение — pinning на публичный ключ CA или поддержка нескольких пинов с grace period. Подробнее о certificate pinning на Wikipedia

Что входит в работу

Мы передаём: исходный код сетевого слоя, документацию по используемым библиотекам, инструкцию по ротации сертификатов, поддержку в течение 2 недель после сдачи.

Сроки и стоимость

Реализация сетевого слоя с REST, retry, кэшированием и offline-режимом — 1–2 недели. Добавление GraphQL или WebSocket — ещё 1–2 недели. gRPC — 2–3 недели, включая кодогенерацию. Стоимость рассчитывается индивидуально после анализа API и требований к offline-поведению. Оценим проект за 1 день — свяжитесь для консультации.