Data Feeds

Descripción general #

Independientemente de tu plataforma de eCommerce, y sin importar si tenemos o no una integración, siempre puedes sincronizar datos con Clerk.io a través de uno o varios feeds en formato JSON.

Admitimos dos variantes diferentes de feeds:

• Varios archivos para diferentes objetos
• Un solo archivo que contiene todos los objetos

Ambas soluciones utilizan la misma estructura de objetos, pero tienen distintas características disponibles para su seguridad e importación, las cuales se detallan en esta guía.

Todos los tipos de objeto 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 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 se pueden generar 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 sin revisar son una manera segura de que los errores se filtren con el tiempo. Si un atributo no existe para un determinado producto, categoría o pedido, simplemente omite el atributo.

Tipos de valor ID #

Recomendamos encarecidamente utilizar 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 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 hará que sean ignorados en la sincronización.

Estructura de objetos #

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

Los objetos deben contener como mínimo los campos requeridos 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 requeridos y los recomendados 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, quizás desees 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 por un tiempo antes de no volver nunca más, es buena idea mantener el historial de estos productos intacto, para que Clerk lo use para mejorar los resultados.

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

Para los demás productos, simplemente omite el atributo o configúralo a index: true.

Categorías #

Cada objeto representa una categoría individual. 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 requeridos y ejemplos de campos 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 cuando se quitan del feed. Por lo general, sólo deben enviarse durante la primera importación y luego pueden quitarse para ahorrar capacidad del servidor. Se pueden eliminar a través de nuestra API CRUD.

Cada objeto representa un solo pedido. Clerk.io utiliza los IDs de productos 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 requeridos y los opcionales. Para incluir datos de paquete, agrega un array tracking al pedido. No envíes los paquetes como objeto de primer nivel separado.

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,
    "tracking": [
      {
        "tracking_code": "ABC123",
        "tracking_link": "https://carrier.example/ABC123",
        "status": "SENT",
        "status_text": "Out for delivery"
      }
    ]
 },
  {
    "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 del cliente o el ID customer de los pedidos para crear un perfil de cliente único y utilizarlo con la segmentación Audience.

A continuación puedes ver los campos requeridos y ejemplos de campos 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 suelen ser todo tipo de contenido de eCommerce que no está clasificado como producto o categoría. Pueden ser artículos, blogs, páginas de aterrizaje, páginas de marca y otros tipos de contenido escrito.

A continuación puedes ver los campos requeridos y ejemplos de campos 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 separadas para cada idioma. Cada Tienda puede configurarse con el idioma del contenido, lo que permite que Search entienda 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 funciona mejor separar los datos de pedidos en diferentes Tiendas también.

Una alternativa es construir feeds multi-idioma JSON, donde todos los atributos de texto se presentan como objetos con los 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 su búsqueda en ese idioma.

Al hacer 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 compatibles #

El idioma debe especificarse con su nombre exacto. Actualmente admitimos 54 idiomas. Si tu idioma no aparece en la lista a continuación, 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

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 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 puede configurarse para enviar estos parámetros a tu feed. Solo tienes que seleccionar la cantidad de objetos que deseas recuperar 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}} comenzará en 0 en la primera llamada, y aumentará progresivamente 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 #

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

La solución multi-feed admite la función opcional de enviar solo los datos que han cambiado en un número determinado de días, en lugar de enviar todos los datos cada vez.

Para hacerlo, asegúrate primero de que tu feed esté configurado para devolver solo los objetos que han 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 etiquetado como 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 que estén 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 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 conexiones cifradas SSL y use Autenticación HTTP si es posible.

Además, desde los ajustes del importador, puedes activar Token Authentication. Clerk.io incluirá entonces un header de autorización 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 #

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

• created: Un timestamp unix de cuándo se actualizó por última vez el feed. El importador de Clerk.io lo usa para identificar si se deben recuperar 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 en cadena 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 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 ofrece una capa adicional de seguridad permitiéndote verificar que la solicitud del feed provenga de una fuente confiable (es decir, nosotros).

El sistema se basa en un secreto compartido; una clave privada de API que puede crearse en my.clerk.io en Developers > API Keys.

Todas las solicitudes de Clerk.io por HTTP o HTTPS incluyen dos parámetros de consulta, hash y salt.

salt es simplemente 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

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