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
adminoeditoren una organización que tenga Apps operativas habilitado. - La URL de la API de Quantum en
QAC_APIy el token de tu sesión enQAC_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 aapprovedorejected, y deapprovedarefunded. - Aprobar y rechazar exigen la capacidad
returns.decide, que solo tiene el rolsupervisor. - Aprobar escribe quién decidió y cuándo, mueve el registro a
approvede inicia el flujoissue-refund. - Los campos
readOnlyno 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
- Referencia del paquete: todos los campos y los errores de validación.
- Permisos y entornos: limita cada rol a sus tiendas y lleva la app de QA a producción.
- Vistas: el catálogo completo de componentes.