API и товарные фиды — это два канала передачи данных о каталоге, через которые AI-агенты получают сведения о продуктах: характеристики, цены, наличие, условия доставки. API отдаёт данные по запросу в структурированном виде, а фид — это файл или поток с заранее описанной схемой, который агент считывает целиком или порциями.

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

Что такое API и товарный фид в контексте AI-агентов

API (программный интерфейс) — это набор методов, через которые агент запрашивает конкретные данные: список категорий, карточку товара, цену, остаток. Ответ приходит в машиночитаемом формате, чаще всего JSON, реже XML.

Товарный фид — это структурированный перечень товаров с фиксированным набором полей, который публикуется по постоянному адресу и обновляется по расписанию. Агент не формирует запрос по каждому товару, а забирает весь массив или его часть.

Ключевое различие: API отвечает на точечный запрос в реальном времени, фид передаёт состояние каталога целиком. Для динамичных параметров — цены, остатки, сроки доставки — предпочтителен API, для описаний и характеристик достаточно фида.

Базовые технические требования к структуре данных

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

Второе требование — единообразие типов данных. Цена указывается числом с фиксированной точностью и валютой, наличие — булевым значением или числовым остатком, а не свободным текстом вроде «есть в наличии на складе». Свободный текст машина интерпретирует неоднозначно.

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

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

Форматы фидов и их совместимость с агентами

Распространённые форматы товарных фидов — XML, JSON и CSV. XML исторически используется в товарных агрегаторах, JSON удобен для API-ответов и современных интеграций, CSV подходит для массового экспорта, но плохо переносит вложенные структуры.

Для AI-агентов предпочтительны XML и JSON: они поддерживают вложенность, позволяют описывать атрибуты внутри одного объекта и однозначно типизируют значения. CSV требует строгого соглашения о разделителях и экранировании, иначе часть полей будет прочитана неверно.

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

Актуальность, частота обновления и кэширование

Цена и наличие — самые чувствительные параметры. Если агент получает устаревшую цену, он формирует неверное предложение, а пользователь сталкивается с расхождением при переходе на сайт.

Практическое правило: критичные поля обновляются чаще, чем описательные. Цены и остатки — по мере изменения, характеристики и описания — по мере редактирования карточки.

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

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

Обработка ошибок и устойчивость интеграции

API должен возвращать осмысленные коды состояния и текст ошибки. Ответ вида «ошибка 500» без пояснения не позволяет понять, что именно пошло не так: неверный параметр, отсутствующий товар или внутренний сбой.

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

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

Как подготовить каталог: пошаговый порядок

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

Шаг 2. Назначение идентификаторов. Присвойте каждому товару постоянный код и убедитесь, что он не зависит от названия или категории. Результат — стабильная адресация товаров.

Шаг 3. Выбор формата и публикация схемы. Определите, что отдаётся через API, а что через фид, и опишите схему каждого канала. Результат — предсказуемая структура данных для агента.

Шаг 4. Настройка обновления. Задайте частоту обновления для критичных и описательных полей, пропишите заголовки кэширования. Результат — актуальные данные без лишней нагрузки.

Шаг 5. Валидация и мониторинг. Введите автоматическую проверку фида и логирование ошибок API. Результат — контроль качества данных до того, как их получит агент.

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

Типичные ошибки при подготовке каталога

Отсутствие уникальных идентификаторов приводит к дублированию товаров в выдаче агента: один и тот же продукт распознаётся как два разных.

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

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

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

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

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

Нужен ли API, если уже есть товарный фид? Фид передаёт состояние каталога целиком и подходит для описаний и характеристик. API нужен там, где важна актуальность в реальном времени: цены, остатки, сроки доставки. На практике оба канала дополняют друг друга.

Какой формат фида выбрать для AI-агентов? Предпочтительны XML и JSON, поскольку они поддерживают вложенные структуры и однозначно типизируют значения. CSV допустим для простых каталогов, но требует строгих соглашений о разделителях и экранировании.

Как часто обновлять данные в фиде? Критичные поля — цену и наличие — обновляют по мере изменения, описательные — по мере редактирования карточки. Частота обновления задаётся отдельно для каждой группы полей.

Что делать при изменении структуры каталога? Новую версию схемы публикуют параллельно со старой и поддерживают обе на период перехода. Это позволяет интеграциям обновиться без разрыва в работе.

Вывод

Каталог, ориентированный на AI-агентов, отличается от обычного тремя свойствами: стабильными идентификаторами, единообразными типами данных и явной схемой. Эти требования не зависят от конкретного агента — они определяются самой задачей машинной обработки товаров.

Практический вывод для владельца каталога: начинать стоит с инвентаризации полей и назначения идентификаторов, а не с выбора формата. Формат и способ публикации — следствие того, какие данные и с какой частотой должны быть доступны. Такой порядок снижает объём переделок и делает интеграцию с агентами предсказуемой.