Pular para o conteúdo principal

​
Nuvemshop Quickstart

Integre a Alana com sua loja Nuvemshop para feeds de produtos com IA e busca semântica. Este guia usa a Nuvemshop Partner API e um widget JavaScript.

​
Pré-requisitos

  • Loja Nuvemshop ativa
  • Chave de API da Alana (obtenha em app.alana.shopping → Configurações → Chaves de API)
  • Node.js 18+ para os scripts de integração

​
1. Configure sua chave de API

No painel da Nuvemshop: Aplicativos → Alana Shopping → Configurações e insira sua chave de API. Ou via variável de ambiente: 
ALANA_API_KEY=sua-chave-aqui
ALANA_WORKSPACE_ID=seu-workspace-id

​
2. Busque o feed de produtos

A Alana gera feeds CSV e JSON compatíveis com Nuvemshop a partir do seu catálogo: 
// fetch-alana-feed.js
const ALANA_BASE = "https://api.alana.shopping";

async function fetchAlanaFeed(limit = 50, offset = 0) {
  const response = await fetch(
    `${ALANA_BASE}/api/mcp/feed/nuvemshop?limit=${limit}&offset=${offset}`,
    {
      headers: { "X-API-Key": process.env.ALANA_API_KEY },
    }
  );

  if (!response.ok) {
    throw new Error(`Erro no feed: ${response.status}`);
  }

  return response.json(); // { platform, products, total, limit, offset }
}

// Sincronizar catálogo em lotes de 50
async function sincronizarCatalogo() {
  let offset = 0;
  let total = Infinity;

  while (offset < total) {
    const { products, total: t } = await fetchAlanaFeed(50, offset);
    total = t;

    for (const product of products) {
      console.log(`Sincronizando: ${product.name}`);
      // Upsert via Nuvemshop API
    }

    offset += 50;
  }

  console.log(`${total} produtos sincronizados`);
}

sincronizarCatalogo();
Via curl: 
curl -X GET "https://api.alana.shopping/api/mcp/feed/nuvemshop?limit=50" \
  -H "X-API-Key: SUA_CHAVE_API"
Resposta: 
{
  "platform": "nuvemshop",
  "products": [
    {
      "id": 12345,
      "name": { "pt": "Tênis Running Pro" },
      "price": "299.90",
      "stock": 42,
      "categories": [{ "name": { "pt": "Calçados" } }]
    }
  ],
  "total": 1250,
  "limit": 50,
  "offset": 0
}

​
3. Adicione busca Alana à sua loja

Integre a busca semântica da Alana via widget JavaScript no tema da sua loja: 
<!-- Adicione ao seu tema (layout/theme.html ou similar) -->
<div id="alana-search-widget">
  <input
    type="text"
    id="alana-search-input"
    placeholder="Buscar produtos..."
    autocomplete="off"
  />
  <ul id="alana-search-results"></ul>
</div>

<script>
  const ALANA_API_KEY = "{{ store.settings.alana_api_key }}";

  async function buscarProdutos(query) {
    if (!query || query.length < 2) {
      document.getElementById("alana-search-results").innerHTML = "";
      return;
    }

    const res = await fetch("https://api.alana.shopping/api/v1/search", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": ALANA_API_KEY,
      },
      body: JSON.stringify({ query, limit: 8 }),
    });

    const { hits } = await res.json();
    renderizarResultados(hits);
  }

  function renderizarResultados(produtos) {
    const lista = document.getElementById("alana-search-results");
    lista.innerHTML = produtos
      .map(
        (p) =>
          `<li><a href="/produtos/${p.handle}">
            <img src="${p.thumbnail}" alt="${p.title}" width="40" />
            <span>${p.title}</span>
            <strong>R$ ${p.price}</strong>
          </a></li>`
      )
      .join("");
  }

  // Debounce: busca 300ms após o usuário parar de digitar
  let debounce;
  document
    .getElementById("alana-search-input")
    .addEventListener("input", (e) => {
      clearTimeout(debounce);
      debounce = setTimeout(() => buscarProdutos(e.target.value), 300);
    });
</script>

​
4. Configure webhooks de feed

Receba notificações push quando seu feed for atualizado: 
curl -X POST "https://api.alana.shopping/api/v1/feeds/nuvemshop/webhooks" \
  -H "X-API-Key: SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-app.com/webhooks/alana",
    "events": ["feed.generated", "feed.failed"],
    "secret": "seu-segredo-hmac"
  }'
Valide a assinatura do webhook no seu servidor: 
import { createHmac } from "crypto";

function validarAssinatura(body, assinatura, segredo) {
  const esperado = createHmac("sha256", segredo)
    .update(body)
    .digest("hex");
  return esperado === assinatura;
}

// Exemplo com Express
app.post(
  "/webhooks/alana",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const sig = req.headers["x-alana-signature"];
    if (!validarAssinatura(req.body.toString(), sig, process.env.WEBHOOK_SECRET)) {
      return res.status(401).json({ erro: "Assinatura inválida" });
    }

    const { event, data } = JSON.parse(req.body);
    console.log(`Evento: ${event}, produtos: ${data?.productCount}`);
    res.status(200).json({ recebido: true });
  }
);

​
5. Verificar integração

# Confirme que o feed está acessível
curl "https://api.alana.shopping/api/mcp/feed/nuvemshop?limit=1" \
  -H "X-API-Key: SUA_CHAVE_API" | jq '.total'

# Verifique as estatísticas de consumo
curl "https://api.alana.shopping/api/v1/feeds/nuvemshop/analytics" \
  -H "X-API-Key: SUA_CHAVE_API"

​
Próximos passos

Last modified on March 17, 2026