Data Feeds

Descripción general #

Independientemente de tu plataforma de eCommerce, y ya tengamos 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:

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

Ambas soluciones utilizan la misma estructura de objeto, pero disponen de diversas funcionalidades para asegurar e importar los datos, las cuales se describen en esta guía.

Todos los tipos de objetos excepto pedidos se reflejan en la base de datos de Clerk.io a partir de los feeds. Si eliminas un objeto del feed, Clerk.io lo eliminará de su base de datos al importar. 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 lo ideal es hacerlo con más 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 siguientes tipos: int, float, str, array, bool, dict (objeto).

Valores nulos #

Valores null sin controlar son una forma segura de 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 ID #

Recomendamos encarecidamente usar enteros como ID, pero también es posible usar cadenas. 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 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

Si se usan guiones o caracteres especiales en los nombres de atributo, se ignoran en la sincronización.

Estructura de objetos #

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

Los objetos deben contener al menos los campos requeridos para su tipo para que la IA de Clerk.io funcione correctamente, y opcionalmente pueden incluir cualquier otro atributo adicional disponible en la plataforma de eCommerce.

Productos #

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

A continuación puedes ver los campos obligatorios y los recomendados que suelen utilizar las tiendas de 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
  }
]

Conservar productos sin indexar #

En algunas configuraciones, es posible 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 por un tiempo antes de desaparecer, resulta útil mantener el historial de estos productos intacto, 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 pero sin ser indexados. Clerk entonces usará el historial de sus ventas para mostrar resultados, pero nunca se mostrarán en llamadas a la API.

Para otros productos, simplemente elimina el atributo o ponlo como index: true.

Categorías #

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

Más abajo puedes ver los campos obligatorios y ejemplos de campos opcionales que suelen utilizar las tiendas de 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 cuando se eliminan del feed. Por lo general, solo hace falta enviarlos durante la primera importación y luego pueden eliminarse para ahorrar capacidad en el servidor. Se pueden eliminar vía nuestra API CRUD.

Los datos de parcels solo pueden sincronizarse actualmente vía API CRUD. Consulta la documentación aquí.

Cada objeto representa un solo pedido. Clerk.io usa los IDs de producto y dirección de email/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 los 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 de los pedidos para crear un único perfil de cliente que luego puede utilizarse en la segmentación de Audience.

A continuación puedes ver los campos obligatorios y ejemplos de campos opcionales que suelen utilizar tiendas de 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. Las páginas son generalmente todos los tipos de contenido de eCommerce que no se clasifica como producto o categoría. Pueden ser artículos, publicaciones de blog, landing 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 utilizar tiendas de 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 Stores separadas para cada idioma. Cada Store puede configurarse con el idioma del contenido, lo que hace que Search entienda 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 es mejor separar los datos de pedidos en distintas Stores.

Como alternativa, puedes construir feeds JSON multi-idioma, en los que 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 aunque el contenido dentro sea el mismo, para asegurarse de que son buscables por idioma.

Cuando realices llamadas a la 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 un idioma relacionado o simplemente “english”. Seguirá funcionando, pero la normalizació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 #

Esta 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 el tipo de contenido 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 funcionalidad opcional que te permite paginar resultados codificando tu feed para aceptar los siguientes parámetros de consulta:

• limit: Número de objetos para devolver por página.
• offset: Í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 tienes que seleccionar la cantidad de objetos que deseas obtener por página.

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

{{limit}} contendrá el número que configures en los ajustes del importador. {{offset}} empezará en 0 en la primera llamada, y aumentará continuamente 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 #

Usar esta funcionalidad significa que Clerk.io dejará de eliminar objetos durante la importación, así que debes usar llamadas a API CRUD para eliminar objetos de la base de datos de Clerk.io.

La solución de feeds múltiples soporta la funcionalidad opcional de enviar solo los datos que han cambiado desde un número determinado de días atrás, en vez de enviar todos los datos cada vez.

Para ello, primero asegúrate de que tu feed esté configurado para devolver únicamente objetos que hayan cambiado en una cantidad determinada 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 de Incremental time {{modified_after}} que se encuentra en los ajustes 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 el número de días que has configurado, añade el parámetro de consulta modified_after a tu feed e incluye el tag que insertará el número de días que has 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 una conexión cifrada SSL y use autenticación HTTP si es posible.

Además, desde los ajustes de importador puedes activar Token Authentication. Clerk.io entonces incluirá un authorisation header en cada solicitud HTTP, que deberás verificar antes de devolver los datos:

X-Clerk-Authorization: Bearer THE_TOKEN

Puedes verificar el token haciendo 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 #

Aparte de los propios objetos, este enfoque admite dos parámetros adicionales:

• created: Un timestamp unix que indica cuándo se actualizó el feed por última vez. El importador de Clerk.io utiliza esto para identificar si deben extraerse nuevos datos.
• strict: Cuando es true todos los datos se importan tal como están. Si es false, Clerk.io intentará limpiar los datos, por ejemplo eliminando productos o categorías duplicadas y convirtiendo números en texto a enteros o flotantes.

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 una prioridad máxima!

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

Además, Clerk proporciona una capa adicional de seguridad permitiéndote verificar que la solicitud al feed provenga de una fuente confiable (es decir, de nosotros).

El sistema se basa en un secreto compartido: una clave de 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 solo una cadena aleatoria usada para saltear la función hash, mientras que hash es un hash SHA512 calculado a partir de la clave API privada de la siguiente forma:

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

Extrayendo ambos 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