Referencia de Campos
Esta página documenta cada campo soportado en el Catálogo de Productos de Fanplayr. Úsela para comprender con qué datos de producto puede trabajar Fanplayr y cómo debe estructurarse cada campo.
¿No sabe por dónde empezar?
Si es nuevo en el formato de catálogo, lea primero la Descripción general. Explica conceptos clave como el modelo de producto PRIMARY/VARIANT y qué campos son los más importantes.
Producto
El objeto Product es la estructura de nivel superior para cada artículo en el catálogo. La interfaz TypeScript a continuación ofrece a los desarrolladores una visión rápida de la forma completa; pase el cursor sobre cualquier tipo para explorarlo. Los lectores no técnicos pueden ir directamente a las descripciones de los campos a continuación.
interface Product {
id: string; // required
type?: Type;
primaryProductId?: string;
categories: string[]; // required
title: string; // required
brands?: string[];
description?: string;
languageCode?: string;
priceInfo: PriceInfo; // required
availability?: Availability;
availableQuantity?: number;
uri: string; // required
images?: Image[];
audience?: Audience;
colorInfo?: ColorInfo;
sizes?: string[];
materials?: string[];
patterns?: string[];
conditions?: string[];
}
Ejemplo
Un ejemplo completo de un objeto Product válido:
{
"id": "805371A",
"type": "PRIMARY",
"categories": ["Women > Shoes", "Sports & Fitness > Shoes"],
"title": "Red Shoes",
"description": "Fancy red shoes",
"brands": ["Designer Brand"],
"availability": "IN_STOCK",
"availableQuantity": 30,
"languageCode": "en",
"priceInfo": {
"price": 89.99,
"originalPrice": 119.99,
"currencyCode": "USD"
},
"uri": "https://www.store.com/shoes/red-shoes",
"images": [
{
"uri": "https://www.store.com/images/805371.jpg",
"width": 500,
"height": 500
}
]
}INFO
El ejemplo anterior incluye saltos de línea para facilitar la lectura. En un archivo de catálogo, cada producto debe ser una única línea codificada en JSON. El archivo debe estar codificado en UTF-8.
Campos
id
- Tipo:
string - Requerido
- Tamaño máximo: 128 bytes
Un identificador único para este producto dentro del catálogo. No puede haber dos productos en el mismo catálogo con el mismo id.
Este valor debe coincidir con el ID de producto rastreado en su integración de Fanplayr; se utiliza para correlacionar los datos del catálogo con el comportamiento del comprador, como las visitas a páginas de productos y las compras.
type
- Tipo: enum
Type - Predeterminado: inferido de
primaryProductId
Indica si este producto es un producto de nivel superior (PRIMARY) o una variación de uno (VARIANT). Consulte Type para ver la lista completa de valores.
En la mayoría de los casos, este campo puede omitirse: Fanplayr inferirá el valor correcto basándose en primaryProductId:
- El valor predeterminado es
'PRIMARY'cuandoprimaryProductIdestá ausente o es igual aid. - El valor predeterminado es
'VARIANT'cuandoprimaryProductIddifiere deid.
primaryProductId
- Tipo:
string
El id del producto PRIMARY al que pertenece esta variante. Se utiliza para agrupar variantes bajo su producto padre.
- Para productos
PRIMARY: dejar vacío, o establecer el mismo valor queid. - Para productos
VARIANT: debe establecerse aliddel producto PRIMARY padre.
categories
- Tipo:
string[] - Requerido (al menos una entrada)
- Tamaño máximo: 1,000 bytes (codificado en JSON)
Las categorías a las que pertenece este producto. Un producto puede pertenecer a múltiples categorías. Proporcionar la ruta completa de la categoría —en lugar de solo la categoría hoja— mejora significativamente la calidad de las recomendaciones y la búsqueda.
Use > para separar los niveles de jerarquía. Si > aparece en el nombre de una categoría, reemplácelo con otro carácter como "|".
"categories": [
"Shoes & Accessories > Shoes",
"Sports & Fitness > Athletic Clothing > Shoes"
]title
- Tipo:
string - Requerido
- Tamaño máximo: 500 bytes
El nombre del producto tal como aparece en su tienda. Este valor se muestra en los widgets de recomendación que se muestran a los compradores, por lo que debe coincidir exactamente con su tienda.
brands
- Tipo:
string[] - Tamaño máximo: 1,000 bytes (codificado en JSON)
La marca asociada a este producto. Se utiliza para impulsar el filtrado y las recomendaciones conscientes de la marca. Se admiten múltiples marcas si es necesario.
description
- Tipo:
string - Tamaño máximo: 500 bytes
Una descripción del producto en texto plano. Se utiliza para mejorar la relevancia de las recomendaciones. Proporcionar una buena descripción ayuda a Fanplayr a comprender mejor qué es el producto.
languageCode
- Tipo:
string
El idioma utilizado en campos de texto como title y description. Debe ser una etiqueta de idioma BCP 47 válida (ej. "en", "fr", "de").
priceInfo
- Tipo: objeto
PriceInfo - Requerido
Información de precios para este producto, incluyendo precio actual, precio original y moneda. Consulte PriceInfo para obtener todos los detalles.
availability
- Tipo: enum
Availability - Predeterminado:
'IN_STOCK'
La disponibilidad actual del producto. Fanplayr utiliza este campo para evitar recomendar productos que los compradores no pueden adquirir. Consulte Availability para ver la lista completa de valores.
availableQuantity
- Tipo:
number
El número de unidades actualmente en stock.
uri
- Tipo:
string - Requerido
La URL canónica de la página de detalles del producto. Se utiliza como destino del enlace cuando un producto se muestra en un widget de recomendación.
images
- Tipo: objeto[]
Image
Una lista de imágenes para este producto. Las imágenes del producto se muestran directamente en los widgets de recomendación — se recomienda encarecidamente proporcionar imágenes precisas y de alta calidad. Las imágenes deben tener al menos 500×500px. Consulte Image para obtener todos los detalles.
audience
- Tipo: objeto
Audience
La audiencia prevista para este producto. Proporcionar datos de audiencia ayuda a Fanplayr a ofrecer recomendaciones más relevantes — por ejemplo, evitando recomendar productos para hombres en una página de categoría para mujeres. Consulte Audience para obtener todos los detalles.
colorInfo
- Tipo: objeto
ColorInfo
Información de color para el producto. Particularmente valiosa para tiendas de moda y vestimenta. Proporcionar este campo permite el filtrado basado en colores, mejora las recomendaciones y permite mostrar muestras de color en los widgets de recomendación de productos. Consulte ColorInfo para obtener todos los detalles.
sizes
- Tipo:
string[] - Máximo: 20 valores
Las tallas disponibles para este producto. Para representar diferentes sistemas o tipos de tallas, use el formato [[size_system:]size_type:]size_value]:
"US:MENS:M"— sistema de tallasUS, tipo de tallaMENS, valor de tallaM"GIRLS:27"— sin sistema de tallas, tipo de tallaGIRLS, valor de talla27"32 inches"— sin sistema ni tipo de talla, valor de talla32 inches
materials
- Tipo:
string[] - Máximo: 20 valores
El material o materiales de los que está hecho este producto (ej. "leather", "cotton", "wood").
patterns
- Tipo:
string[] - Máximo: 20 valores
El patrón o estampado gráfico del producto (ej. "striped", "polka dot", "paisley").
conditions
- Tipo:
string[] - Máximo: 1 valor
La condición del producto. Aunque se define como un array para mantener la coherencia con otros campos, solo se admite un valor. Utilice los valores estándar siempre que sea posible:
"new""refurbished""used"
Tipos
Los siguientes tipos son referenciados por campos en el objeto Product.
Type
El tipo de un producto. Determina si este producto es un artículo de nivel superior o una variación de otro.
| Valor | Descripción |
|---|---|
"PRIMARY" | Un producto de nivel superior. Los productos PRIMARY pueden tener múltiples productos VARIANT agrupados bajo ellos. |
"VARIANT" | Una variación de un producto PRIMARY. Las variantes suelen compartir atributos como el título y la marca con su padre, pero difieren en propiedades como la talla, el color o el precio. |
PriceInfo
Información de precios para un producto.
interface PriceInfo {
currencyCode: string; // required
price: number; // required
originalPrice?: number;
cost?: number;
}currencyCode
- Tipo:
string - Requerido
El código de moneda ISO 4217 de 3 letras para todos los precios en este objeto (ej. "USD", "AUD", "GBP").
price
- Tipo:
number - Requerido
El precio de venta actual del producto. Este es el precio que se muestra a los compradores y se utiliza en los widgets de recomendación.
originalPrice
- Tipo:
number
El precio del producto antes de cualquier descuento. Si se omite o es cero, el valor predeterminado es el de price. Cuando se proporciona, originalPrice debe ser mayor o igual que price. Proporcionar este campo permite a Fanplayr identificar y dirigir productos en oferta y con descuento.
cost
- Tipo:
number
El costo de los bienes para este producto. Se utiliza internamente para la elaboración de informes de beneficio bruto. Este valor nunca se muestra a los compradores.
Availability
El estado de disponibilidad de un producto. Fanplayr lo utiliza para evitar recomendar productos que los compradores no pueden adquirir.
- Predeterminado:
"IN_STOCK"
| Valor | Descripción |
|---|---|
"IN_STOCK" | El producto está disponible para comprar ahora. |
"OUT_OF_STOCK" | El producto no está disponible actualmente. |
"PREORDER" | El producto aún no ha sido lanzado, pero está disponible para pre-ordenar. |
"BACKORDER" | El producto está temporalmente agotado, pero disponible para pedidos pendientes. |
Image
Una imagen asociada a un producto. Las imágenes se muestran directamente en los widgets de recomendación. Las imágenes deben tener al menos 500×500px.
interface Image {
uri: string; // required
width?: number;
height?: number;
}uri
- Tipo:
string - Requerido
La URL de la imagen. Debe ser una URI válida codificada en UTF-8 con una longitud máxima de 5,000 caracteres.
width
- Tipo:
number
El ancho de la imagen en píxeles.
height
- Tipo:
number
La altura de la imagen en píxeles.
Audience
La audiencia prevista para un producto, utilizada para mejorar la relevancia de las recomendaciones.
interface Audience {
genders?: Gender[];
ageGroups?: AgeGroup[];
}
genders
- Tipo:
('male' | 'female' | 'unisex')[] - Máximo: 5 valores
Los géneros a los que está destinado este producto. Utilice los valores estándar siempre que sea posible:
"male""female""unisex"
ageGroups
- Tipo:
('newborn' | 'infant' | 'toddler' | 'kids' | 'adult')[] - Máximo: 5 valores
Los grupos de edad a los que está destinado este producto. Utilice los valores estándar siempre que sea posible:
"newborn"— hasta 3 meses de edad"infant"— de 3 a 12 meses de edad"toddler"— de 1 a 5 años de edad"kids"— de 5 a 13 años de edad"adult"— típicamente adolescentes o mayores
ColorInfo
Información de color para un producto. Particularmente valiosa para tiendas de moda y vestimenta. Proporcionar este campo permite el filtrado basado en colores, mejora las recomendaciones y permite mostrar muestras de color en los widgets de recomendación de productos.
interface ColorInfo {
colorFamilies?: string[];
colors?: string[];
}colorFamilies
- Tipo:
string[] - Máximo: 5 valores
La familia o familias de colores amplias a las que pertenece este producto. Normalmente un producto tiene solo una familia de colores — use "Mixed" en lugar de múltiples valores cuando sea apropiado.
Utilice los valores estándar siempre que sea posible:
"Red" "Pink" "Orange" "Yellow" "Purple" "Green" "Cyan" "Blue" "Brown" "White" "Gray" "Black" "Mixed"
colors
- Tipo:
string[] - Máximo: 75 valores
El nombre o nombres de color específicos para este producto, tal como aparecen en su tienda (ej. "Midnight Navy", "Rose Gold"). Estos pueden diferir de los valores estándar de colorFamilies. Normalmente un producto tiene solo un color — use "Mixed" en lugar de múltiples valores cuando sea apropiado.