Pular para o conteúdo principal

​
VTEX Quickstart

Integrate Alana with your VTEX store to power product feeds and AI search. This guide takes under 5 minutes for developers familiar with VTEX IO.

​
Prerequisites

  • VTEX store with IO enabled
  • Alana API key (get one at app.alana.shopping → Settings → API Keys)
  • VTEX CLI installed: npm install -g vtex

​
1. Configure your API key

In your VTEX IO app manifest or environment settings, add: 
{
  "ALANA_API_KEY": "your-api-key-here",
  "ALANA_WORKSPACE_ID": "your-workspace-id"
}
For VTEX admin panel: go to Apps → My Apps → Alana Shopping → Settings and paste your API key.

​
2. Fetch the product feed

Alana generates VTEX-compatible product feeds from your catalog. Poll this endpoint to sync products: 
// VTEX IO service — fetch Alana feed for VTEX
import axios from "axios";

const ALANA_BASE = "https://api.alana.shopping";
const API_KEY = process.env.ALANA_API_KEY;
const WORKSPACE_ID = process.env.ALANA_WORKSPACE_ID;

export async function fetchAlanaFeed(limit = 50, offset = 0) {
  const response = await axios.get(
    `${ALANA_BASE}/api/mcp/feed/vtex`,
    {
      headers: { "X-API-Key": API_KEY },
      params: { limit, offset },
    }
  );
  return response.data; // { platform, products, total, limit, offset }
}
Using curl: 
curl -X GET "https://api.alana.shopping/api/mcp/feed/vtex?limit=50" \
  -H "X-API-Key: YOUR_API_KEY"
Response: 
{
  "platform": "vtex",
  "products": [
    {
      "productId": "SKU-001",
      "productName": "Running Shoes Pro",
      "category": "Footwear",
      "price": 299.90,
      "stockQuantity": 42
    }
  ],
  "total": 1250,
  "limit": 50,
  "offset": 0
}
Replace or complement VTEX IS with Alana’s semantic search: 
// Proxy search queries to Alana
export async function searchProducts(query: string, facets?: Record<string, string[]>) {
  const response = await axios.post(
    "https://api.alana.shopping/api/v1/search",
    {
      query,
      facetFilters: facets,
      limit: 20,
    },
    {
      headers: {
        "X-API-Key": process.env.ALANA_API_KEY,
        "Content-Type": "application/json",
      },
    }
  );
  return response.data.hits; // Array of matching products
}

​
4. Configure feed webhooks

Receive push notifications when your feed updates instead of polling: 
curl -X POST "https://api.alana.shopping/api/v1/feeds/vtex/webhooks" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-vtex-app.myvtex.com/alana/webhook",
    "events": ["feed.generated", "feed.failed"],
    "secret": "your-hmac-secret"
  }'
Alana will POST to your endpoint when the feed updates. Verify the signature: 
import { createHmac } from "crypto";

export function verifyAlanaSignature(
  body: string,
  signature: string,
  secret: string
): boolean {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return expected === signature;
}

// In your VTEX IO route handler:
app.post("/alana/webhook", (req, res) => {
  const sig = req.headers["x-alana-signature"] as string;
  if (!verifyAlanaSignature(JSON.stringify(req.body), sig, process.env.WEBHOOK_SECRET!)) {
    return res.status(401).send("Invalid signature");
  }
  // Handle feed.generated or feed.failed event
  console.log("Feed event:", req.body.event, "products:", req.body.data?.productCount);
  res.status(200).send("OK");
});

​
5. Verify integration

Check that products are flowing: 
# Confirm feed is accessible
curl "https://api.alana.shopping/api/mcp/feed/vtex?limit=1" \
  -H "X-API-Key: YOUR_API_KEY" | jq '.total'

# Check consumption analytics
curl "https://api.alana.shopping/api/v1/feeds/vtex/analytics" \
  -H "X-API-Key: YOUR_API_KEY"

​
Next steps

Last modified on March 17, 2026