Cualquier (webshop)

API

Una forma flexible de integrar del 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, los cuales se describen en esta guía. Debes:

  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.

Constan de una clave pública, que da acceso a endpoints que exponen datos no sensibles, y una clave privada que permite trabajar con datos en el Store 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 ingresar datos en, permitiendo que la IA de Clerk.io comprenda tu tienda online y prediga resultados. Clerk sincroniza cada dominio de tienda online como su propia instancia de Store única, a la que se accede mediante un conjunto de claves API.

CRUD API #

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 un período de aprendizaje, ya que podemos utilizar todos los pedidos existentes desde el primer día para comprender el comportamiento actual del cliente.

Fuentes 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 salir mal con las llamadas de la API.

Por ejemplo, tu servidor de precios podría fallar, o un atributo de producto podría contener un error que haga 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 la tienda online.

Cualquier dato disponible en la fuente en el momento de su carga será con lo que Clerk trabajará, excepto 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 a Clerk con pedidos.

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

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

Las fuentes de datos deben estar disponibles en una URL que pueda ser accedida por el importador, el cual configuras en my.clerk.io en el backend en System status > Data Sync. Puedes proteger 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 pueden recuperarse 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 como “star wars,” puedes usar el endpoint search/predictive.

Endpoints #

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

Los endpoints que devuelven resultados también requieren el argumento “limit” para controlar la cantidad de resultados a 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úsquedas requiere el parámetro query para encontrar coincidencias.

Puedes encontrar los argumentos necesarios para todos los endpoints en nuestra documentación 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 productos principales 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 se muestra 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 diferentes funciones afectaron los resultados. Cada entrada incluye una feature, un message legible para humanos y metadatos estructurados (metadata) que describen 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 que encuentra al devolver resultados.

Para visualizar tus datos, puedes realizar llamadas a la API desde el servidor, recuperar los IDs de los productos coincidentes y luego obtener toda la información específica del producto desde tu plataforma de tienda online o PIM antes de mostrarlos.

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 de recursos que le envíes, como precios, nombres de marcas, 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 los resultados, lo cual 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": ["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 #

Debe añadirse seguimiento para mantener la IA de Clerk actualizada y personalizar los resultados de un visitante durante su sesión. Esto 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 los visitantes en productos mostrados por Clerk.
  4. Registrar cada pedido realizado en la tienda online.

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 online, incluidos los productos en los que hacen clic, sus búsquedas y las categorías que navegan.

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

Un ID de visitante es simplemente una cadena que se utiliza para identificar la sesión. Puede ser cualquier combinación alfanumérica, y recomendamos que tengan un máximo de 8 caracteres para el mejor rendimiento.

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

?>

Añadir etiquetas #

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

Se recomienda 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 facilita distinguirlos en los 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": ["Homepage - Trending"],
          "visitor": $_SESSION["clerk_visitor_id"]
        }'

Registrar clics #

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

Es importante hacer esta llamada solo cuando realmente se muestra el producto por Clerk.io y no por la plataforma de la tienda online. 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 endpoint usado para mostrar el producto clicado, y product que contiene el ID del producto en 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 en el que se hizo clic. Esto es directo ya que utiliza los datos de la configuración hecha por ti.

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 desde solicitudes GET que son reenviadas por Clerk.io. Debes monitorear si la URL incluye parámetros que indiquen que los visitantes llegan a la página de producto desde un 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
}

Se recomienda monitorear 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 añadirse a la llamada para que Clerk sepa que el clic procede de un email.

Aquí 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 productos, esto debe registrarse para que pueda usarse en la personalización de resultados, especialmente los relacionados con el visitante como Visitor Recommendations o Visitor Alternatives.

Si usas algún endpoint que ya requiere 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 usas estos, 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 ventas #

La IA de Clerk.io depende en gran medida de los pedidos para predecir resultados, así que es clave registrar estos en tiempo real. El endpoint log/sale se usa para esto.

Con el ID de visitante incluido en esta llamada, Clerk sabrá qué productos se mostraron, en cuáles se hizo clic y cuáles se compraron. Esto permite que la IA esté siempre actualizada y modificar resultados al vuelo según el comportamiento del cliente.

Esta llamada también asocia el ID de visitante con el correo electrónico o el ID del cliente que realiza la compra, permitiendo una mejor personalización mediante recomendaciones específicas para el 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 la 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 los períodos de picos de 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 de tasa. Las solicitudes que excedan estos umbrales pueden estar sujetas a limitación, pero que esto ocurra realmente depende de la capacidad actual del servidor.

Clerk.io escala su infraestructura dinámicamente. Durante eventos de alto tráfico como Black Friday, se agregan más servidores y se mantienen activos para manejar una mayor carga, 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.