Что такое интеграция по API

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

Настраиваем такой обмен под ключ: интеграция по API с 1С, CRM, маркетплейсами и платежными системами.

Без интеграций бизнес быстро упирается в ручной труд. Менеджер переносит заявки с сайта в CRM, бухгалтер сверяет оплаты с выписками, склад узнает о заказе из мессенджера. Ошибки копятся, клиенты ждут. Интеграция убирает эти шаги: данные появляются там, где нужны, и тогда, когда нужны.

Что такое интеграция через API

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

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

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

Что обычно связывают с помощью API:

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

Что такое интеграция API и чем она отличается от выгрузок

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

Системы можно связать и без API. Чаще всего встречаются три варианта:

• ручной перенос, когда сотрудник копирует данные из одной программы в другую;
• обмен файлами: одна система раз в час или раз в сутки выгружает файл в XML или CSV, другая его забирает;
• прямое подключение к чужой базе данных, что небезопасно и ломается при любом обновлении.

Файловый обмен до сих пор жив. Синхронизация 1С с интернет-магазином часто идет по стандарту CommerceML (формат XML-файлов для каталога и заказов). Он работает, но с задержкой: если выгрузка раз в час, покупатель может заказать товар, которого уже нет. Обмен данными между системами через API идет по событию или по запросу, поэтому данные свежие.

Сами API тоже бывают разные. Самый распространенный стиль сейчас - REST: запросы идут по протоколу HTTP, данные передаются в формате JSON (текстовый формат вида ключ-значение, который легко читают и люди, и программы). Старые корпоративные и государственные системы часто используют SOAP с обменом XML-документами. GraphQL дает клиенту самому выбрать, какие поля получить в ответе. Стиль определяет внешняя система, а не вкус разработчика.

Как работает интеграция API

Любой обмен через API строится на паре запрос-ответ. Разберем по шагам, что происходит, когда сайт спрашивает у 1С остаток товара.

1. Сайт формирует запрос: адрес метода (endpoint, отдельный адрес для конкретной операции), тип действия и параметры, например артикул.
2. К запросу добавляется ключ доступа или токен, чтобы 1С понимала, кто спрашивает и что ему разрешено.
3. Система-получатель проверяет права, находит данные и собирает ответ.
4. Ответ приходит с кодом статуса: 200 значит все хорошо, 401 - нет доступа, 404 - запись не найдена, 500 - ошибка на стороне сервера.
5. Сайт разбирает ответ в формате JSON и показывает остаток покупателю или записывает его в свою базу.

В REST тип действия задает HTTP-метод. GET читает данные, POST создает новую запись, PUT или PATCH меняют существующую, DELETE удаляет. Поэтому по одному адресу вида /orders можно и получить список заказов, и создать новый.

Есть и обратное направление. Если сайт каждые пять минут спрашивает у платежной системы, прошла ли оплата, получается лишняя нагрузка и задержка. Вместо этого используют вебхуки (webhook, обратный вызов): внешняя система сама отправляет запрос на заранее указанный адрес, когда событие произошло. Оплата прошла, и сайт сразу знает об этом и меняет статус заказа.

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

Интеграция API: пример для интернет-магазина

Посмотрим, как API использовать в обычном интернет-магазине. Покупатель оформляет заказ на сайте, и дальше срабатывает цепочка:

• сайт проверяет остаток через API учетной системы и резервирует товар;
• платежная система принимает оплату картой или через СБП и присылает вебхук об успешном платеже;
• заказ со статусом оплачен уходит в систему CRM, где менеджер видит историю клиента;
• служба доставки получает данные отправления и возвращает трек-номер;
• покупатель получает письмо или push-уведомление, когда меняется статус заказа.

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

Другие частые сценарии использования API:

• вход на сайт через аккаунт социальной сети или банка;
• подсказки адреса и расчет доставки прямо в форме заказа;
• отправка SMS-кодов для входа и подтверждения;
• выгрузка товаров на маркетплейсы и загрузка оттуда заказов;
• передача данных о звонках из телефонии в CRM;
• связка мобильного приложения с тем же сервером, что и у сайта, чтобы корзина и история были общими.

На демо-проектах студии это выглядело бы так. Грядка, магазин фермерских продуктов, берет остатки и цены из учетной системы, а заказы отдает курьерской службе. Капиталика, сервис учета личных финансов, могла бы подтягивать операции из банков, которые открывают API для клиентов. Трассер, система для логистики, принимает координаты машин с GPS-трекеров и отдает клиентам статус груза.

Внешний сервис, например платежный или картографический, почти всегда предлагает готовое решение для типовых задач: SDK (набор готовых библиотек) или модуль для популярной CMS. Готовый модуль экономит время, если процесс стандартный. Если логика нестандартная, например скидки считаются в 1С по сложным правилам, пишем свою интеграцию поверх API.

Интеграция корпоративного портала

Корпоративный портал (внутренний сайт компании для сотрудников) без интеграций быстро превращается в доску объявлений, которую никто не открывает. Ценность появляется, когда портал берет данные из рабочих систем. Отпуска и больничные подтягиваются из кадровой программы, остатки отпусков считаются автоматически, заявки на пропуск уходят в систему контроля доступа, а новые сотрудники получают учетные записи в день выхода.

Технически здесь работают те же API: портал обращается к 1С:ЗУП за кадровыми данными, к службе каталогов за учетными записями, к системе заявок за статусами задач. Сотрудник видит все в одном окне, а бизнес-процессы вроде согласования командировки проходят без бумаг и пересылки писем.

Корпоративный портал: интеграция с внешними сервисами

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

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

Как сделать интеграцию API?

Порядок работы почти не зависит от того, что с чем связываем.

1. Описываем процесс словами: какие данные, откуда, куда, как часто и что делать при расхождении. На этом шаге часто выясняется, что половина проблем не в технике, а в том, что в разных системах по-разному ведут справочники.
2. Изучаем документацию API обеих сторон: какие методы есть, какие ограничения на число запросов, есть ли тестовая среда (песочница для проверок без реальных денег и заказов).
3. Договариваемся о правилах сопоставления: чем связываем записи, какая система главная для цен, для остатков, для клиентов.
4. Пишем интеграцию и тестируем ее на копии данных, прогоняем сценарии с ошибками.
5. Запускаем на реальных данных под наблюдением, настраиваем журнал и оповещения.
6. Передаем документацию и сопровождаем: внешние API меняются, и интеграцию нужно обновлять вслед за ними.

Со стороны заказчика нужны доступы к системам, контакт человека, который знает процесс, и администратор 1С или CRM, если там требуется доработка. Со стороны студии работают аналитик, разработчик и тестировщик.

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

Интеграция web-приложений: безопасность и надежность обмена

Интеграция web-приложений открывает доступ к данным снаружи, поэтому вопросы защиты решаем до первой строки кода. Базовые правила у нас такие.

• Весь обмен идет только по HTTPS, чтобы данные нельзя было перехватить по дороге.
• Каждая интеграция получает свой ключ или токен с минимальными правами: сервис доставки видит адреса заказов, но не видит историю платежей.
• Для доступа от имени пользователя используем OAuth 2.0 (протокол, при котором человек разрешает приложению действовать от его имени и не сообщает ему пароль).
• Ключи храним в защищенном хранилище секретов и меняем по графику или сразу, если сотрудник с доступом уходит из компании.
• Входящие вебхуки проверяем по подписи, чтобы злоумышленник не мог прислать фальшивое уведомление об оплате.

Вторая сторона вопроса - надежность. Сеть иногда рвется посреди запроса, и система не знает, дошел он или нет. Если вслепую повторить запрос на списание денег, клиент заплатит дважды. Для денежных операций используем ключ идемпотентности (уникальный номер операции, по которому получатель понимает, что это повтор, и второй раз действие не выполняет). Многие платежные сервисы поддерживают такой механизм в своем API.

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

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

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

Готовый коннектор подходит, если обе системы популярные, процесс типовой и ждать не хочется. Многие CRM и CMS умеют связываться между собой из коробки, а сервисы-посредники (no-code платформы, которые соединяют приложения без программирования) закрывают простые сценарии вроде новой сделки из заявки с сайта.

Своя разработка нужна, когда:

• одна из систем самописная или сильно доработана;
• данных много, и обмен должен идти без задержек;
• есть нестандартные правила: скидки, резервы, несколько складов, разные юрлица;
• нельзя передавать данные клиентов стороннему посреднику;
• интеграция касается денег, и каждую ошибку надо разбирать по журналу.

Мы обычно начинаем с разбора: смотрим, что уже умеют системы, и предлагаем самый короткий путь. Иногда достаточно настроить готовый модуль, и писать код не нужно вовсе.