До разработки интеграции договорись не только о URL и списке полей, но и о том, какое событие запускает передачу, кто отвечает за смысл каждого поля, что считается успехом и как обнаруживается потерянная или повторная запись. OpenAPI описывает интерфейс HTTP API так, чтобы люди и инструменты понимали доступные операции и форматы; сам документ не доказывает, что бизнес-семантика корректна или что интеграция уже работает. OpenAPI Specification 3.2.1.
Учебный маршрут: форма сайта → CRM
Ниже учебный контракт для тестовой заявки, без настоящих персональных данных:
| Слой | Что зафиксировать в scope |
|---|---|
| Source | Форма сайта; конкретное событие form_submitted; владелец формы — бизнес-команда |
| Trigger | Отправка после успешной серверной валидации; определить, отправляет ли повторный клик второй запрос |
| Payload | submission_id, created_at, consent_status, topic, contact_placeholder; формат времени и допустимые значения задаются сторонами |
| Destination | CRM и конкретный объект/статус; кто владеет полями и маппингом |
| Success | CRM вернула ожидаемый ID/статус, сайт записал результат и можно найти запись для сверки |
| Failure | timeout, HTTP error, невалидное поле, нет согласия, дубликат; владелец ошибки и очередь ручной проверки определены |
| Security | способ авторизации, ротация ключа, среда тест/production и лицо, которому принадлежит секрет |
contact_placeholder здесь — только название поля, не действующий адрес. Реальные значения и приватные токены в статье не нужны.
Пример поведения при timeout
Предположим, сайт отправил тестовую заявку, но ответ CRM задержался и клиентская сторона получила timeout. Из этого ещё нельзя заключить, что CRM не создала запись: сервер мог выполнить запрос, а ответ потерялся по пути. Если сайт автоматически повторит запрос без правила идемпотентности, может появиться дубль.
До разработки запиши конкретные решения:
- Есть ли стабильный
submission_id/idempotency key и кто его создаёт? - Как получатель распознаёт повтор того же события?
- Что сайт показывает человеку, если подтверждение не пришло?
- Где сотрудник ищет запись и повторяет/сверяет операцию безопасно?
- Кто расследует рассинхронизацию и в какой системе лежит журнал?
Точные имена headers, форматы ответов, retry policy и статус-коды определяются документацией реальных API. Не копируй поля примера как готовую спецификацию без проверки API поставщиков.
Согласуй границы ответственности
Поставщик сайта может отвечать за отправку согласованного payload; поставщик CRM — за приём и сохранение; бизнес — за определения lead, согласия и маршрута обработки. Но границы должны соответствовать договору и реальной архитектуре. Укажи, кто владелец каждого поля, кто меняет его формат, кто уведомляет при изменении API и кто проверяет reconciliation.
Проверь сценарии: успешный запрос, timeout после возможной записи, повторная отправка, неизвестное значение поля, отсутствующее согласие, отзыв/изменение статуса и отключённый destination. Для каждого укажи ожидаемый результат и артефакт проверки. OpenAPI может документировать endpoint, schema и ответы, но не заменяет бизнесовые определения и проверку реального потока.
Что должно остаться в контракте
Перед началом работ у команды есть карта source → trigger → payload → destination → response/failure, владельцы данных и систем, тестовые случаи, правила повтора и ручная сверка. Всё, что неизвестно, помечено блокером, а не заполнено предположением. API-документ, тестовая успешная передача или HTTP 200 отдельно не доказывают готовность всей интеграции.
Если нужна оценка конкретной реализации, смотри текущую страницу KCODE / Разработка; сначала согласуй объём и ответственность за исключения.
За пределами самой передачи данных остаётся сопровождение после запуска: заранее назначь того, кто получает уведомление о сбое и проверяет восстановление.
