API — это набор правил, по которым одна программа просит у другой данные или действие и получает ответ: «покажи остаток по артикулу», «создай заказ». REST — самый распространённый стиль таких правил поверх обычного веба, а вебхук — способ, при котором не вы спрашиваете систему о событии, а она сама сообщает вам.

Бизнесу API нужен там, где одни и те же данные вводят руками дважды: из заказа на сайте в учёт, из учёта в кабинет партнёра. Ниже на условном примере показано, как устроен обмен, чем он ломается и что спросить у подрядчика до договора. Проектировщикам адресована статья «Проектирование 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 месяца. Точную цену называем после обследования.