Opción de perfil | Menú Configuración - Integraciones |
Permisos de perfil | Menú Administración - Permisos:
|
En la pantalla de integración con la API es posible generar, consultar, editar y organizar las claves de API con seguridad y mejor usabilidad.
Esta funcionalidad permite realizar integraciones con socios o sistemas externos que no tienen conexión directa con EVO, posibilitando conexiones personalizadas según la necesidad.
EVO API
Si eres cliente EVO Black, la posibilidad de uso de la API está incluida, lo que permite realizar integraciones con otros sistemas con el apoyo de un especialista. La disponibilidad y los límites varían según el plan de API contratado, que puede ser API Plus y API Pro.
Para conocer los planes, consulta el artículo Planes – API EVO.
¿Qué es?
La EVO API permite que distintos sistemas "se comuniquen" entre sí. API significa Interfaz de Programación de Aplicaciones. Funciona como un plan entre los sistemas, indicando cómo enviar y recibir información.
La EVO API sigue el estándar REST, que utiliza funciones como GET, PUT y DELETE para acceder o modificar datos en el servidor.
Una característica importante es que no guarda datos entre una solicitud y otra. Cada solicitud es como acceder a un enlace web: haces la petición y el servidor devuelve los datos, sin una interfaz gráfica.
Consulta la Documentación para desarrolladores para obtener toda la información sobre cómo usar la API.
Comenzando a usar EVO API
Para comenzar, necesitas:
generar una clave de API para enviar solicitudes.
usar una herramienta como Apidog o Swagger para probar las solicitudes.
Generar clave de API
En EVO, puedes crear dos tipos de claves:
Clave de unidad única: da acceso solo a los datos de una unidad.
Clave multiunidad: permite el acceso a los datos de varias unidades, utilizando el parámetro
id-filial.
Vamos a conocer la pantalla y cómo crear la clave.
Conociendo la pantalla
En Configuración - Integraciones, al clíc en la tarjeta de EVO, se presenta una pantalla con dos pestañas y las siguientes opciones:
Pestaña Consumo: permite consultar todas las solicitudes, por mes y por token.
Pestaña Tokens: consulta de todos los tokens registrados, donde es posible activar o desactivar, editar y eliminar.
Botón NUEVO TOKEN: crea nuevos tokens.
Historial de cambios de los tokens.
Cómo crear un Token
Clíc en NUEVO TOKEN.
Se presenta la ventana de solicitud de login y contraseña del sistema EVO.
Clíc en CONFIRMAR.
En la pantalla Nuevo Token, completa los campos* de cada sección según lo indicado
General
En esta sección, completa el Nombre del Token, el Nombre del solicitante y el número de WhatsApp.
*Los campos con asterisco son obligatorios.
Utilización
Finalidad de uso: informa el propósito de la integración seleccionando una de las opciones disponibles.
Uso en interiores / Proveedor o socio: al seleccionar la opción Proveedor/Socio, informa el nombre del socio, el nombre del proveedor, correo electrónico o teléfono.
Si el proveedor no se encuentra en la lista, selecciona la opción Otro.
Permisos
Los permisos seleccionados deben estar relacionados con los datos a los que la clave podrá acceder.
Cada uno de estos permisos está vinculado a los endpoints, y para verificarlo, clíc en expandir.
Después de seleccionar todas las opciones, clíc en CREAR TOKEN.
Importante
Todos los campos obligatorios deben estar completos.
Se presentan los términos de uso; para continuar, clíc en ACEPTAR.
Se genera el DNS y el Token
Atención
Todos los Tokens creados tienen una validez de 2 años a partir de la fecha de creación.
Los Tokens creados por nuestro soporte tienen expiración automática en 3 días.
La proximidad de la expiración será informada en la barra de notificaciones con 30 días de anticipación.
También es posible consultar la validez del Token en la columna Fecha de expiración.
Consulta del consumo de solicitudes
En la pantalla de Consumo, es posible filtrar por mes y por token registrado. En la grilla de resultados se mostrarán los siguientes datos:
Token: token registrado.
Solicitudes por período: cantidad de solicitudes del mes seleccionado.
Estado actual del token, que puede ser Activo o Inactivo.
La consulta se presenta según tu plan. A continuación, consulta los detalles.
EVO API Plus
Solicitudes
En la tarjeta Solicitudes, se muestran las siguientes informaciones:
Consumo mensual, con el total utilizado y el límite por mes.
Consumo diario, con el total utilizado en el día y el límite diario.
Al clíc en Límites de solicitudes, es posible visualizar la cantidad permitida según el plan.
Al alcanzar el límite de solicitudes, se muestra en la tarjeta la fecha de liberación para nuevas solicitudes.
Consumo por día
En Consumo por día se presenta una tarjeta con la información de la cantidad de solicitudes por día. Como se muestra en el ejemplo a continuación, el eje horizontal representa los días y el eje vertical la cantidad de solicitudes. Al pasar el cursor sobre la línea, es posible verificar la cantidad de solicitudes (hits) y el día correspondiente.
EVO API Pro
En las tarjetas se mostrarán los datos del mes seleccionado.
Solicitudes
1- Total de solicitudes de todos los tokens registrados.
2- Valor diurno, valor nocturno y valor total, considerando todas las solicitudes y tokens.
3- Límite de solicitudes: permite verificar el total de solicitudes según el plan contratado. En el ejemplo presentado, se trata de un plan API Pro, en el cual es posible utilizar el header para no tener límite diario.
EVO API Pro
Consumo por día
En Consumo por día se presenta una tarjeta con la información de la cantidad de solicitudes por día. Como se muestra en el ejemplo a continuación, el eje horizontal representa los días y el eje vertical la cantidad de solicitudes. Al pasar el cursor sobre la línea, es posible verificar la cantidad de solicitudes (hits) y el día correspondiente.
Cambio de claves
En la pestaña Tokens, es posible cambiar el estado del token, editarlo o eliminarlo, si es necesario.
En la clave deseada, clíc en el ícono de editar.
Se mostrará la pantalla con los datos para la consulta del DNS y del token.
Es posible agregar o eliminar permisos.
Clíc en Guardar.
Para inactivar o activar un token, selecciona la opción Estado.
Para eliminar la clave, clíc en el ícono de la papelera e ingresa el login y la contraseña. Al eliminar el token, las integraciones que lo utilizan dejarán de funcionar y no podrá volver a utilizarse. Confirma la acción.
Las claves o tokens eliminados y modificados pueden consultarse en el ícono de reloj, ubicado en la parte superior derecha de la pantalla.
Probando la EVO API
La API de EVO utiliza autenticación básica. Para realizar llamadas, necesitas:
Usuario: el DNS generado en EVO.
Contraseña: la clave aleatoria creada en el último paso.
Puedes utilizar dos herramientas para probar las llamadas de la API:
Apidog: explora las áreas del sistema (entidades) y prueba sus funciones (endpoints).
Swagger: ofrece las mismas funcionalidades.
Cómo probar:
Ingresa tu usuario y contraseña.
Completa los datos solicitados para cada función (endpoint).
Las herramientas ofrecen un entorno de prueba seguro (sandbox), donde puedes ver los resultados de las llamadas que realices.
¿Qué son las entidades de la API?
Las entidades son las áreas del sistema a las que puedes acceder o modificar mediante la API. Algunos ejemplos:
Activities: gestionar clases (crear, listar, inscribir clientes).
BankAccounts: ver cuentas bancarias de los clientes.
Configuration: acceder a configuraciones de unidad y medios de pago.
Employees: gestionar colaboradores (agregar, editar, eliminar).
Invoices: buscar facturas por fecha.
Sales: gestionar ventas (crear, listar, devolver ítems).
Management: endpoints para obtener clientes y oportunidades activas y no renovadas.
MemberMembership: endpoints para obtener resúmenes de planes de clientes y realizar la cancelación.
Members: endpoints para obtener, actualizar y autenticar clientes.
Memberships: endpoints para obtener PLANES y sus categorías.
Notifications: endpoints para crear notificaciones.
Payables: endpoints para obtener acreedores y centros de costo.
Prospects: endpoints para obtener, agregar y actualizar oportunidades.
Receivables: endpoints para obtener y marcar cuentas por cobrar, además de obtener centros de costo.
Sales: endpoints para obtener, crear ventas y devolver ítems de venta.
Service: endpoints para obtener servicios.
Voucher: endpoints para obtener vouchers.
Webhook: endpoints para crear, listar y eliminar webhooks.
Workout: endpoints para obtener listas de entrenamientos y asociarlos a los clientes.
Paginación de la EVO API
La API de EVO devuelve, por defecto, 50 registros por vez. Algunos endpoints permiten, de forma excepcional, hasta 100 registros.
Para ajustar la cantidad de registros devueltos, utiliza los parámetros take y skip.
El encabezado de la respuesta siempre informa la cantidad de registros devueltos en relación con el total disponible.
Buenas prácticas en el uso de la EVO API
Uso en el backend: la API fue creada para ser utilizada en el backend, ya que la autenticación básica requiere el uso de claves de API. Usarla en el frontend puede exponer métodos y datos sensibles de tu(s) centro(s).
Evita horarios pico: La API utiliza datos de producción y comparte recursos con los procesos de EVO. Por eso, se recomienda realizar solicitudes más pesadas entre la 1:00 y las 6:00 de la mañana (horario de São Paulo) para no afectar la experiencia de uso del sistema.
Webhook
En la pestaña Webhook es posible enviar eventos del sistema automáticamente a herramientas externas, como bots de IA, plataformas de automatización, WhatsApp e integraciones vía API.
Esta funcionalidad forma parte del plan API Pro.
Para configurar y comprender todas las posibilidades dentro del sistema en detalle, consulta el artículo Configurar y enviar Webhook.