Cómo usar la API de búsqueda de Shoply AI

Sí. Puedes consultar Shoply AI Search de forma programática desde tu propio backend sin cargar el widget en el sitio ni enviar la solicitud a través de tu storefront de Shopify.

La API de búsqueda estándar está disponible con cualquier plan de Shopify que incluya AI Search, incluido Forever Free. Las solicitudes a la API usan la misma asignación mensual de búsquedas que las búsquedas realizadas a través del widget del storefront. Consulta los límites actuales en nuestra página de precios.

Si necesitas límites más altos, un acuerdo de nivel de servicio, una fuente de datos personalizada o una integración que no use un catálogo de Shopify indexado por Shoply, contáctanos sobre un plan Enterprise.

Antes de empezar

Instala Shoply AI en la tienda Shopify cuyo catálogo quieres buscar y permite que termine el índice inicial de productos. Necesitarás el dominio permanente myshopify.com de la tienda, por ejemplo:

your-store.myshopify.com

Se puede llamar a la API desde cualquier entorno de backend. No se requiere una clave de API independiente para el endpoint estándar de búsqueda de productos porque devuelve la misma información pública del catálogo que Shoply puede mostrar en la experiencia de búsqueda del storefront.

Endpoint

POST https://api.shoplyai.ai/product_query_v2
Content-Type: application/json

Cuerpo de la solicitud

query es una cadena JSON dentro del cuerpo de la solicitud, no un objeto JSON anidado. Por ejemplo, la frase de búsqueda waterproof hiking boots se envía como:

"{\"keywords\":\"waterproof hiking boots\"}"

Ejemplo de cURL

Reemplaza your-store.myshopify.com por el dominio permanente de Shopify de tu tienda:

curl --request POST "https://api.shoplyai.ai/product_query_v2" \
  --header "Content-Type: application/json" \
  --data '{
    "store_key": "your-store.myshopify.com",
    "query": "{\"keywords\":\"waterproof hiking boots\"}",
    "start": 0,
    "limit": 8
  }'

Ejemplo de JavaScript

// Build the inner query separately because the API expects it as a JSON-encoded string.
const searchQuery = JSON.stringify({
  keywords: "waterproof hiking boots"
});
 
const response = await fetch("https://api.shoplyai.ai/product_query_v2", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    store_key: "your-store.myshopify.com",
    query: searchQuery,
    start: 0,
    limit: 8
  })
});
 
if (!response.ok) {
  throw new Error(`Shoply search failed with status ${response.status}`);
}
 
const results = await response.json();
console.log(results.docs);

Ejemplo de Python

import json
import requests
 
# The query value is encoded separately to match Shoply's structured search contract.
payload = {
    "store_key": "your-store.myshopify.com",
    "query": json.dumps({"keywords": "waterproof hiking boots"}),
    "start": 0,
    "limit": 8,
}
 
response = requests.post(
    "https://api.shoplyai.ai/product_query_v2",
    json=payload,
    timeout=30,
)
response.raise_for_status()
 
results = response.json()
print(results["docs"])

Respuesta

Una solicitud correcta devuelve:

{
  "num_results": 2,
  "docs": [
    {
      "product_id": "gid://shopify/Product/1234567890",
      "url": "https://your-store.example/products/example-product",
      "product_name": "Example Product",
      "brand": "Example Brand",
      "current_price": "129.00",
      "currency": "USD",
      "main_image": "https://cdn.shopify.com/example-product.jpg",
      "selected_variant_id": "gid://shopify/ProductVariant/1234567891"
    }
  ],
  "display_filters": []
}

• num_results es el número total de productos coincidentes.
• docs contiene los productos clasificados para la página solicitada.
• display_filters contiene filtros disponibles como precio, marca, color u otros atributos específicos del catálogo.

Los objetos de producto pueden contener campos adicionales según el catálogo de la tienda, las variantes, los precios y la configuración de Shoply. Los clientes deben usar los campos que necesiten e ignorar de forma segura los campos desconocidos.

Paginación

Usa start y limit para solicitar resultados adicionales. Por ejemplo, después de solicitar ocho productos con start: 0 y limit: 8, solicita la página siguiente con:

{
  "start": 8,
  "limit": 8
}

Detente cuando start + docs.length sea mayor o igual que num_results, o cuando docs esté vacío.

Notas sobre planes e integración

Si tu storefront personalizado también necesita conversación, agrega chat a un storefront headless de Shopify.

• La búsqueda estándar por API es de autoservicio y no requiere el widget en el sitio.
• Tu tienda Shopify debe permanecer conectada a Shoply AI para que su índice de productos pueda mantenerse actualizado.
• Las búsquedas por API y las búsquedas del storefront comparten la asignación mensual de búsquedas de tu plan de Shopify.
• Mantén la llamada en tu backend si quieres centralizar el almacenamiento en caché, los registros, los reintentos o el control de acceso.
• Contáctanos para obtener soporte Enterprise si necesitas autenticación personalizada, rendimiento garantizado, un SLA, un catálogo que no sea de Shopify o límites superiores a los planes publicados.

Si necesitas ayuda para confirmar tu store key o planificar una integración de producción, contacta a Shoply AI.