🔌 Avanzado y Beta > Endpoints externos

La funcionalidad Endpoints externos permite configurar integraciones HTTP para que Kewbot interactúe con APIs de terceros (CRM, ERP, scoring, validaciones, automatizaciones, etc.).

Con esta página puedes definir cómo Kewbot envía datos, recibe respuestas y decide el siguiente paso dentro de un flujo.

Nota: algunos campos pueden variar según versión del entorno, permisos y módulos habilitados.

---

¿Cuándo se usa?

• Para consultar datos de cliente antes de enrutar o responder.
• Para registrar eventos de conversación en sistemas externos.
• Para disparar automatizaciones fuera de Kewbot.
• Para enriquecer decisiones en ITRs/condiciones con información externa.

---

Vista de listado de endpoints

Campo / columna	Qué muestra	Para qué sirve
Nombre	Nombre interno del endpoint.	Identificación rápida dentro de flujos.
Descripción	Resumen funcional del endpoint.	Entender propósito sin abrir el detalle.
Estado	Activo/Inactivo.	Controlar disponibilidad operativa.
Método	GET, POST, PUT, PATCH, DELETE (según configuración).	Validar semántica de integración.
URL objetivo	Host/ruta principal configurada.	Verificar destino de llamadas.
Última ejecución	Fecha/hora de último uso.	Confirmar uso reciente.
Resultado último intento	Éxito o error más reciente.	Detección temprana de fallos.

---

Formulario de alta/edición de endpoint

Identificación y alcance

Campo	Qué significa
Nombre	Identificador funcional del endpoint en Kewbot.
Código / key interna	Clave técnica para referenciarlo desde flujos o reglas.
Descripción	Objetivo de negocio/técnico de la integración.
Activo	Habilita o bloquea su ejecución sin borrarlo.

Configuración de conexión

Campo	Qué significa
Método HTTP	Tipo de operación contra API externa.
URL base	Dominio/servidor principal del servicio externo.
Path / recurso	Ruta específica del recurso a invocar.
Query params	Parámetros de URL que se envían en la consulta.
Timeout (ms/seg)	Tiempo máximo de espera antes de cortar la llamada.
Reintentos	Número de intentos adicionales ante error o timeout.

Seguridad y autenticación

Campo	Qué significa
Tipo de autenticación	Modo de auth (None, API Key, Bearer, Basic, etc.).
API Key / Token / Usuario / Password	Credenciales según tipo de autenticación elegido.
Header de autorización	Nombre/valor del header para autenticar requests.
Headers personalizados	Pares clave-valor adicionales requeridos por la API.

Request (payload de salida)

Campo	Qué significa
Content-Type	Formato del body (JSON, form, etc.).
Body template	Plantilla de payload enviada al endpoint.
Variables disponibles	Campos de conversación/contacto que se pueden inyectar.
Mapeo de campos de salida	Relación entre datos de Kewbot y estructura requerida por API externa.

Campos a enviar y parámetros disponibles

El cuerpo del request se define en el campo Campos a enviar (JSON) como un objeto JSON de pares clave-valor:

• Clave (izquierda): el nombre del campo que la API externa espera recibir.
• Valor (derecha): un parámetro que Kewbot reemplaza en tiempo de ejecución por el dato correspondiente de la conversación, o un valor fijo (literal).

{
  "id": "_ATTR.client_id",
  "nombre": "{{nombre_cliente}}",
  "telefono": "_PHONE_REMOTE",
  "opcion_elegida": "_BUTTON_VALUE",
  "orden_trabajo": "_REC.orden_trabajo",
  "token": "abc123"
}

En el ejemplo anterior, "token": "abc123" es un valor fijo (se envía tal cual), mientras que el resto son parámetros que se resuelven dinámicamente.

Tipos de parámetros

Parámetro	Qué inyecta	Ejemplo de valor
_PHONE_REMOTE	Número de teléfono del cliente (contacto remoto) en formato internacional.	"telefono": "_PHONE_REMOTE"
_BUTTON_VALUE	Valor o payload del botón que presionó el cliente en el template.	"opcion": "_BUTTON_VALUE"
{{variable}}	Valor de una variable guardada en el ticket durante la conversación (p. ej. respuestas de inputs, resultados de pasos previos).	"dni": "{{dni}}"
_ATTR.nombre_atributo	Valor de un atributo del contacto (agenda / phonebook).	"cliente": "_ATTR.client_id"
_REC.nombre_atributo	Valor de un atributo del registro de campaña, es decir, lo enviado en el objeto attributes al disparar el envío por API (sendTemplate).	"ot": "_REC.orden_trabajo"
(texto fijo)	Cualquier otro valor se envía literal, sin reemplazo. Útil para tokens, claves o constantes.	"token": "abc123"

Notas: - Si un parámetro no puede resolverse (la variable o el atributo no existe), ese campo se envía con valor null. - Kewbot agrega automáticamente el campo message_alias_id al payload cuando hay un mensaje asociado, para que puedas correlacionar la llamada con el envío original. - El botón Simular llamada permite probar la configuración cargando manualmente los valores de cada parámetro antes de usarlo en un flujo real.

Response (procesamiento de entrada)

Campo	Qué significa
Código esperado (2xx/...)	Criterio para considerar la ejecución exitosa.
Mapeo de respuesta	Extracción de campos relevantes del response externo.
Guardar en variable	Persistencia de valores para uso en pasos posteriores del flujo.
Acción en error	Comportamiento cuando API responde error o timeout.
Mensaje/log de error	Texto o traza registrada para diagnóstico.

---

Prueba y validación del endpoint

En la pantalla de endpoint suele existir una opción de probar configuración.

Campo / control	Para qué sirve
Datos de prueba	Simular variables de una conversación real.
Ejecutar test	Lanzar llamada manual para validar configuración.
Status HTTP	Confirmar respuesta técnica del servidor externo.
Response body	Revisar contenido devuelto por API.
Tiempo de respuesta	Medir latencia de la integración.
Log técnico	Detectar errores de auth, formato o mapeo.

---

Recomendaciones de implementación

1. Usar credenciales seguras y rotación periódica.
2. Mantener timeouts y reintentos acotados para no bloquear flujos.
3. Versionar cambios de payload/mapeo con control de pruebas.
4. Definir estrategia de fallback cuando la API externa no esté disponible.
5. Auditar logs de error y tasa de éxito regularmente.

---