Товарний фід для ChatGPT: вимоги, параметри та інструкція

Рекламна платформа ChatGPT Ads створює товарні оголошення безпосередньо з каталогу магазину. Рекламодавець завантажує файл із товарами, обирає набір позицій для групи оголошень і налаштовує шаблон, який підставляє в оголошення назву, опис, ціну, зображення та посилання на сторінку товару. Від якості цього файлу залежить, скільки позицій пройде обробку і буде допущено до показу.

OpenAI використовує для реклами ту саму специфікацію товарного файлу, що й для товарного пошуку в ChatGPT (Agentic Commerce). Базові поля забезпечують видимість товару в пошуку. Рекламні поля вмикають обробку товару для оголошень. Окремий набір полів відповідає за оформлення покупки всередині ChatGPT. У статті описано стабільну версію схеми (Stable), яку OpenAI рекомендує для робочих інтеграцій. Чернеткова версія (Draft) опублікована для планування і зворотного зв'язку, у продакшені вона поки не підтримується.

Принцип роботи товарного фіду в ChatGPT

OpenAI приймає фід як повний знімок каталогу (full snapshot). Кожне вивантаження вважається актуальним джерелом даних про весь асортимент, тому файл містить усі товари, включно з тими, яких тимчасово немає на складі. Рекомендована частота оновлення становить щонайменше один раз на добу.

Кожен рядок файлу описує одну позицію, доступну для купівлі. Якщо футболка продається в чотирьох розмірах і трьох кольорах, фід містить 12 рядків з окремими ідентифікаторами, об'єднаних спільним group_id. Кожен такий рядок має власну ціну, наявність, посилання і зображення.

Рекламне оголошення формується з шаблону типу product_ad_template. Шаблон підтримує чотири макроси: {{brand}} підставляє бренд, {{product.title}} підставляє назву, {{product.body}} підставляє опис, {{product.price}} підставляє ціну. Зображення і цільову сторінку оголошення система бере з полів image_url та url обраного товару, тому окремий креатив і target_url для таких кампаній не завантажуються. Одна група оголошень може містити лише один активний шаблон.

Товар, який зник із чергового знімка, OpenAI не видаляє миттєво. Система зберігає останній оброблений запис до 14 днів, щоб позиції не випадали з показу через затримку одного з файлів. Щоб зняти товар із пошуку під час наступної обробки, достатньо передати is_eligible_search=false. Для повного видалення позицію прибирають з усіх файлів наступних знімків, і збережений запис спливає протягом 14 днів. Для реклами OpenAI радить явно передавати availability=out_of_stock для товарів, які не повинні показуватися.

Формати файлів і технічні вимоги до вивантаження

Фід передається в OpenAI через SFTP. Пріоритетним форматом є Parquet, бажано зі стисненням zstd. Також підтримуються стиснені файли jsonl.gz, csv.gz і tsv.gz. Покроковий посібник OpenAI з рекламних фідів використовує як приклад CSV-файл. Кодування для всіх форматів одне: UTF-8.

Назва файлу повинна бути стабільною. Під час кожного оновлення файл перезаписують новим знімком з тим самим ім'ям. Великий каталог розбивають на кілька частин (шардів). OpenAI рекомендує розміщувати до 500 тисяч товарів в одному файлі та тримати розмір файлу в межах приблизно 500 МБ. Набір шардів теж лишається незмінним від оновлення до оновлення. Кожен товар присутній лише в одному шарді. Розподіл товарів між файлами краще прив'язати до item_id детермінованим правилом, наприклад залишком від ділення хешу ідентифікатора на кількість файлів. Якщо в одному SFTP-розташуванні зберігаються фіди кількох брендів, назви файлів починають із префікса бренду.

Усі файли розміщують безпосередньо в кореневому каталозі SFTP. Вкладені папки спричиняють діагностику invalid_sftp_directory_layout. Кореневий каталог OpenAI розглядає як увесь каталог магазину, тому маркер завершення вивантаження не потрібен. Після того як файли деякий час не змінюються, система обробляє весь вміст кореня. Шарди варто завантажувати без тривалих пауз. Якщо обробка почалася до надходження всіх частин, OpenAI повторно обробить каталог після завершення завантаження.

Товари зіставляються за item_id. Назва файлу на цей процес не впливає, тому перенесення позиції з одного шарда в інший не скидає її історію.

Підготовка акаунта і доступу SFTP

Для роботи потрібні рекламний акаунт ChatGPT Ads, ключ Advertiser API з правами на керування фідами і доступ до API товарних фідів. Сторінки товарів і зображення повинні відкриватися публічно за HTTPS. Якщо функція фідів в акаунті недоступна, OpenAI радить звернутися до команди супроводу акаунта. Налаштування через API складається з п'яти кроків.

1. Створіть фід запитом POST https://api.ads.openai.com/v1/feeds, передавши назву і список країн, наприклад "countries": ["US"]. Відповідь містить feed_id, який знадобиться в усіх наступних запитах.
2. Налаштуйте доступ запитом POST /v1/feeds/{feed_id}/sftp_access. Параметр authentication_method приймає значення password або ssh_key. Для пароля API повертає URI підключення і пароль, повторна генерація пароля анулює попередній. Для входу за SSH у полі ssh_public_key передають повний вміст публічного SSH-ключа.
3. Підготуйте файл каталогу за схемою, описаною нижче.
4. Підключіться SFTP-клієнтом і завантажте файл у корінь, наприклад командою put /path/to/catalog.csv catalog.csv.
5. Перевірте результат обробки в історії завантажень.

Успішна передача файлу підтверджує лише сам факт завантаження. Обробка відбувається асинхронно. Лічильник товарів, придатних для реклами, отримують запитом GET /v1/feeds з параметром include[]=product_count, і під час першого імпорту він може залишатися нульовим. Призупинити або відновити SFTP-доступ дозволяють запити POST /v1/feeds/{feed_id}/sftp_access/pause та /activate. Ці дії стосуються тільки каналу завантаження. Показ оголошень зупиняють окремо на рівні кампанії, групи або оголошення.

Фід можна завантажити і через інтерфейс Ads Manager. Схема файлу при цьому та сама, з додатковою рекламною вимогою щодо прапорця is_ads_eligible.

Обов'язкові поля фіду

Специфікація визначає дев'ять обов'язкових полів. Кожне з них повинно мати значення в кожному рядку. Якщо у файлі немає потрібної колонки, історія завантажень покаже діагностику missing_required_column.

Поле item_id містить стабільний ідентифікатор товару або варіанта, унікальний у межах фіду. Його ніколи не використовують повторно для іншої позиції, і він лишається незмінним після зміни ціни, назви чи фото. Для магазину на OpenCart або WooCommerce зручно брати SKU чи комбінацію ідентифікатора товару з ідентифікатором опції.

Поле title містить назву товару з урахуванням обраного варіанта. OpenAI рекомендує вкладатися в 150 символів. Колір і розмір у назві варіанта роблять оголошення конкретнішим для покупця.

Поле description передає фактичний опис конкретного товару простим текстом без HTML-розмітки, обсягом до 5000 символів. Рекламний шаблон підставляє цей текст у тіло оголошення через макрос {{product.body}}, тому перші речення опису варто присвятити властивостям, які найбільше впливають на рішення про купівлю.

Поле url веде на сторінку товару, де вже вибрано потрібний варіант, якщо сайт це підтримує. Адреса повинна бути абсолютною, стабільною і публічно доступною. UTM-мітки для аналітики додають через параметр landing_page_configuration кампанії, групи чи оголошення.

Поле brand вказує бренд так, як його позначено на сторінці товару. Поле seller_name містить назву продавця, який пропонує товар. Специфікація вимагає реальних назв і забороняє заглушки.

Поле image_url містить пряме посилання на головне зображення у форматі JPEG або PNG. На фото повинен бути саме той варіант, який описує рядок.

Поле availability приймає одне з п'яти значень: in_stock, out_of_stock, pre_order, backorder, unknown. Порожнє, пропущене або нерозпізнане значення призводить до відхилення рядка. Значення unknown передають явно, коли статус складу невідомий, і система не трактує його як наявність. pre_order позначає товар, який продається до офіційного випуску. backorder позначає товар, що тимчасово очікує поставки. Жодне з цих значень не планує автоматичної зміни статусу, тому фід оновлюють, щойно товар з'являється або закінчується.

Поле price передає звичайну ціну. Формат запису складається із суми в основних одиницях валюти, пробілу і трилітерного коду ISO 4217 великими літерами. Запис 79.99 USD означає 79 доларів 99 центів. Десятковим роздільником слугує крапка. Роздільники тисяч, експоненційний запис і зайві знаки після коми не допускаються, для USD використовують рівно два знаки. Ціна повинна бути більшою за нуль і відповідати сумі до оплати без округлень. Поширена помилка експорту з українських CMS полягає в локальному форматі на кшталт «1 299,00 грн», який не відповідає специфікації і дає діагностику invalid_value. Валюту фіду погоджують під час налаштування. Стандартне вивантаження у форматі OpenAI зараз орієнтоване на ринок США, тому приклади в цій статті наведено в доларах.

Правила заповнення значень

Необов'язкове поле з невідомим значенням просто пропускають. Пропущене поле, JSON null і порожня клітинка CSV однаково означають відсутність даних. Рядки-заглушки null, unknown чи n/a використовувати заборонено, виняток становить лише unknown у полі availability. Порожнє значення не дорівнює нулю чи false.

Логічні поля у JSON передають як true або false, у CSV і TSV як рядки true та false малими літерами. Ідентифікатори зберігають як рядки, щоб не втратити нулі на початку, адже GTIN 09506000134352 після перетворення на число перетвориться на некоректний код. Клітинку CSV, що містить кому, лапки або перенесення рядка, беруть у подвійні лапки і подвоюють вбудовані лапки. Об'єкти на кшталт variant_dict у CSV і TSV серіалізують як JSON-рядок. Усі URL повинні бути абсолютними, з протоколом HTTP або HTTPS, причому OpenAI рекомендує HTTPS.

Варіанти товарів та ідентифікатори

Схема розрізняє три рівні ідентифікації. item_id позначає конкретну позицію, group_id позначає батьківський товар, offer_id позначає пропозицію конкретного продавця. Усі три значення лишаються стабільними після змін ціни, залишків, назви чи фото. Ціну в offer_id включати заборонено.

Для кожного варіанта створюють окремий рядок з унікальним item_id, спільним group_id, прапорцем listing_has_variations=true та об'єктом variant_dict, наприклад {"color":"Black","size":"42"}. Значення group_id повинно відрізнятися від кожного item_id у групі. Назви опцій однакові для всієї групи, комбінації значень унікальні. В одну групу об'єднують лише варіанти одного товару в тому вигляді, як їх подано на сайті. Атрибути верхнього рівня, як-от color і size, повинні збігатися зі значеннями у variant_dict, оскільки система не узгоджує суперечливі дані самостійно.

Поле gtin приймає один код із рівно 8, 12, 13 або 14 цифр з коректною контрольною цифрою, без пробілів і дефісів. UPC-A подається як 12-значний GTIN, ISBN-13 як 13-значний. ISBN-10 специфікація не приймає. GTIN ідентифікує конкретну товарну одиницю, тому кожен варіант має власний код.

Контрольну цифру варто перевіряти до вивантаження. Алгоритм простий: цифри від передостанньої справа наліво почергово множать на 3 і на 1, результати додають і підбирають контрольну цифру, яка доповнює суму до числа, кратного 10. Для умовного коду з українським префіксом GS1 482 і основою 482123456789 сума зважених цифр дорівнює 125, найближче кратне десяти число становить 130, отже контрольна цифра 5 і повний код 4821234567895.

Поле mpn містить артикул виробника зі збереженням оригінального регістру і пунктуації. Його передають разом із brand. Вигадувати MPN для заміни відсутнього GTIN специфікація забороняє.

Характеристики товару

Поле condition приймає значення new, refurbished або used. Порожнє значення може бути сприйняте як new, тому вживані й відновлені товари позначають завжди. Поле product_category містить шлях категорії від загальної до вузької через символ >, наприклад Apparel & Accessories > Shoes. Поле material описує основні матеріали, color передає колір відповідно до фото, size передає мітку розміру.

Поле gender приймає male, female або unisex. Поле age_group приймає newborn, infant, toddler, kids або adult і описує цільову аудиторію товару. Вікових обмежень на купівлю це поле не встановлює.

Для габаритів у нових фідах використовують об'єкт dimensions. Він містить додатні десяткові рядки щонайменше для двох із трьох вимірів length, width, height та одиницю unit зі значенням in, cm, ft, m або mm. Інші назви полів в об'єкті недопустимі, порожній об'єкт вважається помилкою. Окремі колонки length, width, height з обов'язковою dimensions_unit залишаються для сумісності зі старими фідами і ігноруються, якщо присутній dimensions. Габарити вказують для самого товару без транспортної упаковки.

Поле weight передає додатну вагу нетто без упаковки і вимагає одиниці в полі item_weight_unit зі значенням g, kg, oz або lb. Система не конвертує одиниці і не визначає їх за ринком, тому всі перерахунки виконують до вивантаження.

Зображення, акційні ціни та наявність

Додаткові ракурси товару передають у полі additional_image_urls. У JSONL це масив рядків, у CSV це один рядок з URL через кому. Кома всередині адреси кодується як %2C. Пробіли й крапки з комою як роздільники списку не підтримуються. Некоректні URL система пропускає без відхилення рядка.

Поле sale_price передає поточну акційну ціну. Вона повинна бути більшою за нуль, строго меншою за price і вказаною в тій самій валюті. Акційна ціна, що дорівнює звичайній, перевищує її або записана в іншій валюті, не використовується. Дати початку й кінця розпродажу в поточному контракті не керують ціною автоматично, тому фід оновлюють у момент старту і завершення акції.

Продавець, доставка, повернення і відгуки

Поле seller_url веде на вітрину або профіль продавця. Для маркетплейсу в seller_name вказують продавця товару. Поле marketplace_seller називає майданчик, де відбувається оплата. Поле marketplace_seller працює лише після окремого налаштування інтеграції.

Вартість доставки у форматі OpenAI передає поле shipping_price: невід'ємна сума в тій самій валюті, що й price. Нуль означає безкоштовну доставку. Порожнє поле означає, що вартість невідома. Інтеграції з окремим налаштуванням приймають поле shipping у форматі country:region:service_class:price, наприклад US::Standard:5.00 USD. Позиція регіону зберігається порожньою, якщо регіон не застосовується. Одну й ту саму вартість доставки двома способами одночасно не передають.

Політику повернення описують трьома полями. accepts_returns зі значенням true або false фіксує, чи приймає продавець повернення. return_deadline_in_days містить додатне ціле число днів і подається тільки разом з accepts_returns=true. return_policy містить URL сторінки з умовами. Посилання на політику не встановлює і не змінює значення accepts_returns. Для товару без права повернення передають accepts_returns=false без строку, за бажанням з посиланням на умови.

Рейтинг товару передають полями review_count і star_rating. Перше містить невід'ємну кількість відгуків саме про товар без відгуків про магазин. Друге містить середню оцінку за шкалою від 0 до 5 з двома знаками після коми, наприклад 4.50. Обидва значення описують ту саму вибірку відгуків. Якщо сайт показує спільні відгуки для всіх варіантів, кожен рядок групи отримує той самий агрегат без повторного підсумовування. Товар без відгуків рейтингу не має.

Окремого налаштування інтеграції потребують ще кілька полів. store_review_count і store_star_rating передають рейтинг магазину. accepts_exchanges вказує на можливість обміну. is_digital позначає цифровий товар без фізичної доставки. size_system задає розмірну систему зі значеннями US, UK, EU, DE, FR, JP, CN, IT, BR, MEX або AU. Проста присутність цих колонок у стандартному файлі їх не активує.

Таблиця параметрів фіду

Таблиця зводить усі поля стабільної схеми файлового завантаження. Статус «потребує налаштування» означає, що поле працює лише після узгодження з OpenAI під час підключення.

Приклад файлу для завантаження

Нижче наведено JSON-фрагмент з однією позицією товару:

{"item_id":"KW-SOCK-GRY-M","group_id":"KW-SOCK","listing_has_variations":true,"variant_dict":{"color":"Gray","size":"M"},"title":"Merino wool socks — gray, size M","description":"Warm merino wool hiking socks with reinforced heel and toe.","url":"https://example.com/products/merino-socks?color=gray&size=m","brand":"Karpaty Wool","seller_name":"Karpaty Wool Store","image_url":"https://example.com/images/merino-socks-gray.jpg","availability":"in_stock","price":"24.00 USD","sale_price":"19.00 USD","is_ads_eligible":true}