Requisitos obligatorios
La activación futura será cerrada por defecto. Una empresa deberá cumplir las
tres condiciones siguientes:
Flujo previsto de activación
- StaffPass confirma el plan Enterprise y la empresa exacta.
- Se revisan finalidad, datos, retención y responsables del cliente.
- Un operador autorizado activa la API para ese tenant.
- StaffPass emite un token una sola vez y almacena únicamente una
representación no reversible.
- El cliente prueba exclusivamente operaciones incluidas en su OpenAPI vigente.
- Se registra aceptación del piloto antes de usar datos o proveedores reales.
Este flujo describe gates obligatorios del producto, no una funcionalidad ya
implementada. No se debe prometer una fecha, token o endpoint hasta que el
backend y sus pruebas implementen el control completo.
Qué debe implementarse para abrir la API
Eliminar el aviso sin implementar estos controles solo expondría rutas internas.
La API puede declararse disponible cuando se complete este orden de trabajo:
- Entitlement por empresa. Agregar al esquema una fuente autoritativa para
el plan vigente y
api_enabled, cerrada por defecto y con auditoría de cada
cambio.
- Credenciales de integración. Crear un modelo ligado a una sola empresa
con identificador público, hash del secreto, scopes, expiración, revocación,
último uso y ambiente. El secreto se muestra una sola vez y nunca se guarda
ni registra en texto claro.
- Autenticación dedicada. Implementar un guard distinto de Firebase que
valide el token, resuelva el tenant desde la credencial y compruebe en cada
solicitud plan Enterprise,
api_enabled, vigencia, revocación y scopes. El
cliente nunca debe elegir su company_id mediante un header.
- API externa versionada. Crear controladores y DTOs bajo una superficie
estable como
/integrations/v1; no reutilizar directamente los controladores
del panel, TimeClock o tareas internas.
- Protecciones operativas. Aplicar rate limits por token y empresa,
idempotency keys en escrituras, request IDs, errores estables y auditoría sin
secretos ni datos personales innecesarios.
- Contrato público. Generar OpenAPI únicamente desde los controladores
externos y publicar base URL, scopes, ejemplos, límites y política de
versiones cuando exista al menos una operación aprobada.
- Pruebas y piloto. Cubrir tokens inválidos, vencidos y revocados;
aislamiento entre empresas; scopes; rate limits; idempotencia; y ausencia de
secretos en logs. Después, validar en staging y con una empresa piloto antes
de habilitar producción.
Criterio para retirar el aviso
El aviso puede retirarse y openapi.json puede publicar operaciones solo
cuando una prueba automatizada demuestre todos los gates anteriores y exista
una base URL externa desplegada. La primera entrega puede ser pequeña: un único
recurso de solo lectura, un scope y un cliente piloto. La seguridad y el
aislamiento multiempresa no pueden posponerse.
Desactivación y compromiso
Ante pérdida, exposición o resultado incierto:
- detén nuevas solicitudes;
- revoca el token afectado antes de emitir otro;
- conserva identificadores e idempotency keys para conciliación;
- no reintentes operaciones financieras o de proveedor cuyo resultado sea
desconocido;
- revisa auditoría por tenant y alcance antes de reactivar.
La desactivación debe conservar evidencia, snapshots y resultados desconocidos;
no debe borrar el historial necesario para investigar.
