Apps operativas

Apps operativas: inicio rápido

Construye una app de devoluciones de punta a punta: el paquete, la instalación, la pantalla en el panel, una acción y el flujo que emite el reembolso.

Actualizado: 2026-11-17

En esta guía

Qué vas a construir

Una app de devoluciones con:

  • Un tipo de registro, returns.request, con cuatro estados.
  • Dos acciones: aprobar y rechazar.
  • Una ranura para adjuntar el comprobante.
  • Un flujo que emite el reembolso cuando alguien aprueba.
  • Dos pantallas: la cola de solicitudes y el detalle.

Necesitas:

  • Un usuario con rol admin o editor en una organización que tenga Apps operativas habilitado.
  • La URL de la API de Quantum en QAC_API y el token de tu sesión en QAC_TOKEN.

1. Escribe el paquete

Un paquete es un único documento JSON con los tipos de registro y la app. Guárdalo como returns.package.json.

{
  "schema": "qac.operational-app-package",
  "packageId": "returns",
  "version": 1,
  "recordTypes": [
    {
      "recordTypeId": "returns.request",
      "name": "Devolución",
      "translations": { "en": { "name": "Return" } },
      "schema": {
        "fields": {
          "orderNumber": { "type": "string", "label": "Pedido", "required": true },
          "storeId": { "type": "string", "label": "Tienda", "required": true },
          "amount": { "type": "money", "label": "Monto", "required": true, "format": "currency" },
          "reason": { "type": "enum", "label": "Motivo", "enumValues": ["defective", "wrong_item", "other"] },
          "decisionNote": { "type": "string", "label": "Nota de decisión", "readOnly": true },
          "decidedBy": { "type": "string", "label": "Decidido por", "readOnly": true },
          "decidedAt": { "type": "datetime", "label": "Fecha de decisión", "readOnly": true },
          "refundReference": { "type": "string", "label": "Referencia de reembolso", "readOnly": true }
        }
      },
      "lifecycle": {
        "initialState": "requested",
        "states": ["requested", "approved", "rejected", "refunded"],
        "transitions": {
          "requested": ["approved", "rejected"],
          "approved": ["refunded"]
        }
      }
    }
  ],
  "app": {
    "appId": "returns",
    "name": "Devoluciones",
    "description": "Solicitudes de devolución, aprobación y reembolso.",
    "translations": { "en": { "name": "Returns", "description": "Return requests, approval, and refund." } },
    "icon": "layers",
    "recordTypeIds": ["returns.request"],
    "flows": [
      {
        "flowId": "issue-refund",
        "label": "Emitir reembolso",
        "workflowType": "ReturnsRefundWorkflow",
        "taskQueue": "automation-processes"
      }
    ],
    "actions": [
      {
        "actionId": "approve",
        "label": "Aprobar",
        "target": "record",
        "recordTypeId": "returns.request",
        "capability": "returns.decide",
        "allowedStates": ["requested"],
        "targetState": "approved",
        "input": { "note": { "type": "string", "label": "Nota" } },
        "set": {
          "decisionNote": { "input": "note" },
          "decidedBy": { "actor": "email" },
          "decidedAt": { "now": true }
        },
        "flowId": "issue-refund",
        "requiresConfirmation": true
      },
      {
        "actionId": "reject",
        "label": "Rechazar",
        "target": "record",
        "recordTypeId": "returns.request",
        "capability": "returns.decide",
        "allowedStates": ["requested"],
        "targetState": "rejected",
        "input": { "note": { "type": "string", "label": "Motivo del rechazo", "required": true } },
        "set": {
          "decisionNote": { "input": "note" },
          "decidedBy": { "actor": "email" },
          "decidedAt": { "now": true }
        }
      }
    ],
    "accessControl": {
      "visibility": "organization",
      "roles": {
        "agent": { "label": "Agente", "capabilities": ["returns.read", "returns.create", "returns.attach"] },
        "supervisor": { "label": "Supervisor", "capabilities": ["returns.read", "returns.create", "returns.attach", "returns.decide"] }
      },
      "assignments": [
        { "orgRole": "member", "role": "agent" },
        { "orgRole": "editor", "role": "supervisor" }
      ]
    },
    "files": [
      {
        "slotId": "receipt",
        "label": "Comprobante",
        "target": "record",
        "recordTypeId": "returns.request",
        "contentTypes": ["application/pdf", "image/*"],
        "maxBytes": 10485760,
        "multiple": true,
        "capability": "returns.attach"
      }
    ],
    "datasets": [],
    "settings": { "refundProvider": "sandbox" },
    "views": [
      {
        "viewId": "returns-queue",
        "name": "Solicitudes",
        "kind": "queue",
        "recordTypeId": "returns.request",
        "version": 1,
        "status": "published",
        "context": { "createCapability": "returns.create" },
        "layout": {
          "sections": [
            {
              "id": "totals",
              "title": "Resumen",
              "columns": 2,
              "components": [
                { "id": "pending", "type": "metric", "title": "Por decidir", "props": { "aggregate": "count", "where": { "state": ["requested"] }, "accent": "amber" } },
                { "id": "refunded", "type": "metric", "title": "Reembolsado", "props": { "aggregate": "sum", "field": "amount", "where": { "state": ["refunded"] } } }
              ]
            },
            {
              "id": "list",
              "title": "Solicitudes",
              "components": [
                { "id": "table", "type": "table", "fieldIds": ["orderNumber", "storeId", "amount", "reason"], "props": { "titleField": "orderNumber" } }
              ]
            }
          ]
        }
      },
      {
        "viewId": "returns-detail",
        "name": "Devolución",
        "kind": "detail",
        "recordTypeId": "returns.request",
        "version": 1,
        "status": "published",
        "layout": {
          "sections": [
            {
              "id": "summary",
              "title": "Solicitud",
              "components": [
                { "id": "fields", "type": "record-detail", "fieldIds": ["orderNumber", "storeId", "amount", "reason", "decisionNote", "decidedBy", "refundReference"] },
                { "id": "decide", "type": "actions", "actionIds": ["approve", "reject"], "props": { "primaryActionId": "approve" } }
              ]
            },
            {
              "id": "receipts",
              "title": "Comprobantes",
              "components": [{ "id": "files", "type": "files", "props": { "slotIds": ["receipt"] } }]
            },
            {
              "id": "history",
              "title": "Historial",
              "components": [{ "id": "activity", "type": "activity" }]
            }
          ]
        }
      }
    ]
  }
}

Lo que dice este documento:

  • Una devolución nace en requested. De ahí solo puede pasar a approved o rejected, y de approved a refunded.
  • Aprobar y rechazar exigen la capacidad returns.decide, que solo tiene el rol supervisor.
  • Aprobar escribe quién decidió y cuándo, mueve el registro a approved e inicia el flujo issue-refund.
  • Los campos readOnly no aparecen en los formularios. Los escriben las acciones y los flujos.

2. Escribe el flujo

El flujo recibe el registro aprobado, emite el reembolso y deja el registro en refunded.

from datetime import timedelta

from temporalio import activity, workflow

with workflow.unsafe.imports_passed_through():
    from qac.operational import OperationalFlowInput, SystemOfRecordsClient


@activity.defn(name="issue_refund")
def issue_refund(flow_input: dict) -> dict:
    envelope = OperationalFlowInput.parse(flow_input)
    client = SystemOfRecordsClient.from_flow_input(envelope)
    # Llama aquí a tu proveedor de pagos. Usa outbox_id como clave de idempotencia.
    reference = "RF-" + envelope.outbox_id[:8]
    client.transition(
        envelope.record["recordId"],
        state="refunded",
        data={"refundReference": reference},
        reason="Reembolso emitido",
    )
    client.report_flow_result(envelope.outbox_id, "completed", output={"refundReference": reference})
    return {"refundReference": reference}


@workflow.defn(name="ReturnsRefundWorkflow")
class ReturnsRefundWorkflow:
    @workflow.run
    async def run(self, flow_input: dict) -> dict:
        return await workflow.execute_activity(
            issue_refund, flow_input, start_to_close_timeout=timedelta(minutes=5)
        )

El nombre del workflow debe coincidir con workflowType, y el workflow debe estar registrado en el worker que atiende la cola declarada en taskQueue. En Flujos está la versión completa, con manejo de fallos.

3. Instala el paquete

jq -n --slurpfile pkg returns.package.json '{package: $pkg[0]}' |
  curl -X POST "$QAC_API/operational-apps/install" \
    -H "Authorization: Bearer $QAC_TOKEN" \
    -H "Content-Type: application/json" \
    -d @-

La instalación valida el documento completo antes de escribir nada. Si todo está bien, crea el tipo de registro, registra el flujo como una automatización de tu organización y guarda la app. La respuesta, abreviada:

{
  "packageId": "returns",
  "version": 1,
  "recordTypes": [{ "recordTypeId": "returns.request", "version": 1, "change": "created" }],
  "automations": [{ "flowId": "issue-refund", "automationId": "0f6c2b1a-7d3e-4a58-9b21-5c4e8d7f6a90", "change": "created" }],
  "appChange": "created",
  "app": { "appId": "returns", "version": 1, "status": "published" },
  "environment": "prod"
}

Si algo está mal, recibes un 400 con todos los problemas a la vez:

{
  "message": "Invalid operational app package: app: actions.approve: state 'aproved' is not in the lifecycle of 'returns.request'.",
  "errors": ["app: actions.approve: state 'aproved' is not in the lifecycle of 'returns.request'."]
}

Instalar dos veces el mismo documento no cambia nada: cada parte vuelve como unchanged.

4. Abre la app en el panel

Entra a Apps operativas en el panel y elige Devoluciones, o abre directamente /es/automation-center/dashboard/operational-apps?appId=returns.

Verás la vista Solicitudes con las dos métricas y la tabla vacía. Pulsa Nuevo registro, completa pedido, tienda, monto y motivo, y guarda. El registro nace en requested y el panel abre su detalle.

También puedes crearlo por API:

curl -X POST "$QAC_API/operational-records" \
  -H "Authorization: Bearer $QAC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"recordTypeId": "returns.request", "data": {"orderNumber": "A-1042", "storeId": "store-01", "amount": 129900, "reason": "defective"}}'

5. Ejecuta una acción

En el detalle, un supervisor ve los botones Aprobar y Rechazar. Al pulsar Aprobar, el panel pide la nota, luego la confirmación, y envía la acción.

La misma acción por API:

curl -X POST "$QAC_API/operational-records/$RECORD_ID/actions" \
  -H "Authorization: Bearer $QAC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"actionId": "approve", "appId": "returns", "input": {"note": "Producto defectuoso confirmado"}, "expectedVersion": 1}'

La respuesta, abreviada, trae el registro ya en approved y el arranque del flujo:

{
  "record": {
    "recordId": "7c1d6a52-1f0e-4b7a-9a43-2f8f0f3f9b10",
    "recordTypeId": "returns.request",
    "state": "approved",
    "version": 2,
    "data": {
      "orderNumber": "A-1042",
      "storeId": "store-01",
      "amount": 129900,
      "reason": "defective",
      "decisionNote": "Producto defectuoso confirmado",
      "decidedBy": "ana@example.com",
      "decidedAt": "2026-11-17T15:04:05.120Z"
    },
    "availableActions": []
  },
  "flow": { "outboxId": "3b1f0c9e-52a7-4d1e-9c55-0a6d7e21f4b8" },
  "environment": "prod"
}

expectedVersion protege contra cambios simultáneos: si alguien más modificó el registro, recibes un 409 y debes recargar. availableActions queda vacío porque ninguna acción aplica en approved.

6. Mira correr el flujo

  • En el detalle aparece el aviso En ejecución junto a las acciones.
  • En Ejecuciones aparece la corrida "Devoluciones - Emitir reembolso", iniciada por el usuario que aprobó.
  • Cuando el flujo termina, el registro pasa a refunded, se completa la referencia de reembolso y el historial muestra los tres cambios: creación, aprobación y reembolso.

Para consultar el arranque por API:

curl "$QAC_API/operational-apps/returns/flows/3b1f0c9e-52a7-4d1e-9c55-0a6d7e21f4b8" \
  -H "Authorization: Bearer $QAC_TOKEN"

Qué sigue