Apps operativas
Apps operativas: permisos y entornos
Roles, capacidades y alcance con un ejemplo por tienda, administradores de la organización, entornos de QA y producción, promoción y suspensión de una app.
Actualizado: 2026-11-17
En esta guía
El modelo en cuatro conceptos
- Capacidad: un nombre que tú eliges para algo que se puede hacer, como
returns.decide. Las acciones, las ranuras de archivos y los formularios declaran qué capacidad exigen. - Rol: un conjunto de capacidades con nombre, propio de la app.
- Asignación: entrega un rol a un usuario (
userId) o a todos los usuarios con un rol de la organización (orgRole, por ejemplomemberoeditor). - Alcance: limita una asignación a ciertos valores de una dimensión, como una lista de tiendas.
Todo se comprueba en el servidor. El panel solo oculta lo que el usuario no puede hacer.
Quién puede abrir la app
visibility tiene dos valores:
organization: cualquier miembro de la organización con acceso a Apps operativas puede abrirla. Lo que puede hacer dentro depende de sus asignaciones.assigned: solo la abren los usuarios con alguna asignación y los administradores de la organización. Los demás no la ven en la lista.
Una app sin accessControl queda abierta a toda la organización y sus acciones no pueden exigir capacidades.
Un ejemplo por tienda
La app de devoluciones del inicio rápido tiene un campo storeId en cada registro. Este bloque limita a cada persona a sus tiendas:
{
"accessControl": {
"visibility": "assigned",
"scopeFields": { "store": "storeId" },
"scopeValues": {
"store": [
{ "value": "store-01", "label": "Centro" },
{ "value": "store-02", "label": "Norte" }
]
},
"roles": {
"agent": { "label": "Agente", "capabilities": ["returns.read", "returns.create", "returns.attach"] },
"supervisor": { "label": "Supervisor", "capabilities": ["returns.read", "returns.create", "returns.attach", "returns.decide"] },
"auditor": { "label": "Auditor", "capabilities": ["returns.read"] }
},
"assignments": [
{ "userId": "user_41", "role": "agent", "scope": { "store": ["store-01"] } },
{ "userId": "user_52", "role": "supervisor", "scope": { "store": ["store-01", "store-02"] } },
{ "orgRole": "editor", "role": "auditor" }
]
}
}
scopeFields conecta la dimensión store con el campo storeId de los registros. Con eso:
user_41, agente de Centro: ve solo las devoluciones destore-01. Puede crear devoluciones de esa tienda y adjuntar comprobantes. Si intenta crear una destore-02, recibe un 403. No ve los botones Aprobar ni Rechazar, y si llama a la acción por API recibe un 403.user_52, supervisor de dos tiendas: ve y decide devoluciones destore-01ystore-02.- Usuarios con rol
editoren la organización: son auditores sin alcance, así que leen las devoluciones de todas las tiendas. No pueden decidir ni ver comprobantes, porque la ranura exigereturns.attach. - Cualquier otro usuario: no puede abrir la app.
La app que recibe cada usuario incluye su permiso ya resuelto. Para user_41:
{
"grant": {
"canOpen": true,
"capabilities": {
"returns.read": { "store": ["store-01"] },
"returns.create": { "store": ["store-01"] },
"returns.attach": { "store": ["store-01"] }
}
}
}
Una capacidad con valor null no tiene restricción de alcance.
Reglas que conviene conocer
- Leer también es una capacidad. Con
scopeFieldsdeclarado, un usuario lee un registro si cae dentro del alcance de al menos una de sus capacidades. Por esoreturns.readexiste aunque ninguna acción la use. - Sin
scopeFields, no hay alcance por registro. Todo el que abre la app lee todos sus registros. - Las asignaciones se suman. Si un usuario tiene dos asignaciones, obtiene las capacidades de ambas. Los valores de una misma dimensión se unen.
- Lo abierto gana. Si una asignación entrega una capacidad sin alcance y otra la limita, la capacidad queda sin límite.
- Una asignación sin
scopeno restringe. Tampoco restringe una dimensión que no aparece enscope. - Acciones de colección y ranuras de la app: no hay registro contra el cual medir el alcance, así que basta con tener la capacidad en cualquier alcance.
- Ranuras de registro: aplican la capacidad de la ranura dentro del alcance del registro.
- Datasets: no tienen alcance. Los lee todo el que puede abrir la app.
- Las asignaciones son privadas. Solo quienes administran definiciones reciben la lista de asignaciones; los demás usuarios reciben únicamente su
grant.
Administradores de la organización
Un administrador de la organización tiene todas las capacidades de la app, sin alcance, sin necesidad de asignación. Así una app nunca puede dejar fuera a su propia organización.
Administrar definiciones es otra cosa: los roles admin y editor pueden instalar paquetes, exportarlos y ver apps en borrador. Un editor no recibe capacidades por eso; para operar la app necesita una asignación, como cualquier usuario.
Entornos
Una app se instala en una organización y en un entorno. QA y producción son espacios separados: cada uno tiene sus tipos de registro, su definición de la app, sus registros, archivos, datasets, configuración y asignaciones. Nada se comparte.
- En el panel trabajas sobre el entorno seleccionado.
- En la API eliges el entorno con la cabecera
x-qac-environment. Sin la cabecera se usa el entorno por defecto de la organización. Una clave que no existe se rechaza con 400. - Un flujo corre en el entorno donde ocurrió la acción. El sobre trae
environmenty el cliente Python escribe en ese mismo entorno.
Promover una app de QA a producción
Promover es copiar datos: instalas el mismo paquete en el otro entorno.
Si guardas el paquete en tu repositorio, instala el mismo archivo en cada entorno:
jq -n --slurpfile pkg returns.package.json '{package: $pkg[0]}' |
curl -X POST "$QAC_API/operational-apps/install" \
-H "Authorization: Bearer $QAC_TOKEN" \
-H "x-qac-environment: prod" \
-H "Content-Type: application/json" \
-d @-
Si la versión buena es la que está instalada en QA, expórtala e instálala en producción:
curl "$QAC_API/operational-apps/returns/package" \
-H "Authorization: Bearer $QAC_TOKEN" \
-H "x-qac-environment: qa" |
jq '{package: .package}' |
curl -X POST "$QAC_API/operational-apps/install" \
-H "Authorization: Bearer $QAC_TOKEN" \
-H "x-qac-environment: prod" \
-H "Content-Type: application/json" \
-d @-
La exportación devuelve el paquete tal como está instalado, incluidas la configuración y las asignaciones de ese entorno. Lo que cambia entre entornos va en overrides, junto a package en el cuerpo de la instalación:
{
"overrides": {
"settings": { "refundProvider": "live" },
"accessControl": {
"assignments": [
{ "userId": "user_52", "role": "supervisor", "scope": { "store": ["store-01", "store-02"] } }
]
}
}
}
settingsse combina sobre la configuración del paquete: solo cambias las claves que envías.accessControl.assignmentsreemplaza la lista completa.accessControl.scopeValuesreemplaza los valores de alcance, por ejemplo si las tiendas de QA no son las de producción.- Ninguna otra parte se puede ajustar al instalar. Si necesitas otra estructura, es otro paquete.
La instalación es repetible. Reinstalar el mismo documento con los mismos overrides no cambia nada, y la respuesta te dice qué se creó, qué se actualizó y qué quedó igual.
Los registros no se promueven. Los datos de QA se quedan en QA.
Suspender una app
Para detener una app, instala el paquete con "status": "suspended" en app. Para reanudarla, vuelve a instalarlo con "status": "published".
Mientras está suspendida:
- Los usuarios dejan de verla y sus registros dejan de estar disponibles para ellos.
- Nadie puede ejecutar acciones, subir archivos ni leer datasets: la API responde 409.
- Los flujos que estaban en cola no arrancan.
- Los registros, el historial y los archivos se conservan intactos.
draft sirve para lo contrario: preparar una app que todavía no deben ver los usuarios. Solo quienes administran definiciones pueden abrirla y probarla.