Как устроена интеграция сайта через API

Интеграция сайта через API — это обмен данными и командами по правилам, которые понимают обе системы. Например, сайт передаёт заказ, а учётная система сообщает, что приняла его. Владельцу бизнеса важно понимать, какое действие считается завершённым, кто отвечает за данные и что произойдёт, если ответ не придёт.

Наличие API ещё не означает, что нужный процесс можно автоматизировать. В нём может не быть операции отмены, поиска по номеру сайта или доступа к нужным полям. Поэтому до разработки проверяют возможности конкретного сервиса и согласуют поведение обмена.

Что именно связывает API

API — программный интерфейс: определённый набор доступных операций и правил обращения к ним. Сайт отправляет запрос, внешняя система проверяет его и возвращает ответ. В ответе могут быть данные, подтверждение действия или причина отказа.

У запроса есть несколько смысловых частей: какую операцию выполнить, над каким объектом, с какими данными и от чьего имени. У ответа — своё значение. «Сообщение получено», «заказ создан» и «заказ готов к выдаче» обозначают разные этапы бизнеса. Интеграция должна сохранять это различие.

Сам обмен может работать в фоне. Покупатель не обязан ждать завершения всех внешних действий на странице, если бизнес допускает отложенную обработку. Но сайт должен честно показывать текущий результат: например, заказ сохранён и ожидает подтверждения. Допустимость такого состояния определяет заказчик.

Учебный пример: передать заказ и подтвердить приём

Рассмотрим условный интернет-магазин и условную учётную систему. Это учебный сценарий, а не описание клиента, действующей интеграции или возможностей конкретного продукта. Его правила нужно явно согласовать перед применением в реальном проекте.

В примере сайт сохраняет заказ и отдельно передаёт его состав в учётную систему. Та создаёт свою запись и возвращает идентификатор. Приём заказа не означает оплату, наличие товара или готовность к выдаче. Эти действия в пример не входят. Персональные данные также не передаются.

Чтобы пример работал, принимающая сторона должна поддерживать защиту от повторного создания одной операции и проверку её результата. В реальном сервисе такую возможность сначала подтверждают документацией и испытанием. Если её нет, порядок восстановления будет другим.

Сначала договориться о данных

Договор формата описывает не только названия полей. Он фиксирует их смысл, обязательность, допустимые значения и реакцию на ошибку.

Условное сообщение в формате JSON может выглядеть так:

{
    "contract_version": "demo-v1",
    "operation_id": "demo-create-order-17",
    "site_order_id": "DEMO-17",
    "items": [
        {
            "product_code": "DEMO-CUP",
            "quantity": 2
        }
    ]
}

Все значения здесь придуманы для обучения. Это пример данных, без адреса сервиса, ключа доступа и команды отправки. Название operation_id выбрано для объяснения; чужой API может использовать другой механизм. Само наличие такого поля не защищает от дублей: принимающая система должна обрабатывать его по согласованным правилам.

Отдельно фиксируют изменение договора. Например, замена штук на упаковки требует согласования единиц, а не только переименования поля. Исполнитель должен знать, как обе стороны перейдут на новый формат и что делать с ещё не отправленными сообщениями старого формата.

Назначить источник истины

Для каждого вида данных определяют, где находится основная запись и кто вправе её менять. В нашем примере сайт отвечает за первоначальный состав заказа, а учётная система — за факт его приёма. Сайт хранит подтверждение, но не придумывает его при отсутствии ответа.

Если заказ уже передан, изменение его состава нельзя безоговорочно считать обычной правкой страницы. Нужно согласовать отдельную операцию изменения, допустимый этап и поведение при конфликте. Иначе позднее сообщение может вернуть старый состав поверх нового. Сравнение версий записи и правила перехода между состояниями помогают отличить актуальное действие от устаревшего.

Права доступа и проверка данных

Доступ к API включает два вопроса: кто обращается и что ему разрешено. В учебном сценарии интеграции достаточно создавать заказы и проверять их приём. Право удалять весь каталог или управлять пользователями для этой задачи не требуется. Если сервис не позволяет выдать достаточно узкие права, это ограничение нужно оценить до подключения.

Секретный ключ внешней системы хранят на сервере в защищённых настройках, с ограниченным доступом. Его не встраивают в общедоступный JavaScript, не сохраняют в публичном репозитории и не записывают открытым текстом в журнал ошибок. Для проверки и рабочего обмена используют отдельные доступы. Заранее определяют, кто сможет отозвать или заменить скомпрометированный ключ. Соединение защищают HTTPS и проверкой сертификата.

Валидация — это проверка данных до того, как они повлияют на заказ. В нашем примере обе стороны проверяют обязательные поля, типы, размер сообщения, код товара и количество. Сервер сайта проверяет содержимое корзины: данные браузера нельзя считать достоверными только потому, что форма выглядит правильно.

Ответ внешней системы тоже проверяют. Неожиданная структура, незнакомое состояние или идентификатор другого заказа требуют разбирательства. Подставлять значение по умолчанию и считать обмен успешным опасно. Для владельца это означает конкретный запрос к исполнителю: показать, как интеграция ведёт себя с ошибочными данными с обеих сторон.

Почему таймаут не равен отказу

Таймаут ограничивает время ожидания ответа. Он нужен, чтобы зависший внешний запрос не удерживал ресурсы сайта бесконечно. Но истечение ожидания не сообщает, успела ли другая система выполнить действие.

В учебном примере учётная система могла создать заказ, после чего связь оборвалась. На сайте подтверждения нет, а во внешней системе запись уже существует. Если просто отправить создание ещё раз, без защиты от повторов, можно получить два заказа.

Поэтому для одной операции сохраняют стабильный идентификатор. При повторе отправляют те же данные с тем же идентификатором; принимающая сторона распознаёт повтор согласно своему договору. Это свойство называют идемпотентностью: повтор одной операции имеет тот же предполагаемый эффект, что и однократное выполнение.

У защиты есть границы: срок хранения идентификатора, область его уникальности, поведение при одновременных запросах и при изменении данных. Их выясняют у конкретного API. Новый идентификатор для каждой попытки разрушает связь с исходной операцией. После окончания срока защиты повтор также может снова создать запись.

Если результат неизвестен, сначала используют доступный механизм сверки. При отсутствии безопасного повтора и надёжной проверки операция требует ручного решения. Повтор запросов, меняющих данные, нельзя включать одинаково для всех ошибок и всех сервисов.

Как разбирать ответы и внешние сбои

В API через HTTP код ответа помогает определить класс ситуации, но бизнес-результат зависит от договора операции. Например, 202 означает приём в обработку, которая ещё не завершилась. Его нельзя автоматически приравнять к подтверждённому созданию заказа.

Количество попыток и их общий срок ограничивают. Интервалы между попытками можно увеличивать и разносить во времени, чтобы множество заказов не обрушилось на восстанавливающийся сервис одновременно. После исчерпания допустимых попыток нужен заметный статус и ответственный за разбор, а не бесконечное ожидание.

Лимиты учитывают ещё при планировании: они могут зависеть от операции и выданного доступа. Фоновый обмен распределяет нагрузку, но не отменяет эти ограничения. Если заказов становится больше, чем интеграция успевает передавать, очередь растёт. Поэтому контролируют не только ошибки, но и возраст самого старого неподтверждённого заказа.

Что сохранять на сайте и как восстановить обмен

В учебном сценарии сохранение заказа и задания на его передачу должно происходить вместе в локальной транзакции. Иначе между этими действиями возможен сбой: заказ останется, а система не узнает, что его нужно отправить. Фоновый обработчик затем выполняет передачу и записывает результат. Такой подход называют transactional outbox — сохранённое исходящее сообщение.

Это решает локальную проблему записи задания, но не гарантирует успех внешней операции. Всё ещё нужны защита от дублей, работающий обработчик и контроль неотправленных сообщений. После перезапуска обработчик должен находить незавершённые задания; два обработчика не должны произвольно создавать один и тот же заказ дважды.

Для диагностики полезны номер заказа, идентификатор операции, время попытки, безопасный код причины и последнее подтверждённое состояние. Секреты и полное содержимое с персональными данными в такой журнал не добавляют. Владельцу нужен доступный список проблемных операций: что задержалось, что отклонено и что требует сверки. Пользовательское сообщение об ошибке не должно раскрывать внутренние технические данные.

Когда нужен повтор, а когда компенсация

Повтор пытается завершить исходное действие. Компенсация исправляет последствия уже выполненного действия по бизнес-правилам.

Допустим, условный заказ принят, но покупатель затем отменил его. Удаление локальной записи не отменяет внешнюю. Если API поддерживает отмену и заказ ещё можно отменить, интеграция выполняет отдельную операцию, фиксирует её результат и учитывает одновременные изменения. Если нужной операции нет или обработка зашла слишком далеко, решение принимает ответственный сотрудник.

Это отдельное расширение учебного сценария, которое требует согласования. Нельзя автоматически отменять заказ только из-за отсутствия ответа: сначала нужно выяснить его состояние. Сама компенсация тоже может завершиться сбоем. Для неё нужны сохранённый ход выполнения, безопасный повтор там, где он поддерживается, и порядок ручного восстановления.

Что проверить до запуска

Попросите исполнителя показать обмен в тестовой среде на согласованных сценариях:

• Корректный заказ принимается, его записи можно сопоставить в обеих системах.
• Неизвестный товар и неправильное количество не превращаются в молча исправленный заказ.
• Потеря ответа после создания не приводит к дублю при восстановлении.
• Две одновременные попытки передачи одной операции не нарушают согласованную защиту.
• Ограничение частоты и недоступность сервиса дают контролируемое ожидание, а затем понятное действие.
• Перезапуск обработчика сохраняет возможность найти и завершить неподтверждённые задания.
• Отзыв доступа останавливает обмен без раскрытия ключа в сообщении или журнале.
• Оператор видит проблемный заказ и понимает, можно ли повторить его автоматически или нужна сверка.

Для обсуждения интеграции сайта подготовьте документацию API, список операций и полей, правила изменения данных, допустимую задержку и ответственного за сбои. Это позволит проверить выполнимость процесса до начала разработки.

Если обмен входит в новый проект со своей бизнес-логикой, его стоит учитывать при проектировании сайта на Laravel: где хранятся состояния, как запускается фоновая обработка и как поддерживается договор с внешней системой. Выбор платформы сам по себе не решает эти вопросы — они становятся частью требований, реализации и приёмки.