Como usar a API de Busca com IA da Shoply

Sim. Você pode consultar a Busca com IA da Shoply programaticamente a partir do seu próprio backend sem carregar o widget no site nem enviar a requisição pela sua storefront da Shopify.

A API de busca padrão está disponível em qualquer plano Shopify que inclua Busca com IA, incluindo o Forever Free. As requisições à API usam a mesma franquia mensal de buscas que as buscas feitas pelo widget da storefront. Veja os limites atuais na nossa página de preços.

Se você precisar de limites mais altos, um acordo de nível de serviço, uma fonte de dados personalizada ou uma integração que não use um catálogo Shopify indexado pela Shoply, fale conosco sobre um plano Enterprise.

Antes de começar

Instale a Shoply AI na loja Shopify cujo catálogo você deseja pesquisar e aguarde a conclusão da indexação inicial dos produtos. Você precisará do domínio permanente myshopify.com da loja, por exemplo:

your-store.myshopify.com

A API pode ser chamada de qualquer ambiente de backend. Não é necessária uma chave de API separada para o endpoint padrão de busca de produtos, porque ele retorna as mesmas informações públicas de catálogo que a Shoply pode exibir na experiência de busca da storefront.

Endpoint

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

Corpo da requisição

query é uma string JSON dentro do corpo da requisição, não um objeto JSON aninhado. Por exemplo, a frase de busca waterproof hiking boots é enviada como:

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

Exemplo em cURL

Substitua your-store.myshopify.com pelo domínio Shopify permanente da sua loja:

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
  }'

Exemplo em 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);

Exemplo em 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"])

Resposta

Uma requisição bem-sucedida retorna:

{
  "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 é o número total de produtos correspondentes.
• docs contém os produtos ranqueados para a página solicitada.
• display_filters contém filtros disponíveis, como preço, marca, cor ou outros atributos específicos do catálogo.

Os objetos de produto podem conter campos adicionais dependendo do catálogo da loja, das variantes, dos preços e da configuração da Shoply. Os clientes devem usar os campos de que precisam e ignorar com segurança campos desconhecidos.

Paginação

Use start e limit para solicitar resultados adicionais. Por exemplo, depois de solicitar oito produtos com start: 0 e limit: 8, solicite a próxima página com:

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

Pare quando start + docs.length for maior ou igual a num_results, ou quando docs estiver vazio.

Observações sobre plano e integração

Se a sua storefront personalizada também precisar de conversa, adicione chat a uma storefront headless da Shopify.

• A busca padrão via API é self-service e não requer o widget no site.
• Sua loja Shopify deve permanecer conectada à Shoply AI para que o índice de produtos continue atualizado.
• As buscas via API e as buscas da storefront compartilham a franquia mensal de buscas do seu plano Shopify.
• Mantenha a chamada no seu backend se quiser centralizar cache, logs, novas tentativas ou controle de acesso.
• Fale conosco para suporte Enterprise se você precisar de autenticação personalizada, throughput garantido, um SLA, um catálogo que não seja da Shopify ou limites além dos planos publicados.

Para ajuda na confirmação da sua store key ou no planejamento de uma integração em produção, entre em contato com a Shoply AI.