Apps operativas
Apps operativas: flujos
Cómo escribir la lógica de una app operativa: el sobre de entrada, el cliente Python, idempotencia, reintentos, archivos y ejecuciones.
Actualizado: 2026-11-17
En esta guía
Qué es un flujo
Un flujo es el código que contiene tu lógica de negocio: calcular diferencias, cruzar un extracto, llamar a un proveedor, crear casos. La definición de la app no lleva fórmulas ni reglas; solo dice cuándo arranca cada flujo.
Un flujo arranca por tres motivos:
- Una acción sobre un registro declara
flowId. - Una acción de colección declara
flowId. - Una ranura de archivos declara
flowIdy alguien confirma una subida.
Un flujo es un workflow de Temporal que corre en un worker de Quantum. En el paquete lo vinculas de una de dos formas:
workflowType+taskQueue: el nombre del workflow y la cola del worker que lo ejecuta. Al instalar el paquete, Quantum registra el flujo como una automatización de tu organización y completaautomationIdpor ti.automationId: una automatización que ya existe en tu organización.
En ambos casos cada corrida es una ejecución normal de la organización: se factura y aparece en Ejecuciones.
El sobre de entrada
Todo flujo recibe un único objeto JSON con esta forma:
{
"schema": "qac.operational-flow-input",
"orgId": "org_8f2c",
"organizationId": "org_8f2c",
"environment": "prod",
"appId": "returns",
"flowId": "issue-refund",
"outboxId": "3b1f0c9e-52a7-4d1e-9c55-0a6d7e21f4b8",
"trigger": { "kind": "action", "actionId": "approve", "recordId": "7c1d6a52-1f0e-4b7a-9a43-2f8f0f3f9b10" },
"input": { "note": "Producto defectuoso confirmado" },
"actor": { "userId": "user_41", "email": "ana@example.com" },
"settings": { "refundProvider": "sandbox" },
"record": {
"recordId": "7c1d6a52-1f0e-4b7a-9a43-2f8f0f3f9b10",
"recordTypeId": "returns.request",
"state": "approved",
"version": 2,
"data": { "orderNumber": "A-1042", "storeId": "store-01", "amount": 129900 }
},
"files": []
}
trigger.kindesactionofile. ConfilelleganslotId,fileIdsy, si la ranura es de registro,recordId.inputson los datos que el usuario envió en la acción, ya validados contra elinputdeclarado.actores la persona que disparó el flujo.settingses la configuración de la app en ese entorno, leída en el momento del arranque.recordes el registro completo tal como está al arrancar el flujo (ya con el cambio de la acción aplicado), onullsi el disparador no tiene registro.filesdescribe los archivos del disparador: el archivo subido, o losfileIdsque se enviaron con una acción de colección. Una acción sobre un registro no trae los archivos de ese registro.outboxIdidentifica este arranque. Es el mismo valor en todos los reintentos.
Si el vínculo del flujo declara input, esas claves llegan en el nivel superior del objeto, debajo de las claves estándar. Cuando el flujo se inicia a través de una automatización, el objeto incluye además los valores por defecto de esa automatización y sus campos habituales (executionId, automationId, userId, email).
El cliente Python
El paquete qac incluye el cliente con el que un flujo registra resultados. Úsalo desde actividades, no desde el código del workflow: hace llamadas HTTP y espera entre reintentos.
from qac.operational import OperationalFlowInput, SystemOfRecordsClient, record_id
envelope = OperationalFlowInput.parse(flow_input)
client = SystemOfRecordsClient.from_flow_input(envelope)
from_flow_input deja el cliente apuntando a la organización, el entorno y la app del sobre. La conexión con Quantum la toma del entorno del worker; tu código no maneja credenciales.
Crear o actualizar registros
result = client.upsert_records([
{
"recordTypeId": "returns.request",
"recordId": record_id("returns.request", "A-1042"),
"data": {"orderNumber": "A-1042", "storeId": "store-01", "amount": 129900},
},
])
# result["counts"] -> {"created": 1, "updated": 0, "unchanged": 0, "rejected": 0}
# result["rejected"] -> registros que no pasaron la validación, con su error
record_id(...)genera un identificador estable a partir de la identidad de negocio. Las mismas partes dan siempre el mismo id.mode="upsert"(por defecto) crea el registro o mezcla los campos que envías con los que ya tiene. Los campos que no mencionas conservan su valor. Si nada cambia, el resultado esunchanged.mode="create"nunca toca un registro que ya existe. Úsalo cuando las personas pueden haber actuado sobre él.statees opcional. Al crear, el registro nace en el estado inicial del ciclo de vida. Al actualizar, el cambio de estado debe ser una transición permitida.- Cada registro se valida contra su esquema. Uno inválido se devuelve como
rejectedcon el motivo; los demás se escriben. - Los flujos pueden escribir campos
readOnly. Esos campos existen justamente para valores que calcula el sistema y que una persona no debe editar. - El cliente envía lotes de 500 registros.
Cambiar el estado de un registro
client.transition(
envelope.record["recordId"],
state="refunded",
data={"refundReference": "RF-20391"},
reason="Reembolso emitido",
)
data se mezcla con los datos actuales. La transición debe estar permitida por el ciclo de vida. Repetir la misma llamada cuando el registro ya está en ese estado no falla.
Escribir filas de dataset
client.write_dataset_rows(
None, # usa la app del sobre
"refunds-by-day",
[{"day": "2026-11-17", "storeId": "store-01", "refunds": 4, "amount": 389700}],
replace=False,
)
- Cada fila se valida contra los campos del dataset. No se aceptan campos no declarados y los campos de
keyson obligatorios. - Una fila con la misma clave reemplaza a la anterior.
- Con
replace=Trueel dataset queda solo con las filas de esta llamada. - El cliente envía lotes de 500 filas. Si una fila es inválida, no se escribe ninguna de su lote.
Leer la configuración
envelope.settings ya trae la configuración. Si necesitas la definición completa, client.get_app() la devuelve.
Reportar el resultado
client.report_flow_result(envelope.outbox_id, "completed", output={"refundReference": "RF-20391"})
El estado es completed o failed. output es un resumen pequeño (máximo 100 KB): los resultados grandes van en registros, datasets o archivos. Con failed, envía el motivo en error.
Reporta siempre. Sin este paso, el arranque se queda en dispatched y la app no sabe si el flujo terminó.
Actividades listas para usar
Si prefieres no escribir actividades para esto, qac.operational_activities trae tres actividades de Temporal que reciben un objeto con flowInput: sor_upsert_records, sor_write_dataset_rows y sor_report_flow_result.
Un flujo completo
from datetime import timedelta
from temporalio import activity, workflow
from temporalio.exceptions import ActivityError, ApplicationError
with workflow.unsafe.imports_passed_through():
from qac.operational import OperationalFlowInput, SystemOfRecordsClient
from qac.operational_activities import sor_report_flow_result
@activity.defn(name="issue_refund")
def issue_refund(flow_input: dict) -> dict:
envelope = OperationalFlowInput.parse(flow_input)
client = SystemOfRecordsClient.from_flow_input(envelope)
record = envelope.record
# Llama aquí a tu proveedor de pagos. Usa outbox_id como clave de idempotencia.
reference = "RF-" + envelope.outbox_id[:8]
client.transition(
record["recordId"],
state="refunded",
data={"refundReference": reference},
reason="Reembolso emitido",
)
return {"refundReference": reference}
@workflow.defn(name="ReturnsRefundWorkflow")
class ReturnsRefundWorkflow:
@workflow.run
async def run(self, flow_input: dict) -> dict:
output, status, error = None, "completed", None
try:
output = await workflow.execute_activity(
issue_refund, flow_input, start_to_close_timeout=timedelta(minutes=5)
)
except ActivityError as exc:
status, error = "failed", str(exc.cause or exc)
await workflow.execute_activity(
sor_report_flow_result,
{"flowInput": flow_input, "status": status, "output": output, "error": error},
start_to_close_timeout=timedelta(minutes=1),
)
if status == "failed":
raise ApplicationError(error)
return output
Idempotencia y reintentos
Supón siempre que tu flujo puede ejecutarse más de una vez. Quantum te da tres garantías y te pide una cosa.
Lo que Quantum garantiza:
- Un arranque por acción. El arranque se guarda en la misma operación que el cambio del registro, con un identificador derivado de la acción, el registro y su versión. Repetir la petición no crea un segundo arranque.
- Un workflow por arranque. El identificador del workflow se deriva del
outboxId. Si el despacho se reintenta, Temporal rechaza el duplicado. - Un arranque por archivo. Confirmar dos veces la misma subida inicia el flujo una sola vez.
Si el flujo no se puede iniciar (por ejemplo, el worker no responde), Quantum reintenta con espera creciente hasta ocho veces. No reintenta cuando el problema no se va a resolver solo: la app está suspendida, la automatización no existe o la facturación no permite la corrida.
Lo que te toca a ti:
- Escrituras idempotentes. Da a cada registro un
recordIddeterminista conrecord_id(...). Así, un reintento de la actividad actualiza el mismo registro en lugar de duplicarlo. - Efectos externos idempotentes. Si llamas a un proveedor, usa
outbox_idcomo clave de idempotencia.
En acciones de colección, el cliente puede enviar idempotencyKey en el cuerpo de la petición. Sin esa clave, cada petición es una corrida nueva.
El cliente Python reintenta por su cuenta los errores de red, las respuestas 5xx y los códigos 408, 425 y 429, hasta cuatro intentos. Los demás errores lanzan SystemOfRecordsError con el código y el cuerpo de la respuesta. Un 409 significa que el registro cambió mientras escribías: deja que la actividad falle y Temporal la reintente.
Leer archivos subidos
Cada elemento de files trae lo necesario para leer el archivo:
{
"fileId": "0d3a4b1e-8a55-4c0b-b1d2-6f3e0a9c7d21",
"slotId": "returns-file",
"bucket": "example-bucket",
"key": "operational-apps/org_8f2c/prod/returns/files/returns-file/0d3a4b1e-8a55-4c0b-b1d2-6f3e0a9c7d21/devoluciones.csv",
"sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"fileName": "devoluciones.csv",
"contentType": "text/csv"
}
import hashlib
import boto3
source = envelope.files_for_slot("returns-file")[0]
body = boto3.client("s3").get_object(Bucket=source.bucket, Key=source.key)["Body"].read()
if hashlib.sha256(body).hexdigest() != source.sha256:
raise ValueError("El archivo no coincide con la suma registrada")
Solo llegan a un flujo archivos confirmados, es decir, aquellos cuyo tamaño y suma SHA-256 Quantum ya verificó. sha256 viene en hexadecimal.
Cómo se ve una corrida
- En la app: al ejecutar la acción o subir el archivo, la pantalla muestra que el flujo está en curso. El aviso de una acción sobre un registro desaparece cuando el registro vuelve a cambiar, que es como llega el resultado.
- En Ejecuciones: la corrida aparece con el nombre de la automatización del flujo y el usuario que la disparó. El identificador de la ejecución es el
outboxId. - En el historial del registro: cada escritura del flujo queda registrada con los campos que cambió y, en las transiciones, el
reasonque enviaste. - Por API: puedes consultar el estado de un arranque con su
outboxId.
curl "$QAC_API/operational-apps/returns/flows/3b1f0c9e-52a7-4d1e-9c55-0a6d7e21f4b8" \
-H "Authorization: Bearer $QAC_TOKEN"
{
"outboxId": "3b1f0c9e-52a7-4d1e-9c55-0a6d7e21f4b8",
"flowId": "issue-refund",
"status": "completed",
"startedAt": "2026-11-17T15:04:05.120Z",
"completedAt": "2026-11-17T15:04:19.871Z",
"executionId": "3b1f0c9e-52a7-4d1e-9c55-0a6d7e21f4b8",
"environment": "prod"
}
status recorre pending (en cola), dispatched (workflow iniciado), y completed o failed (resultado reportado, o arranque imposible). Con failed llega error. Al leer un registro con GET /operational-records/{recordId}, el campo lastFlow trae esta misma información para el último flujo iniciado sobre ese registro.
Si el flujo no llega a iniciarse después de los reintentos, la corrida queda marcada como fallida en Ejecuciones.