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 API #

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

Consisten en una Clave Pública, que da acceso a endpoints que exponen datos no sensibles, y una Clave Privada que 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 después de ser creadas por motivos de seguridad, y puedes crear tantas como necesites para diferentes propósitos.

1. Sincronizar Datos #

El primer paso es ingresar 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 única de Store, a la cual se accede por un conjunto de Claves API.

CRUD API #

Puedes sincronizar tus datos usando los endpoints CRUD de la API, los cuales permiten obtener, enviar, 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 comprender el comportamiento actual de los clientes.

Feeds de Datos #

Además de usar la API CRUD, es muy recomendable añadir un método de sincronización de respaldo. Después de todo, muchas cosas pueden salir mal con las llamadas API.

Por ejemplo, tu servidor de precios podría fallar, o un atributo de producto podría contener un error que haga fallar varias llamadas. Para evitar estos problemas, considera usar uno o más Feeds de Datos como copia de seguridad diaria de tus llamadas CRUD.

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

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

Usar el feed de datos también es una excelente manera de precargar Clerk con pedidos.

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

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

El/los feed(s) de datos deben estar disponibles en una URL a la que pueda acceder el importador, lo cual configuras en el backend de my.clerk.io en System status > Data Sync. Puedes proteger 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 recuperarse mediante 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 mejores productos para una búsqueda sobre “star wars,” puedes usar el endpoint search/predictive.

Endpoints #

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

Los endpoints 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 endpoint al que estás llamando. Por ejemplo, las mejores alternativas requieren products, que es una lista de IDs de producto 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 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, un ejemplo de cómo realizar una llamada a un endpoint de Search para encontrar los productos principales 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": ["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 la respuesta #

Cuando la depuración está habilitada para una solicitud, las respuestas de la API incluyen un array debug que muestra, en orden, cómo diferentes funciones afectaron los resultados. Cada entrada incluye una feature, un message legible, y 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 los resultados encontrados al retornar 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 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 se puede configurar para devolver 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 hará 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 #

Es necesario añadir seguimiento para mantener la IA de Clerk actualizada 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 API que devuelven resultados.
  3. Registrar los clics de los visitantes en productos mostrados por Clerk.
  4. Registrar cada pedido realizado en el webshop.

Crear ID de Visitante #

El ID de sesión también se llama ID de visitante. Es necesario para registrar la actividad del usuario durante una sesión en el webshop, incluidos los productos 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 ID de visitante es solo una cadena que se usa para identificar la sesión. Puede contener cualquier carácter alfanumérico, y recomendamos mantenerlo en un máximo de 8 caracteres para obtener el mejor rendimiento.

Por ejemplo, puedes usar la función de PHP uniqid() para generar IDs ú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 #

Las etiquetas deben agregarse 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 usar etiquetas que describan la página donde se utiliza la llamada y el tipo de resultados que muestra. Un ejemplo podría ser Homepage - Trending. Esto las hace fáciles de distinguir en la analítica.

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 usando el endpoint log/click.

Es importante que solo realices esta llamada cuando el producto clicado haya sido mostrado por Clerk.io y no por la plataforma del webshop. De lo contrario, parecerá como si todos los productos se encontrasen a través de Clerk.

La llamada también debe contener api, que es el endpoint usado para mostrar el producto clicado, y product, que contiene el ID del producto clicado.

Search & Recommendations #

El registro de clics se realiza añadiendo los parámetros a la llamada según el endpoint que se usó para mostrar el producto clicado. Es sencillo, ya que utiliza datos de la configuración que tú has hecho.

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 observar si la URL incluye parámetros indicando que los visitantes llegan a una página de producto desde una Email Recommendation.

Estas solicitudes siempre contendrán los siguientes parámetros de la 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 supervisar si la URL incluye clerk_external: 1 y, si es así, registrar el clic con los datos recibidos.

clerk_api contiene el endpoint API con un carácter * para evitar problemas de codificación. Esto debe cambiarse a / al registrar el clic. external: 1 debe incluirse en la llamada para que Clerk sepa que el clic proviene de un email.

Aquí tienes un ejemplo de llamada a log/click usando 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 ven páginas de producto, esto debería registrarse para poder personalizar resultados, especialmente los relacionados con el visitante como Visitor Recommendations o Visitor Alternatives.

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

Sin embargo, si no los utilizas, debes hacer una llamada separada 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 Email #

Siempre que esté disponible la dirección de email de un cliente conocido en la sesión —ya sea que acabe de iniciar sesión o que haya regresado al sitio ya logueado— regístralo usando el endpoint log/email.

Esto vincula su ID de visitante con su dirección de email, lo cual Clerk.io necesita para activar emails automáticos en función del comportamiento de la sesión, personalizar recomendaciones mostradas dentro de emails y aplicar campañas de Merchandising que segmenten Audiences específicas.

Sin esta llamada, Clerk.io no puede conectar una sesión de navegación con una dirección de email, a menos que el visitante complete una compra.

Haz la llamada una vez por sesión cuando haya un email disponible. Omítela totalmente para visitantes desconocidos:

curl --request POST \
     --url 'https://api.clerk.io/v2/log/email' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "email": "theone@matrix.com",
          "visitor": $_SESSION["clerk_visitor_id"]}'

Registrar Ventas #

La IA de Clerk.io depende en gran medida de los pedidos para predecir resultados, por lo que registrarlos en tiempo real es clave. Para ello se usa el endpoint log/sale.

Incluyendo el ID de visitante en esta llamada, Clerk sabrá qué productos fueron mostrados, clicados y finalmente comprados. Esto permite que la IA siempre esté actualizada y cambie resultados sobre la marcha según el comportamiento del cliente.

Esta llamada también asocia el ID de visitante con la dirección de email o el ID de cliente del comprador, permitiendo una personalización aún mejor a través de recomendaciones específicas para cada cliente.

El id de los productos debe coincidir con los IDs registrados para los clics. Por ejemplo, para productos configurables se debe rastrear el ID del padre tanto en log/click como en log/sale, independientemente de 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 Tasa #

La API utiliza limitación de tasa (rate limiting) para garantizar un uso justo y mantener la estabilidad durante periodos de mucho tráfico.

Los límites son:

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

Las solicitudes dentro de estos límites nunca experimentarán limitación. Las solicitudes que superen estos umbrales pueden verse limitadas, pero si esto ocurre o no depende de la capacidad actual del servidor.

Clerk.io escala su infraestructura dinámicamente. Durante eventos de gran tráfico como Black Friday, se ponen en funcionamiento más servidores para gestionar 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.