Разработка API-интеграций для бизнеса

Документация восстанавливается по факту: смотрим, какие запросы делает официальный клиент или веб-интерфейс сервиса, и фиксируем найденный контракт письменно. Дальше работаем по нему и держим проверку на изменения, потому что недокументированный метод может измениться без предупреждения. Если сервис не предоставляет доступа вовсе, честно скажем об этом до начала работ.

Операции не теряются: они встают в очередь и повторяются по возрастающей паузе, пока система не ответит или пока не сработает ограничение по числу попыток. Если попытки исчерпаны, запись остаётся в журнале с текстом ошибки и попадает в уведомление ответственным. Повторить операцию можно вручную, после того как причина устранена.

Каждая операция имеет ключ идемпотентности, который приходит от источника или формируется из номера сущности и версии. Получив повторно тот же ключ, система не создаёт новую запись, а возвращает результат предыдущей операции. Это обязательное требование, а не опция: сеть и очереди устроены так, что доставка «ровно один раз» невозможна, возможна только обработка повторов.

Лимиты учитываются на этапе проектирования: определяем, сколько запросов нужно на полный обмен, и раскладываем его во времени либо переходим на пакетные методы. При ответе с признаком превышения лимита обмен делает паузу до указанного сервисом времени, а не продолжает обращаться к API. Если лимитов не хватает в пиковые часы, часть данных переводится на вебхуки со стороны сервиса.

Обмен не должен быть чёрным ящиком: настраивается журнал операций с датой, сущностью и результатом, отдельный список неудачных попыток и уведомление, если обмен не проходил дольше заданного порога. Дополнительно ведётся сверка объёмов — сколько записей должно было пройти и сколько прошло. При желании к обмену делается раздел в админке, где видно состояние и можно повторить операцию.

Иногда да, но это худший вариант и мы говорим об этом прямо. Если у сервиса есть выгрузка файлов, обмен строится на файлах: CSV, XLSX или XML по расписанию, с проверкой целостности и разбором частично загруженных файлов. Автоматизация через веб-интерфейс рассматривается как крайняя мера: она ломается от любого изменения вёрстки и не даёт гарантий. Если ни файлов, ни API нет, честнее изменить процесс, чем строить хрупкий обмен.

Как правило нет. Эффективнее связать существующие системы и убрать ручной перенос данных, чем менять программу, к которой привыкла бухгалтерия и на которой построена отчётность. Исключение — случаи, когда система не имеет ни API, ни выгрузок и не развивается: тогда имеет смысл обсудить замену отдельно, но это уже другая задача.

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

Срок определяется на этапе контракта обмена и зависит от документированности API, наличия тестового контура, числа связок и требований к надёжности. Типовая связка по документированному REST API — это недели, а не месяцы; недокументированный протокол, обмен документами с ЭЦП или перенос многолетней истории могут занять существенно дольше. Часть работ — прототип и приёмка на сбоях — мы не сокращаем, потому что именно на них находятся проблемы.

Начинаем с аудита: разбираем текущую схему, находим, где теряются данные и откуда берутся дубли, и показываем это на конкретных операциях. По результату даём план: что можно починить точечно, что проще переписать и сколько стоит каждый вариант. Иногда достаточно добавить журнал, повторы и защиту от дублей, чтобы обмен перестал быть источником проблем.

Мы не можем отвечать за доступность чужого API, но отвечаем за то, как наш обмен переживает эту недоступность: операции не теряются, повторяются и видны в журнале, а ответственные получают оповещение. Если сервис изменил контракт без предупреждения, мы правим адаптер; доработки, вызванные изменениями на стороне провайдера, обсуждаются отдельно и обычно входят в сопровождение.

Работаем по NDA, если это требуется до обсуждения деталей. Доступы выдаются по принципу минимально необходимых прав, в идеале — к тестовому контуру, а не к промышленному. Токены и секреты хранятся в защищённом виде, не попадают в код и в логи, предусмотрена ротация. Подписи входящих вебхуков проверяются до обработки, а в журнале не хранятся платёжные и персональные данные в открытом виде.

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

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