Data Feeds

Descripción general #

Independientemente de tu plataforma de eCommerce, y tanto si tenemos una integración como si no, 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 diferentes objetos
• Un solo archivo que contiene todos los objetos

Las dos soluciones utilizan la misma estructura de objetos, pero tienen diferentes funciones disponibles para su seguridad e importación, las cuales se detallan en esta guía.

Todos los tipos de objeto excepto órdenes se reflejan de 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 se importe. Las órdenes se registran y permanecen en la base de datos.

Recomendamos generar los feeds JSON al menos una vez al día, aunque lo ideal es hacerlo con mayor frecuencia. También pueden generarse bajo demanda cuando el importador de Clerk.io los solicite.

El/los feed(s) debería(n) estar disponible(s) 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 no verificados pueden causar errores con el tiempo. Si un atributo no existe para un producto, categoría u orden simplemente omite el atributo.

Tipos de valor de ID #

Recomendamos encarecidamente utilizar enteros como IDs, pero también es posible usar cadenas. Debes comprometerte siempre con 1 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 o caracteres especiales en los nombres de los atributos provocará que sean ignorados en la sincronización.

Estructura de objetos #

Los feeds JSON consisten en una lista de objetos, con varios campos que componen 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 adicional disponible en la plataforma eCommerce.

Productos #

Cada objeto representa un solo producto. Si tienes productos configurables, recomendamos enviar solo el producto principal 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 usan a menudo las 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 #

En algunas configuraciones, puedes querer mantener productos en la base de datos de Clerk.io sin mostrarlos en ningún resultado.

Si vendes entradas o artículos de segunda mano que estarán disponibles un tiempo antes de nunca volver, es buena idea mantener el historial de estos productos intacto, para que Clerk pueda utilizarlo para mejorar resultados.

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

Para el resto de productos, simplemente omite el atributo o establece 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.

A continuación puedes ver los campos obligatorios y ejemplos de opcionales que usan a menudo las 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"
  }
]

Órdenes #

Las órdenes se registran y no se eliminan cuando son retiradas del feed. Normalmente solo deben enviarse durante la primera importación y luego pueden ser eliminadas para ahorrar capacidad en el servidor. Se pueden eliminar usando nuestra CRUD API.

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

Cada objeto representa una sola orden. Clerk.io utiliza los IDs de producto y la dirección de email/ID de cliente de las órdenes 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 órdenes.

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 con el email o el ID de customer de las órdenes para crear un único perfil de cliente para utilizar con la segmentación de Audience.

A continuación puedes ver los campos obligatorios y ejemplos de opcionales que usan a menudo las 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. Las páginas son generalmente todo tipo de contenido eCommerce que no está clasificado como producto o categoría. Podrían ser artículos, publicaciones de blog, páginas de aterrizaje, páginas de marca y otros tipos de contenido escrito.

A continuación puedes ver los campos obligatorios y ejemplos de opcionales que usan habitualmente las 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 Stores separados para cada idioma. Cada Store se puede configurar con el idioma del contenido, lo que permite que Search comprenda mucho mejor la gramática y los errores ortográficos.

Además, los clientes de diferentes regiones o países suelen tener diferentes preferencias y patrones de búsqueda, por lo que es mejor separar los datos de órdenes en Stores diferentes.

Alternativamente, puedes crear 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 en dicho idioma.

Cuando hagas 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 admitidos #

El idioma debe especificarse con su nombre exacto. Actualmente admitimos 54 idiomas. Si tu idioma no está en la lista, elige un idioma relacionado o simplemente “english”. Funcionará igual, 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 pues 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. 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 función opcional que te permite paginar los resultados codificando tu feed para que acepte los siguientes parámetros de consulta:

• limit: Número de objetos a devolver por página.
• offset: Índice del primer objeto a devolver en la página.

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

Cuando configures tu URL de feed, puedes usar {{limit}} y {{offset}} para añadir 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 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 #

Utilizar esta función significa que Clerk.io dejará de eliminar 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 multi-feed permite la función opcional de enviar solo los datos que han cambiado desde un número de días elegido, en vez de enviar todos los datos cada vez.

Para esto, primero asegúrate de que tu feed esté configurado para devolver solo objetos que hayan cambiado en una cantidad específica de días, cuando la solicitud incluya el parámetro de consulta modified_after.

Luego, añade el número de días en el campo llamado Incremental time {{modified_after}} que aparece 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 utilizar 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 solo acepte conexión SSL encriptada y use HTTP Authentication si es posible.

Además, desde la configuración del importador, puedes activar Token Authentication. Clerk.io incluirá entonces una cabecera authorisation en cada solicitud HTTP, que debes 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: Timestamp unix de cuando el feed fue actualizado por última vez. El importador de Clerk.io lo usa para saber si debe obtener 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 duplicados y convirtiendo números como 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, ¡así que la seguridad es máxima prioridad!

Recomendamos que el feed JSON solo acepte conexiones SSL encriptadas y utilice HTTP Authentication si es posible.

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

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

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

salt es solo una cadena aleatoria utilizada para “salar” la función hash, mientras que hash es un hash SHA512 calculado a partir de la clave privada de API de la siguiente manera:

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

Un ejemplo de solicitud sería la siguiente URL:

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

Obteniendo los parámetros salt y hash de la solicitud, puedes realizar el mismo cálculo en tu servidor y comparar los valores de hash para confirmar que coinciden, lo que significa que la solicitud proviene de Clerk.io