Cualquier (webshop)

API

Una forma flexible de integrar el lado del servidor.

Toda la comunicación con Clerk ocurre a través de la API:

https://api.clerk.io/v2

Configurar esta comunicación requiere 4 pasos, que se describen en esta guía. Necesitas:

  1. Sincronizar datos
  2. Recuperar resultados
  3. Visualizar los resultados
  4. Agregar seguimiento

Claves de API #

Estas claves se utilizan para acceder a los datos de tu tienda. Se encuentran en my.clerk.io > Configuración > Claves de API.

Consisten en una clave pública, que da acceso a los puntos finales que exponen datos no sensibles, y una clave privada que te permite trabajar con datos en la tienda y acceder a datos sensibles, como información de clientes y pedidos.

Las claves privadas solo se pueden ver una vez después de ser creadas por razones de seguridad, y puedes crear tantas como necesites para diferentes propósitos.

1. Sincronizar Datos #

El primer paso es obtener datos dentro, permitiendo que la IA de Clerk.io entienda tu tienda en línea y prediga resultados. Clerk sincroniza cada dominio de tienda en línea como su propia instancia única de tienda, a la que se accede mediante un conjunto de claves de API.

API CRUD #

Puedes sincronizar tus datos utilizando los puntos finales de la API CRUD, que te permiten obtener, publicar, actualizar y eliminar recursos bajo demanda.

curl --request POST \
     --url 'https://api.clerk.io/v2/products' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "private_key": "osLqDAs5s2tlf3adpLv6Mp1hxx3f",
          "products":[
                {
                  "id": 123,
                  "name": "Sable de luz verde",
                  "description": "Sable de luz rebelde antiguo.",
                  "price": 99995.95,
                  "brand": "Je’daii",
                  "categories": [987, 654],
                  "created_at": 1199145600
                },
                {
                  "id": 789,
                  "name": "Estrella de la muerte Deluxe",
                  "description": "Estrella de la muerte. A prueba de tontos."
                  "price": 99999999999999.95,
                  "brand": "Imperial Inc.",
                  "categories": [345678],
                  "created_at": 11991864600
                }
             ]
           }'

Los objetos disponibles son:

Uno de los principales diferenciadores de Clerk es que no hay un período de aprendizaje, ya que podemos utilizar todos los pedidos existentes desde el primer día para entender el comportamiento actual del cliente.

Fuentes de Datos #

Además de utilizar la API CRUD, se recomienda encarecidamente agregar un método de sincronización de respaldo. Después de todo, muchas cosas pueden salir mal con las llamadas a la API.

Por ejemplo, tu servidor de precios podría fallar, o un atributo de producto podría contener un error que cause que varias llamadas fallen. Para evitar estos problemas, considera usar una o más Fuentes de Datos como respaldo diario para tus llamadas CRUD.

Las fuentes de datos son uno o varios archivos JSON que contienen el catálogo actual de las tiendas en línea.

Cualquier dato disponible en la fuente cuando se carga será con lo que Clerk trabaja, excepto por los pedidos, que se registran y no necesitan ser incluidos en la fuente después de la primera importación.

Usar la fuente de datos también es una excelente manera de precargar Clerk con pedidos.

{
  "products": [ ... ],
  "categories": [ ... ],
  "orders": [ ... ],
  "customers": [ ... ],
  "pages": [ ... ],

  "config": {
    "created": 1567069830,
    "strict": false
  }
}

La(s) fuente(s) de datos deben estar disponibles en una URL que pueda ser accedida por el importador, que configuras en el my.clerk.io backend en Estado del sistema > Sincronización de datos. Puedes asegurar la fuente, para que solo nuestro importador pueda acceder a ella.

2. Recuperar Datos #

Una vez que los datos están sincronizados, la IA los analiza y construye índices inteligentes que se pueden recuperar a través de puntos finales únicos dependiendo del caso de uso.

Por ejemplo, para obtener los productos más populares, puedes usar el punto final recommendations/trending, y para mostrar los mejores productos para una búsqueda sobre “star wars,” puedes usar el punto final search/predictive.

Puntos finales #

Todos los puntos finales requieren que envíes la clave pública de la API.

Los puntos finales que devuelven resultados también requieren el argumento " limit" para controlar el número de resultados que se devolverán.

Los parámetros adicionales dependen del punto final que estés llamando. Por ejemplo, las mejores alternativas requieren products que es una lista de IDs de productos para encontrar accesorios, y cualquier llamada relacionada con la búsqueda necesita el parámetro query para encontrar coincidencias.

Puedes encontrar los argumentos necesarios para todos los puntos finales en nuestra documentación de API.

Por defecto, la API de Clerk devuelve todos los resultados disponibles, pero si es necesario, se pueden usar Filtros para definir un subconjunto de coincidencias.

Búsqueda #

A continuación se muestra un ejemplo de hacer una llamada a un punto final de búsqueda para encontrar los mejores productos para una búsqueda sobre “star wars,”

curl --request POST \
     --url 'https://api.clerk.io/v2/search/predictive' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 30,
          "query": "star wars",
          "labels": ["Búsqueda - Predictiva"]
        }'

Recomendaciones #

A continuación se muestra un ejemplo de hacer una llamada a un punto final de recomendaciones para encontrar los productos más populares.

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 30,
          "labels": ["Página de inicio - Tendencias"]
        }'

3. Visualizar Resultados #

La API de Clerk siempre devuelve los IDs de las coincidencias que encontró al devolver resultados.

Para visualizar tus datos, puedes hacer llamadas a la API del lado del servidor, recuperar los IDs de los productos coincidentes, y luego obtener toda la información específica del producto de tu plataforma de tienda en línea o PIM antes de renderizarlos.

Llamada

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 3,
          "labels": ["Página de inicio - Tendencias"]
        }'

Respuesta

{
    "status": "ok",
    "result": [
        12793,
        13827,
        12693
    ],
    "count": 3902,
    "facets": null
}

La API de Clerk también se puede configurar para enviar de vuelta cualquier información específica de recursos que envíes a Clerk, como precios, nombres de marcas, URLs de categorías, imágenes de portada de blogs, y más.

Con esto, a menudo no necesitas hacer llamadas individuales a tu PIM antes de mostrar resultados, lo que cargará tu página más rápido.

Llamada

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 3,
          "labels": ["Página de inicio - Tendencias"],
          "attributes": ["id", "name", "price", "image", "url"]
        }'

Respuesta

{
    "status": "ok",
    "result": [
        12793,
        13827,
        12693
    ],
    "count": 3902,
    "facets": null,
    "product_data": [
        {
            "id": 12793,
            "image": "https://admin.awesomestore.com/image/14df",
            "name": "Jarrón Ovalado Rojo Baccarat Eye Pequeño",
            "price": 520.0,
            "url": "https://admin.awesomestore.com/product/14df"
        },
        {
            "id": 13827,
            "image": "https://admin.awesomestore.com/image/51xs",
            "name": "Cuchara de Sopa Verde 22cm Sabre Transat",
            "price": 13.96,
            "url": "https://admin.awesomestore.com/product/51xs"
        },
        {
            "id": 12693,
            "image": "https://admin.awesomestore.com/image/62x1",
            "name": "Tenedor de Cena Azul Claro 22cm Sabre Transat",
            "price": 13.96,
            "url": "https://admin.awesomestore.com/product/62x1"
        }
    ]
}

4. Seguimiento #

El seguimiento debe añadirse para mantener la IA de Clerk actualizada y personalizar los resultados de un visitante durante su sesión. Requiere 4 pasos:

  1. Generar un ID de sesión para cada visitante.
  2. Agregar etiquetas descriptivas a las llamadas a la API que devuelven resultados.
  3. Registrar los clics de un visitante en productos mostrados por Clerk.
  4. Registrar cada pedido realizado en la tienda en línea.

Crear ID de Visitante #

El ID de sesión también se llama ID de Visitante. Es necesario para registrar la actividad de un usuario durante una sesión en la tienda en línea, incluidos los productos en los que hace clic, sus búsquedas y las categorías que navega.

Esta actividad se almacena para cada tienda, y Clerk.io nunca la comparte entre tiendas.

Un ID de visitante es solo una cadena que se utiliza para identificar la sesión. Puede ser cualquier carácter alfanumérico, y recomendamos mantenerlo a un máximo de 8 caracteres para el mejor rendimiento.

Por ejemplo, podrías usar la función uniqid() de PHP para generar IDs que sean únicos al menos para la sesión actual. Una vez generado, este ID debe incluirse en todas las llamadas a la API de Clerk.io para que el seguimiento funcione.

<?php

session_start();

$current_visitor = uniqid(); //Ejemplo: "646f1f0584371"

$_SESSION["clerk_visitor_id"] = $current_visitor;

?>

Agregar Etiquetas #

Las etiquetas deben añadirse a todas las llamadas que devuelven resultados, como coincidencias de búsqueda o alternativas en una página de producto. El argumento labels es una lista que contiene al menos una cadena, que debería ser la etiqueta descriptiva de esta llamada.

Recomendamos usar etiquetas que describan la página donde se utiliza la llamada, y el tipo de resultados que muestra. Un ejemplo podría ser Página de inicio - Tendencias. Esto las hace fáciles de distinguir en análisis.

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 30,
          "labels": ["Página de inicio - Tendencias"],
          "visitor": $_SESSION["clerk_visitor_id"]
        }'

Registrar Clics #

Debes registrar cada clic en un producto de Clerk.io con el punto final log/click.

Es importante solo hacer esta llamada cuando el producto en el que se hizo clic es realmente mostrado por Clerk.io y no por la plataforma de la tienda en línea. De lo contrario, parecerá que todos los productos se encuentran a través de Clerk.

La llamada también debe contener el api que es el punto final utilizado para mostrar el producto que se hizo clic, y product que contiene el ID del producto que se hizo clic.

Búsqueda y Recomendaciones #

Registrar clics se hace añadiendo los parámetros a la llamada según el punto final utilizado para mostrar el producto que se hizo clic. Esto es sencillo ya que utiliza datos de la configuración que has hecho tú mismo.

curl --request POST \
     --url 'https://api.clerk.io/v2/log/click' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "labels": ["Página de inicio - Tendencias"],
          "api": "recommendations/trending",
          "visitor": $_SESSION["clerk_visitor_id"],
          "product": 12793
        }'

Recomendaciones por Correo Electrónico #

Registrar clics funciona de manera diferente, ya que recibirás los datos de las solicitudes GET que son reenviadas por Clerk.io. Debes monitorear si la URL incluye parámetros que indican que los visitantes aterrizan en una página de producto desde una Recomendación por Correo Electrónico.

Estas solicitudes siempre contendrán los siguientes parámetros de consulta:

{
  "utm_source": "clerk",
  "utm_medium": "email",
  "utm_campaign": "Correo de Bienvenida - Más Vendidos",
  "utm_content": "clerk-recommendations",
  "clerk_product": 12793,
  "clerk_labels": "Correo de Bienvenida - Más Vendidos",
  "clerk_api": "recommendations/popular",
  "clerk_n": 0,
  "clerk_external": 1
}

Recomendamos monitorear si la URL incluye clerk_external: 1 y si lo hace, registrar el clic con los datos que recibes.

clerk_api contiene el punto final de la API con un carácter * para evitar problemas de codificación. Esto debe cambiarse a / al registrar el clic. external: 1 debe añadirse a la llamada para que Clerk sepa que el clic proviene de un correo electrónico.

Aquí hay un ejemplo de llamada log/click que utiliza los datos anteriores:

curl --request POST \
     --url 'https://api.clerk.io/v2/log/click' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "labels": ["Correo de Bienvenida - Más Vendidos"],
          "api": "recommendations/popular",
          "visitor": $_SESSION["clerk_visitor_id"],
          "product": 12793,
          "external": 1
        }'

Registrar Productos #

Cuando los visitantes ven páginas de productos, esto debe registrarse para que pueda ser utilizado para personalizar resultados - específicamente los relacionados con el visitante como Recomendaciones para Visitantes o Alternativas para Visitantes.

Si utilizas algún punto final que ya necesita el ID del producto para funcionar, como recommendations/substituting o recommendations/complementary, Clerk.io registrará automáticamente el ID del producto.

Sin embargo, si no estás utilizando estos, necesitas hacer una llamada separada a log/product, con el ID del producto que se está navegando.

curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/trending' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "visitor": $_SESSION["clerk_visitor_id"],
          "product": 12793
        }'

Registrar Ventas #

La IA de Clerk.io depende en gran medida de los pedidos para predecir resultados, por lo que rastrear estos en tiempo real es clave. Se utiliza el punto final log/sale para esto.

Con el ID de visitante incluido en esta llamada, Clerk entenderá qué productos fueron mostrados, en cuáles se hizo clic y, finalmente, cuáles fueron comprados. Esto permite que la IA se mantenga siempre actualizada y cambie los resultados sobre la marcha según el comportamiento del cliente.

Esta llamada también asocia el ID de Visitante con la dirección de correo electrónico o el ID del cliente del comprador, lo que permite una mejor personalización a través de recomendaciones específicas para el cliente.

El id de los productos debe coincidir con los IDs que se registran para los clics. Por ejemplo, para productos configurables, debes rastrear el ID del padre en ambos log/click y log/sale independientemente de la variante comprada.
price es el precio unitario. Se multiplicará por quantity en Analíticas.
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0",
          "sale": 567,
          "products": [
            {
              "id": 12793,
              "price": 99.95,
              "quantity": 2
            },
            {
              "id": 1546,
              "price": 14.00,
              "quantity": 2
            }
          ],
          "customer": 1234,
          "email": "theone@matrix.com",
          "visitor": $_SESSION["clerk_visitor_id"]}' \
       https://api.clerk.io/v2/log/sale

Esta página ha sido traducida por una IA útil, por lo que puede contener errores de idioma. Muchas gracias por su comprensión.