API y webhooks

Empecemos por lo que no hay

Esta página empieza por el final a propósito, porque es donde casi todo el mercado exagera.

• No hay conectores con productos concretos. Ni con programas de nóminas, ni con ERPs, ni con plataformas de automatización. La web anterior de Ficheo llegó a listar dieciocho logos de terceros y detrás no había ni una llamada saliente. Se quitaron todos.
• La API es de solo lectura. No se puede crear un fichaje ni aprobar una ausencia desde fuera.
• No hay OAuth2. La autenticación es una clave estática que se manda en una cabecera.
• No hay entorno de pruebas. Se prueba contra los datos reales, con una clave de lectura.
• No hay documentación pública con su portal y sus ejemplos en seis lenguajes. Lo que hay es la pantalla del panel, que enseña las rutas y te da la línea de curl montada.

Todo lo que sigue sí existe.

Las claves

En Empresa › Integraciones. Creas una clave, eliges qué puede leer y cuándo caduca.

• La clave se enseña una sola vez, en una ventana que no se cierra sin querer, con botón de copiar y la línea de curl ya montada para probarla en el momento.
• Se ve cuántas veces se ha usado cada una y cuándo fue la última. Una clave que nadie usa desde hace ocho meses es una clave que hay que retirar.
• Retirar una clave avisa antes de qué se rompe.

Qué se puede leer

La diferencia entre «fichajes» y «jornadas» importa: los fichajes son los eventos sueltos y calcular las horas con ellos obliga a repetir del otro lado toda la lógica de pausas, turnos de noche y jornadas abandonadas. Las jornadas vienen con las horas ya hechas.

Los webhooks

Avisan a una dirección tuya cuando pasan dos cosas: alguien ficha, y se resuelve una ausencia.

• Van firmados. La firma está explicada en la propia pantalla, con ejemplo, para que puedas comprobar del otro lado que el aviso viene de aquí y no de cualquiera que conozca tu dirección.
• Tienen reintentos. Si tu servidor está caído, el aviso no se pierde: se reintenta.
• Se paran solos si algo va mal de verdad. Si un destino falla veinte veces seguidas se desactiva y lo dice, en vez de seguir golpeando una puerta que nadie abre.
• Hay botón de prueba y la lista de los últimos intentos con su resultado, para que no tengas que adivinar por qué no te llega nada.

Aislamiento entre empresas

Una clave pertenece a una empresa y solo devuelve datos de esa empresa. Es una de las cosas que se comprueban con pruebas automáticas en cada subida, junto con los permisos y el freno de intentos: el guion de despliegue no deja subir si alguna se pone en rojo, y vuelve solo a la versión anterior.

Y si tu programa no sabe hablar API

Hay dos caminos más, que en la práctica cubren la mayoría de casos:

• El CSV del cierre de mes. Una fila por persona con horas, ausencias, extras, nocturnas y festivos. Cualquier programa de nóminas lo importa mapeando las columnas una vez. Está en exportar horas a nóminas.
• La puerta de entrada de fichajes, con clave propia, para que un aparato o un puente tuyo mande marcajes en JSON. Es la misma que usan los terminales de pared. Esa sí escribe, pero solo hace eso: mandar fichajes.

Para quién es

Para quien ya tiene un sistema que manda: una constructora que lleva el control de obra en su propio programa, un taller con su gestor de órdenes de reparación, una empresa con un cuadro de mando propio. Y para las gestorías que quieran leer las horas de varios clientes sin entrar a cada panel.

Si lo que buscas es un botón que conecte con un programa de nóminas por su nombre, hoy eso no existe aquí, y es mejor que lo sepas ahora que después.