Требования к API-интеграции: шаблон документа и чек-лист

Короткий ответ

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

Почему интеграция без документа затягивается

Без документа интеграция часто идёт так: бизнес говорит «лиды должны попадать в CRM», разработчик за день делает webhook, на тесте выясняется, что продажи ждали и обратной передачи статусов, а служба безопасности спрашивает, где хранятся ключи. Каждый новый вопрос добавляет неделю, и в итоге никто не может сказать, когда проект «закончен», потому что критерии приёмки не записаны.

Документ требований заставляет задать эти вопросы до написания кода и закрывает их подписями обеих сторон.

Двенадцать разделов

1. 11. Цель и границыЗачем, какой результат ожидается и что в проект не входит.
2. 22. Бизнес-сценарии«Клиент пишет номер в WhatsApp → в CRM создаётся лид → назначается менеджеру».
3. 33. Системы и владельцыКаждая система с её техническим и бизнес-владельцем.
4. 44. ДанныеОбъекты, поля, форматы и ссылка на карту полей.
5. 55. ИнтерфейсыЭндпоинты, методы, события, пример запроса и ответа.
6. 66. Аутентификация и безопасностьТип ключа, место хранения, ротация, ограничения по IP, объём прав.
7. 77. Объём и скоростьЧисло запросов в день, пик, ожидаемое время ответа, лимиты.
8. 88. Ошибки и повторыЧто означает каждая ошибка, когда повторять, кто получает уведомление.
9. 99. Журнал и аудитЧто записывается, сколько хранится, кто может смотреть.
10. 1010. Тестирование и приёмкаТестовая среда, тестовые сценарии, критерии «готово».
11. 1111. Запуск и откатЭтапы, дата переключения, как остановить при проблеме.
12. 1212. Контакты и поддержкаКому писать, срок ответа, дежурства.

Как писать бизнес-сценарий

Сценарий пишется по шагам, без технического языка, и на каждом шаге понятно «кто» и «что». Для каждого сценария напишите три варианта: обычный случай, альтернативный (например, клиент уже есть в CRM) и случай ошибки (CRM не отвечает). Случай ошибки забывают чаще всего — и именно он потом создаёт больше всего проблем.

Раздел интерфейсов: нужны примеры

Назвать эндпоинт недостаточно. Для каждого интерфейса добавьте реальный (обезличенный) пример запроса и ответа: какие поля отправляются, какие обязательны, в каком формате ответ, как выглядит ошибка. Документ без примеров ведёт к тому, что две команды понимают одно слово по-разному. Саму карту полей держите в отдельном документе — её формат показан в статье о маппинге полей CRM.

Раздел безопасности

• Ключ или токен: где хранится (не в коде), кто видит, как часто меняется.
• Минимальные права: пользователь интеграции имеет доступ только к нужным объектам и операциям.
• Сеть: ограничение по IP, только HTTPS.
• Персональные данные: какие поля передаются и зачем; ненужное не отправляется.
• Если AI вызывает инструмент: к каким URL он может обращаться и что может менять.

Объём, скорость и лимиты

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

Тестирование и приёмка

1. 1Тестовая средаБез живых данных, но с реальной структурой.
2. 2Список сценариевОбычный, альтернативный и ошибочный вариант каждого бизнес-сценария.
3. 3Критерии приёмкиИзмеримые: время, результат, поведение при ошибке.
4. 4ПодписьБизнес-владелец и технический владелец письменно подтверждают приёмку.

Заполненный пример: один сценарий

Это иллюстративный пример. Сценарий: «Клиент спрашивает в чате статус заказа». Обычный случай: AI спрашивает номер заказа, вызывает эндпоинт чтения системы заказов и сообщает статус. Альтернативный: номер не найден — AI просит проверить номер, при второй неудаче передаёт оператору. Ошибка: API не отвечает 5 секунд — AI говорит клиенту, что сейчас не может проверить статус, и оператору уходит уведомление. Критерий приёмки: ожидаемое поведение во всех 20 запросах в тестовой среде.

Типичные ошибки

• Описывать только «счастливый путь» — нет случаев ошибок.
• Не писать критерии приёмки — проект никогда не «заканчивается».
• Откладывать вопрос хранения ключей.
• Не записывать объёмы и лимиты.
• Написать документ один раз и не фиксировать изменения.

Ограничения

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

Интеграция с Vexvon

При интеграции с Vexvon компания предоставляет AI собственный API как инструмент и сама пишет, когда его вызывать, — например, «когда клиент спрашивает о статусе заказа»; вызовы инструментов защищены от SSRF. В обратную сторону события вроде нового лида, завершённого звонка и смены статуса отправляются в систему компании через webhook. Каналы подключаются через официальные API без передачи паролей. Для крупных компаний мы заполняем анкету безопасности и подписываем NDA. Подробнее — интеграции и безопасность.

Следующий шаг

Откройте двенадцать разделов как пустой шаблон и заполните первые два — цель и сценарии — вместе с бизнес-владельцем. Остальное техническая команда выведет из них. Общая концепция — в статье о корпоративной интеграции AI, архитектура чат-бота — в статье об интеграции чат-бота через API и webhook. Другие статьи — в разделе о корпоративной интеграции; документ можно разобрать вместе во время демо.