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 flowId y 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 completa automationId por 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.kind es action o file. Con file llegan slotId, fileIds y, si la ranura es de registro, recordId.
  • input son los datos que el usuario envió en la acción, ya validados contra el input declarado.
  • actor es la persona que disparó el flujo.
  • settings es la configuración de la app en ese entorno, leída en el momento del arranque.
  • record es el registro completo tal como está al arrancar el flujo (ya con el cambio de la acción aplicado), o null si el disparador no tiene registro.
  • files describe los archivos del disparador: el archivo subido, o los fileIds que se enviaron con una acción de colección. Una acción sobre un registro no trae los archivos de ese registro.
  • outboxId identifica 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 es unchanged.
  • mode="create" nunca toca un registro que ya existe. Úsalo cuando las personas pueden haber actuado sobre él.
  • state es 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 rejected con 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 key son obligatorios.
  • Una fila con la misma clave reemplaza a la anterior.
  • Con replace=True el 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 recordId determinista con record_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_id como 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 reason que 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.