Интеграции · Практический разбор
Интеграция ЭДО с CRM: события, статусы и защита от дублей
Как разделить ответственность систем, спроектировать события и вернуть финальный статус документа в сделку.
Коротко
Что важно забрать в работу
- 01До кода нужно определить источник истины по каждому полю и статусу.
- 02Команды и события должны иметь стабильные идентификаторы и безопасно повторяться.
- 03Вебхук — уведомление о факте, а не безусловное доверие всем присланным данным.
Разделите ответственность систем
CRM обычно хранит сделку, клиента и коммерческий контекст, а документный контур — файл, версии, этапы и решения. Для каждого поля зафиксируйте владельца: где его создают, кто может изменить и куда возвращается результат.
Не пытайтесь синхронизировать всё в обе стороны. Минимальный пилот может передавать идентификатор сделки и документ на входе, а финальный статус, ссылку и причину возврата — на выходе.
Команда и событие — не одно и то же
Команда просит систему выполнить действие: создать процесс или добавить версию. Событие сообщает, что факт уже произошёл: этап завершён или документ возвращён. Разделение упрощает повторные попытки и расследование ошибок.
Каждая операция получает стабильный идентификатор. Если CRM повторит запрос после тайм-аута, АА.Докс вернёт прежний результат, а не создаст второй процесс.
Безопасный вебхук
- 01HTTPS и отдельный секрет для конкретной подписки;
- 02подпись тела сообщения и проверка времени запроса;
- 03идентификатор события для дедупликации;
- 04быстрый подтверждающий ответ и фоновая обработка;
- 05повторные попытки с ограничением и журналом доставки;
- 06возможность повторно запросить актуальное состояние через API.
Контракт интеграции и наблюдение
Опишите схему полезной нагрузки, допустимые статусы, версию контракта, ошибки и поведение при неизвестном поле. Добавьте контрольный сценарий: CRM недоступна, вебхук пришёл дважды, документ возвращён, идентификатор сделки не найден.
В эксплуатации нужны метрики очереди, возраста недоставленного события и доли ошибок по типу. Пользователь должен видеть, что бизнес-решение принято, даже если внешний статус ещё доставляется.
Методика и границы
На чём основан материал
Рекомендации основаны на общих протоколах HTTP, подписи сообщений и событийной интеграции. Конкретная схема зависит от API вашей CRM и требований инфраструктуры.
Источники
- RFC 9110: HTTP Semantics
Семантика HTTP-методов, статусов и повторяемости запросов.
- RFC 2104: HMAC
Стандарт механизма проверки целостности сообщения с секретным ключом.
- CloudEvents
Открытая спецификация общего формата описания событий.
FAQ
Частые вопросы
Что лучше: опрос API или вебхуки?
Вебхуки быстрее сообщают о событии, но требуют повторов и проверки подписи. Периодический опрос проще восстановить. Надёжная схема часто использует вебхук как сигнал и API как способ сверить состояние.
Где хранить файл?
Нужно выбрать единственный источник оригинала и передавать ссылку или копию по утверждённому правилу. Две независимые изменяемые копии быстро создают конфликт версий.
Как версионировать контракт API?
Изменения, ломающие совместимость, вводятся как новая версия. Добавление необязательного поля можно делать совместимо, если потребители готовы игнорировать неизвестные поля.