API — это набор правил, по которым одна программа просит у другой данные или действие и получает ответ: «покажи остаток по артикулу», «создай заказ». REST — самый распространённый стиль таких правил поверх обычного веба, а вебхук — способ, при котором не вы спрашиваете систему о событии, а она сама сообщает вам.
Бизнесу API нужен там, где одни и те же данные вводят руками дважды: из заказа на сайте в учёт, из учёта в кабинет партнёра. Ниже на условном примере показано, как устроен обмен, чем он ломается и что спросить у подрядчика до договора. Проектировщикам адресована статья «Проектирование API для интеграций», здесь только то, что нужно понимать заказчику.
Что такое API на примере склада партнёра
Условный пример. Магазин продаёт товары, которые лежат на складе партнёра. Менеджер магазина звонит на склад: «Сколько осталось по артикулу А-100?» — «Четырнадцать». Затем: «Отгрузите два». Звонок можно заменить программой: магазин отправляет складу короткое сообщение в согласованной форме и получает ответ тоже в согласованной форме. Эта форма и есть API: перечень вопросов и команд, которые склад готов принимать, и точное описание того, как их задавать и что будет в ответе.
Из примера следуют три свойства.
- Это договорённость, а не программа. Пока стороны её соблюдают, внутри у каждой может быть что угодно: другой язык, другая база.
- Это дверь с замком. Склад отвечает тем, кто представился, и только на разрешённые вопросы.
- У договорённости есть владелец. Кто её меняет, тот предупреждает тех, кто на неё опирается.
Бизнес избавляется от двойного ввода и связанных с ним ошибок, а партнёры подключаются по инструкции без звонков. Кабинет, админ-панель и интерфейс для телефона становятся такими же клиентами того же API, как партнёрская система; об этом на страницах «Разработка цифровых сервисов» и «Разработка админ-панели». Чего API не даёт: он быстро и аккуратно передаст неверный остаток, если в учёте он неверный, и не решит, чьё значение главное при расхождении. Это решение бизнеса, а не программиста.
Как выглядит обмен: запрос, ответ и что такое REST
Любой обмен по API состоит из запроса и ответа. В запросе четыре части: куда (адрес объекта, например остаток или заказ), что сделать (получить, создать, изменить, удалить), с какими данными (артикул, список позиций) и кто спрашивает (ключ).
| Что хотим | Как говорим с API | Что приходит в ответ |
|---|---|---|
| Узнать остаток | Получить «остаток» по артикулу А-100 на складе 2 | Число и время, на которое оно верно |
| Создать заказ | Создать «заказ» со списком позиций | Номер заказа и его статус |
| Изменить заказ | Изменить «заказ» номер 428: количество | Новое состояние или причина отказа |
| Отменить заказ | Отменить «заказ» номер 428 | Статус «отменён» или сообщение, что уже поздно |
В ответе всегда есть код результата, и его смысл понятен без программиста: группа 2xx значит «получилось», 4xx — «виноват запрос» (неверный формат, нет права, нет такого объекта), 5xx — «виновата принимающая сторона, повторите позже». Если подрядчик говорит, что интеграция «иногда не работает», попросите разбить сбои на эти группы: сразу видно, чья это часть.
REST — не продукт и не протокол, а стиль: у каждого объекта свой адрес, действия стандартные, каждый запрос самодостаточен и не зависит от предыдущих. Данные ходят по обычному вебу (HTTP), чаще всего в формате JSON: это пары «название: значение», которые читает и человек, и программа. REST понимают почти все системы, поэтому без причины для другого способа берут его.
Опрос, вебхук, очередь или файл: какой способ обмена выбрать
| Способ | Как работает | Когда выбирают | Чем неудобен |
|---|---|---|---|
| Запрос по API (опрос) | Вы сами спрашиваете по расписанию: «есть новые заказы?» | Данные нужны сейчас или раз в несколько минут | Задержка до следующего опроса, много пустых запросов |
| Вебхук | Вы сообщаете адрес, и система сама отправляет на него сообщение о событии | О событии нужно узнать сразу: заказ собран, платёж прошёл | Нужен доступный адрес; сообщение может прийти дважды, не по порядку или потеряться |
| Очередь сообщений | Отправитель кладёт сообщение в промежуточное хранилище, получатель забирает, когда готов | Получатель бывает недоступен, поток неровный | Ещё один компонент, за которым нужно следить |
| Обмен файлами | Одна система кладёт CSV или XML в папку, другая забирает по расписанию | У системы нет API, большие выгрузки раз в сутки | Данные идут пачками; повреждённый файл останавливает обмен тихо |
| Доступ к базе другой системы | Вы читаете её таблицы напрямую | Другого пути нет | Ломается при обновлении системы и обходит её права; крайняя мера, риск записывают |
Вебхук похож на звонок курьера в дверь, а опрос — на проверку почтового ящика каждые пять минут. Курьер может не дозвониться, поэтому надёжная схема сочетает способы: вебхук сообщает «что-то изменилось», получатель запрашивает актуальные данные по API, а раз в сутки идёт сверка чисел. Если потеря одного события стоит денег, вебхук без сверки не используют. Подлинность вебхука проверяют подписью, иначе любой сможет прислать «заказ оплачен». Технические приёмы разобраны в статье «Outbox и гарантированная доставка простыми словами». Старые системы иногда предлагают только SOAP: тот же обмен запросами и ответами, но в формате XML и с более громоздким описанием.
Ключи, токены и права: как система узнаёт, кто спрашивает
Ключ API — длинная секретная строка, которую система предъявляет в каждом запросе как пропуск. Он опознаёт программу, а не человека. Токен — временный пропуск: его выдают на время после проверки, он быстро истекает, и его утечка менее опасна, чем утечка постоянного ключа. Проверять нужно не только «кто», но и «что разрешено»: ключ, которым читают остатки, не должен позволять создавать заказы и видеть заказы чужих клиентов.
Что можно проверить без чтения кода:
- на каждую систему и каждого подрядчика выдан отдельный ключ, иначе нельзя отозвать один, не остановив остальные;
- ключи не лежат в коде, переписке и общей таблице;
- ключ перевыпускается без остановки обмена, а ключи ушедшего подрядчика отзываются в тот же день;
- чтение отделено от записи, частота запросов ограничена;
- соединение защищено (HTTPS), каждое обращение попадает в журнал.
Подробности — на странице «Защита API от несанкционированного доступа» и в статье «Как защитить API от взлома».
Версии и сбои: что видит бизнес, когда обмен ломается
Версия API — обещание, что формат обмена не изменится без предупреждения. Пока партнёры вызывают первую версию, она остаётся прежней, изменения выходят во второй, а у первой есть известная дата отключения. Менять формат молча «потому что клиент у нас один» нельзя: через год клиентов станет несколько, и у каждого свой график обновлений.
Бизнес видит сбои не в виде кодов, а в виде симптомов. Таблица подсказывает, о чём спросить подрядчика.
| Что видит бизнес | Вероятная причина | Что спросить |
|---|---|---|
| Заказ задвоился | Запрос повторили после обрыва связи, а получатель не узнаёт повтор | Что будет, если отправить один заказ дважды? Покажите тест |
| Остатки отстают | Данные обновляются по расписанию или лежат в кэше | Как часто обновляются остатки и где видно время обновления? |
| Часть заказов не дошла | Сообщение отправили один раз и не проверили подтверждение | Где виден список недоставленного и кто его разбирает? |
| После обновления у партнёра всё встало | Формат изменили без новой версии | Как объявляются изменения и какая версия сейчас? |
| Обмен «работает», а числа не сходятся | Разные единицы, округление, часовой пояс или смысл поля | Кто главный по этому полю и как сверяются суммы? |
| На тестовой среде работало, на боевой нет | Тестовые данные не похожи на боевые, другие права и объём | Чем отличаются среды и как проверялась нагрузка? |
API и 1С: что реально доступно и на что смотреть
В 1С нет единой кнопки «включить API»: способ зависит от версии платформы и конфигурации, и его выясняют до начала работ. Обычно встречаются четыре варианта.
- Стандартный обмен конфигурации: файлы по правилам обмена, например с сайтом по формату CommerceML (разбор).
- Стандартный интерфейс OData: через веб-сервер публикуются выбранные объекты, удобно читать справочники и документы.
- HTTP-сервисы, которые пишут в конфигурации под задачу: точные операции вроде «создать заказ с проверками».
- Веб-сервисы SOAP: встречаются в старых решениях.
Что учесть. Интеграция работает рядом с рабочей базой, поэтому её нагрузку считают заранее: частый опрос в рабочее время замедляет учёт, и ставят кэш или очередь. Для обмена заводят отдельную учётную запись с узкими правами. Доработки конфигурации могут сломать HTTP-сервис при обновлении, поэтому обновления проверяют на копии. Писать напрямую в таблицы базы 1С не принято: так обходят её правила. Схемы обмена описаны на странице «Интеграция 1С с CRM и сайтом», подключение ИИ к 1С — в статье «Как подключить ИИ к 1С».
Что требовать от подрядчика: документацию, тестовую среду и журнал
До договора и при приёмке просите пять вещей. Если на любую отвечают «устно» или «потом», это красный флаг.
| Что требовать | Как выглядит нормально | Тревожный признак |
|---|---|---|
| Описание интерфейса | Один файл (формат OpenAPI) и страница документации: операции, примеры запросов и ответов, список ошибок, правила повторов, лимиты, версии | Документация «в голове у разработчика» или в мессенджере |
| Тестовая среда | Отдельный адрес и ключи, тестовые данные, умеет имитировать сбой и повторную доставку | Проверяют на боевых данных |
| Журнал обмена | Видно, кто, когда и что отправил и получил; поиск по номеру заказа | Журнал только у подрядчика |
| Оповещения и сверка | О сбое узнаёт ваш сотрудник, а не клиент; раз в сутки сверяются числа и суммы | О сбое узнают из жалоб клиентов |
| Владение | Код, ключи и документация лежат у вас, владелец интерфейса назван | Ключи в личном аккаунте подрядчика |
Развёрнутый чек-лист приёмки для технических специалистов приведён в статье «Проектирование API для интеграций».
Что делаем мы и с чего начать
Мы делаем связку между вашими системами: определяем, кто главный по каждому полю, пишем интерфейс, тестовую среду и журнал, подключаем 1С и сторонние сервисы. Начинаем с одной связки, а не со всей архитектуры. Услуга описана на странице «Разработка API и бэкенда на заказ».
Обследование стоит 200 000 ₽ и занимает 2–3 недели за один-два процесса, 350 000 ₽ и 3–4 недели, если в обмене несколько систем. На выходе схема обмена, источники данных по каждому полю, требования и вилка бюджета; сумма вычитается из первого этапа, если вы продолжаете с нами. Одну связку проверяет лёгкий пилот за 150 000–400 000 ₽ и 2–8 недель. Исходники лежат в вашем репозитории с первого коммита, круглосуточного дежурства нет. Цены и сроки — на странице «Тарифы».
Частые вопросы
API и интеграция — это одно и то же?
Нет. API — интерфейс, через который программа принимает запросы. Интеграция — работа по соединению систем, она может использовать API, файлы или очередь. Хорошая интеграция опирается на описанный API, плохая — на ручные выгрузки.
REST API — это протокол?
Нет, это стиль построения интерфейса поверх обычного веба (HTTP): у объектов свои адреса, действия стандартные, каждый запрос самодостаточен. Данные чаще всего передаются в формате JSON.
Чем вебхук отличается от обычного запроса?
В обычном запросе вы спрашиваете сами и получаете ответ сразу. Вебхук работает наоборот: система сообщает вам о событии на заранее указанный адрес. Надёжная схема сочетает оба способа и ежедневную сверку.
Можно ли подключиться к 1С по API?
Обычно да: через стандартный интерфейс OData, HTTP-сервисы или обмен файлами. Что доступно, зависит от версии платформы и конфигурации, это выясняется до начала работ. Если нет ни интерфейса, ни выгрузки, мы говорим об этом до договора.
Безопасно ли открывать API наружу?
Безопасно, если у каждой системы свой ключ, права ограничены по операциям и объектам, частота запросов ограничена, соединение защищено, а обращения пишутся в журнал. Это проверяют на уровне кода и конфигурации, а не обещанием подрядчика.
Что такое тестовая среда и зачем она нужна?
Отдельная копия интерфейса с тестовыми данными и своими ключами. Партнёр отлаживает на ней обмен, не затрагивая боевые данные. Хорошая среда умеет имитировать сбои и повторную доставку.
Что делать, если подрядчик ушёл, а ключей и документации нет?
Выпустить новые ключи, отозвав старые, и восстановить описание интерфейса по коду и журналам. Поэтому код, ключи и документация лежат у вас с первого дня. Чужую интеграцию мы берём на сопровождение после разбора, если есть исходники или их можно восстановить.
Сколько стоит сделать API или интеграцию?
Обследование — 200 000 ₽ за один-два процесса и 350 000 ₽ при нескольких системах. Одну связку проверяет лёгкий пилот за 150 000–400 000 ₽ и 2–8 недель, обмен с несколькими системами — тяжёлый пилот за 400 000–1 200 000 ₽ и 2–3 месяца. Точную цену называем после обследования.