Data Feeds

Descripción general #

Independientemente de tu plataforma de eCommerce, y tengas o no una integración, siempre puedes sincronizar datos con Clerk.io a través de uno o más feeds en formato JSON.

Admitimos dos variantes diferentes de feeds:

• Archivos múltiples para distintos objetos
• Un solo archivo que contiene todos los objetos

Ambas soluciones usan la misma estructura de objeto, pero tienen diferentes opciones disponibles para asegurar e importar los datos, las cuales se detallan en esta guía.

Todos los tipos de objetos 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 al importar. Los pedidos se registran y se mantienen en la base de datos.

Recomendamos generar el feed JSON al menos una vez al día, pero idealmente con mayor frecuencia. También pueden generarse bajo demanda cuando el importador de Clerk.io los solicite.

El feed debe estar disponible en una URL accesible desde los servidores de Clerk.io.

https://your-website.com/json-feed.json

Tipos de datos #

Admitimos atributos de los tipos: int, float, str, array, bool, dict (objeto).

Valores nulos #

Los valores null sin controlar son una vía segura para que aparezcan errores con el tiempo. Si un atributo no existe para un producto, categoría o pedido determinado, simplemente omite el atributo.

Tipos de valor ID #

Recomendamos altamente usar enteros como IDs, pero también es posible usar cadenas. Siempre debes comprometerte a un solo tipo en tu feed, lo que significa que todos los IDs de tus objetos deben ser del mismo tipo.

Nombres de atributos #

Los atributos de objeto solo pueden contener valores alfanuméricos (A-Z, 0-9) y guiones bajos.
Por lo tanto, un nombre de atributo válido podría ser brand_name pero no läbel-mærke

Usar guiones o caracteres especiales en los nombres de atributos hará que sean ignorados en la sincronización.

Estructura de objetos #

Los feeds JSON consisten en una lista de objetos, con un rango de campos que componen sus datos.

Los objetos deben contener como mínimo los campos obligatorios para su tipo para que la IA de Clerk.io funcione correctamente, y opcionalmente pueden tener cualquier atributo extra disponible en la plataforma de eCommerce.

Productos #

Cada objeto representa un solo producto. Si tienes productos configurables, recomendamos enviar solo el producto padre, e incluir atributos que describan los hijos, como color, size, material, etc.

A continuación puedes ver los campos obligatorios y los recomendados que suelen usarse en las tiendas online.

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 indexar #

En algunas configuraciones, puede que quieras mantener productos en la base de datos de Clerk.io sin mostrarlos en resultados.

Si vendes entradas o artículos usados que estarán disponibles durante un tiempo antes de no volver, es una buena idea guardar el historial de estos productos para que Clerk pueda usarlo y mejorar los resultados.

Para hacer esto, agrega el atributo especial index: false a los objetos de productos que deban mantenerse sin indexar. Clerk usará su historial de ventas para mostrar resultados, pero nunca se mostrarán en ninguna llamada a la API.

Para el resto de productos, simplemente omite el atributo o indícalo como index: true.

Categorías #

Cada objeto representa una sola categoría. Clerk.io construye un árbol interno de categorías en función de las subcategorías proporcionadas para cada una.

A continuación puedes ver los campos obligatorios y ejemplos de opciones usadas frecuentemente en tiendas online.

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 sacarlos del feed. Solo es necesario enviarlos en la primera importación y luego puedes quitarlos para ahorrar recursos del servidor. Se pueden eliminar a través de nuestra CRUD API.

Cada objeto representa un solo pedido. Clerk.io usa los IDs de productos y la dirección de correo electrónico/ID de cliente de 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 necesarios y los opcionales. Para incluir datos de envío, añade un array tracking al pedido. No envíes paquetes como objetos principales separados.

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 único cliente. Los atributos proporcionados se unen a la email o ID de customer desde los pedidos para crear un solo perfil de cliente para su uso en la segmentación de Audience.

A continuación puedes ver los campos requeridos y ejemplos de otros opcionales que suelen usarse en tiendas online.

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. Las páginas suelen ser contenido de eCommerce que no es producto ni categoría. Puede ser artículos, blogs, landing pages, páginas de marca u otro tipo de contenido escrito.

A continuación puedes ver los campos requeridos y ejemplos opcionales usados frecuentemente.

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 se puede configurar con el idioma del contenido, lo cual hace que Search entienda mejor la gramática y los errores de ortografía.

Además, los clientes de diferentes regiones o países tienden a tener diferentes preferencias y patrones de búsqueda, por lo que también es mejor separar datos de pedido en Stores independientes.

Una alternativa es construir feeds JSON multi-idioma, donde los atributos de texto se envían como objetos con códigos de idioma como keys y sus traducciones como valores.

Todos los atributos de texto deben tener llaves de idioma aunque el contenido sea igual, para asegurar que sean buscables por idioma.

Al hacer llamadas a la API, incluye el parámetro language y la key del idioma correspondiente para que los datos correctos sean obtenidos.

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, elige uno relacionado o simplemente “english”. Seguirá funcionando, solo que la neutralización gramatical 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 porque es eficiente para tu servidor y ofrece el máximo control.

Con este enfoque, creas archivos de feed individuales para cada uno de tus objetos. Utiliza el método de sincronización llamado Clerk.io JSON Feed V2.

Estos soportan 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 permite paginar resultados haciendo que tu feed acepte los siguientes parámetros de consulta:

• limit: El número de objetos devueltos por página.
• offset: El índice del primer objeto devuelto en la página.

El importador de Clerk.io puede configurarse para enviar estos parámetros a tu feed. Solo tienes que seleccionar la cantidad de objetos que quieres obtener por página.

Cuando configures la URL de tu feed, puedes usar {{limit}} y {{offset}} para añadir los datos como parámetros de consulta.

{{limit}} tendrá el número que configures en los ajustes del importador. {{offset}} iniciará en 0 en la primera llamada, y crecerá en base a 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 #

Usar esta función significa que Clerk.io dejará de borrar objetos al importar, por lo que deberás usar llamadas CRUD API para eliminar objetos de la base de datos de Clerk.io.

La solución de multi-feeds soporta la función opcional de enviar solo los datos que han cambiado desde un determinado número de días, en vez de enviar todos los datos cada vez.

Para ello, asegúrate primero de que tu feed está configurado para devolver solo los objetos que hayan cambiado en una cantidad de días indicada, cuando la petición 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}} 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 solo actualice los objetos incluidos en los feeds.

Para usar la cantidad de días configurada, añade el parámetro de consulta modified_after a tu feed e incluye la etiqueta que insertará automáticamente el número de días configurado. Por ejemplo:

https://awsumstuff.com/feed/products.json?modified_after={{modified_after}}&limit={{limit}}&offset={{offset}}

Seguridad #

Recomendamos que el feed JSON solo acepte conexión cifrada por SSL y que utilice autenticación HTTP si es posible.

Además, desde la configuración del importador puedes activar Token Authentication. Clerk.io entonces incluirá un header 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 petición 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 solo archivo JSON. Esto utiliza el método de sincronización llamado Clerk.io JSON Feed.

Parámetros #

Además de los objetos en sí, este enfoque soporta dos parámetros adicionales:

• created: Timestamp unix de la última actualización del feed. El importador de Clerk.io lo usa para saber si hay nuevos datos para importar.
• strict: Cuando es true, todos los datos se importan tal como están. Cuando es false, Clerk.io intentará limpiar los datos, por ejemplo eliminando productos o categorías duplicadas, y convirtiendo números en cadenas a enteros o floats.

Ejemplo de feed #

{
  "products": [ ... ],
  "categories": [ ... ],
  "orders": [ ... ],
  "customers": [ ... ],
  "pages": [ ... ],

  "config": {
    "created": 1567069830,
    "strict": false
  }
}

Seguridad #

Tus datos son extremadamente sensibles para el negocio, ¡así que la seguridad es máxima prioridad!

Recomendamos que el feed JSON solo acepte conexión cifrada SSL y que utilice autenticación HTTP si es posible.

Además, Clerk provee una capa extra permitiéndote verificar que la solicitud del feed proviene de un origen fiable (es decir, nosotros).

El sistema se basa en un secreto compartido; una Private API key que se puede crear en my.clerk.io bajo Developers > API Keys.

Todas las peticiones Clerk.io vía HTTP o HTTPS incluyen dos parámetros de consulta: hash y salt.

salt es solo una cadena aleatoria usada para “salting” la función hash, mientras que hash es un hash SHA512 calculado a partir de la Private API Key de la siguiente forma:

hash = SHA512(salt + private_key + str(int(floor(unix_timestamp() / 100))))

Una solicitud de ejemplo sería la siguiente URL:

https://example.com/clerk-product-feed.php?salt=f4Ke...A02X&hash=4DFF...340F

Al obtener ambos parámetros salt y hash desde la solicitud, puedes hacer el mismo cálculo en tu servidor y comparar los valores de hash para confirmar que son iguales, lo que demuestra que la solicitud proviene de Clerk.io