Интерфейс есть, серверной части нет
Кабинет или приложение делает другая команда, и ей нужен API: понятный, документированный и с тестовым стендом, а не набор адресов в переписке.
Разработка API и бэкенда на заказ: REST и интеграционные сервисы
Бэкенд — серверная часть, к которой обращаются кабинет, сайт, мобильное приложение, 1С и другие системы: она хранит данные, проверяет права и исполняет правила. Мы разрабатываем REST API с документацией OpenAPI, интеграционные сервисы между системами, бэкенд внутренних сервисов, обработчики событий и очередей. Отдельно закладываем версии, единый формат ошибок, защиту от повторных запросов, ограничение частоты и журнал. Исходники и сервер остаются у вас.
Обследование — 200 000 ₽, 2–3 неделиЛёгкий пилот одного API — 150 000–400 000 ₽Документация OpenAPI и тестовый стенд к приёмке
С чем приходят
Когда нужен отдельный API или бэкенд
Системы обмениваются файлами и руками
Выгрузка в таблицу, письмо, загрузка в другую систему. Нужен сервис в центре, который принимает, проверяет, преобразует и передаёт данные.
Старый обмен сломался, и никто не знает почему
Обмен писали давно, журнала нет, потерянное сообщение не найти. Нужен сервис, где видна каждая попытка, а недоставленное остаётся в списке, а не исчезает.
Партнёрам нужен доступ по API
Нужны отдельные ключи на каждого, права по операциям, ограничение частоты, документация и возможность отозвать доступ, не остановив остальных.
Скрипт вырос в систему
Задача началась как скрипт по расписанию, теперь это десяток режимов и исключений. Пора разделить приём, обработку и очередь.
События приходят со стороны
Вебхуки площадок и платёжных провайдеров, сигналы оборудования. Нужен приёмник с проверкой подписи (где отправитель её поддерживает), очередью и защитой от дублей.
Состав
Четыре типовые поставки: из чего состоят и где ломаются
Состав и проверки при приёмке записываются в обследовании, поэтому на сдаче никто не спорит о том, что считать готовым.
Поставка
Из чего состоит
Что проверяем при приёмке
Где ломается
ПоставкаAPI для кабинета или приложенияREST и OpenAPI
Из чего состоитРесурсы и операции, вход и права, постраничная выдача, загрузка файлов, версии, описание в OpenAPI
Что проверяем при приёмкеКаждая операция из-под каждой роли, чужие данные недоступны, коды ошибок совпадают с описанием, документация совпадает с поведением
Где ломаетсяОтвет сервера поменяли, а приложения старых версий остались у пользователей и перестали работать
ПоставкаИнтеграционный сервис между системамиобмен без потерь
Из чего состоитПриём и отправка, преобразование и сопоставление справочников, очередь, повторы, защита от дублей, журнал, оповещения
Что проверяем при приёмкеПовтор запроса не создаёт вторую запись, при недоступной смежной системе сообщения остаются в очереди, а недоставленное видно в списке и в журнале
Где ломаетсяЧужая сторона поменяла формат или сертификат, и обмен остановился без шума, пока не пожаловался клиент
ПоставкаБэкенд внутреннего сервисаданные и правила
Из чего состоитМодель данных, правила процесса, роли, журнал изменений, отчёты и выгрузки, фоновые задачи
Что проверяем при приёмкеСценарии по протоколу испытаний, миграции схемы применяются на копии; восстановление из резервной копии на чистом сервере проверяется при выводе в эксплуатацию
Где ломаетсяПравила процесса живут в интерфейсе, а не на сервере, и второй клиент обходит их напрямую
ПоставкаОбработчик событий и очередейвебхуки и фоновые задачи
Из чего состоитПриём вебхуков, очередь задач, фоновая обработка, отложенные и повторные операции, список недоставленного
Что проверяем при приёмкеПодпись входящих событий проверяется там, где отправитель её поддерживает; если нет, используем секрет в адресе, список адресов отправителя и повторный запрос события у источника. Повторная доставка не создаёт дублей, сообщения в очереди сохраняются на диск и переживают перезапуск брокера (проверяется отдельным испытанием)
Где ломаетсяОчередь растёт, а никто не смотрит; повторная доставка создаёт дубли; один тяжёлый обработчик занимает всех исполнителей
Контракт
Что закладываем в любой API, кроме самих операций
Шесть пунктов, которые записываем в контракт до кода. Подробный разбор каждого есть в статье про проектирование API для интеграций, здесь только что фиксируем и что решаете вы.
Что закладываем
Что записываем в контракт
Что решаете вы
Что бывает без этого
Что закладываемОписание OpenAPIлежит рядом с кодом
Что записываем в контрактПути, параметры, схемы запросов и ответов, коды ошибок, способ входа. Расхождения в схемах и кодах ответов ловят проверки в сборке
Что решаете выКто подключается и нужны ли заготовки клиентов для их языков
Что бывает без этогоДокументация устарела, и подрядчик партнёра угадывает поведение по ответам сервера
Что закладываемВерсиизакладываем с первого дня
Что записываем в контрактВнутри версии добавляем необязательные поля, если клиенты по правилам документации игнорируют незнакомое. Остальное (переименование, удаление, смена типа или смысла, новое обязательное поле в запросе, новое значение закрытого перечня статусов) выходит новой версией с датой отключения старой
Что решаете выКто из потребителей обновляется сам, а кто раз в год
Что бывает без этогоПоле переименовали молча, и чужая интеграция перестала читать данные
Что закладываемФормат ошибокодин на весь интерфейс
Что записываем в контрактНастоящие коды ответов и одинаковая структура тела: стабильный машинный код, сообщение, поле с ошибкой, номер запроса
Что решаете выЧто показывать пользователю, а что писать только в журнал
Что бывает без этогоКлиент разбирает текст ошибки, и любая правка формулировки ломает обмен
Что закладываемПовторы запросовключ идемпотентности
Что записываем в контрактОперации записи принимают ключ: повтор с тем же ключом возвращает прежний результат, срок хранения ключей указан. То же правило действует на приёме вебхуков
Что решаете выКакие операции нельзя повторять без подтверждения человека
Что бывает без этогоСеть потеряла ответ, и в учёте два одинаковых заказа
Что закладываемОграничение частотылимиты по ключам
Что записываем в контрактОтдельные лимиты на чтение и запись, ответ с указанием, когда повторить. Тяжёлые операции (выгрузки, пересчёты) оформлены задачей: клиент получает номер и забирает результат
Что решаете выКакой объём считать нормальным для каждого потребителя
Что бывает без этогоОдин партнёр занимает все ресурсы, и остальные получают отказы
Что закладываемЖурнал и трассировканомер у каждого запроса
Что записываем в контрактНомер попадает в ответ и в журнал вместе с ключом, операцией и временем. По номеру или, если его нет, по времени и ключу видно, дошёл ли запрос до сервера и чем закончился
Что решаете выКто из ваших сотрудников читает журнал и как долго он хранится
Что бывает без этогоЖалоба «заказ не пришёл» превращается в переписку между командами
Приёмка
Как принимаем API и что делаем с нагрузкой
Скорость и предел нагрузки зависят от вашего профиля, поэтому в общем виде цифр мы не называем. Вместо этого фиксируем, что и как измеряем.
Приёмка по сценариям
Протокол испытаний пишется до начала разработки. В нём каждая операция с ожидаемым результатом, включая ошибочные случаи: неверные данные, чужой объект, просроченный ключ, повтор запроса. Автоматические проверки сверяют схемы и коды ответов с описанием OpenAPI и запускаются при каждой сборке, а смысл полей и порядок операций проходят по сценариям протокола.
Права проверяем с чужой стороны
Для каждой роли и каждого ключа пробуем открыть чужие данные, подставив чужой идентификатор. Это типовая уязвимость API: нарушение авторизации на уровне объектов входит в число главных рисков по списку OWASP API Security, поэтому проверяем её отдельно.
Сбои проверяем намеренно
Отключаем смежную систему, обрываем соединение посреди записи, отправляем одно событие дважды, перезапускаем сервис с непустой очередью. Нормальный результат: сообщения не пропадают молча (недоставленное видно в журнале), дублей нет, ответственному ушло оповещение.
Нагрузка
Сначала договариваемся о профиле: сколько пользователей и систем обращается, какие операции самые частые, когда бывают пики, как быстро растёт объём данных. Проверяем на стенде, близком по конфигурации к боевому серверу, с обезличенными или сгенерированными данными сопоставимого объёма. В протокол попадают измеренные значения для вашего профиля, а не обещание «выдержит столько-то»; при смене сервера или базы замер повторяется. Нагрузочные испытания относятся к выводу в эксплуатацию, а в пилотах профиль только фиксируется. Узким местом может оказаться база данных или чужая система, а не код сервиса.
Обмен с 1С
API и обмен с 1С: когда отдельный сервис оправдан
Отдельный сервис оправдан, когда систем три и больше и обмены сложнее простой пересылки или когда нужен разбор расхождений постфактум; между двумя системами прямой обмен может оказаться дешевле. Если задача — просто связать 1С с сайтом, CRM или маркетплейсом, начните со страниц про интеграцию 1С и про интеграции и сопровождение.
Две системы: прямая связь
Стандартный формат там, где он есть, свой код там, где его нет. Для сайта и 1С это разобрано на странице про интеграцию сайта с 1С и в статье про обмен по CommerceML.
Три системы и больше: слой обмена
Прямых связей становится много, и сервис в центре начинает окупаться: правила преобразования и журнал пишутся один раз. Он принимает данные от любой стороны, приводит к общему виду, хранит очередь и журнал, а каждая система знает только про него. Изменение на одной стороне правится в одном месте. Цена такого решения: ещё один сервис в эксплуатации и точка отказа в центре. Поэтому выбор между прямой связью и сервисом записываем в обследовании вместе с причиной.
Когда сервис нужен, даже если систем две
- Нужен разбор расхождений постфактум: кто, что и когда отправил, что ответила вторая сторона.
- Данные нужно преобразовывать сложнее, чем умеет стандартный обмен: сопоставление справочников, расчёты, объединение записей.
- Одну из сторон предстоит заменить, и менять обмен целиком не хочется.
- Принимающая сторона бывает недоступна часами, а сообщения терять нельзя.
Какая система главная при расхождении, решается до написания кода и записывается в схему обмена. Без этого сервис в центре просто быстрее множит дубли. Для связки с CRM схема описана в статье про типовые схемы интеграции 1С с CRM.
Что делаем
Из чего состоит работа и сколько она стоит
Цены — по тарифам. Точная цена только у обследования, дальше вилка, которая сужается по его результатам.
Обследование интерфейса или обмена
Потребители и их запросы, объекты и операции, права, схема обмена, требования к надёжности, профиль нагрузки, вилка бюджета. Вычитается из первого этапа, если продолжаете с нами.
200 000 ₽ · 2–3 недели
Обследование нескольких систем
Если в обмене участвуют 1С, CRM, сайт, склад и платёжный провайдер: схема обменов, матрица источников истины, требования к очередям и журналу.
350 000 ₽ · 3–4 недели
Лёгкий пилот: один API или одна связка
Сначала контракт OpenAPI, затем набор операций или один обмен на ваших данных, тестовый стенд, журнал, протокол испытаний. Лёгкий пилот от 150 000 ₽ — один API или одна связка на ваших данных, а не готовая интеграционная платформа.
150 000 – 400 000 ₽ · 2–8 недель
Первая версия сервиса обмена (тяжёлый пилот)
Работающий интеграционный сервис на боевых данных: очередь, повторы, защита от дублей, оповещения, подключение боевых систем, регламент эксплуатации. Это MVP, а не система в ежедневной эксплуатации. Резервные копии с проверкой восстановления, нагрузочные испытания и полный мониторинг относятся к выводу в эксплуатацию; в первой версии — копия по расписанию и оповещение о недоступности.
400 000 – 1 200 000 ₽ · 2–3 месяца
Вывод в эксплуатацию
Рабочая система в ежедневной эксплуатации: опытная эксплуатация, нагрузочные испытания по согласованному профилю, полный мониторинг, резервные копии с проверкой восстановления, обучение, передача исходников и инструкций.
от 1 500 000 ₽ этапами по 300 000 – 700 000 ₽
Сопровождение
Мониторинг, разбор сбоев, правки при изменениях на чужой стороне. Три пакета часов, ставка сверх пакета — 5 000 ₽ в час.
от 20 000 ₽ в месяц
Процесс
Как идёт работа
Недели 1–4 — Обследование
Выясняем, кто будет вызывать интерфейс и что ему нужно, какие данные и в какой системе главные, каковы пики нагрузки и что должно происходить при сбое. На выходе документ, с которым можно идти в тендер и сравнивать предложения, в том числе не наши.
Первый шаг разработки — Контракт
Порядок один и для пилота: сначала согласованный объём работ (обследование или, для небольшого пилота, разговор и письменный список «входит / откладываем»), затем контракт OpenAPI. Пишем описание и формат ошибок, согласуем их с командой клиента до кода. Это позволяет команде кабинета или приложения начать работу параллельно, на заглушках.
Основной этап — Реализация
Собираем операции короткими итерациями. Раз в две недели показываем работающую версию на тестовом стенде, проверки на соответствие описанию запускаются при каждой сборке.
Перед запуском — Прогон на копии
Сначала тестовые контуры смежных систем; если их нет, работаем на копии базы в вашем контуре. Потом боевые данные в режиме чтения, без выноса за пределы вашего периметра. На стенде используем обезличенные или сгенерированные данные. Запись на боевую сторону включаем последней, первые обмены смотрим вместе.
После запуска — Сопровождение или передача
Передаём исходники, инструкции и доступ к журналу. Сопровождение у нас или у вас: решаете вы.
Цена
Что двигает цену внутри вилки
Потребители и роли
Один потребитель с одним ключом и десяток партнёров со своими правами — разный объём проверок и разный объём документации.
Качество чужих интерфейсов
У смежной системы может не быть документации, тестового контура или стабильного формата. Тогда часть бюджета уходит на выяснение, как она на самом деле работает.
Требования к надёжности
Очередь, повторы, оповещения, разбор расхождений и защита от дублей увеличивают объём работ по сравнению с обменом «отправил и забыл».
Состояние данных и справочников
Если справочники ведутся в нескольких местах и противоречат друг другу, первые недели уходят на правила сопоставления, а не на код.
Контроль
Что остаётся у вас и чего мы не делаем
Остаётся у вас
- Исходный код сервиса в вашем репозитории с первого коммита; порядок передачи прав записывается в договоре.
- Описание OpenAPI, схема данных и схема обмена: объекты, направления, правила разрешения конфликтов.
- Журнал запросов с доступом ваших сотрудников и оповещения, которые приходят вашему ответственному.
- Ключи, учётные записи и доступы оформлены на вас, а не на нас.
- Право остановиться после любой ступени: сделанное остаётся у вас по акту.
Мы этого не делаем
- Не обещаем процент доступности: он зависит от чужих систем и вашей инфраструктуры. В сопровождении записываем время реакции и часы пакета.
- Не обещаем интеграцию через серверную часть для систем без API и без выгрузки: возможен робот, который действует в интерфейсе программы, но он хрупок при её обновлениях и оценивается отдельно, как автоматизация.
- Мобильные приложения для магазинов приложений в эту услугу не входят; для вашего или чужого приложения поставляем серверную часть и описание интерфейса.
- Не строим открытые платформы для внешних разработчиков с порталом, биллингом и поддержкой.
- Не принимаем платежи от вашего имени: этим занимается платёжный провайдер.
- Не берём работы дешевле 150 000 ₽ и не дежурим круглосуточно.
- Лицензии ФСТЭК у нас нет, аттестацию объектов не проводим.
Инструменты
На чём собираем
Серверная часть и данные
- Python: Django или FastAPI, при необходимости Go
- PostgreSQL
- Redis или совместимое хранилище для кэша; очередь в PostgreSQL или RabbitMQ, выбираем на обследовании
- S3-совместимое хранилище (своё или у хостера) для файлов
Контракт, проверка и развёртывание
- OpenAPI и контрактные проверки в сборке
- Keycloak, ключи доступа, двухфакторный вход для администраторов
- Docker, Nginx, GitLab CI
- Prometheus и Grafana, журнал запросов
Материалы
Материалы по теме
Проектирование API для интеграций: версии и ошибки
Ресурсы и операции, формат ошибок, ключ идемпотентности, постраничная выдача, вебхуки и документация OpenAPI.
- Идемпотентность
- Версии без поломок
- Чек-лист приёмки
CommerceML: как устроен обмен 1С с сайтом
Файлы, порядок запросов, типовые поломки и момент, когда формата уже не хватает.
- Сеанс обмена
- Сбои и причины
- Сверка
Интеграция 1С с CRM: типовые схемы
Кто главный для каких данных, где обмен ломается и когда готового коннектора мало.
- Кто главный
- Дубли
- Готовое или своё
Как составить техническое задание на разработку
Что записать, чтобы оценка и приёмка опирались на один документ.
- Границы
- Данные
- Критерии приёмки
Заявка
Разберём ваш API или обмен между системами
Сорок минут созвона: кто будет обращаться к интерфейсу, какие системы участвуют, что должно происходить при сбое. По итогам скажем, с какой ступени начинать и в какую вилку это укладывается.
Вопросы
Частые вопросы: разработка API и бэкенда
Сколько стоит разработка API?
Один API или одна связка проверяются лёгким пилотом: 150 000–400 000 ₽ и 2–8 недель, первым шагом идёт контракт OpenAPI. Точная цена только у обследования: оно стоит 200 000 ₽ за один-два процесса и 350 000 ₽, если в обмене несколько систем, и вычитается из первого этапа, если продолжаете с нами. Дальше цена идёт вилкой, которая сужается по его итогам. Первая версия интеграционного сервиса с очередями и несколькими системами на боевых данных (в тарифах «Пилот, тяжёлый») — 400 000–1 200 000 ₽ за 2–3 месяца. Вывод в эксплуатацию идёт отдельной ступенью от 1 500 000 ₽ этапами по 300 000–700 000 ₽.
Чем бэкенд отличается от API?
Бэкенд — вся серверная часть: данные, правила, фоновые задачи, очереди. API — та её часть, которая открыта другим программам. Бывает бэкенд без внешнего API, если доступ нужен только своему интерфейсу, и бывает API-обёртка над чужой системой.
Нужен ли именно REST или можно выбрать другой протокол?
Не обязательно. По умолчанию берём REST с данными в JSON, он описывается в OpenAPI. Если смежная система умеет только SOAP или файловый обмен, подстраиваемся под неё. Причину выбора записываем в обследовании.
Чем интеграционный сервис отличается от обмена 1С по CommerceML?
Стандартный обмен закрывает типовую схему между 1С и сайтом. Интеграционный сервис нужен, когда систем три и больше и обмены сложнее простой пересылки, когда данные нужно преобразовывать сложнее стандартного обмена или когда важен журнал каждой попытки и разбор расхождений постфактум.
Как вы защищаете от дублей и потери данных?
Ключ идемпотентности для операций записи, проверка подписи входящих событий там, где отправитель её поддерживает, и проверка их идентификатора, очередь с повторами и список недоставленного. Чужая система может упасть, но сообщения не пропадают молча: доставка «не меньше одного раза» плюс защита от дублей, а недоставленное остаётся в списке и в журнале. Если отправитель не умеет повторять запрос, это записывается в схему обмена как риск. Оповещение о сбое уходит вашему ответственному сразу, а не после жалобы клиента.
Что с нагрузкой? Выдержит ли сервис наш объём?
Заранее и в общем виде не скажем: «выдержит» относится к вашему профилю нагрузки и проверяется, а не обещается. Профиль (пользователи, самые частые операции, пики, рост данных) фиксируем на обследовании, измеренные значения передаём при выводе в эксплуатацию. Если упираемся в базу или в чужую систему, это записывается в протокол.
Можно ли доработать уже существующий бэкенд?
Да, если есть исходники или их можно восстановить. Сначала разбор состояния: сборка, документация, тесты, схема данных. Потом цена. Брать на доработку то, чего не видели, нельзя.
Что входит в сопровождение API и обмена?
Сопровождение берём ежемесячно: 20 000, 60 000 или 120 000 ₽ в месяц (до 4, 12 или 25 часов). В часы входят мониторинг очереди и журнала, разбор сбоев и правки при смене формата или сертификата на чужой стороне. Работы сверх пакета — 5 000 ₽ в час, согласуем до начала.
Вы работаете только в Ростове-на-Дону?
Мы в Ростове-на-Дону, работаем с заказчиками по всей России: удалённо и в вашем контуре. Доступ к системам и обследование согласуем на старте с вашей службой безопасности.
Смежное
Что посмотреть рядом
- Разработка веб-сервисов и веб-приложений на заказ
- Разработка SaaS-платформы на заказ
- Разработка личного кабинета клиента и партнёра
- Разработка CRM и внутренних систем на заказ
- Разработка программного обеспечения на заказ
- Интеграция 1С с CRM, сайтом и маркетплейсами
- Интеграция сайта с 1С: каталог, остатки, заказы
- Интеграции и сопровождение
- Цены и сроки по ступеням
- Проектирование API для интеграций
- CommerceML: обмен 1С с сайтом
- Интеграция 1С с CRM: типовые схемы