API Integration Requirements

This page documents what the external product API must provide for the Virbe retail kiosk flows to work. Share this page with the API provider's engineering team.

OverviewCopy Anchor Link

Virbe calls the external API using the Call Webhook node, which sends an HTTP POST request. Two types of lookups are needed:

1. Product search – natural language query with optional filters, returns multiple products
2. Product lookup – EAN/SKU code lookup, returns a single product

What Virbe SendsCopy Anchor Link

Depending on the flow, Virbe sends different data in the request body:

• User's natural language query – the customer's search phrase (e.g., "pink running shoes for women")
• Structured filters – extracted from conversation (gender, activity type, color, price range)
• EAN/SKU code – for direct product lookup via scan
• Conversation context (optional) – last N text messages for RAG-style processing

All values are injected using Virbe template variables (e.g., {{conv.search_query}}).

Input OptionsCopy Anchor Link

Option A: Natural Language Query (Recommended)Copy Anchor Link

The preferred input format. Virbe passes the customer's search phrase directly, as if typed into the website search bar.

{
  "query": "pink running shoes for women for trail running",
  "limit": 4
}

Optional additional filter parameters:

{
  "query": "running shoes",
  "filters": {
    "gender": "women",
    "maxPrice": 100,
    "discountedOnly": true
  },
  "limit": 4
}

Option B: Structured Filters OnlyCopy Anchor Link

For scenarios where preferences are collected step by step:

{
  "gender": "women",
  "category": "running-shoes",
  "color": "pink",
  "activity": "trail-running",
  "maxPrice": 100,
  "limit": 4
}

Option C: EAN/SKU LookupCopy Anchor Link

For RFID, barcode, and QR code scanning:

{
  "ean": "3608439415678"
}

Or by SKU:

{
  "sku": "SKU-12345"
}

Expected Response FormatCopy Anchor Link

JSON Response (Recommended)Copy Anchor Link

{
  "products": [
    {
      "id": "5506776",
      "title": "Trail Running Shoe XT6",
      "description": "Lightweight trail shoe with aggressive grip sole, designed for technical terrain and fast descents.",
      "price": 89.99,
      "currency": "EUR",
      "brand": "Kalenji",
      "gender": "women",
      "color": "pink",
      "sizes": ["36", "37", "38", "39", "40", "41"],
      "imageUrl": "https://cdn.example.com/products/5506776/main.jpg",
      "productPageUrl": "https://www.example.com/products/trail-running-shoe-xt6",
      "category": "running-shoes",
      "discountRate": 0.15
    }
  ]
}

Field ReferenceCopy Anchor Link

Additional fields can be included (e.g., rating, stockStatus, specifications) and will be available to the LLM for conversational responses.

Plain Text Response (Alternative)Copy Anchor Link

For simpler integrations, the API can return pre-formatted plain text:

id: 5506776
title: Trail Running Shoe XT6
description: Lightweight trail shoe with aggressive grip sole...
price: 89.99
brand: Kalenji
gender: women
color: pink
sizes: 36, 37, 38, 39, 40, 41

AuthenticationCopy Anchor Link

Configure authentication in the Call Webhook node's headers section:

Authorization: Bearer YOUR_API_KEY

Or as a custom header:

X-Api-Key: YOUR_API_KEY

Error HandlingCopy Anchor Link

The API should return standard HTTP status codes:

Use an If-Else Router node after the Call Webhook to check the response status and route to appropriate error handling flows.

Cookie settings