API de control horario: qué debe ofrecer y qué preguntar antes de contratar
Siete preguntas concretas para saber si una API es usable o es un adorno de la página de precios: claves de solo lectura, qué devuelve cada fichaje, cómo se obtienen los totales y si cuadran con la nómina, límites documentados y webhooks. Con una prueba de fuego de veinte minutos.
Respuesta corta: pide la documentación antes de firmar y léela. Si es pública, buena señal. Si te la mandan por correo tras una llamada comercial, mala. Y comprueba cuatro cosas concretas: si puedes crear claves de solo lectura, qué devuelve cada fichaje, si hay webhooks o toca consultar, y en qué plan está incluida.
Por qué la documentación debería ser pública
Alguna vez nos han preguntado si no es peligroso tener la documentación de la API abierta a cualquiera. Es una duda razonable y la respuesta es que no, por dos motivos.
El primero es de seguridad: la seguridad de una API no está en que nadie sepa qué endpoints tiene, está en la credencial. Saber que existe /api/v1/fichajes no sirve de nada sin una clave válida. La seguridad por ocultación no es seguridad, es un retraso.
El segundo es práctico: quien evalúa la integración casi nunca es quien firma. Es un desarrollador, o el proveedor que mantiene el ERP. Si para ver si la integración es viable hay que darles acceso a tu cuenta, o pedir un PDF a comercial, la evaluación se pospone y a veces no se hace.
Todos los proveedores serios de software de infraestructura publican su documentación. Si tu proveedor de fichaje la esconde, la pregunta interesante es qué más no quiere que se vea antes de firmar.
Las siete preguntas que separan una API usable de un adorno
1. ¿Está incluida en mi plan o es un módulo aparte?
Es la primera y la que más presupuestos rompe. Muchos comparadores enseñan un precio por empleado y la API aparece como extra, a veces con un mínimo mensual que multiplica el coste. Pregunta también si funciona durante el periodo de prueba: si no, no puedes validar la integración antes de comprometerte, que es justo cuando hace falta.
2. ¿Puedo crear una clave de solo lectura?
Fundamental y muchas veces ausente. La mayoría de integraciones solo leen: llevar horas a una hoja, a un BI, a la nómina. Si la única clave disponible puede además escribir en el registro, cualquier fuga de esa clave —un repositorio, una hoja compartida, un empleado que se va— pasa de ser un problema de confidencialidad a un problema de integridad de tu registro legal.
Lo correcto es que las claves nazcan de solo lectura y que la escritura sea una excepción justificada.
3. ¿Qué devuelve exactamente cada fichaje?
Pide un ejemplo real de respuesta. Cosas que deberían estar y a menudo faltan:
- Identificador estable del apunte.
- Tipo de apunte: entrada, salida, inicio y fin de pausa. Si solo te dan pares cerrados entrada-salida, no podrás calcular las pausas y tus horas no cuadrarán con las suyas.
- Sello en UTC y hora local ya convertida. Si solo te dan una de las dos, prepárate para el error de una hora.
- Método de fichaje: sin él no sabes si el dato viene del móvil, del kiosco o de una importación.
- Centro de trabajo.
- Un campo libre para tu referencia. Ver la pregunta 5.
4. ¿Cómo obtengo las horas totales?
Si la respuesta es «emparejando los apuntes», que exista al menos un endpoint que devuelva los totales ya sumados. Y entonces la pregunta importante: ¿usa el mismo cálculo que el informe que descarga mi gestoría?
Si no, tendrás dos cifras para el mismo mes, y ese es el peor sitio donde puede aparecer una discrepancia. Antes de firmar, compara el total del endpoint con el del export de nómina para el mismo periodo. Si no coincide al minuto, tienes un problema que aparecerá el día de una revisión salarial.
5. ¿Puedo mandar mi propio código de proyecto, obra o cliente?
Un campo de texto libre por fichaje, donde metes tu identificador, es lo que convierte el registro horario en información de gestión. Sin él, cruzar horas con obras exige mantener una tabla de correspondencias por tu cuenta.
Y una pregunta de segundo nivel: si mando ese código, ¿se imputa solo a un proyecto en su sistema, o se queda en un campo suelto que nadie usa?
6. ¿Hay webhooks?
Si los hay, bien. Si no los hay, tampoco es descalificatorio: para la mayoría de casos, consultar cada quince minutos o hacer una pasada nocturna funciona igual y es más fácil de depurar —si una pasada falla, la siguiente recupera, sin colas ni reintentos que mantener—.
Lo que sí es descalificatorio es que te digan que sí y luego resulte que son un aviso genérico sin datos, o que no haya reintentos. Pide un ejemplo de payload.
7. ¿Qué límites tiene?
Los límites no son malos; los límites no documentados sí. Necesitas saber peticiones por minuto, máximo de días por consulta, máximo de registros por respuesta y —esto se olvida— cómo te avisa de que la respuesta venía truncada. Sin ese aviso, un día tu informe mostrará medio mes y nadie se dará cuenta.
Dos preguntas extra si te van a integrar la nómina
- ¿Vienen las ausencias y las vacaciones? Sin ellas la nómina no se cierra desde la API, y volverás al CSV.
- ¿Cómo aparecen las correcciones? Si un fichaje corregido sustituye al original, tu sistema perderá el rastro. Si se añade uno nuevo con su estado y su motivo, puedes auditar. Y ahí verás si el proveedor se toma en serio la inalterabilidad del registro.
La prueba de fuego, en veinte minutos
Con la documentación pública y una cuenta de prueba, esto se resuelve rápido:
- Crea una clave. Comprueba que es de solo lectura intentando escribir: debe responder un error claro.
- Pide los fichajes de un mes. Mira si están las pausas y si vienen las dos horas (UTC y local).
- Pide los totales del mismo mes. Compáralos con el export de nómina. Deben coincidir.
- Fuerza un error: una fecha mal formada, un rango invertido. Un buen error te dice qué has hecho mal; uno malo devuelve 500 y te deja a ciegas.
- Pide un rango enorme y comprueba qué pasa cuando te pasas del tope.
Si los cinco pasos salen bien, la integración te va a costar una tarde. Si el tercero falla, no la hagas hasta que te lo expliquen.
Documentación pública, claves de solo lectura por defecto
Puedes leer la documentación completa en controlhorariolegal.com/api sin registrarte, y validar toda la integración durante los 30 días de prueba. Los totales de la API salen del mismo cálculo que el export para nómina.
Probar 30 días gratis →Preguntas frecuentes
¿Es peligroso que la documentación de una API sea pública?
No. La seguridad de una API está en la credencial, no en desconocer los endpoints: saber que existe una ruta no sirve de nada sin una clave válida. Publicar la documentación permite además que el desarrollador o el proveedor que hará la integración la evalúe sin necesidad de acceso a la cuenta.
¿Qué es una clave de API de solo lectura y por qué importa?
Es una credencial que permite consultar datos pero no modificarlos. Importa porque la mayoría de integraciones solo necesitan leer, y si la única clave disponible también puede escribir en el registro horario, una fuga de esa clave pasa de ser un problema de confidencialidad a comprometer la integridad de un registro con valor legal.
¿Debe la API devolver las pausas por separado?
Sí. Si solo devuelve pares cerrados de entrada y salida, no se pueden calcular las pausas y los totales propios nunca cuadrarán con los del proveedor. Cada apunte —entrada, salida, inicio de pausa y fin de pausa— debe venir identificado con su tipo.
¿Es un problema que un software de fichaje no tenga webhooks?
No necesariamente. Para la mayoría de integraciones, consultar el endpoint de fichajes cada quince minutos o hacer una pasada nocturna funciona igual de bien y es más fácil de depurar. Lo que sí es un problema es que los anuncien y luego no traigan datos o no tengan reintentos.
¿Cómo compruebo que los totales de la API son fiables?
Pidiendo el total de un mes por API y comparándolo con el informe de horas que descarga la gestoría para ese mismo periodo. Si no coinciden, hay dos cálculos distintos para la misma jornada, y esa discrepancia aparecerá en el peor momento posible.
¿Suele estar incluida la API en el precio base?
Depende del proveedor: en muchos es un módulo aparte, a veces con un mínimo mensual que altera bastante el coste real. Conviene preguntar también si funciona durante el periodo de prueba, porque si no se puede validar la integración antes de contratar, se está comprando a ciegas.
Última actualización: 17 de agosto de 2026. Este artículo tiene fines informativos y no constituye asesoramiento legal.