Интерфейс для программы
Через API одна программа запрашивает у другой данные или поручает действие: прочитать справочник, создать заявку, проверить заказ. Документация определяет доступные операции, параметры запроса и ответы. Внутреннее устройство сервиса при этом может оставаться неизвестным его пользователю.
Пример: заявка на ремонт
Представим вымышленную управляющую компанию. Житель заполняет форму, а обращение должно появиться в системе выездных работ вместе с адресом и фотографией. Наличие API у обеих сторон выглядит достаточным. Однако выясняется, что принимающая система создаёт только текстовую карточку, а вложения загружаются отдельной операцией.
Интеграция теперь должна связать два шага и показать, что делать, если первый успешен, а второй нет. Иначе диспетчер получит неполную заявку, а житель — уверенное сообщение об отправке. Обещание интеграции стоит оценивать по завершённой карточке, которую реально может использовать исполнитель.
Договор касается смысла данных
Совпадающие названия полей не гарантируют одинакового содержания. Адрес может быть свободным текстом или ссылкой на справочник, дата — местным временем или временем с указанным поясом, статус — внутренним этапом конкретной команды. Нужно определить преобразования и случаи, когда сведения нельзя корректно перенести.
Полезно взять несколько типовых записей и одну пограничную: неполный адрес, неизвестную категорию или большой файл. Для каждой заранее опишите ожидаемый результат. Это превращает разговор о совместимости в проверку: какие сведения сохраняются, какие преобразуются и что оператор увидит при невозможности переноса.
Ответ не пришёл — действие могло выполниться
Если соединение оборвалось после отправки запроса, отправитель может не знать, успела ли система создать заявку. Слепое повторение способно породить дубликат. Идемпотентность означает, что повтор одинаковой операции сохраняет тот же предполагаемый эффект; MDN отдельно объясняет это свойство. Оно не возникает автоматически у любого запроса.
Способ защиты уточняют в документации конкретного API: предусмотрен ли ключ повторной операции, поиск по внешнему идентификатору или другой механизм. В учебном примере важно получить одну заявку и восстановить её номер после неопределённого ответа. Простое сообщение «сеть недоступна» не решает этот вопрос.
Ограничения становятся частью процесса
Лимит запросов, размер файлов, доступность отдельных полей и срок жизни полномочий влияют на работу после запуска. Если загрузку большой очереди не продумали, интеграция может успешно проходить демонстрацию на одной записи и останавливаться при накоплении заявок. Поэтому проверять нужно и нормальную нагрузку, и возврат после перерыва.
Разделите техническую ошибку и отказ по содержанию. Временную недоступность иногда можно обработать повтором; неверный адрес требует исправления данных. Оператору нужны различимые состояния и возможность продолжить работу после устранения причины, сохранив связь с исходной записью.
Как принять интеграцию
Попросите показать путь одной заявки от формы до рабочей карточки, затем воспроизвести повторную отправку и согласованный сбой загрузки вложения. Проверьте, где хранится связь записей, кто замечает незавершённый перенос и как восстанавливается процесс. Эти вопросы выявляют трудности, которые скрывает успешный запрос в демонстрации.
