Data Feeds

Descripción general #
Independientemente de tu plataforma de eCommerce y de si contamos con una integración o no, siempre puedes sincronizar datos con Clerk.io a través de uno o más feeds en formato JSON.
Admitimos dos variaciones diferentes de los feeds:
- Múltiples archivos para diferentes objetos
- Un único archivo que contiene todos los objetos
Ambas soluciones utilizan la misma estructura de objetos, pero cuentan con diversas funcionalidades para asegurar e importar los datos, que se describen en esta guía.
Todos los tipos de objeto excepto pedidos se reflejan desde los feeds en la base de datos de Clerk.io. Si eliminas un objeto del feed, Clerk.io lo eliminará de la base de datos cuando se importe. Los pedidos se registran y se mantienen en la base de datos.
Recomendamos generar los feeds JSON al menos una vez al día, aunque idealmente con mayor frecuencia. También pueden generarse bajo demanda cuando el importador de Clerk.io los solicite.
El/los feed(s) deben estar disponibles en una URL accesible desde los servidores de Clerk.io.
https://your-website.com/json-feed.json
Tipos de datos #
Clerk.io admite enteros (int), decimales (float), cadenas de caracteres (str), booleanos (bool), listas (array) y diccionarios (dict, u objetos JSON) como valores de atributos.
Las listas y diccionarios personalizados deben ser planos: no pueden contener otras listas o diccionarios. Por ejemplo, {"material": "cotton", "weight": 0.5} es compatible, pero {"details": {"material": "cotton"}} no lo es.
Valores nulos #
Los valores null no controlados son una fuente segura de errores con el tiempo. Si un atributo no existe para un producto, categoría o pedido, simplemente omite el atributo.
Tipos de valor de ID #
Recomendamos encarecidamente usar enteros como IDs, pero también es posible usar cadenas. Debes comprometerte con un solo tipo en tu feed; es decir, todos los IDs de tus objetos deben ser del mismo tipo.
Nombres de atributos #
Los atributos de los objetos solo pueden contener valores alfanuméricos (A-Z, 0-9) y guiones bajos.
Así, un nombre de atributo válido podría ser brand_name, pero no läbel-mærke
El uso de guiones o caracteres especiales en los nombres de los atributos hará que se ignoren durante la sincronización.
Estructura de objetos #
Los feeds JSON consisten en una lista de objetos, con varios campos que conforman sus datos.
Cada objeto debe contener los campos obligatorios para su tipo. También puedes enviar cualquier atributo personalizado que necesites, utilizando los tipos de datos compatibles. Los atributos recomendados y opcionales mencionados abajo son ejemplos, no una lista completa de lo que puedes enviar.
Productos #
Cada objeto representa un producto individual. Si tienes productos configurables, te recomendamos enviar solo el producto principal e incluir atributos que describan a los hijos, como color, size, material, etc.
A continuación puedes ver los campos obligatorios y los recomendados que suelen emplear las tiendas de eCommerce. Además de estos, puedes enviar cualquier atributo con los nombres que quieras, mientras tengan un tipo de dato soportado.
| Atributo | Importancia | Tipo | Descripción |
|---|---|---|---|
id | Obligatorio | int/str | El ID del producto, debe ser único por cada producto |
name | Obligatorio | str | El nombre del producto. |
description | Obligatorio | str | La descripción del producto. |
price | Obligatorio | float | El precio actual de venta del producto. |
list_price | Recomendado | float | El precio original de lista. Útil para mostrar descuentos. |
on_sale | Recomendado | bool | Indica si un producto está en oferta o no. |
image | Obligatorio | str | La URL completa de la imagen del producto. Cuando se use como miniatura recomendamos un tamaño máximo de 200x200px. |
url | Obligatorio | str | La URL del producto. |
categories | Obligatorio | array | Un array de IDs de categorías a las que pertenece el producto. |
created_at | Obligatorio | int | El timestamp UNIX de cuándo se creó el producto. |
brand | Recomendado | str | La marca del producto. |
color | Recomendado | dict | Un diccionario de color que contiene name, converted_name, image, y color_code. |
reviews_amount | Recomendado | int | El número de reseñas del producto. |
reviews_avg | Recomendado | float | La puntuación promedio de las reseñas del producto. |
Ejemplo JSON #
[
{
"id": 135,
"name": "Lightsaber",
"description": "Antique Rebel Lightsaber",
"price": 79995.95,
"list_price": 99995.95,
"on_sale": true,
"image": "https://galactic-empire-merch.com/images/a-r-lightsaber.jpg",
"url": "https://galactic-empire-merch.com/antique-rebel-lightsaber",
"brand": "Je'daii",
"categories": [987, 654],
"created_at": 1199145600,
"color": {
"name": "Emerald",
"converted_name": "Green",
"image": "https://galactic-empire-merch.com/images/a-r-lightsaber-emerald.jpg",
"color_code": "#7CFC00"
},
"reviews_amount": 164,
"reviews_avg": 4.8
},
{
"id": 261,
"name": "Death Star Deluxe",
"description": "Death Star - Guaranteed idiot proof",
"price": 99999999999999.95,
"list_price": 99999999999999.95,
"on_sale": false,
"image": "https://galactic-empire-merch.com/images/death-star.jpg",
"url": "https://galactic-empire-merch.com/death-star",
"brand": "Imperial Inc.",
"categories": [345678],
"created_at": 1197565600
}
]
Mantener Productos Sin Indexación #
Para algunas configuraciones, puedes querer mantener productos en la base de datos de Clerk.io sin mostrarlos en ningún resultado.
Si vendes entradas o artículos usados disponibles por tiempo limitado, es conveniente mantener el historial de estos productos, para que Clerk lo utilice para mejorar los resultados.
Para ello, agrega el atributo especial index: false a los productos que deban mantenerse sin indexar. Clerk usará el historial de sus ventas para mostrar resultados, pero nunca se mostrarán en ninguna llamada API.
Para el resto de productos, simplemente omite el atributo o déjalo como index: true.
Categorías #
Cada objeto representa una categoría individual. Clerk.io construye un árbol interno de categorías basado en las subcategorías proporcionadas para cada categoría.
A continuación puedes ver los campos obligatorios y ejemplos de campos opcionales que suelen emplear las tiendas de eCommerce.
| Atributo | Importancia | Tipo | Descripción |
|---|---|---|---|
id | Obligatorio | int/str | El ID único para la categoría. |
name | Obligatorio | str | El nombre de la categoría. |
url | Obligatorio | str | La URL de la categoría. |
subcategories | Obligatorio | array | Un array de IDs de categorías que son subcategorías de esta categoría. Puede ser una lista vacía para categorías sin subcategorías. |
image | Opcional | str | URL completa de la imagen de la categoría. |
description | Opcional | str | La descripción de la categoría. |
Ejemplo JSON #
[
{
"id": 1,
"name": "Imperial Goods",
"subcategories": [42, 25],
"url": "https://galactic-empire-merch.com/imperial-goods"
},
{
"id": 42,
"name": "Tatooine",
"subcategories": [],
"url": "https://galactic-empire-merch.com/imperial-goods/tatooine"
},
{
"id": 25,
"name": "Coruscant",
"subcategories": [],
"url": "https://galactic-empire-merch.com/imperial-goods/coruscant"
}
]
Pedidos #
Los pedidos se registran y no se eliminan al ser removidos del feed. Generalmente solo deben enviarse durante la primera importación, y pueden eliminarse después para ahorrar capacidad del servidor. Se pueden eliminar a través de nuestra CRUD API.
Cada objeto representa un pedido individual. Clerk.io usa los IDs de producto y el correo electrónico/ID de cliente en los pedidos para analizar el comportamiento del cliente e identificar tendencias. Junto con products, es el tipo de objeto más importante.
A continuación puedes ver los campos obligatorios y los opcionales. Para incluir datos de envíos, añade un array tracking al pedido. No envíes paquetes como objetos separados de primer nivel.
| Atributo | Importancia | Tipo | Descripción |
|---|---|---|---|
id | Obligatorio | int/str | El ID del pedido, debe ser único por pedido. |
products | Obligatorio | array | Los productos del pedido. Cada producto es un objeto con ID, cantidad y precio unitario. |
time | Obligatorio | timestamp unix | El momento en que se realizó el pedido, en formato Unix Timestamp. |
customer | Opcional | int/str | El ID del cliente. |
email | Opcional | str | El correo electrónico del cliente. Necesario para utilizar nuestros productos Auto-Email y Audience. |
tracking | Opcional | array | Un array de objetos de seguimiento para los envíos del pedido. Cada objeto debe contener un tracking_link y puede incluir tracking_code, status y status_text. |
Ejemplo JSON #
[
{
"id": 123458,
"customer": 789,
"email": "vader@the-death-star.com",
"products": [{"id":456,"quantity":1,"price":200.00}, {"id":789,"quantity":2,"price":120.00}],
"time": 1389871120,
"tracking": [
{
"tracking_code": "ABC123",
"tracking_link": "https://carrier.example/ABC123",
"status": "SENT",
"status_text": "Out for delivery"
}
]
},
{
"id": 123456,
"customer": 456,
"email": "obi.wan@kenobi.me",
"products": [{"id":456,"quantity":1,"price":200.00}, {"id":789,"quantity":2,"price":120.00},{"id":123,"quantity":2,"price":60.00}],
"time": 1389870977
},
{
"id": 123457,
"customer": "",
"products": [{"id":789,"quantity":2,"price":120.00}],
"time": 1389871090
}
]
Clientes #
Cada objeto representa un cliente individual. Los atributos proporcionados se fusionan luego con el email o el ID del cliente de los pedidos para crear un perfil de cliente único para la segmentación con
Audience.
A continuación puedes ver los campos obligatorios y ejemplos de campos opcionales que suelen emplear las tiendas de eCommerce.
| Atributo | Importancia | Tipo | Descripción |
|---|---|---|---|
id | Obligatorio | int/str | El ID del cliente, debe ser único por cliente. |
name | Obligatorio | str | Nombre completo del cliente. |
email | Obligatorio | str | Correo electrónico del cliente. |
subscribed | Obligatorio | bool | Booleano que indica si el cliente está suscrito a boletines. Este valor debe ser true para que Clerk.io pueda enviar emails de marketing a este cliente. |
zip | Opcional | str | Código postal del cliente. |
gender | Opcional | str | Género del cliente. |
age | Opcional | int | Edad del cliente. |
is_b2b | Opcional | bool | Booleano que indica si el cliente es una empresa. |
Ejemplo JSON #
[
{
"id": 135,
"name": "Luke Skywalker",
"email": "luke@rebels.com",
"subscribed": true,
"gender": "male",
"zip": "1134",
"is_b2b": "false"
},
{
"id": 165,
"name": "Leia Organa",
"email": "leia@royalty.org",
"subscribed": false,
"gender": "female",
"age": 19,
"interests": ["politics", "outlaws"],
"is_b2b": true
}
]
Páginas #
Cada objeto representa una sola página. Generalmente las páginas representan cualquier tipo de contenido en eCommerce que no es clasificado como producto o categoría. Puede tratarse de artículos, entradas de blog, páginas de aterrizaje, páginas de marcas y otros tipos de contenido escrito.
A continuación puedes ver los campos obligatorios y ejemplos de opcionales que suelen emplear las tiendas de eCommerce.
| Atributo | Importancia | Tipo | Descripción |
|---|---|---|---|
id | Obligatorio | int/str | ID de la página, debe ser único por página. |
type | Obligatorio | str | Tipo de contenido. Se utiliza para separar páginas como CMS, entradas de blog y páginas de aterrizaje. |
url | Obligatorio | str | URL completa de la página. |
title | Obligatorio | str | Título de la página. |
text | Obligatorio | str | Texto completo de la página. |
image | Opcional | str | URL completa de la imagen de la página. |
Ejemplo JSON #
[
{
"id": 135,
"type": "cms",
"url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
"title": "Open Hours",
"text": "The main text about our opening hours..."
},
{
"id": 1354,
"type": "blog",
"url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
"title": "New Blog Post",
"text": "The main text about our opening hours...",
"keywords": ["blog", "post", "new"]
}
]
Multi-idioma #
Clerk.io funciona mejor cuando creas Stores separadas para cada idioma. Cada Store puede configurarse con el idioma del contenido, lo que permite a Search entender mucho mejor la gramática y los errores ortográficos.
Además, los clientes de diferentes regiones o países suelen tener distintas preferencias y patrones de búsqueda, por lo que lo ideal es separar los datos de pedidos en diferentes Stores.
Otra opción es construir feeds JSON multi-idioma, donde todos los atributos de texto se proporcionan como objetos con los códigos de idioma como claves y las traducciones como valores.
Todos los atributos de texto deben tener claves de idioma incluso si el contenido es el mismo, para asegurar que sea buscable para el idioma correspondiente.
Al hacer llamadas API, incluye el parámetro language y la clave de idioma correspondiente para obtener los datos correctos.
Ejemplo JSON multi-idioma #
[
{
"id": 135,
"name": {
"english":"Lightsaber",
"spanish":"Sable de luz",
"italian":"Spada laser"
},
"description": {
"english":"Antique Rebel Lightsaber",
"spanish":"Sable de luz rebelde antiguo",
"italian":"Antica spada laser ribelle"
},
"price": 99995.95,
"image": {
"english":"https://galactic-empire-merch.com/images/a-r-lightsaber.jpg",
"spanish":"https://galactic-empire-merch.com/es/images/a-r-lightsaber.jpg",
"italian":"https://galactic-empire-merch.com/it/images/a-r-lightsaber.jpg"
},
"url": {
"english":"https://galactic-empire-merch.com/antique-rebel-lightsaber",
"spanish":"https://galactic-empire-merch.com/es/antique-rebel-lightsaber",
"italian":"https://galactic-empire-merch.com/it/antique-rebel-lightsaber"
},
"brand": "Je'daii",
"categories": [987, 654],
"created_at": 1199145600,
"color": {
"name": "Emerald",
"converted_name": "Green",
"image": "https://galactic-empire-merch.com/images/a-r-lightsaber-emerald.jpg",
"color_code": "#7CFC00"
},
"reviews_amount": 164,
"reviews_avg": 4.8
},
{
"id": 261,
"name": {
"english":"Death Star Deluxe",
"spanish":"Estrella de la Muerte de lujo",
"italian":"La Morte Nera Deluxe"
},
"description": {
"english":"Death Star - Guaranteed idiot proof",
"spanish":"Estrella de la Muerte: a prueba de idiotas garantizada",
"italian":"Morte Nera - A prova di idiota garantita"
},
"price": 99999999999999.95,
"image": {
"english":"https://galactic-empire-merch.com/images/death-star.jpg",
"spanish":"https://galactic-empire-merch.com/es/images/death-star.jpg",
"italian":"https://galactic-empire-merch.com/it/images/death-star.jpg"
},
"url": {
"english":"https://galactic-empire-merch.com/death-star",
"spanish":"https://galactic-empire-merch.com/es/death-star",
"italian":"https://galactic-empire-merch.com/it/death-star"
},
"brand": "Imperial Inc.",
"categories": [345678],
"created_at": 1197565600
}
]
Ejemplo de llamada #
curl -X GET \
https://api.clerk.io/v2/recommendations/popular \
-H 'Content-Type: application/json' \
-d 'key=your_store_public_key&limit=10&language=italian'
Idiomas soportados #
El idioma debe especificarse con su nombre exacto. Actualmente soportamos 54 idiomas. Si tu idioma no está en la lista inferior, elige uno relacionado o simplemente “english”. Funcionará igual, pero la neutralización de gramática en Search será menos efectiva.
- afrikaans
- albanian
- arabic
- armenian
- azerbaijani
- basque
- belarusian
- bengali
- bosnian
- bulgarian
- catalan
- chinese
- croatian
- czech
- danish
- dutch
- english
- estonian
- finnish
- french
- galician
- georgian
- german
- greek
- hebrew
- hindi
- hungarian
- icelandic
- indonesian
- irish
- italian
- japanese
- korean
- latvian
- lithuanian
- macedonian
- malay
- norwegian
- persian
- polish
- portuguese
- romanian
- russian
- serbian
- slovak
- slovenian
- spanish
- swedish
- filipino
- thai
- turkish
- ukrainian
- urdu
- vietnamese
Feeds múltiples #
Este es el enfoque recomendado, ya que es eficiente para tu servidor y ofrece el mayor grado de control.
Con este enfoque, creas archivos de feed individuales para cada uno de tus objetos. Esto utiliza el método de sincronización llamado Clerk.io JSON Feed V2.
Estos admiten content-type: application/x-ndjson o application/json.
Cada feed debe contener un array de objetos.
URL #
https://awsumstuff.com/feed/products.json
Salida #
[
{
"id": 135,
"name": "Lightsaber",
"description": "Antique Rebel Lightsaber",
"price": 99995.95,
},
...
]
Paginación #
Esta es una característica opcional que te permite paginar resultados codificando tu feed para aceptar los siguientes parámetros de consulta:
limit: Número de objetos a devolver por página.offset: Índice del primer objeto a devolver en una página.
El importador de Clerk.io puede configurarse para enviar estos parámetros a tu código de feed. Simplemente tienes que seleccionar la cantidad de objetos que deseas recuperar por página.
Cuando configuras la URL de tu feed, puedes utilizar {{limit}} y {{offset}} para agregar los datos como parámetros de consulta.
{{limit}} contendrá el número que configures en la configuración del importador. {{offset}} empezará en 0 en la primera llamada y crecerá según el limit.
Ejemplo:
- Llamada 1:
limit=100&offset=0 - Llamada 2:
limit=100&offset=100 - Llamada 3:
limit=100&offset=200
La condición de parada es cuando tu feed devuelve un array vacío.
URL #
https://awsumstuff.com/feed/products.json?limit={{limit}}&offset={{offset}}
Incrementos #
El uso de esta característica significa que Clerk.io dejará de eliminar objetos al importar, por lo que deberás utilizar llamadas a la CRUD API para eliminar objetos de la base de datos de Clerk.io.
La solución multi-feed admite la funcionalidad opcional de enviar sólo los datos que hayan cambiado desde un número determinado de días, en lugar de enviar todos los datos cada vez.
Para esto, asegúrate de que tu feed esté configurado para devolver solo los objetos modificados en una cantidad específica de días, cuando la solicitud incluya el parámetro de consulta modified_after.
Después, añade un número de días en el campo llamado Incremental time {{modified_after}} que se encuentra en la configuración del importador de Clerk.io.
Esto hará que el importador de Clerk.io mantenga todos los datos en la base de datos y sólo actualice los objetos incluidos en los feeds.
Para utilizar el número de días que configuraste, añade el parámetro de consulta modified_after a tu feed e incluye la etiqueta que insertará la cantidad de días que hayas configurado. Por ejemplo:
https://awsumstuff.com/feed/products.json?modified_after={{modified_after}}&limit={{limit}}&offset={{offset}}
Seguridad #
Recomendamos que el feed JSON sólo acepte conexiones cifradas SSL y utilice Autenticación HTTP si es posible.
Además, desde la configuración del importador puedes activar Token Authentication. Clerk.io incluirá entonces una cabecera de autorización en cada solicitud HTTP que deberás verificar antes de devolver los datos:
X-Clerk-Authorization: Bearer THE_TOKEN
Puedes verificar el token con una solicitud POST al endpoint token/verify:
curl -X POST \
https://api.clerk.io/v2/token/verify \
-H 'Content-Type: application/json' \
-d '{"token": "THE_TOKEN", "key": "your_store_public_key"}'
Feed único #
Con este enfoque, ensamblas todos tus objetos en un único archivo JSON. Esto utiliza el método de sincronización llamado Clerk.io JSON Feed.
Parámetros #
Además de los propios objetos, este enfoque admite dos parámetros adicionales:
created: Un timestamp unix de cuándo se actualizó el feed por última vez. El importador de Clerk.io lo utiliza para identificar si deben recuperarse nuevos datos.strict: Cuando estruetodos los datos se importarán tal como están. Cuando esfalse, Clerk.io intentará limpiar los datos, por ejemplo, eliminando productos o categorías duplicados, y convirtiendo números entrecomillados en enteros o flotantes.
Ejemplo Feed #
{
"products": [ ... ],
"categories": [ ... ],
"orders": [ ... ],
"customers": [ ... ],
"pages": [ ... ],
"config": {
"created": 1567069830,
"strict": false
}
}
Seguridad #
¡Tus datos son extremadamente sensibles para tu negocio, por lo que la seguridad es la máxima prioridad!
Recomendamos que el feed JSON sólo acepte conexiones SSL cifradas y utilice Autenticación HTTP si es posible.
Además, Clerk provee una capa de seguridad adicional permitiéndote verificar que la solicitud del feed proviene de una fuente confiable (es decir, nosotros).
El sistema se basa en un secreto compartido; una clave privada API que puedes crear en my.clerk.io bajo Developers > API Keys.
Todas las solicitudes de Clerk.io vía HTTP o HTTPS incluyen dos parámetros de consulta hash y salt.
salt es simplemente una cadena aleatoria utilizada para “saltear” la función hash, mientras que hash es un hash SHA512 calculado a partir de la clave privada API de la siguiente manera:
hash = SHA512(salt + private_key + str(int(floor(unix_timestamp() / 100))))
Una solicitud de ejemplo podría ser la siguiente URL:
https://example.com/clerk-product-feed.php?salt=f4Ke...A02X&hash=4DFF...340F
Al obtener los parámetros salt y hash de la solicitud, puedes hacer el mismo cálculo en tu servidor y comparar los valores de hash para confirmar que son iguales, indicando que la solicitud proviene de Clerk.io
Esta página ha sido traducida por una IA útil, por lo que puede contener errores de idioma. Muchas gracias por su comprensión.