Claves de API y webhooks

Con una clave de API, tu gestoría, tu ERP, tu programa de nóminas o tu herramienta de análisis leen los datos de FichMe sin que tengas que exportar nada a mano. Cada clave lleva solo los permisos que elijas, caduca y se puede revocar en cualquier momento. Las crea un administrador, sin pedir nada a soporte.

Antes de empezar#

• Decide a quién le das la clave. Quien la reciba tratará datos de tu plantilla en nombre de tu empresa. Al crearla tendrás que declarar que tienes firmado con esa persona o empresa el contrato de encargo de tratamiento del artículo 28 del RGPD.
• La parte técnica es de quien programa la integración. Tiene la guía en la página para desarrolladores y la documentación completa en api.fichme.com/v1/docs.
• La primera clave de la empresa te pide aceptar las Condiciones de uso de la API en nombre de la empresa.

Crear una clave#

1. En el menú, entra en Configuración›Claves de API.
2. Pulsa Crear clave. Se abre Crear clave de API, en tres pasos: Configurar, Revisar y Copiar la clave.
3. En Nombre y responsable, escribe un Nombre de la clave que te diga a quién se la das y para qué, como «Gestoría Pérez — nóminas». En Email del responsable, el correo de quien recibirá los avisos de caducidad y de revocación; si lo dejas vacío, serás tú.
4. En Permisos, elige la plantilla que más se parezca a lo que va a hacer la integración, o Empezar desde cero. Después marca o desmarca los permisos uno a uno.
5. En Caducidad, elige 30 días, 90 días o 1 año. En Enterprise tienes además Sin caducidad.
6. Si quieres, en Restringir por dirección IP (opcional), añade las IP o rangos desde los que se podrá usar, uno por fila y como mucho 20. Sin ninguno, funciona desde cualquier IP.
7. Pulsa Revisar clave, comprueba el resumen y marca la declaración del contrato de encargo. La primera vez, acepta también las condiciones de uso.
8. Pulsa Crear clave.

Verás Clave creada con la clave completa. Pulsa Copiar y guárdala en un lugar seguro: no volverás a verla. Entrégasela a quien la vaya a usar por un canal seguro, nunca por chat ni en un correo sin cifrar. Al terminar, pulsa Hecho, ya la he guardado.

Las plantillas de permisos#

Gestionar tus claves#

En Configuración›Claves de API tienes cuatro pestañas: Claves, Uso, Webhooks y Ajustes. Arriba ves cuántas claves activas llevas de las que permite tu plan.

En la lista, el menú … de cada clave tiene:

Las claves revocadas y caducadas desaparecen de la lista a los 90 días.

Rotar una clave#

Rota una clave si se ha filtrado (en un repositorio, en un correo, en un proveedor que ya no trabaja contigo) o como limpieza periódica. Al rotar eliges qué pasa con la actual:

• Retirarla ya: deja de funcionar en cuanto confirmas. Es lo recomendado si se ha filtrado.
• Mantenerla unos días: las dos funcionan durante el solape que elijas, de 1 a 7 días, para cambiarla en la integración sin cortes.

Después de Rotar clave, copia la nueva: tampoco la volverás a ver.

Permitir que una integración fiche#

Si un terminal, un torno o tu ERP van a registrar fichajes, hacen falta dos cosas:

1. En la pestaña Ajustes, activa Permitir registrar fichajes por API.
2. Que la clave tenga el permiso clock:write (lo lleva la plantilla Terminal o ERP que ficha).

Los fichajes por API usan siempre la hora del servidor y quedan marcados como API. La empresa responde de que el sistema que ficha identifique bien a cada persona. Por API no se cambian fichajes pasados: eso se hace con solicitudes de corrección. Recuerda que la geovalla no se aplica a los fichajes por API.

Webhooks: avisos a tus sistemas#

Con un webhook, FichMe avisa a tu sistema en cuanto pasa algo: un fichaje nuevo o corregido, una solicitud de corrección creada, aprobada o rechazada, una ausencia creada, aprobada, rechazada o cancelada, o el alta, un cambio, la desactivación o la eliminación de un empleado.

1. En la pestaña Webhooks, pulsa Añadir endpoint.
2. Escribe la URL (https) de tu sistema y, si quieres, una Descripción (opcional).
3. En Eventos, marca los que quieres recibir, o Todos los eventos.
4. Pulsa Añadir endpoint y copia el Secreto de firma: sirve para comprobar que cada aviso viene de FichMe, y no se vuelve a mostrar.

Desde el menú de cada webhook puedes Enviar prueba, Pausar, Rotar secreto o Borrar, y ver sus entregas recientes. Si tu sistema no responde, FichMe reintenta varias veces; tras 72 horas sin ninguna respuesta correcta, desactiva el webhook y avisa a los administradores. Puedes tener hasta 10 webhooks. Los detalles técnicos están en la página para desarrolladores.

Las claves y los asistentes de IA#

La misma clave sirve también para el servidor de asistentes de IA de FichMe, para agentes y automatizaciones que actúan en nombre de la empresa. Necesita un plan con asistentes de IA y tenerlos activados. Esas llamadas salen en Uso como /mcp/…. Para que cada persona conecte su propio Claude o ChatGPT no hace falta ninguna clave: mira Asistentes de IA.

Preguntas frecuentes#

He perdido la clave. ¿Puedo verla otra vez?#

No. FichMe solo la enseña al crearla. Rótala: tendrás una nueva con los mismos permisos.

¿Qué pasa con mis claves si bajo de plan o se para la suscripción?#

Si tu plan deja de incluir la API, las claves dejan de funcionar y solo puedes revocarlas. Si la suscripción se para, tampoco funcionan, pero vuelven solas en cuanto la regularizas.

He llegado al máximo de claves#

Verás «Has llegado al máximo de claves activas de tu plan». Revoca una que no uses o pasa a un plan superior.

¿Puedo crear claves con una clave?#

No. Las claves solo se crean y se gestionan desde el panel, por un administrador.