Ir al contenido

Usuarios y organización por API

Una empresa se organiza en personas, roles, grupos y puestos: quién entra, qué puede hacer, en qué equipo trabaja, en qué área y con qué puesto. Esta ficha deja que un agente haga por API lo que un administrador hace en el panel, en Usuarios y en Organización. Son cincuenta y cuatro operaciones, con las mismas reglas y los mismos mensajes de rechazo que el panel, más los límites que una llave no puede cruzar (sección siguiente).

ParaOperaciones
Invitar, ver, editar y quitar a una personacrearUsuario, verificarCorreoDeUsuario, listarUsuarios, obtenerUsuario, actualizarUsuario, quitarUsuarioDeLaEmpresa
Los roles de una personaasignarRolesAUsuario, listarRolesDeUsuario
La clave y las sesiones de una personaenviarRestablecimientoDeClaveDeUsuario, listarSesionesDeUsuario, eliminarSesionesDeUsuario
El PIN del puesto de una personaconsultarPinDelPuestoDeUsuario, actualizarMarcaDeOperaEnPuestos
El catálogo de roleslistarRoles, listarRolesAsignables, listarRolesAsignablesDeEmpresa, obtenerRol
Los grupos de roleslistarGruposDeRoles, consultarSincronizacionDeGruposDeRoles, obtenerGrupoDeRoles, listarUsuariosDeGrupoDeRoles, crearGrupoDeRoles, actualizarGrupoDeRoles, eliminarGrupoDeRoles, actualizarActivacionDeGrupoDeRoles
Los grupos de personaslistarGruposDePersonas, crearGrupoDePersonas, obtenerGrupoDePersonas, actualizarGrupoDePersonas, archivarGrupoDePersonas, agregarPersonaAGrupoDePersonas, consultarQuitarPersonaDeGrupoDePersonas, quitarPersonaDeGrupoDePersonas
Las áreas de trabajolistarAreasDeTrabajo, crearAreaDeTrabajo, listarOpcionesDeAreasDeTrabajo, obtenerAreaDeTrabajo, consultarQuienOperoEnAreaDeTrabajo, listarPersonasDisponiblesDeAreaDeTrabajo, actualizarAreaDeTrabajo, archivarAreaDeTrabajo, asociarBodegasAAreaDeTrabajo
Los puestos de trabajoobtenerConfiguracionDePuestos, actualizarCambioRapidoDePuestos, actualizarTiemposDePuestos, listarPuestosDeTrabajo, obtenerPuestoDeTrabajo, actualizarPuestoDeTrabajo, desactivarPuestoDeTrabajo, listarMovimientosDePuestoDeTrabajo
Las sucursales de una personaasignarSucursalesAUsuario, listarSucursalesParaAsignacion, listarAsignacionesDeSucursalesDeUsuario, quitarAsignacionesDeSucursalesDeUsuarioEnEmisor

Estas reglas rigen igual con una llave de producción y con una de prueba. Si un agente las necesita, no hay otra ruta por API: lo hace una persona en el panel.

  • No asigna roles de plataforma ni de máquina. SUPER-ADMIN, MASTER y los roles de las llaves no se pueden dar con una llave, ni directo ni dentro de un grupo de roles, ni al invitar. Responde 403 con «La llave no puede asignar ese rol» y no cambia nada. listarRolesAsignablesDeEmpresa trae sólo lo que la llave sí puede dar: arma las listas con ese resultado.
  • No toca cuentas intocables. Una persona con SUPER-ADMIN en cualquier empresa, o con un rol global, o con un grupo de roles activo que contiene SUPER-ADMIN, no se edita, no se quita, no se le cambian los roles, no se le restablece la clave y no se listan ni cierran sus sesiones. Responde 403 «No tienes permisos para esta operación sobre esa persona». Leer su perfil y sus roles sí se puede.
  • Una persona que es de dos empresas se protege. Con la llave de una empresa, actualizarUsuario, listarSesionesDeUsuario y eliminarSesionesDeUsuario sobre una persona que también pertenece a otra empresa responden el mismo 403, sin nombrar ni contar las otras empresas: la cuenta es una sola para toda la plataforma. Siguen abiertos para ella: cambiarle roles y grupos en tu empresa, quitarla de tu empresa, restablecerle la clave y asignarle sucursales.
  • Una persona de otra empresa no existe. Un id que no es de tu empresa responde 404, igual que uno inventado.
  • El alta es sólo por invitación. crearUsuario manda un correo y la persona elige su clave. passwordMode sólo acepta auto_invite (el valor por defecto); temp_password, tempPassword y manual_invite responden 400 y no crean nada. verificarCorreoDeUsuario responde sólo si el correo ya es de tu empresa: una cuenta que existe en otra empresa responde igual que una inexistente. Si el correo ya tiene cuenta, crearUsuario la suma a tu empresa y responde igual que con una cuenta nueva; el nombre sale de tu cuerpo, nunca de la cuenta existente. 409 sólo si ya es de tu empresa.
  • El restablecimiento de clave sólo manda el correo. enviarRestablecimientoDeClaveDeUsuario no recibe password (si lo mandas responde 400) y ninguna respuesta trae la clave. No hay forma de fijar ni de leer la clave de una persona por API.
  • Dar ADMIN avisa. Cada vez que una llave de producción da ADMIN a una persona, por rol directo, por un grupo de roles o al invitar, los SUPER-ADMIN de la empresa reciben un aviso que nombra a la persona y a la llave. En modo de prueba no se avisa.
  • Los puestos no se abren ni se conectan. Con una llave no se registra un puesto, no se usa «este navegador», no se genera ni se usa un enlace de reconexión, no se anula un puesto ni se levanta su bloqueo. Esas operaciones no existen en esta ficha: son del panel y del aparato del puesto. La llave sí configura (cambio rápido, tiempos), edita, da de baja y revisa los movimientos.
  • No se cambia el RUT de una persona. Fijar o corregir el RUT es sólo del panel.
  • Una llave con acceso a la empresa. La llave del proyecto que instala redcumbre init es FULL-API y alcanza. redcumbre api describir crearUsuario muestra el rol exacto de cada operación.
  • El archivo de la llave en el proyecto, como en Modo de prueba y producción. No lo leas, no lo imprimas ni le pidas a la persona que pegue el secreto en el chat.
  • Un cuerpo, una consulta y unos parámetros sólo con los campos que la operación declara: uno de más responde 400 CAMPO_NO_PERMITIDO_CON_LLAVE y no se guarda nada.
  • Paginación, errores y límites: Reglas comunes. listarUsuarios se pagina con page y limit (hasta 300); sin parámetros devuelve la primera página, no la lista entera.

Con una llave de prueba, las cincuenta y cuatro operaciones responden desde un conjunto de ejemplo y no guardan nada: no invitan, no cambian roles, no tocan la cuenta de nadie y no mandan ningún correo. Las lecturas devuelven los mismos campos con contenido sintético; las escrituras validan el cuerpo como en producción y responden como hechas, con identificadores negativos y siempre los mismos. El techo de roles, las cuentas intocables y la lista cerrada de campos rigen igual. Eso confirma que la llave, el rol y el cuerpo son correctos; no confirma que algo se haya guardado.

Cada paso usa un subcomando de redcumbre usuarios, redcumbre roles, redcumbre grupos-de-roles, redcumbre grupos-de-personas, redcumbre areas, redcumbre puestos o redcumbre sucursales-de-usuarios. Todos trabajan con la llave de prueba; para producción agrega --produccion --confirmar <slug-de-la-empresa>, y con --ensayo ves la petición sin hacerla. La alternativa genérica es redcumbre api <operationId>.

Ventana de terminal
redcumbre buscar "usuarios de la empresa"
redcumbre api describir crearUsuario

Resultado esperado: las operaciones de esta ficha, con su método, su ruta y los campos del cuerpo.

Ventana de terminal
redcumbre roles asignables-de-empresa

Resultado esperado: los roles que la llave puede asignar en la empresa, sin SUPER-ADMIN, MASTER ni roles de máquina. redcumbre roles listar y redcumbre roles ver <id-del-rol> leen el catálogo completo, que es el mismo para toda empresa.

Ventana de terminal
redcumbre usuarios verificar-correo --correo persona@example.com
redcumbre usuarios invitar --cuerpo @invitacion.json
{
"email": "persona@example.com",
"firstName": "Persona",
"lastName": "De Ejemplo",
"roles": ["VIEWER"]
}

Resultado esperado: la persona queda en la empresa con los roles pedidos y recibe un correo para elegir su clave; la respuesta no trae ninguna clave. verificar-correo responde existe: true sólo si ya es de tu empresa.

Ventana de terminal
redcumbre usuarios listar --buscar ejemplo --pagina 1 --limite 50
redcumbre usuarios ver <id-de-la-persona>
redcumbre usuarios editar <id-de-la-persona> --cuerpo @cambios.json
redcumbre usuarios roles <id-de-la-persona>

Resultado esperado: de cada persona salen sólo id, zitadelUserId, email, nombre, apellido, nombreCompleto, rut, telefono, sus roles y gruposDeRoles de esta empresa, createdAt y updatedAt. Nunca salen claves, segundo factor, IP, tokens ni los roles de otra empresa. --todas recorre todas las páginas.

Ventana de terminal
redcumbre usuarios asignar-roles <id-de-la-persona> --cuerpo @roles.json
{
"roles": ["VIEWER", "SII-COMPRAS"]
}

Resultado esperado: la persona queda con esos roles en la empresa. Con ADMIN en la lista, los SUPER-ADMIN reciben el aviso. Pedir un rol fuera del techo responde 403 y no cambia ninguno.

Ventana de terminal
redcumbre usuarios restablecer-clave <id-de-la-persona>
redcumbre usuarios sesiones <id-de-la-persona>
redcumbre usuarios cerrar-sesiones <id-de-la-persona>

Resultado esperado: restablecer-clave responde que envió el correo, sin clave; sesiones lista las sesiones abiertas y cerrar-sesiones las cierra todas. Con producción, las tres acciones que cambian algo piden --confirmar.

Ventana de terminal
redcumbre usuarios quitar <id-de-la-persona>

Resultado esperado: la persona pierde el acceso y sus roles en tu empresa. Su cuenta en otras empresas no cambia. Una cuenta intocable responde 403.

Ventana de terminal
redcumbre grupos-de-roles listar
redcumbre grupos-de-roles sincronizacion
redcumbre grupos-de-roles crear --cuerpo @grupo.json
redcumbre grupos-de-roles editar <id-del-grupo> --cuerpo @cambios.json
redcumbre grupos-de-roles activar-o-desactivar <id-del-grupo>
redcumbre grupos-de-roles usuarios <id-del-grupo>
redcumbre grupos-de-roles eliminar <id-del-grupo>
{
"code": "EQUIPO-COMPRAS",
"name": "Equipo de compras",
"description": "Quienes revisan las compras",
"roleKeys": ["SII-COMPRAS", "VIEWER"]
}

Resultado esperado: un grupo da a sus miembros los roles que contiene. roleKeys pasa por el mismo techo: con SUPER-ADMIN o MASTER responde 403. activar-o-desactivar alterna el estado del grupo. Agregar ADMIN a un grupo activo, o activar uno que lo contiene, avisa a los SUPER-ADMIN por cada miembro. sincronizacion dice si los grupos están al día con el proveedor de identidad. eliminar borra el grupo y sus miembros lo pierden.

Ventana de terminal
redcumbre grupos-de-personas listar --buscar facturación
redcumbre grupos-de-personas crear --cuerpo @grupo.json
redcumbre grupos-de-personas agregar-persona <id-del-grupo> --cuerpo @persona.json
redcumbre grupos-de-personas consultar-quitar-persona <id-del-grupo> <id-de-la-persona>
redcumbre grupos-de-personas quitar-persona <id-del-grupo> <id-de-la-persona>
redcumbre grupos-de-personas archivar <id-del-grupo>
{
"nombre": "Facturación",
"usuarioIds": [101, 102]
}
{
"usuarioId": 103
}

Resultado esperado: el grupo trae id, nombre, personas (en el orden del turno), reparto, usos y archivadoAt. Las personas tienen que ser de tu empresa. consultar-quitar-persona dice qué pasaría antes de quitarla.

Ventana de terminal
redcumbre areas listar --estado ACTIVA
redcumbre areas crear --cuerpo @area.json
redcumbre areas disponibles <id-del-area>
redcumbre areas asociar-bodegas <id-del-area> --cuerpo @bodegas.json
redcumbre areas archivar <id-del-area>
redcumbre puestos configuracion
redcumbre puestos cambio-rapido --cuerpo @cambio.json
redcumbre puestos listar
redcumbre puestos editar <id-del-puesto> --cuerpo @cambios.json
redcumbre puestos desactivar <id-del-puesto>
redcumbre puestos movimientos <id-del-puesto>

Resultado esperado: las áreas traen su estado y las bodegas asociadas; quien-opero dice quién operó en el área y disponibles trae, por puesto activo, las personas disponibles (sin RUT ni correo). Los puestos traen su estado y su configuración; desactivar da de baja el puesto y el aparato que lo usa deja de operar. Un puesto nuevo se registra desde el aparato, con la persona presente: no se hace con una llave.

Ventana de terminal
redcumbre sucursales-de-usuarios para-asignacion
redcumbre sucursales-de-usuarios asignar <id-de-zitadel-de-la-persona> --cuerpo @sucursales.json
redcumbre sucursales-de-usuarios listar <id-de-zitadel-de-la-persona>
redcumbre sucursales-de-usuarios quitar-de-emisor <id-de-zitadel-de-la-persona> <id-del-emisor>

Resultado esperado: la persona queda con esas sucursales y la que marques como por defecto. El identificador de estas rutas es el zitadelUserId de la persona, no su id. quitar-de-emisor quita todas las sucursales de ese emisor.

CódigoCuándoQué hacer
400Un campo que la operación no declara, passwordMode distinto de auto_invite o un password al restablecer la claveCorrige el cuerpo; no se guardó nada.
403 «La llave no puede asignar ese rol»Un rol de plataforma o de máquina, solo o dentro de un grupoUsa los roles de roles asignables-de-empresa.
403 «No tienes permisos para esta operación sobre esa persona»Cuenta intocable, o persona de dos empresas en editar o sesionesNo hay ruta por API: lo hace una persona en el panel.
404Una persona, un grupo, un área o un puesto que no es de tu empresa o no existeRevisa el id. Los dos casos responden igual.
409La persona ya es de tu empresaUsa la operación de editar.