API-интеграция — обмен данными и действиями между программами по согласованным правилам. Пользователь меняет карточку, а в другом приложении создаётся связанная запись; сайт передаёт заказ внутренней системе. Видимый результат может быть простым, но правила связи определяются заранее.
Для разработки API и интеграций недостаточно вопроса о возможности подключения. Основной источник, ответственность за ошибки и результат повторного запроса тоже входят в работу.
Выберите основной источник данных
Если телефон клиента меняют в обоих приложениях, какое правило определит итог? Последнее изменение, утверждённое изменение и данные главной системы — разные решения. Фраза «двусторонняя синхронизация» не устраняет конфликт автоматически.
Условный пример: магазин передаёт заказ бизнес-программе, а склад возвращает наличие. Источники заказа и остатков здесь разные. Владельца каждого поля нужно записать, иначе запоздавший ответ может заменить новое старым.
Определите границы операции
Создание заказа способно включать клиента, товары и адрес. Нужно согласовать поведение, если другая сторона приняла только часть. Успешный HTTP-ответ не обязательно означает завершение всего бизнес-процесса.
- Передаваемые поля и их смысл.
- Обязательные и пустые значения.
- Соответствие идентификаторов источника и получателя.
- Форматы дат, единиц и валют.
- Ответ, обозначающий завершение.
Доступ и разрешения
Ключ интеграции должен разрешать необходимые действия. Передача всего административного доступа через аккаунт клиента или партнёра создаёт избыточные полномочия. Нужны порядок замены и закрытия ключа.
Руководство OWASP по REST рассматривает HTTPS, контроль доступа и проверку входных данных. В проекте технический контроль согласуется с бизнес-моделью ролей и разрешений.
Что происходит при разрыве связи?
Запрос может быть отправлен без получения ответа. Тогда неизвестно, выполнила ли другая сторона операцию. Прежде чем предложить повтор, нужно выяснить, не создаст ли он вторую такую же запись.
Разные операции по-разному переносят повторение. Система может распознавать повторный запрос по согласованному идентификатору или иному механизму. До выбора реализации определяют бизнес-результат: сколько раз допустимо создавать заказ и какие состояния требуют отдельной проверки.
Как объяснять ошибки пользователю?
Сообщения «возникла ошибка» недостаточно для работы. Пользователь должен понимать, что исправить, сохранена ли операция и куда обратиться. Технический журнал может содержать идентификатор для поиска, не записывая лишние секреты и личные сведения.
Нужно видеть и состояние обмена. Если последнее обновление давно устарело, остаток и статус нельзя без пояснения представлять текущими. Ожидание операции отличается от окончательной ошибки.
Тестовая среда и приёмка
- Успешный обмен с полными данными.
- Отсутствующее обязательное поле.
- Неверный или закрытый ключ.
- Задержка другой стороны.
- Отправка одного запроса дважды.
- Частично принятая сложная операция.
Проверки полезны не только при первом подключении, но и после изменений партнёра. Возможности и ограничения внешнего сервиса не находятся под полным контролем вашего приложения. Эта граница должна быть понятна в правилах поддержки.
Пример повторного получения одного события
Представим, что партнёрская система повторно передала уведомление об операции. Во второй отправке не следует создавать новый заказ, если бизнес-событие то же самое. Идентификатор распознавания согласуют заранее.
Журналу недостаточно сообщать о получении ответа. Полезны разные состояния: принято, уже обработано, ожидает или содержит противоречие. От них зависит действие поддержки. Секретные ключи при этом не отображаются открыто.
- Повторите событие с тем же идентификатором.
- Проверьте отсутствие второго заказа.
- Сравните, не объединяются ли разные события.
- Оцените понятность ожидания пользователю.
Конкретный технический механизм не объявляется универсальным. Определяется приёмочный результат: повторная связь не превращается в повторную бизнес-операцию. Документы другой стороны показывают доступные средства.
Сложнее ситуация, когда первый запрос принят, а ответ потерян. Команда должна отличать неизвестный результат от явного отказа. Для проверки можно временно смоделировать отсутствие ответа и затем запросить состояние согласованным способом. Не следует считать каждую задержку доказательством неудачи и безусловно повторять действие. Именно такие сценарии позволяют оценивать надёжность обмена, а не только красивый успешный пример.
Назначьте владельца связи с партнёром. Если доступ отозван или документация изменилась, технической команде нужен понятный путь уточнения. Ответственность за внешний аккаунт и за собственный код различается; это следует записать до запуска, а не выяснять только после остановки обмена.
Частые вопросы
Достаточно ли наличия API?
Нет. Могут потребоваться разрешения аккаунта, подходящие условия, тестирование и совместимость данных.
Почему цена интеграции различается?
На объём влияют отношения данных, ошибки и возможности другой стороны. Это связано и с бюджетом CRM.
166 Cargo присутствует в портфолио как пример заказных и документных операций. Для своей связи рассмотрите вместе планирование PHP/Laravel API и процесс заказа.
