Cualquier (webshop)

API

Una forma flexible de integrar del lado del servidor.

Toda la comunicación con Clerk se realiza 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. Añadir seguimiento

Claves de API #

Estas claves se utilizan para acceder a los datos de tu Store. Se encuentran en my.clerk.io > Developers > API Keys.

Constan de una clave Pública, que da acceso a endpoints que exponen datos no sensibles, y una Clave Privada que te permite trabajar con datos en la Store y acceder a datos sensibles, como información de clientes y pedidos.

Las Claves Privadas solo pueden verse una vez tras ser creadas por motivos 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 webshop y prediga resultados. Clerk sincroniza cada dominio de webshop como su propia instancia de Store única, a la que se accede mediante un conjunto de API Keys.

API CRUD #

Puedes sincronizar tus datos usando los endpoints 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": "Green Lightsaber",
                  "description": "Antique rebel lightsaber.",
                  "price": 99995.95,
                  "brand": "Je’daii",
                  "categories": [987, 654],
                  "created_at": 1199145600
                },
                {
                  "id": 789,
                  "name": "Death Star Deluxe",
                  "description": "Death Star. Fool proof."
                  "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 periodo de aprendizaje, ya que podemos utilizar todos los pedidos existentes desde el primer día para entender el comportamiento actual de los clientes.

Feeds de Datos #

Además de usar la API CRUD, se recomienda encarecidamente añadir un método de sincronización de respaldo. Después de todo, muchas cosas pueden fallar 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 el fallo de varias llamadas. Para evitar estos problemas, considera usar uno o más Data Feeds como copia de seguridad diaria para tus llamadas CRUD.

Los feeds de datos son uno o varios archivos JSON que contienen el catálogo actual de la webshop.

Cualquier dato disponible en el feed cuando se carga, será lo que Clerk utiliza, excepto los pedidos, que se registran y no necesitan incluirse en el feed después de la primera importación.

Usar el data feed también es una excelente forma de precargar Clerk con pedidos.

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

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

El/los data feed(s) deben estar disponibles en una URL que pueda ser accedida por el importador, que configuras en el backend de my.clerk.io en System status > Data Sync. Puedes asegurar el feed, para que solo nuestro importador pueda acceder a él.

2. Recuperar Datos #

Una vez sincronizados los datos, la IA los analiza y construye índices inteligentes que pueden ser recuperados a través de endpoints únicos según el caso de uso.

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

Endpoints #

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

Los endpoints que devuelven resultados también requieren el argumento “limit” para controlar la cantidad de resultados que se deben devolver.

Los parámetros adicionales dependen del endpoint 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 búsqueda necesita el parámetro query para encontrar coincidencias.

Puedes encontrar los argumentos necesarios para todos los endpoints en nuestra documentación de la 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.

A continuación, se muestra un ejemplo de cómo hacer una llamada a un endpoint de Search para encontrar los principales productos para una búsqueda de “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": ["Search - Predictive"]
        }'

Recommendations #

A continuación, un ejemplo de cómo hacer una llamada a un endpoint de Recommendations 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": ["Homepage - Trending"]
        }'

Depuración de Respuestas #

Cuando la depuración está habilitada para una solicitud, las respuestas de la API incluyen un array debug que muestra, en orden, cómo distintas funciones afectaron los resultados. Cada entrada incluye una feature, un message legible y un metadata estructurado que describe los efectos específicos.

{
  "status": "ok",
  "result": [
    "riverbank",
    "pretty-tree"
  ],
  "count": 2,
  "hits": 2,
  "debug": [
    {
      "feature": "merchandising",
      "message": "Applying merchandising campaign: Test-promote-in-results. Any calculated effects are available in the metadata.",
      "metadata": {
        "promote_in_result": {
          "frequency=(2, 0)": {
            "promoted_products": [
              [
                "riverbank"
              ]
            ]
          }
        }
      }
    },
    {
      "feature": "merchandising",
      "message": "Applying merchandising campaign: test-promote-to-position. Any calculated effects are available in the metadata.",
      "metadata": {
        "promote_to_position": {
          "position=(0, 1)": {
            "promoted_products": [
              [
                "0001",
                "FFFF"
              ]
            ]
          }
        },
        "adjust_position": {
          "FFFF": [
            {
              "max_depth": 1,
              "boost": 100000
            }
          ]
        }
      }
    },
    {
      "feature": "merchandising",
      "message": "Applying merchandising campaign: Test campaign. Any calculated effects are available in the metadata.",
      "metadata": {
        "boost": {
          "SPACER0": -2.0
        }
      }
    }
  ]
}

3. Visualizar Resultados #

La API de Clerk siempre devuelve los IDs de las coincidencias encontradas al devolver resultados.

Para visualizar tus datos, puedes realizar llamadas a la API del lado del servidor, obtener los IDs de los productos coincidentes y luego obtener toda la información específica de los productos desde tu plataforma de webshop 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": ["Homepage - Trending"]
        }'

Respuesta

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

La API de Clerk también puede configurarse para devolver cualquier información específica del recurso que envíes a Clerk, como precios, nombres de marca, URLs de categorías, imágenes de portada de blog y más.

Con esto, a menudo no necesitas hacer llamadas individuales a tu PIM antes de mostrar resultados, lo que permitirá que tu página cargue 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": ["Homepage - Trending"],
          "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": "Baccarat Eye Small Oval Red Vase",
            "price": 520.0,
            "url": "https://admin.awesomestore.com/product/14df"
        },
        {
            "id": 13827,
            "image": "https://admin.awesomestore.com/image/51xs",
            "name": "Sabre Transat Garden Green 22cm Soup Spoon",
            "price": 13.96,
            "url": "https://admin.awesomestore.com/product/51xs"
        },
        {
            "id": 12693,
            "image": "https://admin.awesomestore.com/image/62x1",
            "name": "Sabre Transat Light Blue 22cm Dinner Fork",
            "price": 13.96,
            "url": "https://admin.awesomestore.com/product/62x1"
        }
    ]
}

4. Seguimiento #

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

  1. Generar un ID de sesión para cada visitante.
  2. Añadir etiquetas descriptivas a las llamadas a la API que devuelven resultados.
  3. Registrar los clics de un visitante en los productos mostrados por Clerk.
  4. Registrar cada pedido realizado en la webshop.

Crear ID de Visitante #

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

Esta actividad se almacena para cada Store, y Clerk.io nunca la comparte entre Stores.

Un visitor ID es simplemente una cadena usada para identificar la sesión. Puede ser cualquier carácter alfanumérico y recomendamos mantenerla a un máximo de 8 caracteres para un rendimiento óptimo.

Por ejemplo, podrías usar la función uniqid() de PHP para generar IDs que son únicos al menos para la sesión actual. Una vez generado, este ID debe ser incluido 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;

?>

Añadir Etiquetas #

Se deben añadir etiquetas a todas las llamadas que devuelvan 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 debe ser la etiqueta descriptiva de esta llamada.

Recomendamos utilizar etiquetas que describan la página donde se usa la llamada y el tipo de resultados que muestra. Un ejemplo podría ser Homepage - Trending. Esto facilita distinguirlas en las analíticas.

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": ["Homepage - Trending"],
          "visitor": $_SESSION["clerk_visitor_id"]
        }'

Registrar Clics #

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

Es importante solo hacer esta llamada cuando el producto clicado es realmente mostrado por Clerk.io y no por la plataforma de la webshop. De lo contrario, parecerá que todos los productos fueron encontrados mediante Clerk.

La llamada también debe contener el campo api, que es el endpoint usado para mostrar el producto sobre el que se hizo clic, y product, que contiene el ID del producto sobre el que se hizo clic.

Search & Recommendations #

El registro de clics se realiza añadiendo los parámetros a la llamada según el endpoint usado para mostrar el producto sobre el que se hizo clic. Esto es sencillo, ya que utiliza los datos que has configurado 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": ["Homepage - Trending"],
          "api": "recommendations/trending",
          "visitor": $_SESSION["clerk_visitor_id"],
          "product": 12793
        }'

Email Recommendations #

El registro de clics funciona de manera diferente, ya que recibirás los datos de solicitudes GET que son reenviadas por Clerk.io. Debes monitorizar si la URL incluye parámetros que indiquen que los visitantes llegan a una página de producto desde una Email Recommendation.

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

{
  "utm_source": "clerk",
  "utm_medium": "email",
  "utm_campaign": "Welcome Email - Bestsellers",
  "utm_content": "clerk-recommendations",
  "clerk_product": 12793,
  "clerk_labels": "Welcome Email - Bestsellers",
  "clerk_api": "recommendations/popular",
  "clerk_n": 0,
  "clerk_external": 1
}

Recomendamos monitorizar si la URL incluye clerk_external: 1 y, si es así, registrar el clic con los datos que recibas.

clerk_api contiene el endpoint 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 email.

Aquí tienes un ejemplo de llamada a 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": ["Welcome Email - Bestsellers"],
          "api": "recommendations/popular",
          "visitor": $_SESSION["clerk_visitor_id"],
          "product": 12793,
          "external": 1
        }'

Registrar Productos #

Cuando los visitantes visualicen páginas de producto, esto debe registrarse para poder personalizar los resultados, en particular los relacionados con el visitante como Visitor Recommendations o Visitor Alternatives.

Si usas cualquier endpoint que ya necesite el ID de producto para funcionar, como recommendations/substituting o recommendations/complementary, Clerk.io registrará el ID automáticamente.

Sin embargo, si no usas estos, debes hacer una llamada independiente a log/product, con el ID del producto que se está visualizando.

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 es clave rastrearlos en tiempo real. El endpoint log/sale se utiliza para esto.

Con el visitor ID incluido en esta llamada, Clerk entenderá qué productos se mostraron, en cuáles se hizo clic y cuáles se compraron finalmente. Esto permite que la IA se mantenga siempre actualizada y cambie los resultados en tiempo real según el comportamiento del cliente.

Esta llamada también asocia el Visitor ID con la dirección de email o el ID de cliente del comprador, lo que permite personalización aún mejor mediante recomendaciones específicas para clientes.

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 tanto en log/click como en log/sale sin importar la variante comprada.
price es el precio unitario. Se multiplicará por quantity en Analytics.
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

Limitación de Frecuencia #

La API utiliza limitación de frecuencia para asegurar un uso justo y mantener la estabilidad durante los periodos de mayor tráfico.

Los límites son:

  • 50 peticiones por segundo por Store
  • 100 peticiones por segundo por dirección IP

Las peticiones que respeten estos límites nunca experimentarán limitación. Las peticiones que superen estos umbrales pueden ser limitadas, aunque si esto ocurre o no depende de la capacidad del servidor en ese momento.

Clerk.io escala su infraestructura dinámicamente. Durante eventos de alto tráfico como Black Friday, se añaden más servidores y permanecen activos para manejar la carga adicional, lo que significa que la capacidad efectiva es mucho mayor de lo que sugieren los límites base.

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