Saltar al contenido
GUREN AI Docs

Plataforma y desarrolladores

Referencia de la API

Endpoints públicos y de plataforma de Guren AI: chat de Ana, ingreso de leads, agenda, diagnóstico APA, validación de SQL, integraciones, Laura y David, con autenticación, errores y límites.

Actualizado el

La API de Guren AI tiene dos partes: la API del sitio, que usa guren.cl (chat, leads, agenda, voz), y la API de plataforma bajo /api/v1, que atiende los avisos de los proveedores, las integraciones de cada cliente y las funciones de Laura y David.

#Convenciones

  • Base: https://guren.cl. Todo por HTTPS.
  • Formato: JSON en solicitudes y respuestas (Content-Type: application/json), salvo la importación de prospectos de Laura, que también acepta text/csv.
  • Fechas: ISO 8601 en UTC; las horas de agenda, en hora de Santiago (America/Santiago).
  • Teléfonos: formato internacional E.164 (+56912345678).
  • Tamaño: los avisos entrantes aceptan cuerpos de hasta 1 MB.

#Autenticación

TipoCómo se envíaDónde se usa
PúblicaSin credenciales.Chat de Ana en el sitio, formulario de contacto, agenda, catálogo de conectores, diagnóstico APA y demo del guardrail de David.
Firma del proveedorLa firma propia de cada proveedor: X-Hub-Signature-256 (Meta), firma v0 de Slack, firma de Twilio, X-Vapi-Secret, clave de Google Ads.Avisos entrantes de cada proveedor.
Firma de Guren AIX-Guren-Timestamp y X-Guren-Signature (HMAC-SHA256). Ver Webhooks firmados.Ingreso desde tu sistema y webhook saliente.
AdministraciónAuthorization: Bearer <token>Salud, sesiones y simulación de integraciones; operación de Laura; consultas de David sobre tu capa semántica.

#Errores

CódigoSignificado
400Cuerpo inválido o faltan campos obligatorios. El detalle viene en error.
403Origen no permitido: el chat de Ana solo responde a solicitudes desde el propio sitio.
401Firma o token inválido (invalid_signature, unauthorized).
404Cliente, instancia o recurso inexistente.
405Método no permitido.
413Cuerpo mayor a 1 MB.
422Solicitud válida pero rechazada por una regla: por ejemplo, una consulta SQL bloqueada por el guardrail.
429Límite de uso alcanzado (por ejemplo, sesiones de voz de demostración por hora). Incluye resetInSeconds.
503Función no habilitada en este entorno (por ejemplo, rutas de administración sin token configurado).

#API del sitio

Método y rutaQué hace
POST /api/ana/chatEnvía un mensaje a Ana con el historial y recibe su respuesta y la etapa. Solo acepta solicitudes desde el propio sitio y tiene límites por minuto y por día.
GET|POST /api/voice/sessionEntrega la configuración de una sesión de voz de demostración (máximo 3 minutos, con límite por IP).
POST /api/leadIngresa un lead del formulario de contacto y lo envía al destino configurado.
GET /api/booking/availability?date=AAAA-MM-DDHorarios libres de un día, en hora de Santiago.
POST /api/bookingCrea una reunión con Google Meet. Rechaza horarios pasados o a menos de 15 minutos.
POST /api/eventAnalítica propia del sitio, sin cookies. Responde siempre 204.
GET /api/healthEstado del servicio: {"status":"ok"}.

#Chat de Ana

Ana es sin estado en el chat web: quien llama mantiene el historial y lo envía en cada turno. El historial se sanea antes de usarse (ver saneamiento).

POST /api/ana/chat
curl -X POST https://guren.cl/api/ana/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "¿Pueden atender llamadas fuera de horario?",
    "history": [
      { "role": "user", "content": "Hola, tengo una clínica dental" },
      { "role": "assistant", "content": "¡Hola! ¿Qué te gustaría resolver en la clínica?" }
    ]
  }'
respuesta 200
{
  "ok": true,
  "role": "assistant",
  "name": "Ana",
  "tenant": "guren-corp",
  "company": "Guren AI",
  "content": "Sí, podemos ayudar a que tu clínica dental atienda consultas 24/7. Por ejemplo, si un paciente llama a las 10 de la noche, la llamada se atiende y la hora queda agendada para el día siguiente.\n\n¿Cuántas llamadas diarias recibes aproximadamente?",
  "thought": "…",
  "stage": "BOOKING",
  "context": { "industry": "isMedical", "pain": "operational_efficiency" }
}
CampoDescripción
contentLa respuesta de Ana, ya revisada por los guardrails de salida.
stageDISCOVERY, SOLUTION_MAPPING, QUALIFICATION o BOOKING.
contextLo que Ana ya sabe de la conversación (rubro, canal de leads, volumen, dolor, CRM), en etiquetas canónicas.
thoughtNota interna de diagnóstico. No la muestres al visitante.

#Ingreso de leads

POST /api/lead
POST https://guren.cl/api/lead
Content-Type: application/json

{ "name": "Camila Rojas", "email": "camila.rojas@ejemplo.cl", "company": "Ejemplo SpA",
  "phone": "+56912345678", "message": "Quiero cotizar para 3 sucursales", "source": "Formulario precios" }
respuesta 200
{ "ok": true, "leadId": "lead_1793019740123_a9f1b2", "message": "Lead recibido correctamente para Camila Rojas", "timestamp": "2026-11-02T15:02:20.123Z" }

name, email y company son obligatorios; si faltan o el correo no es válido, responde 400. Para integrar leads de tus sistemas en una implementación, usa el ingreso firmado.

#Plataforma · Integraciones de Ana

Método y rutaAutenticaciónQué hace
GET /api/v1/connectorsPúblicaCatálogo de conectores: tipo, categoría, capacidades, configuración y secretos que pide cada uno.
GET|POST /api/v1/hooks/metaFirma de MetaAviso único de la app de Meta de Guren AI. Enruta por número de WhatsApp o página.
GET|POST /api/v1/hooks/:cliente/:instanciaFirma del proveedorAviso de una instancia: Vapi, Slack, Twilio, Google Ads, ingreso firmado o Meta con app propia.
GET /api/v1/tenants/:cliente/health[?live=1]AdministraciónConfiguración y secretos faltantes por conector. Con live=1, prueba la conexión.
GET /api/v1/tenants/:cliente/sessions?contact=tel:+569…AdministraciónEstado de la sesión de un contacto: historial, cadencia y registro de acciones.
POST /api/v1/tenants/:cliente/simulateAdministraciónInyecta un evento canónico para ensayos. En modo borrador no envía nada.
catálogo de conectores
curl https://guren.cl/api/v1/connectors

#Plataforma · Laura

Método y rutaAutenticaciónQué hace
GET|POST /api/v1/laura/u/:tokenToken firmadoBaja en un clic (RFC 8058) desde el enlace o el encabezado List-Unsubscribe de cada correo.
POST /api/v1/laura/:cliente/slackFirma de SlackBotones de aprobación, rechazo y pausa en Slack.
GET /api/v1/laura/:cliente/summary · /log · /replies · /mailboxes[?live=1]AdministraciónEmbudo, registro de actividad, cola de respuestas y salud de los buzones.
GET /api/v1/laura/:cliente/prospects[?status=] · /prospects/:idAdministraciónProspectos por estado y detalle (investigación, puntaje, borradores, historial).
POST /api/v1/laura/:cliente/prospectsAdministraciónImporta prospectos como JSON ({"rows": [...]}) o CSV.
POST /api/v1/laura/:cliente/prospects/:id/{approve|reject|pause|reply|meeting}AdministraciónAcciones humanas sobre un prospecto.
POST /api/v1/laura/:cliente/search/apollo · /inbound-reply · /tickAdministraciónBúsqueda en Apollo, registrar una respuesta recibida por otra vía y forzar un ciclo de trabajo.

#Plataforma · David

Método y rutaAutenticaciónQué hace
GET /api/v1/david/apaPúblicaLas 10 preguntas del diagnóstico y su escala.
POST /api/v1/david/apaPúblicaCalcula el diagnóstico APA. Ver Diagnóstico APA.
POST /api/v1/david/demo/validatePúblicaValida un SQL con el guardrail sobre el esquema de referencia. No ejecuta nada.
GET /api/v1/david/:cliente/brainAdministraciónÍndice de la capa semántica, reglas, dominios y validación.
POST /api/v1/david/:cliente/askAdministraciónPregunta en lenguaje natural → respuesta con sello de auditoría.
POST /api/v1/david/:cliente/compileAdministraciónSolicitud estructurada → SQL certificado y resultado del guardrail, sin ejecutar.
POST /api/v1/david/:cliente/validateAdministraciónGuardrail sobre cualquier SQL, con la capa semántica del cliente.

#Probar el guardrail de David

POST /api/v1/david/demo/validate
curl -X POST https://guren.cl/api/v1/david/demo/validate \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT SUM(p.payment_value) FROM olist_orders o JOIN olist_order_items i ON o.order_id = i.order_id JOIN olist_order_payments p ON o.order_id = p.order_id LIMIT 10"}'
respuesta 422
{
  "ok": false,
  "status": "BLOCKED",
  "issues": [
    {
      "code": "UNSAFE_MULTI_JOIN_DUPLICATION",
      "message": "Agregar olist_order_payments cruzando olist_order_items (relación 1:N) duplica filas en silencio. Agrega cada hecho por separado (CTE) y luego une."
    }
  ],
  "schema": "olist-demo"
}

Una consulta segura responde 200 con "status": "APPROVED". Los códigos de bloqueo están en Consultas seguras.