API и интеграции систем

Какие задачи решают API и интеграции систем?

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

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

Что такое API и почему это важно?

API (Application Programming Interface) — это интерфейс, который описывает, какие данные и операции программа открывает другим программам и по каким правилам. Такие интерфейсы есть у платежных сервисов, служб доставки, маркетплейсов и многих программ ERP и CRM. API-интеграция — это программный слой, который позволяет двум системам общаться через эти интерфейсы.

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

Скрытая цена ручного переноса данных

Когда между системами нет API-интеграции, со временем следующие проблемы становятся привычной частью работы:

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

Каким компаниям это имеет смысл?

• Компаниям, которые продают через несколько каналов, например через сайт, маркетплейсы и физический магазин.
• Фирмам, которые хранят остатки и данные по взаиморасчетам в ERP, а заказы принимают в другой системе.
• Компаниям, которые регулярно обмениваются данными с дилерами, поставщиками или партнерами.
• Организациям, где отделы продаж и клиентской поддержки работают в разных программах.

Типы API-интеграций, которые нужны чаще всего

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

Интеграции платежей

При интеграции виртуального POS-терминала или платежного сервиса основные вопросы — чтобы данные карты не хранились на вашем сервере, проверка 3D Secure и надежная запись результата платежа в заказ. Способы, при которых платежная форма открывается на инфраструктуре платежного сервиса или карта представлена токеном, заметно снижают нагрузку по защите данных карты. Сценарии возврата, частичного возврата и рассрочки тоже нужно разобрать в рамках API-интеграции с самого начала.

Интеграции доставки

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

Подключения к ERP и бухгалтерии

ERP и бухгалтерские программы, такие как Logo, Mikro или SAP, чаще всего являются главным источником данных об остатках, ценах, взаиморасчетах и счетах. Сайт, мобильное приложение или портал дилеров получает эти данные из ERP, а заказы и платежи отправляет обратно в ERP. В API-интеграции с ERP самое важное решение — какие данные, в каком направлении и как часто будут передаваться.

Подключения к CRM

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

e-Fatura, маркетплейсы и сервисы сообщений

Компании, которые хотят автоматизировать программно процессы электронных счетов e-Fatura и e-Arşiv в Турции, обычно работают с частными интеграторами, допущенными Управлением доходов Турции (Gelir İdaresi Başkanlığı); для программного подключения такие интеграторы чаще всего предоставляют API. Для компаний, которые продают на маркетплейсах, синхронизация товаров, остатков, цен и заказов — тоже часто нужный тип API-интеграции. Сервисы сообщений, такие как SMS, email и WhatsApp, могут быть частью потоков уведомлений.

Согласованность остатков при продаже в нескольких каналах

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

Как проходит проект по API и интеграциям систем?

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

1. Инвентаризация систем: перечисляем программы, которыми вы пользуетесь, их версии, состояние API и технических ответственных.
2. Карта потоков данных: рисуем, какие данные из какой системы в какую идут и каким событием запускаются.
3. Решение об основном источнике: для данных о товарах, остатках, ценах, клиентах и заказах определяем единый верный источник.
4. Сопоставление полей: документируем, как поля в двух системах соответствуют друг другу, с учетом различий в единицах, валютах, налогах и кодах.
5. Разработка и тестирование: по возможности разрабатываем в тестовых средах поставщиков, не затрагивая реальные данные.
6. Контролируемый запуск: сначала запускаем интеграцию на ограниченном объеме данных, а после проверки результатов открываем на полный охват.
7. Мониторинг: после запуска следим за ошибками и предупреждениями и наблюдаем, что поток работает исправно.

Почему основной источник так важен?

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

Тестовая среда и переход на боевую

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

Готовый модуль или индивидуальная интеграция?

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

Технические принципы безошибочного потока данных

Установить соединение — легкая часть работы; основной труд в том, чтобы продумать, что произойдет, когда что-то пойдет не так. Система на другой стороне может не ответить, сеть может прерваться, одно и то же уведомление может прийти дважды. Если API и интеграции систем построены с учетом таких ситуаций, поток данных становится надежным.

В реальном времени или по расписанию?

• Webhook: система на другой стороне сообщает вашей системе, когда происходит событие, например при поступлении платежа или доставке посылки. Это быстро, но требует мер, чтобы проверять пришедшее уведомление и не терять его.
• Опрос по расписанию: ваша система через определенные промежутки времени спрашивает другую сторону, нет ли новой записи. Используется для систем, у которых нет webhook.
• Пакетная передача: большие наборы данных передаются сразу целиком в определенные часы. Подходит для обновления каталога товаров или прайс-листа.

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

Обработка ошибок и повторные попытки

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

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

Журналирование и предупреждения

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

Безопасность

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

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

Сопровождение интеграции

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

Разработка собственного API

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

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

В хорошо спроектированном API ищут следующие свойства:

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

Один из широко применяемых стандартов документирования API — спецификация OpenAPI, которую развивает OpenAPI Initiative. Описания, написанные по этой спецификации, читаются и людьми, и программами; команды, которые будут пользоваться вашим API, могут создавать из такого описания страницы документации, средства тестирования и клиентский код.

Если перед открытием API внешним пользователям предоставить тестовую среду, подключающиеся команды смогут пробовать, не затрагивая боевые данные. Если ключи доступа выдаются каждому партнеру отдельно, при необходимости можно закрыть доступ одного партнера, не затрагивая остальных.

Объем работ, подготовка и частые ошибки

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

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

Что вам нужно подготовить

• Список программ, которыми вы пользуетесь, их версии и сведения о лицензиях.
• Для каждой системы контакты поставщика программы или технического ответственного.
• Документацию по API, если она есть, доступы к тестовой среде и порядок подачи заявки на ключ API.
• Краткое описание передач, которые сегодня делаются вручную: кто, когда и какие данные куда переносит.

Частые ошибки

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

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

Нужно ли менять наши действующие программы ради API и интеграций систем?

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

Сколько занимает API-интеграция?

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

Что, если у системы, к которой мы хотим подключиться, нет API?

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

Как мы узнаем, что интеграция выдала ошибку?

Нужно настроить мониторинг, который записывает результат каждой передачи и при ошибке отправляет предупреждение ответственным. Так проблемы можно заметить до того, как они дойдут до клиента.

Безопасна ли API-интеграция?

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

Сломается ли интеграция, если система на другой стороне изменит свой API?

Может сломаться. Следить за объявлениями поставщиков о версиях и вовремя адаптировать интеграцию к новой версии — часть сопровождения интеграции.

Давайте свяжем ваши системы между собой

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