Autenticación

FreeMaint acepta dos mecanismos de autenticación: JWT (emitidos por /auth/login, utilizados por nuestras aplicaciones web y móviles) y claves API (creadas en /company-settings/api, utilizadas por sus propias integraciones).

JWT (sesiones de usuario)

1. POST /auth/login — Cuerpo: {email, password}. Devuelve {access_token, refresh_token}.
2. Enviar la cabecera Authorization — En cada solicitud: Authorization: Bearer <access_token>.
3. Actualizar cuando caduque — POST /auth/refresh con el refresh_token para obtener un nuevo access_token. Los tokens de acceso duran 2 horas.

Clave API (integraciones de servidor)

1. Abra /company-settings/api o /profile/api-keys — Los administradores crean claves en Configuración de la empresa > API, a partir del plan Business. Una persona cuyo rol tiene el permiso «Crear claves de API personales» crea las suyas en Perfil > Seguridad > Claves de API. Un rol con el permiso «Gestionar integraciones» (por ejemplo, la plantilla Administrador de integraciones) puede crear, revocar y eliminar las claves de la empresa sin ser administrador; solo un administrador asigna una clave a otra persona.
2. Haga clic en 'Nueva clave' — Opcionalmente, defina una caducidad y un nivel de acceso (Solo lectura por defecto). La clave sin formato se muestra UNA SOLA VEZ: cópiela de inmediato.
3. Úselo — Envíe Authorization: Bearer fmk_<rawKey> en cada solicitud. Formato: empieza por fmk_ seguido de 32 caracteres hexadecimales.

Notas de seguridad

• Las claves API se almacenan como hashes SHA-256: una vez que cierra el cuadro de diálogo de revelación, el valor bruto es irrecuperable
• Revocar una clave la desactiva inmediatamente; la fila se mantiene para auditoría
• Cada clave pertenece a una sola empresa y solo accede a los datos de esa empresa: un registro de otra empresa simplemente no se encuentra
• Las claves pueden tener un expiresAt opcional para integraciones de corta duración
• Niveles de acceso, un techo por encima de los permisos del propietario: READ (predeterminado — solo consultas), READ_STOCK (consultas + adjustStock — ideal para un quiosco de consumo), FULL (todas las operaciones que permite el rol del propietario)
• Cada clave actúa como su propietario: cada llamada lleva sus permisos y su visibilidad de datos, y lo que escribe queda firmado con su nombre. Si el propietario se desactiva, la clave se rechaza (401, código API_KEY_OWNER_INACTIVE) hasta que un administrador la asigne a otra persona en Configuración de la empresa > API — el valor de la clave no cambia.

Probar una integración

No existe un entorno de pruebas aparte: una clave de API siempre se dirige a los datos reales de la empresa a la que pertenece. Dos maneras de probar sin riesgo. (1) Use una segunda empresa como empresa de pruebas: el aislamiento entre empresas es el mismo mecanismo que separa a todos los clientes, así que nada de lo que haga allí puede alcanzar sus datos de producción. Las claves de API requieren el plan Business, así que esa empresa también debe estar en Business: una empresa gratuita no puede crear ninguna. (2) Para trabajo de solo lectura, cree una clave con nivel de acceso READ: puede ejecutar todas las consultas y ninguna mutación, de modo que no puede cambiar nada. Cuando quiera empezar a escribir, una clave READ_STOCK permite adjustStock y nada más.