Apps operativas
Apps operativas: referencia del paquete
El documento del paquete campo por campo: tipos de registro, acciones, permisos, archivos, datasets, flujos, vistas, estados, versiones y errores de validación.
Actualizado: 2026-11-17
En esta guía
El documento
Un paquete es un objeto JSON con cinco claves:
schema: siempre"qac.operational-app-package".packageId: identificador del paquete.version: entero positivo. Es tu número de versión del paquete.recordTypes: lista de tipos de registro que la app necesita.app: la definición de la app.
Los identificadores (packageId, appId, recordTypeId, actionId, flowId, slotId, datasetId, componentId, roles y nombres de campo) empiezan por una letra y usan letras, números, punto, guion bajo o guion, hasta 80 caracteres.
El inicio rápido tiene un paquete completo. Los fragmentos de esta página se apoyan en él.
Tipos de registro
Cada elemento de recordTypes:
recordTypeId,name: obligatorios.description,translations: opcionales.status:published(por defecto),draftodeprecated. Solo un tipo publicado admite registros nuevos y puede ser usado por una app.schema.fields: los campos, por nombre.schema.additionalProperties: si estrue, se aceptan campos no declarados. Por defecto se rechazan.lifecycle: opcional.
Campos
Cada campo declara type y, opcionalmente, label, required, readOnly, format y translations.
string: texto.number: número.money: número que representa un importe.boolean: verdadero o falso.datetime: texto con fecha y hora.enum: texto dentro deenumValues.relation: identificador de otro registro. Declararelation.recordTypeIdyrelation.cardinality(oneomany; conmanyel valor es una lista).attachment: texto que referencia un adjunto.array: lista.json: objeto libre.
format ajusta la presentación: text, currency, percentage, date, datetime o email.
readOnly marca un campo que las personas no editan. No aparece en formularios y la API rechaza un cambio directo. Las acciones (con set) y los flujos sí pueden escribirlo.
Ciclo de vida
initialState: estado con el que nace el registro.states: todos los estados.transitions: por cada estado, la lista de estados a los que puede pasar.
Una transición que no está declarada se rechaza, venga de una acción, de un flujo o de una edición. Un tipo sin lifecycle no restringe el estado.
La app
appId,name: obligatorios.description,translations,icon: opcionales.recordTypeIds: los tipos de registro que la app gobierna. Deben estar publicados.status:published(por defecto),draftosuspended.flows,actions,accessControl,files,datasets,settings,modules,views,customComponents: las secciones que siguen.
translations existe en casi todas las piezas. Las claves son idiomas y cada una puede traer name, label, title, description, states y enumValues:
{
"translations": {
"en": { "name": "Return", "states": { "requested": "Requested", "refunded": "Refunded" } }
}
}
Flujos
Cada elemento de flows:
flowId,label: identificador y nombre visible.workflowType+taskQueue: el workflow y la cola de su worker. La instalación registra una automatización y completaautomationId.automationId: en lugar de lo anterior, una automatización existente de tu organización.input: objeto fijo que se envía al flujo en cada arranque.
Los detalles están en Flujos.
Acciones
{
"flows": [
{ "flowId": "import-returns", "label": "Importar devoluciones", "workflowType": "ReturnsImportWorkflow", "taskQueue": "automation-processes" }
],
"actions": [
{
"actionId": "register-refund",
"label": "Registrar reembolso manual",
"description": "Para reembolsos emitidos fuera del flujo.",
"target": "record",
"recordTypeId": "returns.request",
"capability": "returns.decide",
"allowedStates": ["approved"],
"targetState": "refunded",
"input": { "reference": { "type": "string", "label": "Referencia", "required": true } },
"set": { "refundReference": { "input": "reference" } },
"reserve": { "key": "refund-reference:{input.reference}" },
"requiresConfirmation": true
},
{
"actionId": "import",
"label": "Importar archivo",
"target": "collection",
"capability": "returns.create",
"flowId": "import-returns"
}
]
}
actionId,label,description: identificador y textos del botón.target:recordactúa sobre un registro;collectionactúa sobre la app (importaciones, corridas).recordTypeId: obligatorio en acciones de registro. Debe estar enrecordTypeIds.capability: capacidad que necesita el usuario. Debe pertenecer a algún rol. Sincapability, basta con poder abrir la app.allowedStates: estados en los que la acción está disponible. Sin esta lista, lo está en todos.targetState: estado al que pasa el registro. Debe ser una transición permitida desde el estado actual.input: campos que se piden al usuario, con la misma forma que los campos de un tipo de registro. Se rechazan campos no declarados.set: datos que la acción escribe en el registro. Cada campo toma su valor de una fuente:{ "input": "reference" }: un campo deinput. Si es opcional y no llega, el campo del registro no se toca.{ "actor": "id" }o{ "actor": "email" }: quien ejecuta la acción.{ "now": true }: la fecha y hora de la ejecución.{ "value": "manual" }: una constante (texto, número, booleano onull).
reserve: garantía de unicidad.keyes una plantilla con{input.<campo>},{record.<campo>}o{recordId}. La clave resultante solo puede pertenecer a un registro: si otro ya la tiene, la acción falla con 409.releaseOnStateslista los estados que liberan la clave.flowId: flujo que arranca cuando la acción se aplica.requiresConfirmation: el panel pide confirmación antes de enviar.
En una acción de colección solo aplican capability, input, flowId y requiresConfirmation. El cuerpo de la petición admite además fileIds (hasta 50 archivos confirmados de la app) e idempotencyKey.
Permisos
accessControl declara quién abre la app y qué puede hacer:
visibility:organizationoassigned.roles: por cada rol,labelycapabilities.assignments: quién recibe cada rol. Cada asignación tieneuserIduorgRole(exactamente uno),roley, opcionalmente,scope.scopeFields: por cada dimensión de alcance, el campo del registro que la lleva.scopeValues: catálogo opcional de valores por dimensión (value,label,active). Se guarda con la app para que tus flujos y pantallas lo lean; Quantum no valida contra él.
El modelo completo, con un ejemplo, está en Permisos y entornos.
Archivos
{
"files": [
{
"slotId": "returns-file",
"label": "Archivo de devoluciones",
"target": "app",
"contentTypes": ["text/csv"],
"maxBytes": 5242880,
"capability": "returns.create",
"flowId": "import-returns"
}
]
}
slotId,label: identificador y nombre visible.target:recordadjunta a un registro;appadjunta a la app.recordTypeId: obligatorio contarget: "record".contentTypes: tipos aceptados. Admite un tipo exacto (application/pdf), una familia (image/*) o cualquiera (*/*).maxBytes: tamaño máximo.multiple: la pantalla permite elegir varios archivos a la vez.capability: capacidad para subir, listar y descargar. En una ranura de registro se aplica además el alcance del registro.flowId: flujo que arranca cuando una subida queda confirmada.
La subida tiene tres pasos, que el panel hace por ti: pedir la subida con nombre, tipo, tamaño y suma SHA-256; enviar el archivo a la URL firmada; y confirmar. Quantum compara tamaño y suma antes de dar el archivo por válido.
Datasets
{
"datasets": [
{
"datasetId": "refunds-by-day",
"label": "Reembolsos por día",
"fields": {
"day": { "type": "string", "label": "Día" },
"storeId": { "type": "string", "label": "Tienda" },
"refunds": { "type": "number", "label": "Reembolsos" },
"amount": { "type": "money", "label": "Monto", "format": "currency" }
},
"key": ["day", "storeId"]
}
]
}
fields: campos de cada fila, con la misma forma que los de un tipo de registro.key: campos que identifican una fila. Escribir otra fila con la misma clave reemplaza la anterior.
Los flujos escriben las filas. Las pantallas las leen con GET /operational-apps/{appId}/datasets/{datasetId}, que acepta limit (100 por defecto, 1000 como máximo), cursor y filtros de igualdad filter.<campo>=<valor> sobre campos de texto, número y booleano.
Configuración
settings es un objeto libre con la configuración de la app en una organización: tiendas, tolerancias, parámetros. Los flujos lo reciben en el sobre y los componentes propios en su contexto. No guardes secretos: lo lee todo el que puede abrir la app.
Vistas, módulos y componentes propios
views: las pantallas. Ver Vistas.modules: agrupación opcional de vistas, conmoduleId,name,descriptionyviewIds. La pantalla estándar lista las vistas directamente.customComponents: páginas tuyas que se muestran dentro de una vista. Cada una declaracomponentId,label,url(https) yheightopcional.
Estado de la app
draft: solo la ven y la ejecutan quienes administran definiciones (rolesadminyeditor). No aparece en el selector de apps; se abre por enlace directo.published: disponible según sus permisos.suspended: nadie puede ejecutar acciones, subir archivos ni leer datasets. La app y los registros de sus tipos dejan de ser visibles para quienes no administran definiciones, y los flujos pendientes no arrancan.
status es el único interruptor. No hay otro paso de activación.
Versiones
versiondel paquete es tuya: súbela cuando publiques cambios. Queda registrada en la app instalada.- La instalación asigna las versiones internas. Un tipo de registro cuyo contenido cambió recibe una versión nueva; uno idéntico queda igual. Lo mismo ocurre con la app.
- Los registros existentes conservan la versión del esquema con la que nacieron y se validan contra ella.
- Instalar un documento idéntico no escribe nada.
Instalar y exportar
POST /operational-apps/installcon{ "package": { ... }, "overrides": { ... } }instala o actualiza. Requiere roladminoeditor.GET /operational-apps/{appId}/packagedevuelve{ "package": { ... } }con la app instalada como documento de paquete.
overrides ajusta el paquete para una instalación concreta sin editarlo. Solo admite:
settings: se combina en profundidad sobreapp.settings.accessControl.assignments: reemplaza las asignaciones.accessControl.scopeValues: reemplaza el catálogo de valores.
Errores de validación
La instalación responde 400 con message y una lista errors. Nada se escribe si hay al menos un error. Los errores de la app llevan el prefijo app: y los de un tipo de registro recordTypes.<id>:.
Del documento:
schema must be 'qac.operational-app-package'.packageId is required and must use letters, numbers, dot, underscore or hyphen.version must be a positive integer.overrides: 'views' cannot be overridden.
De los tipos de registro:
recordTypes.returns.request: name is required.recordTypes.returns.request: Field 'amount' has an invalid definition or unknown type.recordTypes.returns.request: Lifecycle transition 'approved' -> 'paid' targets an undeclared state.
De la app:
app: recordTypeIds: 'returns.request' is not a published record type.app: flows: 'issue-refund' needs automationId or workflowType.app: flows: 'issue-refund' needs taskQueue with workflowType.app: actions.approve: record actions need recordTypeId.app: actions.approve: 'returns.request' is not in recordTypeIds.app: actions.approve: state 'aproved' is not in the lifecycle of 'returns.request'.app: actions.approve: set writes unknown field 'decidedOn'.app: actions.approve: set reads undeclared input 'note'.app: actions.approve: flow 'issue-refund' is not declared.app: actions.approve: capability 'returns.decide' is granted to no role.app: actions.approve: capability 'returns.decide' requires accessControl.app: accessControl: each assignment needs exactly one of userId or orgRole.app: accessControl: assignment uses unknown role 'manager'.app: accessControl: scope 'store' has no scopeFields entry.app: files.receipt: contentTypes is required.app: datasets.refunds-by-day: key field 'day' is not declared.app: customComponents.refund-calculator: url must be https.app: views.returns-detail: custom component 'refund-calculator' is not declared.
Al ejecutar, los errores más comunes son:
- 400: los datos de la acción no cumplen
input, o la acción produciría un registro inválido. - 403: falta la capacidad, o el registro está fuera del alcance del usuario.
- 409: el registro cambió (
expectedVersion), la acción no aplica en el estado actual, la transición no está permitida, la clave dereserveya pertenece a otro registro, o la app está suspendida.