Что такое API: как программы обмениваются данными

API простыми словами: договор между программами

API, Application Programming Interface, — интерфейс программирования приложений: набор правил, по которым одна программа использует возможности другой. Он описывает доступные операции, входные данные, результат и ошибки. Это может быть интерфейс библиотеки внутри компьютера или удалённого сервиса; API не обязательно работает через Интернет.

В бизнесе чаще обсуждают веб-API: сайт передаёт заказ в учётную систему, CRM узнаёт остатки, служба доставки возвращает статус. Сотруднику не нужно вручную переносить каждую строку между окнами. Но наличие API ещё не означает, что обмен уже настроен: нужны сопоставление данных, права и обработка сбоев.

• Меньше ручного ввода: заказ переходит между системами автоматически.
• Быстрее актуализация: остатки и статусы обновляются по согласованному правилу.
• Проверяемый результат: известно, какой объект создан и где искать ошибку.
• Управляемый доступ: интеграции можно разрешить отдельные операции.

Пример: CRM передаёт заказ в 1С

Менеджер создаёт заказ CRM-1001. Интеграция проверяет обязательные поля, находит соответствие контрагента и номенклатуры, отправляет запрос в учётную систему. Полученный внутренний идентификатор сохраняется в CRM. Повторная доставка должна узнавать уже обработанный заказ.

Заранее решают, кто владеет каждым полем: цена из CRM или прайс из 1С, остаток склада или витрины, окончательный статус оплаты. Иначе два исправно работающих интерфейса начнут перезаписывать изменения друг друга. Факт доставки JSON не равен корректному проведению документа.

Для 1С могут применяться HTTP-сервисы, веб-сервисы, OData и другие поддерживаемые механизмы. Выбор зависит от конфигурации, расширений, версии платформы и требований. Нельзя обещать одинаковый готовый endpoint для любой установленной 1С. Прямое изменение таблиц СУБД не является универсальной заменой штатному интерфейсу. Подготовку веб-контура разбираем отдельно: публикация 1С на IIS и Apache с HTTPS.

Из чего состоит HTTP-запрос

• Endpoint: адрес операции, например /api/orders.
• Метод: какое действие запрашивается — GET, POST и другие.
• Параметры: идентификатор в пути, фильтр в query или поля в теле.
• Заголовки: формат, токен и служебные признаки по контракту.
• Тело: например JSON с реквизитами заказа.

POST /api/orders HTTP/1.1
Content-Type: application/json
Idempotency-Key: order-1001

{"external_id":"CRM-1001","amount_kopecks":125000}

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

Чтение и изменение: не перепутать операции

PUT обычно задаёт представление ресурса целиком по контракту, PATCH применяет частичное изменение, DELETE запрашивает удаление связи ресурса с адресом. Нельзя угадывать поведение только по названию URL: смотрите документацию и разрешённые методы.

Идемпотентность HTTP означает одинаковый предполагаемый эффект повторного одинакового запроса, а не обязательно одинаковый статус ответа. POST сам по себе такой гарантии не даёт. Автоматический повтор записи требует отдельного анализа контракта.

JSON, поля и пагинация: где ломается обмен

JSON популярен в веб-API, но встречаются XML, двоичные форматы и передача файлов. Формат — лишь оболочка. Для обмена важны смысл каждого поля, допустимые значения и ограничения.

• Сумма: копейки или рубли, валюта, точность и правила округления.
• Дата: часовой пояс, момент события и дата документа.
• Пустое значение: отсутствие поля, null и пустая строка могут различаться.
• Идентификатор: внутренний номер базы не всегда совпадает с номером CRM.
• Справочники: ставка налога, единица измерения и код склада должны сопоставляться.

Большой список часто отдают страницами: limit/offset, cursor или иная схема. Получить первую страницу и объявить выгрузку завершённой — типичная ошибка. При изменяющихся данных учитывают порядок, контрольную точку и возможное повторение элементов. Конкретный способ выбирают по документации сервиса.

HTTP-статус помогает искать причину

• 200 / 201: успешная обработка / создание; проверьте полезный результат.
• 202: запрос принят, завершение может произойти позже.
• 400: запрос некорректен; подробности ищут в ответе.
• 401 / 403: проблема с подтверждением доступа / отказ в разрешении; уточняют контракт.
• 404 / 405: ресурс не найден / метод не разрешён.
• 409 / 422: конфликт состояния / семантически неприемлемые данные.
• 429: слишком много запросов; учитывают ограничения сервиса.
• 5xx: ошибка на стороне обслуживающей цепочки; нужна диагностика.

Статус не заменяет код ошибки приложения и correlation ID. Ответ 200 с записью в очереди не доказывает проведение заказа. После 202 нужен предусмотренный способ узнать итог. После тайм-аута неизвестно, успел ли сервис записать документ: немедленный повтор без защиты от дублей опасен.

REST, RPC, SOAP, GraphQL и MCP — разные задачи

REST — архитектурный подход, а не синоним любого JSON по HTTPS. RPC строится вокруг вызова процедур; SOAP задаёт собственную модель сообщений. GraphQL позволяет запрашивать данные по схеме. Событийный обмен может использовать брокер и очередь вместо прямого ожидания ответа.

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

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

Токен — не разрешение на все данные

Аутентификация определяет, кто обращается, авторизация — что ему можно. API-ключ, bearer-токен, OAuth и взаимная TLS-аутентификация применяются в разных схемах; они не взаимозаменяемы автоматически. Bearer-токен требует защищённого хранения и передачи: его предъявитель может получить связанные с ним права.

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

OAuth — механизм делегирования доступа; выдаваемые scopes и дальнейшие проверки определяются сервисом. Машинной задаче не следует выдавать личный административный токен сотрудника. MFA человека и управление сервисными учётными данными — связанные, но разные задачи.

Webhook: сервис сам сообщает о событии

При polling клиент регулярно спрашивает: «что изменилось?». При webhook источник отправляет уведомление на согласованный адрес. Для входящего webhook нужен доступный приёмник; выдавать ему доступ ко всей внутренней сети не требуется.

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

Тяжёлую работу удобно выполнять после надёжного приёма в очередь. Успешный HTTP-ответ приёмника и фактическое обновление заказа — разные этапы. Нужны повторная доставка, сверка пропусков и наблюдение за очередью. Конкретный тайм-аут GitHub или другого сервиса нельзя переносить на всех поставщиков.

Повтор после сбоя: как не создать второй заказ

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

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

Тайм-ауты ограничивают, число повторов тоже. Для разрешённых повторов применяют задержку с ростом и случайным разбросом; учитывают Retry-After, если он предусмотрен. Ошибку прав не исправляет бесконечная отправка. В промышленной записи нужна долговременная, атомарно согласованная защита от дублей, переживающая перезапуск и несколько обработчиков.

Что согласовать до разработки

1. Зафиксировать бизнес-операцию и источник истины по каждому полю.
2. Получить документацию, тестовую среду и ограниченные учётные данные.
3. Согласовать схему, версии, справочники и идентификаторы.
4. Описать ошибки, повторы, порядок событий и частичный успех.
5. Определить лимиты, объём, частоту и допустимое отставание.
6. Проверить результат в целевой системе и назначить владельца.

OpenAPI позволяет описать HTTP-интерфейс: операции, параметры, схемы, ответы и механизмы безопасности. Swagger UI — один из инструментов просмотра и вызова, а не название любого API. Автоматическая документация полезна, но сама не доказывает правильность реализации и полноту бизнес-проверок.

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

API не отвечает: порядок диагностики

1. Адрес и DNS: нужное имя, путь, окружение и версия.
2. Сеть: маршрут, порт, VPN, firewall и ограничения источников.
3. TLS: имя сертификата, срок, цепочка и время компьютера.
4. HTTP: метод, заголовки, формат и фактический статус.
5. Доступ: токен, срок, scopes и права на объект.
6. Приложение: схема, бизнес-правила, очередь и целевая запись.

Если curl работает, а браузер — нет, отдельно проверяют CORS и особенности клиента. CORS — механизм браузерного доступа, он не заменяет серверную авторизацию. Если запрос остановился до HTTP, приложение может вообще не получить его и не записать прикладной журнал.

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

Практика: запустить свой API на компьютере

В архиве — небольшой сервер Python 3 без сторонних пакетов и файл заказа. Он работает только на 127.0.0.1, хранит учебные заказы в памяти и не обращается в Интернет. Это настоящий локальный HTTP-обмен, но не промышленный сервис, не OAuth и не подключение к 1С.

Распакуйте ZIP и откройте терминал в его папке. Выберите команду своей системы:

# Windows
py -3 api-lab.py
# Linux: вместо предыдущей команды
python3 api-lab.py

Команда запускает сервер; окно оставляют открытым. Ожидаемая строка — TRAINING ONLY и адрес http://127.0.0.1:18081/api/orders. Если порт занят, сначала остановите предыдущий учебный экземпляр; параметр --port позволяет выбрать другой свободный порт, который затем нужно заменить во всех командах.

Аутентификации и TLS в стенде нет. Не меняйте адрес прослушивания на внешний и не вводите реальные данные. Ограничения специально упрощены: один обработчик, до 100 заказов, тело до 4096 байт. Для остановки нажмите Ctrl+C в первом окне: память и ключи будут потеряны.

Шаг 1. Получить список и увидеть ответ

Во втором окне терминала из той же папки выполните:

# Windows PowerShell
curl.exe -i --max-time 5 http://127.0.0.1:18081/api/orders
# Linux: вместо Windows-варианта
curl -i --max-time 5 http://127.0.0.1:18081/api/orders

curl.exe явно вызывает программу curl в Windows, минуя возможный псевдоним оболочки. Параметр -i показывает заголовки вместе с телом; --max-time 5 ограничивает время ожидания. По умолчанию выполняется GET. На свежем сервере ожидаются статус 200 и JSON:

{"orders": [], "count": 0}

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

Шаг 2. Создать заказ и безопасно повторить

Файл order.json уже лежит в архиве. В нём внешний номер CRM-1001 и сумма 125000 копеек. Для Windows:

curl.exe -i --max-time 5 -X POST http://127.0.0.1:18081/api/orders -H "Content-Type: application/json" -H "Idempotency-Key: order-1001" --data-binary "@order.json"

В Linux используют тот же вызов с curl вместо curl.exe. -X POST выбирает метод, первый -H объявляет JSON, второй задаёт ключ повтора. --data-binary читает тело из файла после @: так кавычки JSON не приходится экранировать в командной строке.

Первая отправка на свежем сервере возвращает 201 и id 1. Повторите точно ту же команду: придёт 200, тот же id и заголовок X-Lab-Replayed: true. Повторный GET покажет count 1. Такое различие статусов — правило стенда, не универсальный стандарт дедупликации.

• Измените amount_kopecks в файле, сохранив ключ: ожидается 409.
• Укажите отрицательную сумму: ожидается 422, заказ не добавится.
• Верните исходный файл перед следующими опытами.

# Проверка неподдерживаемого удаления, Windows
curl.exe -i --max-time 5 -X DELETE http://127.0.0.1:18081/api/orders

Этот вызов ничего не удаляет: сервер отвечает 405 и Allow: GET, POST. Если вы перезапустили сервер, список снова пуст. Надёжность сохранения, подпись вебхуков и доступ к реальной учётной системе данный опыт не доказывает.

Что контролировать после запуска обмена

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

Практический критерий: заказ CRM-1001 появился ровно один раз, имеет верные реквизиты, связан с исходным заказом и дошёл до нужного бизнес-состояния. Время ответа 80 мс ничего не говорит о правильности цены или проведении документа.

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

Скачать стенд и карточку интеграции

В архиве нет рабочих ключей и производственных данных. Сервер предназначен только для локального обучения.

Интеграция требует приложения и надёжной инфраструктуры

Вопросы и ответы

Документация и границы проверки

Первичные материалы: HTTP RFC 9110, методы HTTP, MDN, статусы HTTP, MDN, bearer-токены, OpenAPI, webhooks GitHub, идемпотентность Stripe, OWASP API Security. Проверены 14 ноября 2026 года.

Схемы оригинальные, в стиле шаблона AVG IT. При подготовке выполнены 14 проверок реального локального HTTP-обмена: чтение, создание, повтор, конфликт ключа, неверные данные, формат, размер тела и неподдерживаемая операция. Учебный код не является готовой интеграцией, сервером аутентификации или подтверждением работы стороннего продукта.