Usuarios y organización por API
Qué resuelve
Sección titulada «Qué resuelve»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).
| Para | Operaciones |
|---|---|
| Invitar, ver, editar y quitar a una persona | crearUsuario, verificarCorreoDeUsuario, listarUsuarios, obtenerUsuario, actualizarUsuario, quitarUsuarioDeLaEmpresa |
| Los roles de una persona | asignarRolesAUsuario, listarRolesDeUsuario |
| La clave y las sesiones de una persona | enviarRestablecimientoDeClaveDeUsuario, listarSesionesDeUsuario, eliminarSesionesDeUsuario |
| El PIN del puesto de una persona | consultarPinDelPuestoDeUsuario, actualizarMarcaDeOperaEnPuestos |
| El catálogo de roles | listarRoles, listarRolesAsignables, listarRolesAsignablesDeEmpresa, obtenerRol |
| Los grupos de roles | listarGruposDeRoles, consultarSincronizacionDeGruposDeRoles, obtenerGrupoDeRoles, listarUsuariosDeGrupoDeRoles, crearGrupoDeRoles, actualizarGrupoDeRoles, eliminarGrupoDeRoles, actualizarActivacionDeGrupoDeRoles |
| Los grupos de personas | listarGruposDePersonas, crearGrupoDePersonas, obtenerGrupoDePersonas, actualizarGrupoDePersonas, archivarGrupoDePersonas, agregarPersonaAGrupoDePersonas, consultarQuitarPersonaDeGrupoDePersonas, quitarPersonaDeGrupoDePersonas |
| Las áreas de trabajo | listarAreasDeTrabajo, crearAreaDeTrabajo, listarOpcionesDeAreasDeTrabajo, obtenerAreaDeTrabajo, consultarQuienOperoEnAreaDeTrabajo, listarPersonasDisponiblesDeAreaDeTrabajo, actualizarAreaDeTrabajo, archivarAreaDeTrabajo, asociarBodegasAAreaDeTrabajo |
| Los puestos de trabajo | obtenerConfiguracionDePuestos, actualizarCambioRapidoDePuestos, actualizarTiemposDePuestos, listarPuestosDeTrabajo, obtenerPuestoDeTrabajo, actualizarPuestoDeTrabajo, desactivarPuestoDeTrabajo, listarMovimientosDePuestoDeTrabajo |
| Las sucursales de una persona | asignarSucursalesAUsuario, listarSucursalesParaAsignacion, listarAsignacionesDeSucursalesDeUsuario, quitarAsignacionesDeSucursalesDeUsuarioEnEmisor |
Lo que una llave no puede hacer
Sección titulada «Lo que una llave no puede hacer»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,MASTERy los roles de las llaves no se pueden dar con una llave, ni directo ni dentro de un grupo de roles, ni al invitar. Responde403con «La llave no puede asignar ese rol» y no cambia nada.listarRolesAsignablesDeEmpresatrae sólo lo que la llave sí puede dar: arma las listas con ese resultado. - No toca cuentas intocables. Una persona con
SUPER-ADMINen cualquier empresa, o con un rol global, o con un grupo de roles activo que contieneSUPER-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. Responde403«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,listarSesionesDeUsuarioyeliminarSesionesDeUsuariosobre una persona que también pertenece a otra empresa responden el mismo403, 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.
crearUsuariomanda un correo y la persona elige su clave.passwordModesólo aceptaauto_invite(el valor por defecto);temp_password,tempPasswordymanual_inviteresponden400y no crean nada.verificarCorreoDeUsuarioresponde 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,crearUsuariola suma a tu empresa y responde igual que con una cuenta nueva; el nombre sale de tu cuerpo, nunca de la cuenta existente.409sólo si ya es de tu empresa. - El restablecimiento de clave sólo manda el correo.
enviarRestablecimientoDeClaveDeUsuariono recibepassword(si lo mandas responde400) y ninguna respuesta trae la clave. No hay forma de fijar ni de leer la clave de una persona por API. - Dar
ADMINavisa. Cada vez que una llave de producción daADMINa una persona, por rol directo, por un grupo de roles o al invitar, losSUPER-ADMINde 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.
Qué necesitas antes
Sección titulada «Qué necesitas antes»- Una llave con acceso a la empresa. La llave del proyecto que instala
redcumbre initesFULL-APIy alcanza.redcumbre api describir crearUsuariomuestra 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_LLAVEy no se guarda nada. - Paginación, errores y límites: Reglas comunes.
listarUsuariosse pagina conpageylimit(hasta 300); sin parámetros devuelve la primera página, no la lista entera.
Cómo se comporta el modo de prueba
Sección titulada «Cómo se comporta el modo de prueba»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>.
1. Ubica las operaciones
Sección titulada «1. Ubica las operaciones»redcumbre buscar "usuarios de la empresa"redcumbre api describir crearUsuarioResultado esperado: las operaciones de esta ficha, con su método, su ruta y los campos del cuerpo.
2. Revisa qué roles puedes dar
Sección titulada «2. Revisa qué roles puedes dar»redcumbre roles asignables-de-empresaResultado 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.
3. Invita a una persona
Sección titulada «3. Invita a una persona»redcumbre usuarios verificar-correo --correo persona@example.comredcumbre 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.
4. Lista, ve y edita
Sección titulada «4. Lista, ve y edita»redcumbre usuarios listar --buscar ejemplo --pagina 1 --limite 50redcumbre usuarios ver <id-de-la-persona>redcumbre usuarios editar <id-de-la-persona> --cuerpo @cambios.jsonredcumbre 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.
5. Cambia los roles
Sección titulada «5. Cambia los roles»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.
6. Restablece la clave y cierra sesiones
Sección titulada «6. Restablece la clave y cierra sesiones»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.
7. Quita a una persona de la empresa
Sección titulada «7. Quita a una persona de la empresa»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.
8. Administra los grupos de roles
Sección titulada «8. Administra los grupos de roles»redcumbre grupos-de-roles listarredcumbre grupos-de-roles sincronizacionredcumbre grupos-de-roles crear --cuerpo @grupo.jsonredcumbre grupos-de-roles editar <id-del-grupo> --cuerpo @cambios.jsonredcumbre 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.
9. Arma grupos de personas
Sección titulada «9. Arma grupos de personas»redcumbre grupos-de-personas listar --buscar facturaciónredcumbre grupos-de-personas crear --cuerpo @grupo.jsonredcumbre grupos-de-personas agregar-persona <id-del-grupo> --cuerpo @persona.jsonredcumbre 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.
10. Define áreas y puestos
Sección titulada «10. Define áreas y puestos»redcumbre areas listar --estado ACTIVAredcumbre areas crear --cuerpo @area.jsonredcumbre areas disponibles <id-del-area>redcumbre areas asociar-bodegas <id-del-area> --cuerpo @bodegas.jsonredcumbre areas archivar <id-del-area>redcumbre puestos configuracionredcumbre puestos cambio-rapido --cuerpo @cambio.jsonredcumbre puestos listarredcumbre puestos editar <id-del-puesto> --cuerpo @cambios.jsonredcumbre 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.
11. Asigna sucursales a una persona
Sección titulada «11. Asigna sucursales a una persona»redcumbre sucursales-de-usuarios para-asignacionredcumbre sucursales-de-usuarios asignar <id-de-zitadel-de-la-persona> --cuerpo @sucursales.jsonredcumbre 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.
Errores que vas a ver
Sección titulada «Errores que vas a ver»| Código | Cuándo | Qué hacer |
|---|---|---|
400 | Un campo que la operación no declara, passwordMode distinto de auto_invite o un password al restablecer la clave | Corrige 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 grupo | Usa 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 sesiones | No hay ruta por API: lo hace una persona en el panel. |
404 | Una persona, un grupo, un área o un puesto que no es de tu empresa o no existe | Revisa el id. Los dos casos responden igual. |
409 | La persona ya es de tu empresa | Usa la operación de editar. |