Контракт данных оффера: идентификаторы, типы и ссылки

ShopTools AI подбирает предложения из каталога. Корректный JSON ещё не делает запись подходящей для показа или проверки: в поле кода может оказаться артикул, а адрес магазина может вести на трекер.

Рассмотрим контракт, который можно использовать при проектировании такой интеграции. Это модель требований к данным, а не описание всех полей действующего API ShopTools.

Определите смысл каждого значения

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

• Тип предложения: промокод, акция без кода или предложение на конкретный товар.
• Код: строка для проверки у магазина, а не SKU и не служебная надпись об отсутствии кода.
• Регион и даты: известные значения либо явная неопределённость, без подстановки удобных условий.
• Назначение: проверенный домен продавца отдельно от адреса партнёрского перехода.

Разделите ссылки и обязанности

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

Товарный URL отвечает на вопрос «какой товар», домен продавца задаёт контекст магазина, а партнёрская ссылка описывает маршрут перехода. Подменять одно поле другим при нехватке данных опасно.

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

Стабильный ID и ключ объединения решают разные задачи

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

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

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

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

Проверьте контракт на плохих входах

1. Передайте неожиданный контейнер вместо массива и убедитесь, что формат не угадывается.
2. Проверьте служебный текст вместо кода, SKU, неизвестную страну и противоречивые даты.
3. Сравните одинаковые коды разных магазинов и разные кампании одного продавца.
4. Проверьте обновление версии схемы, неполную выгрузку и повторную обработку записи.

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