> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alana.shopping/llms.txt
> Use this file to discover all available pages before exploring further.

# VTEX Quickstart

> Integrate Alana Shopping B2B with your VTEX store in under 5 minutes — product feed, search, and webhooks.

# 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](https://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:

```json theme={null}
{
  "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:

```typescript theme={null}
// 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`:

```bash theme={null}
curl -X GET "https://api.alana.shopping/api/mcp/feed/vtex?limit=50" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Response:**

```json theme={null}
{
  "platform": "vtex",
  "products": [
    {
      "productId": "SKU-001",
      "productName": "Running Shoes Pro",
      "category": "Footwear",
      "price": 299.90,
      "stockQuantity": 42
    }
  ],
  "total": 1250,
  "limit": 50,
  "offset": 0
}
```

## 3. Integrate with VTEX Intelligent Search

Replace or complement VTEX IS with Alana's semantic search:

```typescript theme={null}
// 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:

```bash theme={null}
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:

```typescript theme={null}
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:

```bash theme={null}
# 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

* [Search API](/api-reference/v1/search) — facets, autocomplete, boost rules
* [Error Reference](/api-reference/errors) — error codes and troubleshooting
* [Manifest endpoint](/api-reference/v1/search) — machine-readable capability discovery