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 los feeds:

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

Ambas soluciones usan la misma estructura de objeto, pero cuentan con diversas funciones disponibles para su seguridad e importación, que se detallan en esta guía.

Todos los tipos de objeto excepto los pedidos se espejan desde los feeds a 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 el/los feed(s) 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 #

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

Valores nulos #

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

Tipos de valores ID #

Recomendamos encarecidamente usar enteros como IDs pero también es posible usar strings. Siempre debes comprometerte con un 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.
Por lo tanto, un nombre de atributo válido podría ser brand_name pero no läbel-mærke.

El uso de guiones u otros caracteres especiales en los nombres de atributos hará que sean ignorados en la sincronización.

Estructura de los objetos #

Los feeds JSON constan de una lista de objetos, con una variedad de campos que conforman sus datos.

Los objetos deben contener como mínimo los campos obligatorios para el tipo, para que la IA de Clerk.io funcione correctamente, y opcionalmente pueden contener 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 ejemplos de opcionales que suelen usar 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
  }
]

Mantener productos sin indexar #

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

Si vendes entradas o artículos usados que estarán disponibles un tiempo antes de no volver, es una buena idea mantener el historial de estos productos intacto, para que Clerk lo use y mejore los resultados.

Para ello, añade el atributo especial index: false a los objetos de producto que deban mantenerse sin indexar. Clerk usará el historial de sus ventas para mostrar resultados, pero nunca aparecerán en ninguna llamada de la API.

Para los demás productos, simplemente omite el atributo o ponlo en index: true.

Categorías #

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

A continuación puedes ver los campos obligatorios y ejemplos de opcionales que suelen usar 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 al quitarlos del feed. Por lo general, solo deben enviarse durante la primera importación y luego se pueden quitar para ahorrar capacidad del servidor. Puedes eliminarlos usando nuestra CRUD API.

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

Cada objeto representa un solo pedido. Clerk.io usa los IDs de producto y la 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 opcionales. No es posible enviar atributos adicionales para los 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 combinan luego con el email o el ID de customer de los pedidos para crear un único perfil de cliente que se usa para segmentar en Audience.

A continuación puedes ver los campos obligatorios y ejemplos de opcionales que suelen usar las 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 normalmente son todo tipo de contenido de eCommerce que no se clasifica como producto o categoría. Puede tratarse de artículos, blogs, landings, páginas de marca y otros tipos de contenido escrito.

A continuación puedes ver los campos obligatorios y ejemplos de opcionales que suelen usar las 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 tiendas Stores separadas para cada idioma. Cada Store se puede configurar 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 preferencias y patrones de búsqueda distintos, lo que significa que lo ideal es separar los datos de pedidos también en diferentes Stores.

Una alternativa es construir feeds JSON multi-idioma, donde todos los atributos de texto se proporcionan 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 el mismo, para asegurar que sean buscables por idioma.

Al hacer llamadas a la API, incluye el parámetro language y la clave de idioma correspondiente para recibir 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 disponibles #

El idioma debe especificarse con su nombre exacto. Actualmente admitimos 54 idiomas. Si tu idioma no aparece en la lista, elige uno relacionado o simplemente “english”. Seguirá funcionando, pero la neutralización gramatical en Search será menos eficaz.

• 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 te ofrece el mayor grado de control.

Con este enfoque, construyes archivos de feed individuales para cada uno de tus objetos. Esto utiliza el método de sincronización denominado 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 función opcional que te permite paginar los resultados configurando tu feed para aceptar los siguientes parámetros de consulta:

• limit: La cantidad 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 tienes que elegir la cantidad de objetos que quieres recuperar por página.

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

{{limit}} contendrá el número que configures en los ajustes del importador. {{offset}} comenzará en 0 en la primera llamada y aumentará según el 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 devuelve un array vacío.

URL #

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

Incrementos #

El uso de esta función implica que Clerk.io dejará de eliminar objetos al importar, por lo que necesitarás usar las llamadas CRUD API para eliminar objetos de la base de datos de Clerk.io.

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

Para ello, asegúrate de que tu feed esté configurado para devolver SOLO los objetos que hayan cambiado en una cantidad de días específica, al incluir el parámetro de consulta modified_after.

Luego, añade una cantidad de días en el campo marcado como Incremental time {{modified_after}} encontrado 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 que se incluyan 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. Por ejemplo:

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

Seguridad #

Recomendamos que el feed JSON solo acepte conexiones cifradas SSL y utilice Autenticación HTTP si es posible.

Además, desde los ajustes del importador, puedes activar Token Authentication. Clerk.io incluirá un header de autorización en cada petición HTTP, que tendrás que 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 que indica cuándo se actualizó por última vez el feed. El importador de Clerk.io lo usa para identificar si deben recuperarse nuevos datos.
• strict: Cuando es true, todos los datos se importan tal cual. Cuando es false, Clerk.io intentará limpiar los datos, por ejemplo, eliminando productos o categorías duplicadas y convirtiendo números en cadena 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 la máxima prioridad!

Recomendamos que el feed JSON solo acepte una 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 del feed proviene de una fuente confiable (es decir, nosotros).

El sistema se basa en un secreto compartido; una clave API privada que puedes crear en my.clerk.io bajo Developers > API Keys.

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

salt es simplemente 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, del siguiente modo:

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

Recogiendo ambos 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, lo que significa que la solicitud proviene de Clerk.io