API Reference

Base URL: https://api.advisorai.do/v1

Autenticación: Incluye tu API key en el header de cada request: Authorization: Bearer YOUR_API_KEY. Las API keys se crean en Dashboard > Settings > API Keys.
Límites de tasa: 60 requests/minuto por API key. Burst: 10/segundo. Si excedes el límite, recibirás 429 Too Many Requests con header Retry-After.
POST/v1/chat/turn

Envía un mensaje del visitante y recibe la respuesta del agente IA vía Server-Sent Events.

Parámetros

messagestringrequired

El mensaje del visitante

visitorIdstringrequired

Identificador único del visitante

conversationIdstring

ID de conversación existente para continuar

metaobject

Metadatos: pageUrl, productId, utm_source

Respuesta

Stream SSE con eventos: content (texto parcial), tool_start (nombre del tool), tool_end (resultado), done (fin del stream), error.

Ejemplo

curl -X POST https://api.advisorai.do/v1/chat/turn \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Do you have the RAV4 available?",
    "visitorId": "visitor_abc123"
  }'
GET/v1/catalog/items

Obtiene una lista paginada de items del catálogo.

Parámetros

pagenumber

Número de página (default: 1)

pageSizenumber

Items por página (default: 20, max: 100)

searchstring

Búsqueda

availableboolean

Filtrar por disponibilidad

Respuesta

{ items: [...], total: number, page: number }

Ejemplo

curl https://api.advisorai.do/v1/catalog/items?page=1&pageSize=20 \
  -H "Authorization: Bearer YOUR_API_KEY"
POST/v1/catalog/items

Crea o actualiza un item del catálogo. Si externalId ya existe, el item se actualiza (upsert).

Parámetros

externalIdstringrequired

ID de tu sistema para este item

titlestringrequired

Título del item

descriptionstring

Descripción del item

pricenumberrequired

Precio en centavos

currencystring

Código ISO 4217 (default: USD)

attributesobject

Atributos específicos del vertical

imageUrlstring

URL de imagen

availableboolean

Disponibilidad (default: true)

Respuesta

{ id: string, externalId: string, ... }

Ejemplo

curl -X POST https://api.advisorai.do/v1/catalog/items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "rav4-2024",
    "title": "Toyota RAV4 2024",
    "price": 3250000,
    "attributes": { "make": "Toyota", "model": "RAV4", "year": 2024 }
  }'
DELETE/v1/catalog/items/:id

Elimina permanentemente un item del catálogo.

Parámetros

idstringrequired

ID del item (parámetro de ruta)

Respuesta

{ deleted: true }

Ejemplo

curl -X DELETE https://api.advisorai.do/v1/catalog/items/itm_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
GET/v1/leads

Obtiene una lista paginada de leads capturados.

Parámetros

pagenumber

Número de página

pageSizenumber

Items por página

statusstring

Filtro: new, contacted, qualified, converted

searchstring

Buscar por nombre o email

Respuesta

{ leads: [...], total: number }

Ejemplo

curl https://api.advisorai.do/v1/leads?status=new \
  -H "Authorization: Bearer YOUR_API_KEY"
GET/v1/conversations

Obtiene una lista paginada de conversaciones.

Parámetros

pagenumber

Número de página

pageSizenumber

Items por página

statusstring

Filtro: active, completed

dateFromstring

Fecha ISO 8601

dateTostring

Fecha ISO 8601

Respuesta

{ conversations: [...], total: number }

Ejemplo

curl "https://api.advisorai.do/v1/conversations?dateFrom=2026-04-01" \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhooks

Próximamente
Eventos planificados: conversation.completed, lead.captured, visit.scheduled