Интеграция API: данные и обработка ошибок

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

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

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

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

Заказы: передача в складскую, транспортную или бухгалтерскую систему.
Остатки и цены: распространение центральных данных по каналам продаж.
Клиенты: согласованный доступ CRM, поддержки и продаж к одной записи.
Статусы: сообщения об оплате, заказе, доставке и согласовании.
Отчётность: содержательное объединение данных разных приложений.

В B2B персональная цена может храниться в ERP, заказ — в магазине, а получение оплаты — в бухгалтерии. Цель не копировать всё повсюду, а доставить нужную информацию на нужный экран вовремя.

API, webhook, файлы и ручной процесс

API нужен не всегда. Выбор зависит от частоты, объёма данных, критичности операций и технических возможностей.

Метод	Как работает	Пример	Что учесть
API	Одна система запрашивает данные или отправляет их другой.	Создание заказа, проверка остатков, изменение клиента.	Аутентификация, лимиты запросов, ответы об ошибках.
Webhook	Источник отправляет уведомление при событии.	Новый заказ, подтверждение оплаты, отмена подписки.	Повторы уведомлений и доступность получателя.
Передача файла	Обмен CSV, XML или другими файлами по расписанию.	Каталог товаров, периодический прайс, перенос из старой системы.	Схема, кодировка и время обновления.
Ручной процесс	Человек вводит или подтверждает данные на экране.	Редкие исключения и решения, требующие оценки.	Права, контроль и журнал операции.

API и webhook различаются инициативой: через API Ваша система спрашивает «Каков статус заказа?», а webhook сообщает «Статус изменился». Часто используются оба подхода.

Выберите подходящие процессы

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

Что запускает действие: заказ, оплата, форма, согласование или расписание?
Откуда и куда поступают данные?
Требуется ли решение или одобрение человека?
Какая актуальность нужна: немедленная, с небольшим интервалом или ежедневная?
Как неверные или неполные данные влияют на работу?
Кого информировать о завершении?

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

Для процессов с одобрением полезно руководство по автоматизации рабочих процессов и согласованиям (на турецком).

Поля и ответственные за данные

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

Что определить для каждого поля?

Название и смысл: остаток — доступное к продаже количество или физическое наличие на складе?
Тип: текст, число, дата, денежное значение, список или файл.
Обязательность: допустимо ли пустое значение и останавливает ли оно операцию?
Уникальный идентификатор: где создаётся код товара, ID клиента или номер заказа?
Преобразование: как сопоставляются статусы разных систем?
Основной источник: какая система отвечает за верное значение?
Направление: одно- или двустороннее обновление?

Если описание товара ведётся в PIM, остатки — в ERP, публикация — в магазине, задайте единственный основной источник для каждого поля. Иначе системы могут перезаписывать изменения друг друга.

Практическое правило: не выбирайте двусторонний обмен по умолчанию. Сначала проверьте, решает ли задачу односторонний поток.

Ошибки, журналы и проверка

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

Что включить в план?

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

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

Для согласованности товаров, категорий и медиа полезны также заметки из руководства по оптимизации товарных изображений (на турецком).

Что спросить у поставщика ПО?

Фраза «поддерживаем интеграцию» ещё не означает наличие нужного потока данных. Уточните:

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

Ответы должны оценить не только разработчики, но и ответственные за операции, продажи и финансы.

Шаблон плана интеграции

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

Цель: какую операционную проблему решаем?
Состав: системы, записи и действия первого этапа.
Схема: событие, источник, получатель и результат.
Словарь данных: соответствия, обязательность и преобразования полей.
Ответственность: основные источники и владельцы процессов.
Метод: где нужны API, webhook, файл или ручное одобрение.
Ошибки: повторы, оповещения, вмешательство и хранение журналов.
Проверка и приёмка: кто подтверждает успешные, ошибочные и исключительные сценарии.

Наличия поля в API мало: пустое и неизвестное значение могут означать разное. Закрепите это в договорённостях о данных. Отдельно решите, удаляется, отключается или сохраняется в целевой системе запись, удалённая в источнике.

Интеграция API: договорённости о данных и ошибки