Data Feeds

Descripción general #

Independientemente de tu plataforma de comercio electrónico, y ya sea que 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.

Soportamos dos variaciones diferentes de los feeds:

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

Las dos soluciones utilizan la misma estructura de objeto, pero tienen varias características disponibles para asegurar e importar, que se describen en esta guía.

Todos los tipos de objetos excepto pedidos se reflejan 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 son registrados y mantenidos en la base de datos.

Recomendamos generar el(los) feed(s) JSON al menos una vez al día, pero idealmente con más frecuencia. También pueden generarse bajo demanda cuando el importador de Clerk.io los solicita.

El(los) feed(s) deben estar disponibles en una URL que sea accesible desde los servidores de Clerk.io.

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

Tipos de datos #

Soportamos atributos de los tipos: int, float, str, array, bool.

Valores nulos #

Los valores null no verificados son una forma segura de que se cuelen errores con el tiempo. Si un atributo no existe para un producto, categoría u orden dada, simplemente omite el atributo.

Tipos de valores de ID #

Recomendamos encarecidamente usar enteros como IDs, pero también es posible usar cadenas. Siempre debes comprometerte a 1 tipo en tu feed, lo que significa que todos los IDs para 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.
Así, 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 una gama de campos que componen sus datos.

Los objetos deben contener como mínimo los campos requeridos para que la IA de Clerk.io funcione correctamente, y opcionalmente pueden contener cualquier atributo extra disponible en la plataforma de comercio electrónico.

Productos #

Cada objeto representa un único producto. Si tienes productos configurables, recomendamos enviar solo el producto padre, e incluir atributos que describan a los hijos, como color, tamaño, material, etc.

A continuación puedes ver los campos requeridos y ejemplos de los opcionales que son utilizados frecuentemente por las tiendas de comercio electrónico.

Ejemplo JSON #

[
  {
    "id": 135,
    "name": "Lightsaber",
    "description": "Antique Rebel Lightsaber",
    "price": 99995.95,
    "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_names": ["Green","Red"],
    "color_codes": ["#7CFC00","#FF3131"],
    "reviews_amount": 164,
    "reviews_avg": 4.8
  },
  {
    "id": 261,
    "name": "Death Star Deluxe",
    "description": "Death Star - Guaranteed idiot proof",
    "price": 99999999999999.95,
    "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, 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 no volver, es una buena idea mantener la historia de estos productos intacta, para que Clerk pueda usarla para mejorar los resultados.

Para hacer esto, agrega el atributo especial index: false a los objetos de producto que deben mantenerse sin ser indexados. Clerk usará entonces la historia de sus ventas para mostrar resultados, pero nunca se mostrarán en ninguna llamada a la API.

Para otros productos, simplemente omite el atributo o configúralo en index: true.

Categorías #

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

A continuación puedes ver los campos requeridos y ejemplos de los opcionales que son utilizados frecuentemente por las tiendas de comercio electrónico.

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 son registrados y no se eliminan cuando se eliminan del feed. Generalmente solo deben enviarse durante la primera importación y luego pueden eliminarse nuevamente para ahorrar capacidad del servidor. Pueden eliminarse a través de nuestra API CRUD.

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

Cada objeto representa un único pedido. Clerk.io utiliza los IDs de producto y la dirección de correo electrónico/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 requeridos y los campos 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 único cliente. Los atributos proporcionados se fusionan con el email o el ID de customer del cliente de los pedidos para crear un único perfil de cliente para su uso con la segmentación de Audiencia.

A continuación puedes ver los campos requeridos y ejemplos de los opcionales que son utilizados frecuentemente por las tiendas de comercio electrónico.

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 única página. Las páginas son generalmente todos los tipos de contenido de comercio electrónico que no se clasifican como un producto o categoría. Podría ser artículos, publicaciones de blog, páginas de destino, páginas de marca y otros tipos de contenido escrito.

A continuación puedes ver los campos requeridos y ejemplos de los opcionales que son utilizados frecuentemente por las tiendas de comercio electrónico.

Ejemplo JSON #

[
  {
    "id": 135,
    "type": "cms",
    "url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
    "title": "Open Hours",
    "text": "El texto principal sobre nuestro horario de apertura..."
 },
  {
    "id": 1354,
    "type": "blog",
    "url": "https://galactic-empire-merch.com/imperial-goods/tatooine",
    "title": "Nueva Publicación de Blog",
    "text": "El texto principal sobre nuestro horario de apertura...",
    "keywords": ["blog", "post", "nuevo"]
 }
]

Multi-idioma #

Clerk.io funciona mejor cuando creas tiendas separadas Stores para cada idioma. Cada tienda puede configurarse con el idioma del contenido, lo que hace que la búsqueda entienda mucho mejor los errores gramaticales y de ortografía.

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

Una alternativa a esto 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 dentro de ellos es el mismo, para asegurarse de que sean buscables para el idioma.

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_names": ["Green","Red"],
    "color_codes": ["#7CFC00","#FF3131"],
    "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. Si tu idioma no está en la lista a continuación, elige un idioma que use la misma raíz, o simplemente “english”. Aún funcionará, pero la neutralización gramatical en la búsqueda será menos efectiva.

• danés
• holandés
• inglés
• finlandés
• francés
• alemán
• italiano
• noruego
• portugués
• ruso
• español
• sueco

Múltiples feeds #

Este es el enfoque recomendado ya que es eficiente para tu servidor y 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 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 función opcional que te permite paginar 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 puede configurarse para enviar estos parámetros a tu código de feed. Simplemente debes 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 la configuración del importador. {{offset}} comenzará en 0 en la primera llamada, y crecerá continuamente basado en 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 #

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

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

Para hacer esto, comienza asegurándote de que tu feed esté configurado para devolver solo objetos que han cambiado en una cantidad especificada de días, cuando la solicitud incluye el parámetro de consulta modified_after.

Luego, agrega un número de días en el campo etiquetado 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 solo actualice los objetos que están incluidos en los feeds.

Para usar el número de días que has configurado, agrega el parámetro de consulta modified_after a tu feed e incluye la etiqueta 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 por SSL y use Autenticación HTTP si es posible.

Además, desde la configuración del importador, puedes activar Token Authentication. Clerk.io incluirá entonces un header de autorización en cada solicitud HTTP, que necesitas 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 #

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

• created: Un timestamp unix de cuándo se actualizó por última vez el feed. El importador de Clerk.io utiliza esto para identificar si se deben obtener nuevos datos.
• strict: Cuando true todos los datos se importarán tal cual. Cuando false, Clerk.io intentará limpiar los datos, por ejemplo, eliminando productos o categorías duplicadas, y convirtiendo números en cadenas 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, por lo que la seguridad es de la más alta prioridad.

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

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

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

Todas las solicitudes de Clerk.io a través de HTTP o HTTPS incluyen dos parámetros de consulta hash y salt.

salt es solo una cadena aleatoria utilizada para saltear la función hash mientras que hash es un hash SHA512 calculado a partir de la clave API privada 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 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 los mismos, lo que significa que la solicitud proviene de Clerk.io.