API significa Application Programming Interface (Interfaz de Programación de Aplicaciones). En el contexto de APIs, la palabra Aplicación se refiere a cualquier software con una función específica. La interfaz puede entenderse como un contrato de servicio entre dos aplicaciones. Este contrato define cómo se comunican utilizando solicitudes y respuestas. La documentación de sus respectivas APIs contiene información sobre cómo los desarrolladores deben estructurar estas solicitudes y respuestas, como esta API Reference.La EVO API es una API REST. REST significa Transferencia Representacional de Estado. REST define un conjunto de funciones como GET, PUT, DELETE, entre otras, que pueden utilizarse para acceder a los datos del servidor. El solicitante y los servidores intercambian datos utilizando HTTP.La característica principal de una API REST es la ausencia de estado. Esto significa que los servidores no guardan datos del cliente entre solicitudes. Las solicitudes al servidor son similares a las URLs que escribes en el navegador para visitar un sitio web. La respuesta del servidor corresponde a datos simples, sin la renderización gráfica típica de una página web.
Para obtener las claves necesarias para realizar solicitudes de API, es necesario crearlas dentro del propio EVO. Es importante entender que existen dos tipos de claves de API que pueden crearse:
Clave única de sucursal: clave creada en la instancia de una sucursal con permisos y acceso solo a los datos de esa sucursal;
Clave multisucursal: clave creada en una instancia de ADM General con acceso solo a llamadas que contienen el parámetro idbranch.
La ruta para la creación de las claves en EVO es Configuraciones - Integraciones y acceder al card EVO en la sección API:Al hacer clic en el card EVO se presenta la siguiente pantalla:1- Lista en orden alfabético con todos los Tokens de integración creados.2- Campo de búsqueda para encontrar el nombre del Token.3- NUEVO TOKEN: botón para crear nuevos Tokens.4- Acciones: editar y eliminar los Tokens creados.5- Historial de eliminación de Tokens.
Se mostrará la ventana de solicitud de usuario y contraseña del sistema EVO.Haz clic en CONFIRMAR.
2.
Completa el Nombre del Token, el Nombre del solicitante y el WhatsApp.
3.
Completa la información de uso.
Propósito de uso: indica la finalidad de la integración seleccionando las opciones existentes.
Uso interno/Proveedor socio: al seleccionar la opción Proveedor/Socio, informa el socio, el nombre del proveedor, correo electrónico o teléfono.
🚧 Si el proveedor no está en la lista, es necesario solicitar el registro en este formulario.
4.
Completa los 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 endpoints y para verificarlos haz clic en la flecha para expandir.
📘 Lee este artículo para entender a qué endpoint se refiere cada permiso.
Después de seleccionar todas las opciones haz clic en CREAR TOKEN.Después de crear el token, se mostrarán las claves para utilizar en la autenticación:
El método de autenticación de la EVO API es Basic Authentication, lo que significa que para realizar llamadas a la API es necesario un usuario y una contraseña: el DNS como usuario y la clave aleatoria única creada en el último paso como contraseña.Los clientes de API HTTP que disponemos para que puedas probar llamadas de API son este, el Api Reference, donde podrás navegar por las diferentes entidades y sus endpoints, pudiendo probarlos. También está el Swagger, donde podrás hacer lo mismo en una interfaz más simple.Para realizar las pruebas de llamadas solo tendrás que proporcionar el usuario y la contraseña y completar los parámetros definidos en cada endpoint. Tanto este canal como Swagger ofrecen un entorno sandbox donde podrás ver las respuestas de tus llamadas de prueba. "Enviar"
Las entidades de API son las diferentes áreas del producto sobre las cuales puedes realizar llamadas de API. A continuación se presenta un resumen de las principales entidades de la EVO API:
Activities: endpoints para obtener clases existentes, inscribir alumnos en ellas, crear clases de prueba y ver listas de clases;
Configuration: endpoints para obtener configuraciones de la unidad, gateway, banderas de tarjeta, traducción de tarjeta y ocupación;
Employees: endpoints para obtener, agregar, actualizar y eliminar colaboradores;
El estándar de paginación para las respuestas de llamadas de la EVO API es de 50 registros. Algunos endpoints excepcionalmente permiten 100 registros en la respuesta.Para controlar la paginación de las respuestas de tus llamadas, utiliza los parámetros take y skip.El parámetro total en el header indica la cantidad total de elementos disponibles para paginación en la API.
Para garantizar el rendimiento y la estabilidad del sistema, la EVO API implementa límites de solicitudes (rate limits). Estos límites controlan el número de llamadas que pueden realizarse dentro de intervalos de tiempo específicos, basándose en los siguientes criterios:
Por minuto (por IP): Límite de 40 solicitudes por minuto. Al alcanzarlo se retornará el estado 429 (Too Many Requests), y se deberá esperar 1 minuto para realizar nuevas llamadas.
💎 Clientes de API PRO no tienen el límite por minuto.
Por hora (por clave de API): Límite de 10.000 solicitudes por hora. Si se supera, la clave será bloqueada por 1 hora.
Por hora (por DNS): Límite de 20.000 solicitudes por hora para todas las claves asociadas al mismo DNS. Al excederlo, todas las claves de la academia quedan bloqueadas por 1 hora.
Nota: Durante el horario de 0h a 5h, los límites no se aplican, permitiendo ejecuciones de alto volumen, como solicitudes en lote.
Para más información y buenas prácticas sobre cómo evitar bloqueos, consulta la sección completa de Límites de solicitudes.
Por último, aquí hay algunas buenas prácticas para el uso efectivo de la EVO API.Primero que nada, es importante dejar claro que la EVO API fue diseñada para usarse en backend, ya que Basic Authentication requiere las claves de API para las solicitudes.
🚧 Esto significa que usarla en frontend puede exponer métodos y datos de tu(s) academia(s). Siempre impleméntala en backend.
Además, es esencial saber que la EVO API consume datos de producción, lo que compite con los procesos normales de uso del propio EVO. Por lo tanto, se recomienda realizar solicitudes de API pesadas durante la madrugada, entre la 01:00 y las 06:00, para evitar lentitud en el uso del EVO por parte de la(s) academia(s).
