API:
как связать
системы

Что такое API простыми словами

API — программный интерфейс: правила, по которым один программный компонент обращается к другому. В правилах описано, какие действия доступны, что нужно передать и какой ответ можно получить. Аббревиатура раскрывается как Application Programming Interface. Человек нажимает кнопку в приложении, а программа может вызвать API, чтобы выполнить нужное действие.

Представьте сайт с заявками на поставку оборудования. Посетитель заполняет форму. Сервер сайта проверяет данные и обращается к CRM: «Создай обращение с такими полями». CRM возвращает идентификатор записи или сообщение об ошибке. Менеджеру не приходится переносить каждую заявку вручную. Но этот обмен заработает только после настройки: наличие API у CRM ещё не означает, что сайт уже с ней связан.

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

Как работает запрос к API

В обычном HTTP-обмене есть клиент — программа, которая обращается за данными или действием, — и сервер, который принимает запрос. Клиентом здесь может быть сервер вашего сайта, а не браузер посетителя. Одна система в разных ситуациях способна выступать в обеих ролях.

У запроса обычно есть адрес, метод, заголовки и, если требуется, тело с данными. Адрес конкретной операции называют конечной точкой, или endpoint. Метод помогает определить действие. Заголовки могут сообщать формат и сведения для доступа. Тело содержит передаваемый объект, например поля обращения. Набор обязательных элементов определяется документацией конкретного API.

Адрес example.com здесь условный: это схема для объяснения, а не команда для подключения вашей CRM. Даже одинаковая по смыслу операция в двух сервисах может иметь разные поля и правила.

Посмотрите настоящий ответ API без программирования

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

1. Откройте публичный адрес примера в браузере.
2. Найдите поле full_name: оно обозначает владельца и название репозитория.
3. Посмотрите private: логическое значение false означает, что репозиторий не закрытый.
4. Сравните адрес API с html_url: второй ведёт на обычную страницу для человека.

{
  "name": "Hello-World",
  "full_name": "octocat/Hello-World",
  "private": false,
  "html_url": "https://github.com/octocat/Hello-World"
}

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

Как увидеть код ответа в Postman

В клиенте Postman откройте новый HTTP-запрос через Add, выберите GET, вставьте тот же URL и нажмите Send. В нижней области проверьте статус и тело ответа. Для этого публичного примера не добавляйте секреты своей компании. Кнопки и расположение панелей зависят от версии приложения.

Для последующей работы с GitHub изучите официальное руководство по REST API: там описаны методы, параметры, заголовки и доступ. Наш пример показывает только чтение открытого объекта. Он не подтверждает, что интеграция с вашей CRM или системой оплаты настроена.

REST, JSON, вебхук и SDK: что с чем сравнивать

Эти слова описывают разные части решения. JSON — формат данных. REST — архитектурный стиль. Вебхук — способ уведомить другую систему о событии. SDK — комплект средств для разработчика, который может упростить использование API. Их не нужно выбирать как взаимоисключающие альтернативы.

Веб-API может использовать HTTP и JSON, но не всякий такой интерфейс полностью следует принципам REST. Также встречаются SOAP, удалённые вызовы процедур и другие подходы. Для заказчика важнее наличие нужных операций, документации и поддержки, чем современное название технологии. Обзор вариантов есть в материале AWS об API.

Опрос по расписанию и уведомление о событии

При опросе интеграция регулярно спрашивает: «Что изменилось после предыдущей проверки?» При вебхуке источник сам отправляет уведомление на согласованный адрес: «Заказ изменился». Это уменьшает ожидание и число пустых запросов, но не отменяет обработку ошибок.

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

Для чего API нужен сайту и компании

Начинайте с конкретного ручного действия или потери данных. «Подключить все системы» не определяет результат проекта. Полезная формулировка: «Каждая подтверждённая заявка сайта появляется в нужной воронке CRM, имеет источник и ответственного; непереданные заявки видны в журнале».

Это варианты применения, а не обещание поддержки любого поля выбранным сервисом. У некоторых продуктов API доступен только на определённом тарифе или покрывает лишь часть возможностей интерфейса. Предварительное обследование входит в задачи внедрения CRM, разработки сайта и создания AI-агентов.

Что проверить в документации и задании

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

• Системы и объекты. Какая CRM, какая версия сайта, что считается заявкой, заказом или клиентом.
• Направление. Только сайт → CRM либо ещё обратное изменение статусов. Двусторонний обмен требует правил разрешения конфликтов.
• Источник истины. Где редактируется цена и какой системе верить при расхождении.
• Поля и справочники. Соответствие названий, обязательность, типы, допустимые значения, валюта и часовой пояс.
• Момент обмена. Сразу после события, по расписанию или вручную; допустимая задержка.
• Объём. Обычная нагрузка, пиковый поток и первоначальная выгрузка накопленных записей.
• Ошибки. Что повторяется автоматически, что попадает ответственному и как восстанавливается очередь.
• Эксплуатация. Владелец доступов, документации и поддержки после запуска.

При выдаче списков проверьте пагинацию — разбиение результата на страницы. Успешно получить первые 100 записей не значит выгрузить все 8 000. Для обмена изменениями нужны контрольные отметки и понятный способ повторить пропущенный промежуток. Конкретные параметры берутся из документации поставщика.

Что означают ошибки API

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

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

Отдельный случай — браузер блокирует чтение ответа из-за CORS. Это ограничение доступа между источниками, а не доказательство, что API недоступен всем клиентам. Способ подключения должен проверить разработчик. Отключение защиты браузера у посетителей не является исправлением интеграции.

Почему один успешный запрос ещё ничего не гарантирует

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

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

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

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

Как обращаться с ключами и правами

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

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

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

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

Как принять интеграцию у разработчика

Попросите показать полный путь одного тестового объекта. Для заявки это форма, сохранение на сайте, передача, карточка CRM и назначение ответственного. Сверьте значения в конечной системе. Уведомление в браузере и строка HTTP 200 не заменяют этой проверки.

В акте проверки фиксируйте конкретные идентификаторы тестовых объектов, дату, результат и оставшиеся замечания. Числовые требования — допустимая задержка, объём и время восстановления — согласуют для проекта заранее. Универсального «API должно отвечать за одну секунду» для всех операций нет.

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

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

Частые вопросы об API