Integraciones

Visión general

La pantalla está en el menú Integraciones, con el subtítulo Conecte ChatISP a los sistemas del proveedor. El acceso exige el permiso Integraciones en el perfil (vea Usuarios y perfiles).

Fuera de esta pantalla quedan otras conexiones con servicios externos: los números de WhatsApp y la API oficial de Meta (Conexiones de WhatsApp), Google Calendar, que cada usuario conecta en Mi cuenta (vea Google Calendar), y el correo del sistema (vea Correo del sistema).

Ravicor

Ravicor es la plataforma de gestión de red de Ravi Systems. Conectado a ChatISP, responde por todo lo relacionado con la red en la ficha del cliente; el ERP sigue siendo la fuente del registro y de lo financiero.

Qué habilita la conexión

• La escena de la red del abonado en la tarjeta de la conversación: concentradora, sesión PPPoE, OLT y señal de la ONU, equipo, Wi-Fi, dispositivos conectados, caídas y reinicios (vea Ficha del cliente: red).
• Las acciones en el equipo del cliente: Reiniciar y Editar Wi-Fi, por el agente o por la IA.
• Para la IA, también la prueba de velocidad y el análisis y cambio del canal Wi-Fi, cuando el Ravicor instalado ya tiene estos diagnósticos.
• La vinculación manual de cliente por la búsqueda de registros (vea Vínculo manual).
• El botón Importar de Ravicor, que trae a ChatISP los ERPs registrados en Ravicor.
• Mientras no haya ningún ERP registrado en ChatISP, la identificación del cliente por el teléfono la hace Ravicor.

Estados de la tarjeta

Conectar por emparejamiento (recomendado)

En el emparejamiento nadie copia ninguna clave: ChatISP solicita acceso, alguien lo libera en Ravicor y la clave llega sola, guardada cifrada. No aparece en ninguna pantalla.

1. En la tarjeta Ravicor, complete Dirección del Ravicor con la IP o el nombre del servidor (por ejemplo 192.168.0.10). También puede ser la URL completa. Sin protocolo, ChatISP intenta HTTPS y, si no hay certificado, HTTP.
2. Haga clic en Conectar. La tarjeta pasa a Esperando liberación.
3. En Ravicor, abra Configuración › Integraciones y libere la solicitud de ChatISP.
4. Vuelva a ChatISP: la pantalla verifica sola cada pocos segundos y cambia a Conectada en cuanto se libera la solicitud, con el aviso Integración confirmada. No es necesario recargar.

Mientras espera, Cancelar solicitud desiste de la conexión. Si la solicitud es rechazada o eliminada en Ravicor, la tarjeta vuelve al inicio con el aviso La conexión fue eliminada en el Ravicor.

Probar y desconectar

• Probar conexión hace una llamada a Ravicor y responde Integración confirmada. o No fue posible conectar. Verifique la dirección y la clave.
• Desconectar pide la confirmación ¿Desconectar del Ravicor? El acceso del ChatISP se cancela en ambos lados. ChatISP avisa a Ravicor, que borra la clave, y limpia la conexión de este lado. Los ERPs importados de Ravicor siguen registrados en ChatISP.
• Al abrir la pantalla con la tarjeta conectada, ChatISP verifica si la conexión todavía existe en Ravicor; si fue eliminada allí, avisa y vuelve al estado inicial.

Configuración manual

Debajo del botón Conectar, Informar la clave de API manualmente abre los campos Dirección (URL completa) y Clave de API. La tarjeta pasa a Configurada con el texto Configurado con una clave de API informada manualmente.

ERPs y sistemas externos

La tarjeta ERPs y sistemas externos reúne las fuentes de registro y financieras de la atención. El ERP es quien dice quién es el cliente, en qué situación está el contrato y cuánto debe; ChatISP se comunica directamente con él, sin intermediarios.

La lista de ERPs

Cada ERP registrado ocupa una fila:

Sin ningún ERP, la tarjeta muestra Ningún ERP conectado todavía. Agregue una fuente o importe de Ravicor. Debajo de la lista de ERPs está la tabla de los sistemas externos genéricos (vea Sistemas externos).

Qué empresa atiende el ERP

Con más de una base de conocimiento activa (varias empresas en el mismo ChatISP), cada línea gana la elección Atiende: Todas las bases o el nombre de una base. Tocar graba al instante (Listo, la elección ya vale para las próximas atenciones.). En los números de una base, la asistente y la ficha del cliente consultan solo sus ERP y los que atienden todas. Con una sola base, nada aparece y el ERP atiende todo. Vea Varias bases: una por empresa.

Botones de la tarjeta

• Agregar fuente abre la ventana Agregar fuente externa, con una tarjeta para cada ERP homologado (IXC Provedor, SGP (TSMX), Hubsoft, Gesprov, ReceitaNet, Pipesoft: Registro guiado, en el patrón homologado) y la tarjeta Otro sistema (Integración genérica por API).
• Importar de Ravicor aparece con Ravicor conectado por emparejamiento. Vea Importar ERPs de Ravicor.

Registrar un ERP

1. En ERPs y sistemas externos, haga clic en Agregar fuente y elija el ERP.
2. En la ventana Conectar ERP, complete Nombre de esta conexión (cómo aparecerá el ERP en la pantalla y en la tarjeta del cliente) y Dirección (URL) de la API.
3. Complete las credenciales del ERP elegido (tabla abajo).
4. Haga clic en Probar y conectar. ChatISP hace una llamada real al ERP antes de grabar: solo guarda si la credencial funciona.
5. Una vez guardado, el ERP ya nace activado y la primera carga del espejo de abonados comienza en segundo plano. La pantalla puede cerrarse: la carga sigue sola y el conteo de abonados crece en la lista.

Campos por ERP

Mensajes al probar

Editar

En la edición, los campos secretos (token, contraseña, client secret) vienen vacíos con la sugerencia Deje en blanco para mantener la clave actual. En blanco, se mantiene la credencial guardada. En Hubsoft, para cambiar la credencial, informe Client Secret y Contraseña del usuario juntos. Toda edición se valida con una llamada real antes de grabar, vuelve a activar el ERP y dispara una nueva carga del espejo.

Particularidades de cada ERP

IXC Provedor

• El espejo se arma a partir de los logins de acceso, contratos, clientes, grupos de velocidad y planes de venta. La velocidad del plan viene del grupo de velocidad del login.
• La sincronización periódica trae solo lo que cambió desde la anterior. Cuando IXC libera un contrato por el pago sin marcar el cambio, el botón Actualizar de la tarjeta vuelve a leer ese cliente directamente en el ERP.
• Financiero: facturas pendientes (hasta 100 por cliente), último pago, boleto, enlace del gateway y Pix copia y pega cuando la cartera genera Pix, con la imagen del código QR suministrada por el propio IXC. ChatISP no genera ni actualiza boletos en IXC.
• Una factura cobrada por tarjeta o gateway que todavía no fue emitida llega sin forma de pago y aparece marcada en la ventana de facturas.
• Desbloqueo de confianza por contrato, con los días y restricciones configurados en IXC. La liberación temporal de IXC no está disponible por la API.
• Lista los títulos por fecha de vencimiento en la propia API, lo que alimenta la regla de cobranza automática sin espejo intermedio (Automatización de envíos).

Hubsoft

• Autenticación OAuth con client ID, client secret, usuario (correo) y contraseña.
• El espejo se arma a partir de los servicios de cada cliente. La sincronización periódica le pide a Hubsoft los servicios modificados desde el día de la anterior; la velocidad viene del texto del plan (por ejemplo "200 Mbits").
• Financiero: hasta 50 facturas pendientes por consulta, último pago, línea digitable, enlace del PDF y Pix copia y pega cuando la cartera genera Pix.
• Desbloqueo de confianza por servicio, con el tope de días definido en el panel de Hubsoft.

SGP (TSMX)

• Usa las rutas de consulta de la categoría URA de la API de SGP, solo lectura. El token y la aplicación deben ser correctos en conjunto.
• La API no ofrece filtro por fecha: cada sincronización recorre todo el listado de clientes.
• SGP no publica la velocidad en números, por lo que la tarjeta muestra solo el nombre del plan.
• Financiero: los títulos del contrato, cada uno con línea digitable, enlace del boleto y Pix copia y pega; el último pago sale de la misma consulta. El botón Actualizar de la tarjeta vuelve a leer al cliente directamente en SGP.
• Desbloqueo de confianza por la promesa de pago de la URA de SGP (el límite de promesas en el mes es regla de SGP y el rechazo vuelve explicado). Localización por CPF/CNPJ en vivo.

Gesprov

• Exige la API de monitoreo de servicios en la instalación de Gesprov.
• La unidad que Gesprov bloquea, libera y factura es el servicio; es lo que aparece como contrato en la tarjeta.
• Cada sincronización recorre todo el listado de servicios y completa teléfonos y correo a partir del registro de clientes.
• Las consultas financieras de Gesprov se hacen por el CPF/CNPJ del cliente, guardado cifrado en el espejo y abierto solo en el momento de la consulta.
• Financiero: facturas pendientes, Pix del gateway o del boleto (sin Pix en la factura, ChatISP solicita uno al gateway, lo que funciona con el gateway Efí), boleto en PDF. El último pago solo aparece cuando Gesprov informa la fecha de liquidación.
• Desbloqueo de confianza por servicio; las reglas (intervalo entre desbloqueos, servicio ya activo) son de Gesprov y el rechazo vuelve explicado.

ReceitaNet

• Sistema de servidor único: la dirección ya viene completada. Dos credenciales, cualquiera puede faltar: el token de la integración de cobranza por chat y el Client ID y Client Secret de la Central del Abonado.
• Con el token, cada cobro ya trae el registro del cliente y el pago listo (boleto, línea digitable y Pix copia y pega): el espejo nace de los propios cobros y la regla de cobranza por vencimiento consulta la API directamente.
• Con la Central del Abonado: segunda vía con código QR, facturas pagadas con la fecha del pago y la liberación en confianza (notificación de pago). Sin la Central, el último pago no aparece y el desbloqueo no está disponible.

Pipesoft

• Client ID y Client Secret del usuario de la API (Proveedor > Control de Usuario > API). Libere a ese usuario los controles cliente, plan y título; la escritura de cliente solo se usa para la liberación en confianza.
• El listado de clientes no trae teléfono ni dirección: la carga completa consulta cada registro individualmente, en paralelo, y las sincronizaciones siguientes rehacen el listado y completan los registros por partes. En bases de algunos miles de clientes la primera carga tarda algunos minutos.
• Velocidad del plan por el catálogo de planes de Pipesoft (el número es la velocidad aplicada, con el margen del aprovisionamiento). Sin el control de planes liberado, la tarjeta muestra solo el nombre del plan.
• Financiero: todos los títulos del cliente, con línea digitable y Pix copia y pega; último pago; segunda vía; localización por CPF/CNPJ en vivo. El botón Actualizar de la tarjeta vuelve a leer al cliente directamente en Pipesoft.
• Desbloqueo de confianza por la observación de Pipesoft: el cliente deja de ser bloqueado por atraso hasta la fecha límite (5 días por defecto) y la sesión se libera.
• Regla de cobranza por vencimiento por el espejo de títulos de ChatISP, renovado cada 6 horas.

Comparativo de capacidades por ERP

La localización por nombre completo usa el espejo local, por eso vale para todos; la localización por documento consulta el ERP en vivo. Cómo aparece cada recurso para el agente está en Ficha del cliente: lo que depende de cada ERP.

Espejo local y sincronización

Para identificar al cliente por el teléfono en milisegundos, sin depender de que el ERP responda en ese instante, ChatISP guarda una copia reducida de los abonados de cada ERP activo: el espejo local.

Qué guarda el espejo

Una fila por acceso (login o servicio) con el código del cliente y del contrato en el ERP, login de la conexión, nombre, plan, velocidad, situación normalizada, ciudad, barrio, dirección, teléfonos y correo. CPF/CNPJ, contraseñas de conexión y credenciales que el ERP devuelve junto se descartan. La excepción es Gesprov, cuyo documento queda guardado cifrado porque su API solo hace cobranza por CPF/CNPJ.

Cuándo sincroniza

En las cargas completas, los accesos que desaparecieron del ERP pasan a Cancelado en el espejo, en lugar de seguir apareciendo como activos.

Teléfonos

Todos los campos de teléfono del registro entran en el espejo, en el orden del ERP y sin repetir el mismo número escrito de dos maneras. En la búsqueda, los números se normalizan con el código de país 55 y el noveno dígito del celular. Un número sin código de área aprovecha el código de área del número vecino en el mismo campo.

Importar ERPs de Ravicor

Con Ravicor conectado por emparejamiento, el botón Importar de Ravicor copia a ChatISP los ERPs registrados en Ravicor, con dirección y credencial. El aviso {n} ERP(s) sincronizado(s) desde Ravicor lo confirma.

• Los ERPs importados se convierten en registros propios de ChatISP, marcados como importado de Ravicor, con espejo propio.
• Importar de nuevo actualiza la dirección y la credencial de los ya importados y crea los nuevos. Nunca borra nada: un ERP eliminado de Ravicor sigue en ChatISP hasta que se elimine aquí.
• La casilla Usar este ERP en la atención nunca es modificada por la importación: prevalece la elección hecha en ChatISP.
• Si el ERP rechaza la credencial de un ERP importado (porque fue cambiada en Ravicor), ChatISP vuelve a importar solo e intenta de nuevo.

Sistemas externos (integración genérica por API)

Cualquier sistema del proveedor con una API HTTP (un sistema financiero propio, un CRM, un sistema de órdenes de servicio) puede integrarse sin programación en ChatISP: usted describe las operaciones en JSON y la IA, los flujos y la tarjeta del cliente pasan a usarlas. El JSON es la única lista de operaciones permitidas: solo lo que esté en él puede ejecutarse, siempre contra la dirección base registrada.

Registrar

1. En ERPs y sistemas externos, haga clic en Agregar fuente y elija Otro sistema.
2. Complete la ventana Nuevo sistema (campos abajo).
3. Haga clic en Guardar. El JSON se valida al instante; un error de estructura aparece como El JSON de operaciones no es válido, seguido del punto con problema.
4. Use Probar en la tabla para ejecutar una operación real y ver la respuesta.

Formato de las operaciones

{
  "operacoes": [
    {
      "id": "faturas_abertas",
      "descricao": "Lista las facturas pendientes del cliente por el CPF",
      "metodo": "GET",
      "caminho": "/api/v1/faturas?cpf={cpf}&situacao=aberta",
      "parametros": [{ "nome": "cpf", "descricao": "CPF del cliente, solo numeros" }],
      "resposta": "lista de facturas con vencimiento, valor y enlace del boleto"
    },
    {
      "id": "liberar_confianca",
      "descricao": "Desbloqueo de confianza por el codigo del cliente",
      "metodo": "POST",
      "caminho": "/api/v1/desbloqueio",
      "corpo": { "cliente": "{codigo}", "dias": 3 },
      "parametros": [{ "nome": "codigo", "descricao": "Codigo del cliente" }]
    }
  ]
}

ChatISP no sigue redirecciones y aprovecha hasta 64 KB de cada respuesta. Las respuestas de 200 a 299 cuentan como éxito.

La tabla de sistemas

Columnas Nombre (con la dirección base), Operaciones (cuántas), Disponible para la IA, Última prueba (fecha en verde o rojo), Situación y las acciones Editar, Probar y Eliminar (con el aviso ¿Eliminar este sistema? La IA y los flujos dejarán de usarlo.).

La ventana de prueba lista las operaciones, abre un campo para cada parámetro de la operación elegida y muestra la respuesta con el código HTTP. Sin operaciones registradas, aparece Registre las operaciones en el JSON para probar.

Dónde se usan las operaciones

• IA: con Disponible para la IA activado, la IA recibe la lista de operaciones con sus descripciones y decide cuándo llamar a cada una. Vea Inteligencia artificial.
• Flujos: la etapa Consultar sistema elige el sistema, la operación y los parámetros, y responde al cliente con {resposta.campo} en el mensaje. Sin sistema registrado, la etapa muestra Registre un sistema externo en Integraciones para usar esta etapa. Vea Flujos.
• Tarjeta del cliente: por las convenciones de la próxima sección.

Convenciones de los sistemas externos

Algunos recursos de la ficha del cliente se activan automáticamente cuando el JSON de operaciones declara parámetros con nombres acordados. Basta con seguir los nombres:

Las respuestas envueltas en {"ok": true, "dados": {...}} se desenvuelven automáticamente. Cuando hay más de una operación que sirve, vale la que tiene menos parámetros. El vínculo manual a un sistema externo solo aparece cuando el sistema declara la búsqueda y la tarjeta del vinculado.

API de ChatISP (claves) Recurso del plan

La tarjeta API de ChatISP ("Claves para que otros sistemas usen la API: mensajes, conversaciones, contactos, órdenes de servicio, agenda e indicadores, cada clave con sus permisos.") crea las claves que el ERP, el CRM, el portal del suscriptor, el monitoreo o el BI del proveedor usan para trabajar con la atención por la API pública. La API pública y los webhooks forman parte de los planes a partir de PREMIUM; el número de claves activas depende del plan (3 en PREMIUM, 10 en GOLD, sin límite en ENTERPRISE). Fuera del plan, la tarjeta muestra el recurso bloqueado con el plan a partir del cual se incluye. El medidor junto al título muestra cuántas claves están en uso.

La parte superior de la tarjeta muestra la Dirección de la API de su instalación, con la sugerencia la clave va en el encabezado Authorization: Bearer, y el botón Documentación de la API, que abre la referencia completa.

Crear una clave

1. Haga clic en Nueva clave.
2. Asigne un Nombre que identifique el sistema que la usará. Ese nombre aparece en el historial de todo lo que haga la clave.
3. Active solo los permisos que la integración necesita (vea la tabla de abajo). En una clave nueva vienen activados Enviar mensajes, Consultar conversaciones y Abrir atenciones.
4. Con más de un número de WhatsApp conectado, elija el Número de origen: el número por el que esta clave envía cuando la llamada no informa la conexión. Sin esto, la API rechaza el envío que no informa conexao_id. La opción Ninguno (la llamada debe informar la conexión) deja la elección a cada llamada. Con un solo número, el campo no aparece.
5. Ajuste el Límite por minuto: llamadas aceptadas por minuto, predeterminado 60, máximo 10.000. 0 desactiva el límite.
6. Haga clic en Guardar. La ventana Clave creada muestra la clave completa con el botón Copiar.

Permisos de la clave

Los permisos están en tres grupos. Cada uno habilita un conjunto de operaciones de la API:

Conexiones, departamentos, agentes, plantillas, etiquetas y motivos están disponibles para cualquier clave activa, sin permiso: son los registros que toda integración necesita para armar las llamadas. El código técnico de cada permiso y las operaciones exactas que habilita están en Permisos de la clave (alcances).

La tabla de claves

• Columnas Nombre, Clave de API (solo el inicio, para reconocerla), Permisos (una etiqueta por permiso activado), Usos (pase el mouse para ver el Último uso) y Situación (Activa o Inactiva).
• Editar cambia nombre, permisos y límite, y permite desactivar la clave sin borrarla. La clave en sí no cambia: la integración sigue con el mismo valor, ya con los permisos nuevos.
• Revelar muestra la clave completa de nuevo, para quien tiene el permiso Integraciones.
• Eliminar borra la clave; el sistema que la usaba deja de poder llamar a la API.

Las 37 operaciones, el formato de las llamadas, los códigos de error y la colección para Postman e Insomnia están en la documentación de la API: Introducción a la API de ChatISP.

Webhooks de salida Recurso del plan

Un webhook avisa a un sistema suyo, por HTTP, cuando algo sucede en la atención. Forma parte del mismo recurso del plan que la API pública.

Crear un webhook

1. Haga clic en Nuevo webhook.
2. Informe Nombre y Dirección (la URL que recibirá los avisos).
3. Marque los eventos (al menos uno). En un webhook nuevo vienen marcados Mensaje recibido, Conversación creada y Conversación cerrada.
4. Haga clic en Guardar. La ventana Webhook creado muestra el Secreto, que sirve para verificar la firma de cada entrega.

Eventos disponibles

Cómo funcionan las entregas

• Cada evento se convierte en un POST con cuerpo JSON y los encabezados X-ChatISP-Evento, X-ChatISP-Entrega y X-ChatISP-Assinatura, que lleva el HMAC SHA-256 del cuerpo calculado con el secreto.
• El envío nunca retrasa la atención: el evento entra en una cola y se entrega en segundo plano, normalmente algunos segundos después.
• Las respuestas de 200 a 299 cuentan como entregadas. La espera máxima por respuesta es de 10 segundos.
• Si falla, ChatISP intenta de nuevo después de 1 minuto, 5 minutos, 15 minutos, 1 hora y 6 horas. Después del último intento, la entrega se descarta.

La tabla de webhooks

Columnas Nombre (con la URL), Eventos, Último envío (pase el mouse para ver el resultado; un número destacado indica entregas en la cola) y Situación. Acciones: Editar (incluso desactivar; las entregas pendientes quedan guardadas hasta reactivarlo), Probar (entrega en el momento un evento de prueba e informa Entrega de prueba aceptada o La entrega de prueba falló, con el código o el error), Secreto (revela el secreto) y Eliminar (las entregas pendientes se descartan).

El contenido exacto de cada evento, la verificación de la firma en PHP, Node.js y Python, y las reglas de reenvío y de duplicados están en Webhooks de salida en la documentación de la API.

Google Calendar

El reflejo de los compromisos en Google Calendar es individual: cada usuario conecta su propia cuenta Google en Mi cuenta, en la tarjeta Google Calendar, con el botón Conectar mi cuenta Google. La autorización se abre en una pestaña de la central de conexión de Ravi Systems; al concluir, aparece Cuenta Google conectada. Sus próximos compromisos serán reflejados.

• El sentido es único: los compromisos en los que el usuario es el responsable aparecen en su agenda de Google. Lo que se cree en Google no vuelve a ChatISP.
• Con la cuenta conectada, los tipos de compromiso configurados para ello pueden generar la sala de Google Meet automáticamente.
• Desconectar conserva los eventos ya creados en Google; los próximos dejan de reflejarse.

Detalles en Agenda.

Correo del sistema

ChatISP envía pocos correos: invitaciones para nuevos usuarios y códigos de recuperación de contraseña. Estos correos salen por un canal de envío mantenido por Ravi Systems, sin necesidad de configurar un servidor SMTP. No existe SMTP propio por instalación. Los mensajes al cliente final siempre salen por WhatsApp.

Seguridad de las credenciales

• Tokens, contraseñas y claves de ERPs, de Ravicor y de los sistemas externos quedan cifrados en la base de datos de ChatISP.
• Las credenciales de ERP y de sistemas externos son de solo escritura: una vez guardadas, nunca vuelven a la pantalla. Para cambiarlas, escriba la nueva; en blanco mantiene la actual.
• La clave de Ravicor obtenida por emparejamiento no aparece en ninguna pantalla.
• Las claves de la API de ChatISP y los secretos de los webhooks pueden revelarse de nuevo, por quien tiene el permiso Integraciones.
• Los datos personales sensibles que devuelven los ERPs (CPF/CNPJ, contraseñas de conexión) se descartan en el espejo local, con la excepción del documento cifrado de Gesprov y de ReceitaNet.
• Los sistemas externos solo ejecutan operaciones declaradas en el JSON y solo contra la dirección base registrada.

Problemas comunes