Referencia API

Todos los endpoints requieren autenticación via API key. Base URL: https://vendaq-api.fly.dev/api/v1/public

Conversaciones

GET /conversations

Listar conversaciones con paginación y filtros.

Query params: page, limit, status, channel, from, to

Response:

{ data: [{ id, status, channel, summary, intent, startedAt, lastMessageAt, customerId, customerName }], meta: { page, limit, total } }

Ejemplo:

curl -H "X-API-Key: vdq_live_xxx" "https://vendaq-api.fly.dev/api/v1/public/conversations?status=active&limit=10"

GET /conversations/:id

Obtener conversación con todos los mensajes.

Response:

{ data: { id, status, channel, ..., messages: [{ id, role, type, content, createdAt }] } }

Ejemplo:

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

POST /conversations/:id/messages

Enviar un mensaje a una conversación.

Request body:

{ "content": "Hola, tu pedido está en camino", "role": "agent" }

Response:

{ data: { id, conversationId, role, type, content, createdAt } }

Ejemplo:

curl -X POST -H "X-API-Key: vdq_live_xxx" -H "Content-Type: application/json" -d '{"content":"Hola"}' "https://vendaq-api.fly.dev/api/v1/public/conversations/UUID/messages"

Clientes

GET /customers

Listar clientes con búsqueda.

Query params: page, limit, search

Response:

{ data: [...], meta: { page, limit, total } }

Ejemplo:

curl -H "X-API-Key: vdq_live_xxx" "https://vendaq-api.fly.dev/api/v1/public/customers?search=juan"

GET /customers/:id

Obtener cliente con conversaciones recientes.

Response:

{ data: { id, name, phone, email, ..., recentConversations: [...] } }

Ejemplo:

curl -H "X-API-Key: vdq_live_xxx" "https://vendaq-api.fly.dev/api/v1/public/customers/UUID"

POST /customers

Crear cliente.

Request body:

{ "name": "Juan Pérez", "phone": "+56912345678", "email": "[email protected]" }

Response:

{ data: { id, name, phone, email, createdAt, ... } }

Ejemplo:

curl -X POST -H "X-API-Key: vdq_live_xxx" -H "Content-Type: application/json" -d '{"name":"Juan","phone":"+56912345678"}' "https://vendaq-api.fly.dev/api/v1/public/customers"

PATCH /customers/:id

Actualizar campos del cliente.

Request body:

{ "name": "Juan P.", "tags": ["vip"] }

Response:

{ data: { ...updated customer } }

Ejemplo:

curl -X PATCH -H "X-API-Key: vdq_live_xxx" -H "Content-Type: application/json" -d '{"name":"Juan P."}' "https://vendaq-api.fly.dev/api/v1/public/customers/UUID"

Productos

GET /products

Listar productos.

Query params: page, limit, search

Response:

{ data: [...], meta: { page, limit, total } }

Ejemplo:

curl -H "X-API-Key: vdq_live_xxx" "https://vendaq-api.fly.dev/api/v1/public/products"

GET /products/:id

Obtener producto.

Response:

{ data: { id, title, description, price, currency, inStock, ... } }

Ejemplo:

curl -H "X-API-Key: vdq_live_xxx" "https://vendaq-api.fly.dev/api/v1/public/products/UUID"

POST /products

Crear producto (source=api).

Request body:

{ "title": "Camiseta Negra", "price": "19990", "currency": "CLP", "inStock": true }

Response:

{ data: { id, title, price, source: "api", ... } }

Ejemplo:

curl -X POST -H "X-API-Key: vdq_live_xxx" -H "Content-Type: application/json" -d '{"title":"Camiseta","price":"19990"}' "https://vendaq-api.fly.dev/api/v1/public/products"

PATCH /products/:id

Actualizar producto.

Request body:

{ "price": "14990", "inStock": false }

Ejemplo:

curl -X PATCH -H "X-API-Key: vdq_live_xxx" -H "Content-Type: application/json" -d '{"price":"14990"}' "https://vendaq-api.fly.dev/api/v1/public/products/UUID"

DELETE /products/:id

Eliminar producto.

Response:

{ data: { id, deleted: true } }

Ejemplo:

curl -X DELETE -H "X-API-Key: vdq_live_xxx" "https://vendaq-api.fly.dev/api/v1/public/products/UUID"

Knowledge Base

GET /knowledge

Listar chunks de conocimiento.

Query params: page, limit

Response:

{ data: [{ id, sourceType, content, createdAt }], meta: { page, limit, total } }

Ejemplo:

curl -H "X-API-Key: vdq_live_xxx" "https://vendaq-api.fly.dev/api/v1/public/knowledge"

POST /knowledge

Agregar documento. Se divide automáticamente en chunks.

Request body:

{ "content": "Texto largo del documento...", "sourceType": "document", "sourceId": "faq-v2" }

Response:

{ data: [...chunks], meta: { chunksCreated: N } }

Ejemplo:

curl -X POST -H "X-API-Key: vdq_live_xxx" -H "Content-Type: application/json" -d '{"content":"..."}' "https://vendaq-api.fly.dev/api/v1/public/knowledge"

DELETE /knowledge/:id

Eliminar chunk de conocimiento.

Response:

{ data: { id, deleted: true } }

Ejemplo:

curl -X DELETE -H "X-API-Key: vdq_live_xxx" "https://vendaq-api.fly.dev/api/v1/public/knowledge/UUID"

Escalaciones

GET /escalations

Listar escalaciones.

Query params: page, limit, status

Response:

{ data: [{ id, question, category, urgency, status, createdAt }], meta: {...} }

Ejemplo:

curl -H "X-API-Key: vdq_live_xxx" "https://vendaq-api.fly.dev/api/v1/public/escalations?status=pending"

POST /escalations/:id/resolve

Resolver escalación con respuesta.

Request body:

{ "resolution": "El producto estará disponible el lunes." }

Ejemplo:

curl -X POST -H "X-API-Key: vdq_live_xxx" -H "Content-Type: application/json" -d '{"resolution":"..."}' "https://vendaq-api.fly.dev/api/v1/public/escalations/UUID/resolve"

POST /escalations/:id/cancel

Cancelar escalación pendiente.

Ejemplo:

curl -X POST -H "X-API-Key: vdq_live_xxx" "https://vendaq-api.fly.dev/api/v1/public/escalations/UUID/cancel"

Agent Config

GET /agent

Obtener configuración actual del agente AI.

Response:

{ data: { id, profile, personality, rules, knowledgeSettings, version } }

Ejemplo:

curl -H "X-API-Key: vdq_live_xxx" "https://vendaq-api.fly.dev/api/v1/public/agent"

PATCH /agent

Actualizar campos de configuración.

Request body:

{ "profile": { "greeting": "¡Bienvenido!" }, "personality": { "formality": "usted" } }

Ejemplo:

curl -X PATCH -H "X-API-Key: vdq_live_xxx" -H "Content-Type: application/json" -d '{"profile":{"greeting":"Hola"}}' "https://vendaq-api.fly.dev/api/v1/public/agent"

Webhooks

GET /webhooks

Listar webhooks registrados.

Response:

{ data: [{ id, url, events, active, createdAt }] }

Ejemplo:

curl -H "X-API-Key: vdq_live_xxx" "https://vendaq-api.fly.dev/api/v1/public/webhooks"

POST /webhooks

Registrar webhook.

Request body:

{ "url": "https://myapp.com/webhook", "events": ["message.received", "escalation.created"], "secret": "my_secret" }

Response:

{ data: { id, url, events, active, createdAt } }

Ejemplo:

curl -X POST -H "X-API-Key: vdq_live_xxx" -H "Content-Type: application/json" -d '{"url":"https://myapp.com/wh","events":["message.received"]}' "https://vendaq-api.fly.dev/api/v1/public/webhooks"

DELETE /webhooks/:id

Eliminar webhook.

Response:

{ data: { id, deleted: true } }

Ejemplo:

curl -X DELETE -H "X-API-Key: vdq_live_xxx" "https://vendaq-api.fly.dev/api/v1/public/webhooks/UUID"

Analytics

GET /analytics/summary

Resumen de métricas por rango de fechas.

Query params: from, to (ISO dates, default últimos 30 días)

Response:

{ data: { period, conversations: { total, resolved, resolutionRate, avgResponseMs }, escalations: { total, resolved }, topIntents: [...] } }

Ejemplo:

curl -H "X-API-Key: vdq_live_xxx" "https://vendaq-api.fly.dev/api/v1/public/analytics/summary?from=2026-01-01&to=2026-01-31"