API para Desarrolladores

Integra tus sistemas con Vendaq. Gestiona conversaciones, clientes, productos, conocimiento y más a través de nuestra API REST.

Quick Start

Base URL: https://vendaq-api.fly.dev/api/v1/public/

Autenticación: API Key en header X-API-Key o Authorization: Bearer vdq_live_xxx

Rate Limit: 100 requests/minuto por API key

curl -H "X-API-Key: vdq_live_tu_api_key_aqui" \
  https://vendaq-api.fly.dev/api/v1/public/conversations

Autenticación

Las API keys se crean desde el dashboard de Vendaq en Configuración → API Keys. La key completa solo se muestra una vez al crearla. El formato es vdq_live_ seguido de 32 caracteres hexadecimales.

Producción: vdq_live_a1b2c3d4...
Testing: vdq_test_a1b2c3d4...

Las keys son por tenant (organización), no por usuario. Puedes definir scopes para limitar los permisos.

Endpoints por Recurso

Conversaciones

Método	Ruta	Descripción
`GET`	`/conversations`	Listar conversaciones (paginado, filtros)
`GET`	`/conversations/:id`	Obtener conversación con mensajes
`POST`	`/conversations/:id/messages`	Enviar mensaje a conversación

Clientes

Método	Ruta	Descripción
`GET`	`/customers`	Listar clientes (búsqueda, paginado)
`GET`	`/customers/:id`	Obtener cliente con historial
`POST`	`/customers`	Crear cliente
`PATCH`	`/customers/:id`	Actualizar cliente

Productos

Método	Ruta	Descripción
`GET`	`/products`	Listar productos
`GET`	`/products/:id`	Obtener producto
`POST`	`/products`	Crear producto (source=api)
`PATCH`	`/products/:id`	Actualizar producto
`DELETE`	`/products/:id`	Eliminar producto

Knowledge Base

Método	Ruta	Descripción
`GET`	`/knowledge`	Listar chunks de conocimiento
`POST`	`/knowledge`	Agregar documento (auto-chunking)
`DELETE`	`/knowledge/:id`	Eliminar chunk

Escalaciones

Método	Ruta	Descripción
`GET`	`/escalations`	Listar escalaciones
`POST`	`/escalations/:id/resolve`	Resolver con respuesta
`POST`	`/escalations/:id/cancel`	Cancelar escalación

Agent Config

Método	Ruta	Descripción
`GET`	`/agent`	Obtener configuración del agente
`PATCH`	`/agent`	Actualizar configuración

Webhooks

Método	Ruta	Descripción
`GET`	`/webhooks`	Listar webhooks registrados
`POST`	`/webhooks`	Registrar webhook
`DELETE`	`/webhooks/:id`	Eliminar webhook

Analytics

Método	Ruta	Descripción
`GET`	`/analytics/summary`	Resumen: conversaciones, tiempos, intenciones

Eventos de Webhook

conversation.created — Nueva conversación iniciada
conversation.resolved — Conversación resuelta
message.received — Mensaje recibido del cliente
message.sent — Mensaje enviado por el agente/AI
escalation.created — Nueva escalación creada
escalation.resolved — Escalación resuelta
customer.created — Nuevo cliente registrado

Los webhooks incluyen firma HMAC-SHA256 en el header X-Vendaq-Signature. Reintentos: 3 veces con backoff exponencial.

Códigos de Error

Código	Significado
`400`	Bad Request — Parámetros inválidos
`401`	Unauthorized — API key inválida o faltante
`403`	Forbidden — Scope insuficiente
`404`	Not Found — Recurso no encontrado
`409`	Conflict — Recurso ya existe o conflicto de estado
`429`	Rate Limited — Excediste 100 req/min (ver Retry-After)
`500`	Server Error — Error interno

Formato de error: { error: { code: "ERROR_CODE", message: "Descripción"} }

Ver Referencia Completa →