Техническое задание на API-интеграцию описывает не «связать две системы», а поведение каждой бизнес-операции: событие, входные данные, поиск существующего объекта, ожидаемый результат, повтор, ошибка и способ проверки. Конкретный язык программирования и сервер важны позже. Сначала нужно договориться, что считается одним заказом, оплатой или обращением.
Эта структура дополняет общее ТЗ на CRM. Здесь фокус только на обмене через API, вебхуки и сервисный слой.
Граница интеграции и цель
В начале документа укажите бизнес-проблему и границу первой очереди. Например: «Менеджеры вручную создают заказы в 1С после согласования сделки. Первая очередь автоматизирует только создание заказа и возврат его номера; товары, оплаты и отгрузки остаются вне проекта».
Это лучше формулировки «двусторонняя синхронизация amoCRM и 1С». У ограниченного результата есть принимающий сотрудник, тестовые данные и понятная дата завершения. Для всего, что не входит, добавьте отдельный список — иначе пожелания незаметно станут обязательствами.
Карточка бизнес-операции
Для каждой операции заведите отдельную карточку. Ниже — учебный пример. Значения нужно адаптировать к реальным системам и подтвердить по документации.
- ID требования: ORDER-01.
- Событие: сделка перешла в согласованный этап после заполнения обязательных полей.
- Источник истины: CRM для коммерческих условий до создания заказа; 1С для номера и статуса исполнения после создания.
- Вход: ID сделки, компания, внешний ID контрагента, позиции, количество, цена, ставка НДС.
- Результат: создан один заказ клиента; его ID, номер и ссылка сохранены в сделке.
- Повтор: повтор того же события возвращает ссылку на существующий заказ и не создаёт новый.
- Ошибка: операция получает код, понятное сообщение и доступна для повторного запуска после исправления данных.
- Владелец: руководитель продаж принимает результат; специалист 1С подтверждает корректность документа.
Отдельно опишите, что произойдёт, если сделка вернётся на предыдущий этап, товар будет удалён или заказ уже отгружен. Не все изменения можно безопасно синхронизировать автоматически.
Контракт данных
| Поле | Что зафиксировать | Пример проверки |
|---|---|---|
| Идентификатор | Внутренний ID, внешний ID и область уникальности | Повтор одного external_operation_id не создаёт новый объект |
| Тип и формат | Строка, число, дата, валюта, часовой пояс, кодировка | Дата не сдвигается, сумма не теряет копейки |
| Обязательность | Можно ли пропустить поле и кто его заполняет | Пустой ИНН приводит к согласованному результату |
| Справочник | Соответствие статусов, товаров, единиц и ставок | Неизвестное значение не подменяется первым из списка |
| Персональные данные | Цель передачи, объём, хранение и доступ | Сервис не пишет токены и лишние данные в открытый журнал |
Приложите примеры реальных, обезличенных payload: успешного, неполного и ошибочного. Названия полей в двух системах могут совпадать, но иметь разный смысл. Для статуса «Оплачен» уточните, означает ли он любую оплату, полную сумму или подтверждённое поступление на счёт.
Доставка, повтор и порядок событий
API-запрос может завершиться таймаутом после того, как получатель уже создал объект. Поэтому «не получили ответ» не равно «операция не выполнена». В ТЗ нужен идемпотентный ключ или другой способ найти результат перед повторным созданием.
Опишите политику повторов: какие ошибки временные, сколько попыток выполняется, как растёт интервал, когда операция уходит на ручной разбор. Укажите порядок событий. Если «оплата» пришла раньше «создания заказа», сервис должен отложить её, связать позже или явно остановить — но не молча потерять.
Официальная документация amoCRM устанавливает лимиты запросов и ответы 429, 401, 402, 403 и 504, которые должны учитываться в обработке. Ограничения и рекомендации API amoCRM.
Авторизация и безопасность
Укажите способ авторизации каждой системы, необходимые права и владельца технического аккаунта. Секреты не включают в ТЗ открытым текстом. Документ должен ссылаться на защищённое хранилище и описывать выдачу, ротацию и отзыв доступа.
Для webhook добавьте проверку источника, HTTPS и защиту от повторной отправки. Для приложения — жизненный цикл установки и удаления. Для сервера — список администраторов, резервное копирование и действия при утечке токена. Для персональных данных укажите минимально нужный состав и срок хранения журналов.
Что должно быть видно поддержке
Требование «логировать ошибки» недостаточно. По одному идентификатору специалист должен увидеть время, тип операции, источник, связанные объекты, номер попытки, код ответа, безопасный фрагмент сообщения и итог. Секреты и чувствительные данные в журнал не попадают.
Определите алерты: что считается инцидентом, через сколько минут он создаётся, кому приходит и какие сведения приложены. Кроме ошибок полезны положительные метрики: время последней успешной операции, длина очереди и число обработанных заказов за период. Так можно заметить тишину, когда ошибок нет, но события перестали приходить.
Минимальный набор приёмочных тестов
| Тест | Ожидаемый результат | Доказательство |
|---|---|---|
| Обычная операция | Создан и связан один корректный объект | ID с обеих сторон и запись журнала |
| Повтор события | Второй объект не создан | Тот же ключ операции и ссылка на результат |
| Неполные данные | Операция остановлена понятным способом | Код ошибки и поле, которое нужно исправить |
| Таймаут после записи | Повтор находит ранее созданный объект | Нет дубля, операция завершена |
| Недоступность API | Событие сохранено и повторено по правилам | История попыток и время восстановления |
| Отзыв доступа | Алерт содержит причину, данные не теряются | 401/403, очередь и инструкция восстановления |
| Массовый поток | Лимиты не нарушены, отставание измеримо | Метрики очереди и время завершения |
Каждый тест содержит входные данные и принимающего. Замечание «не работает» замените ссылкой на операцию и фактическим результатом. Если исправление меняет контракт, обновляются и ТЗ, и тест.
Что передаётся после разработки
В состав передачи включите репозиторий, список окружений, схему компонентов, конфигурацию без секретов, зависимости, миграции базы, инструкцию развёртывания, мониторинг, резервное копирование и runbook инцидента. Для low-code добавьте экспорт workflow и версию узлов; для виджета — исходный архив и процесс сборки.
ТЗ готово, когда другой специалист может объяснить один сценарий и провести тест без устных догадок. После этого можно оценивать разработку интеграции и отделять обязательную первую очередь от будущего развития.