ПРАКТИЧЕСКОЕ РУКОВОДСТВО / API-интеграции
Как описать API-интеграцию и проверить обмен данными
Контракт обмена между системами: сущности, направление, дубли, сбои и проверка перед запуском.
КОРОТКИЙ ОТВЕТ
Что согласовать до разработки API-интеграции?
Для каждого события опишите отправителя, получателя, поля и правило обновления. Затем разберите три ситуации: успешную передачу, повтор запроса и временный сбой. Эти правила определяют, как избежать дублей и восстановить обмен.
01 / ПОДГОТОВКА
Что собрать до начала работы
Выберите сущности и операции: создание клиента, изменение заказа, передача статуса или другое действие. Для каждого поля укажите формат, обязательность, источник и правило заполнения, если значение отсутствует.
Определите направление синхронизации и конфликт изменений. Если обе системы могут редактировать одно поле, заранее выберите правило приоритета или процедуру ручного разбора. Иначе данные начнут перезаписывать друг друга.
Согласуйте ключ уникальности и защиту от повторной обработки. Идентификатор события и бизнес-идентификатор заказа решают разные задачи. Проверьте, как повтор запроса влияет на создание сущности.
Определите допустимую задержку, журнал ошибок и ответственного за инцидент. Доступы должны храниться на сервере; секреты не публикуются в браузерном коде, документации или журнале запросов.
02 / РЕШЕНИЕ
Как выбрать подход
| Ваша ситуация | С чего начать |
|---|---|
| Нужна реакция на изменение | Проверьте события и вебхуки, затем механизм повторов. |
| Нужна периодическая сверка | Согласуйте окно синхронизации и обработку изменений. |
| Открытого API недостаточно | Сначала исследуйте допустимые способы обмена, затем оцените объём. |
03 / ПРОВЕРКА
Как понять, что результат готов
Один и тот же запрос дважды не создаёт нежелательный дубль.
После временного сбоя обмен восстанавливается по согласованному сценарию.
Ошибку можно найти по безопасному идентификатору, а записи можно сверить между системами.
04 / ЧАСТЫЕ ОШИБКИ
На что обратить внимание
- Считать HTTP 200 подтверждением правильного бизнес-результата.
- Повторять запросы бесконечно без задержек и ограничения попыток.
- Хранить доступы в клиентском JavaScript или записывать секреты в логи.
ПРИМЕР ИЗ ПРАКТИКИ
В кейсе Sunflo TuneCRM разработала связку с 1С и маршрутизацию заказов. Здесь важно не просто создать заявку, но и передать её правильному исполнителю с учётом точки сборки.
Проекты TuneCRM ↗Официальные источники
Возможности конкретного аккаунта и условия платформ проверяются перед началом работ.