Извлечение данных о товарах через API: JSON для PIM

Задача интеграции

Для PIM-интеграции сначала извлеките подтверждаемые характеристики из данных поставщика, затем проверьте JSON и только после этого обновляйте карточку. Модель не должна дописывать материал, совместимость или сертификат, которых нет в источнике. Ниже — текстовый пример через API429; он не требует привязки к одной версии Gemini.

Подготовка исходного текста

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

Схема полей

Учебный документ и эталон JSON

Все данные ниже вымышлены. JSON подготовлен как эталон для проверки: он не является результатом замера или гарантией ответа модели.

SKU: DEMO-42.
Название: Рюкзак «Север».
Цвет: синий.
Объём: 20 л.

{
  "sku": {
    "value": "DEMO-42",
    "quote": "SKU: DEMO-42."
  },
  "name": {
    "value": "Рюкзак «Север»",
    "quote": "Название: Рюкзак «Север»."
  },
  "colour": {
    "value": "синий",
    "quote": "Цвет: синий."
  },
  "volume": {
    "value": "20 л",
    "quote": "Объём: 20 л."
  },
  "material": {
    "value": null,
    "quote": null
  }
}

Подключение к API429

Выберите точный ID модели в каталоге, затем проверьте доступ своего ключа по GET /v1/models. Используйте тот же ключ и базовый URL, что и при генерации. Само наличие модели на сайте не подтверждает доступ конкретного ключа.

curl https://gateway.api429.com/v1/models \
  -H "Authorization: Bearer $API429_API_KEY"

Ключ храните в переменной окружения API429_API_KEY, выбранный ID — в API429_MODEL. Не записывайте секрет в исходник или журнал. Контракт запроса и примеры авторизации — в документации API429.

Запрос и проверка ответа

Возьмите полный пример Python с валидатором и замените в нём только эти две строки:

FIELDS = ('sku', 'name', 'colour', 'volume', 'material')
SOURCE = 'SKU: DEMO-42.\nНазвание: Рюкзак «Север».\nЦвет: синий.\nОбъём: 20 л.\n'

Запрос использует POST /v1/chat/completions с полями model, messages, max_tokens, stream. Пример выводит результат, прошедший структурные и текстовые проверки, и сам не создаёт записей в рабочей системе. Параметры специальных JSON-режимов выбранной модели проверяйте отдельно; код не предполагает их поддержку по одному имени модели.

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

Проверка перед передачей в систему

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

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

Какие ошибки включить в тестовую выборку

Включите в контрольную выборку два похожих SKU, конфликтующие единицы и отсутствующий материал. Если источник не содержит совместимость с конкретным устройством, ожидайте null, а не предположение модели. Проверяйте сохранность регистра и ведущих нулей в артикулах.

Повторы и стоимость обработки

Храните идентификатор и версию исходного документа, а также состояние обработки в своём приложении. После перезапуска не создавайте вторую запись для уже принятого результата. При 429 сначала изучите сообщение и баланс; повторяйте только временные ошибки с ограничением попыток. Неудачный разбор JSON и HTTP-ошибка требуют разных действий.

Выбирайте модель по своему набору документов, а не по названию семейства. Считайте цену принятого результата вместе с повторами и проверкой; текущие тарифы API429 и сравнение Gemini отделены от проверки качества. Сначала запустите небольшую размеченную выборку, затем расширяйте поток.

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

Можно ли сразу публиковать результат на маркетплейсе?

Сначала сопоставьте значения с карточкой и правилами площадки. Успешный HTTP-ответ не проверяет товарные свойства. Пример выводит JSON, но ничего не публикует.

Как обрабатывать одинаковый товар от нескольких поставщиков?

Сохраняйте идентификатор поставщика и версию источника. При конфликте значений отправляйте различия на проверку; не выбирайте первое непустое поле без правила приоритета.