Data Feeds

Descripción general #

Independientemente de tu plataforma 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 los feeds:

• Múltiples archivos para diferentes objetos
• Un solo archivo que contenga todos los objetos

Las dos soluciones utilizan la misma estructura de objetos, pero cuentan con diferentes características para proteger e importar los datos, que se detallan en esta guía.

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

Recomendamos generar el(los) feed(s) 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(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 #

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

Valores nulos #

Valores null sin controlar son una forma segura de que errores se cuelen con el tiempo. Si un atributo no existe para un producto, categoría o pedido determinado, simplemente omítelo.

Tipos de valor para ID #

Recomendamos encarecidamente usar enteros como IDs, pero también es posible usar cadenas. Siempre debes comprometerte con un solo tipo en tu feed, es decir, todos los IDs para tus objetos deben ser del mismo tipo.

Nombres de atributos #

Los atributos del objeto sólo pueden contener valores alfanuméricos (A-Z, 0-9) y guiones bajos.
Por tanto, 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 sean ignorados en la sincronización.

Estructura de los objetos #

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

Los objetos deben contener como mínimo los campos obligatorios para el tipo de objeto para que la IA de Clerk.io funcione correctamente, y opcionalmente pueden contener cualquier atributo extra disponible en la plataforma 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 ejemplos de campos opcionales que suelen ser usados por tiendas eCommerce.

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 #

Para algunas configuraciones, puede que desees mantener productos en la base de datos de Clerk.io sin mostrarlos en ningún resultado.

Si vendes entradas o artículos usados que estarán disponibles durante un tiempo antes de desaparecer para siempre, es buena idea mantener el historial de estos productos intacto, para que Clerk lo utilice para mejorar los resultados.

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

Para otros productos, simplemente omite el atributo o establécelo en index: true.

Categorías #

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

A continuación puedes ver los campos obligatorios y ejemplos de campos opcionales que suelen ser usados por tiendas eCommerce.

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. Por lo general sólo deben enviarse durante la primera importación y luego se pueden retirar para ahorrar capacidad del servidor. Se pueden eliminar mediante nuestra CRUD API.

Actualmente los datos de parcels sólo pueden sincronizarse vía CRUD API. Consulta la documentación aquí.

Cada objeto representa un solo pedido. Clerk.io utiliza los IDs de producto y el email o ID de cliente dentro 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 obligatorios y opcionales. No es posible enviar atributos adicionales para pedidos.

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
 },
  {
    "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 solo Cliente. Los atributos proporcionados se fusionan con el email o el ID de customer del pedido para crear un solo perfil de cliente que se utiliza en la segmentación de Audience.

A continuación puedes ver los campos obligatorios y ejemplos de campos opcionales que suelen ser usados por tiendas eCommerce.

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 se refiere a todo tipo de contenido eCommerce que no esté clasificado como producto o categoría. Puede ser artículos, entradas de blog, landings pages, páginas de marca y otros tipos de contenido escrito.

A continuación puedes ver los campos obligatorios y ejemplos de campos opcionales que suelen ser usados por tiendas eCommerce.

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 Tiendas separadas para cada idioma. Cada Tienda puede configurarse con el idioma del contenido, lo que permite que Search entienda mucho mejor la gramática y los errores ortográficos.

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

Una alternativa a esto es construir feeds JSON multi-idioma, donde todos los atributos de texto se proporcionen como objetos con códigos de idioma como claves y sus traducciones como valores.

Todos los atributos de texto deben tener claves de idioma incluso si el contenido es igual, para asegurar que sean buscables en el idioma correspondiente.

Al hacer llamadas a la API, incluye el parámetro language y la clave de idioma correspondiente, para obtener los datos correctos.

Ejemplo de 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 de abajo, elige uno relacionado o simplemente “english”. Igual funcionará, pero 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, ya que es eficiente para tu servidor y ofrece el mayor control.

Con este enfoque, creas archivos individuales de feeds para cada objeto. 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 los resultados codificando tu feed para aceptar los siguientes parámetros de consulta:

• limit: El número de objetos a devolver por página.
• offset: El índice del primer objeto a devolver en una página.

El importador de Clerk.io se puede configurar para enviar estos parámetros a tu código de feed. Solo debes seleccionar la cantidad de objetos que deseas obtener por página.

Al configurar tu URL de feed, puedes utilizar {{limit}} y {{offset}} para agregar los datos como parámetros de consulta.

{{limit}} contendrá el número configurado en la configuración del importador. {{offset}} comenzará en 0 en la primera llamada e irá creciendo continuamente en función de limit.

Por 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 devuelva 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 necesitarás usar llamadas CRUD API para eliminar objetos de la base de datos de Clerk.io.

La solución de feeds múltiples soporta la función opcional de enviar sólo los datos que hayan cambiado en un número determinado de días, en lugar de enviar todos los datos cada vez.

Para ello, empieza asegurando que tu feed esté configurado para devolver sólo los objetos que hayan cambiado en una cantidad especificada de días, cuando la solicitud incluya el parámetro de consulta modified_after.

Luego, añade un número de días en el campo titulado 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 usar el número de días configurado, añade el parámetro de consulta modified_after a tu feed e incluye la etiqueta que insertará 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 sólo acepte conexión cifrada SSL y utilice Autenticación HTTP si es posible.

Además, desde la configuración del importador, puedes activar Token Authentication. Clerk.io entonces incluirá 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 #

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 obtenerse nuevos datos.
• strict: Cuando es true, todos los datos se importarán tal cual. 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, por lo que la seguridad es de máxima prioridad!

Recomendamos que el feed JSON únicamente acepte una conexión encriptada SSL y utilice Autenticación HTTP si es posible.

Además, Clerk ofrece una capa adicional de seguridad 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 API privada que puede crearse en my.clerk.io en 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 sólo una cadena aleatoria utilizada para “saltear” la función hash, mientras que hash es una suma SHA512 calculada desde la clave API privada de la siguiente manera:

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

Un ejemplo de solicitud 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 hash para confirmar que son iguales, lo que significa que la solicitud proviene de Clerk.io