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), draft o deprecated. Solo un tipo publicado admite registros nuevos y puede ser usado por una app.
  • schema.fields: los campos, por nombre.
  • schema.additionalProperties: si es true, 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 de enumValues.
  • relation: identificador de otro registro. Declara relation.recordTypeId y relation.cardinality (one o many; con many el 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), draft o suspended.
  • 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 completa automationId.
  • 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: record actúa sobre un registro; collection actúa sobre la app (importaciones, corridas).
  • recordTypeId: obligatorio en acciones de registro. Debe estar en recordTypeIds.
  • capability: capacidad que necesita el usuario. Debe pertenecer a algún rol. Sin capability, 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 de input. 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 o null).
  • reserve: garantía de unicidad. key es 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. releaseOnStates lista 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: organization o assigned.
  • roles: por cada rol, label y capabilities.
  • assignments: quién recibe cada rol. Cada asignación tiene userId u orgRole (exactamente uno), role y, 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: record adjunta a un registro; app adjunta a la app.
  • recordTypeId: obligatorio con target: "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, con moduleId, name, description y viewIds. La pantalla estándar lista las vistas directamente.
  • customComponents: páginas tuyas que se muestran dentro de una vista. Cada una declara componentId, label, url (https) y height opcional.

Estado de la app

  • draft: solo la ven y la ejecutan quienes administran definiciones (roles admin y editor). 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

  • version del 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/install con { "package": { ... }, "overrides": { ... } } instala o actualiza. Requiere rol admin o editor.
  • GET /operational-apps/{appId}/package devuelve { "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 sobre app.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 de reserve ya pertenece a otro registro, o la app está suspendida.