Reten Docs

Estados de Actividad

Catálogo canónico de los estados operacionales, de display, y de resultado de una actividad en Reten — con sus transiciones válidas y reglas de proyección.

Una actividad expone dos estados: uno operativo, filtrable vía el query param (status), que refleja la situación real de la actividad en su ciclo de ejecución; y otro informativo (lifecycleStatus), calculado en cada respuesta, con valores más amigables pensados para mostrar en interfaces de usuario.

El resultado (resultStatus) de una actividad es un estado separado, reportado por el operador desde la plataforma de Reten o desde un proveedor externo. Una actividad COMPLETED indica únicamente que fue ejecutada, independiente de si el resultado de negocio fue positivo o negativo: por ejemplo, una visita a un cliente con el objetivo de cerrar una venta queda como COMPLETED aunque la venta no se concrete.

Esta página documenta los estados de una actividad: el operativo, el informativo y el de resultado.

status (operacional, filtrable)

Es el state machine real de la actividad. Las transiciones entre valores están restringidas por reglas duras del backend (ver diagrama más abajo). Es la única dimensión filtrable vía query param status en los endpoints de listado.

READY

Lista

Actividad está completamente resuelta y lista para accionar. Si el cliente tiene configurado un proveedor para hacer dispatch de las actividades, la próxima acción del sistema intenta despachar, de lo contrario la actividad permanece READY y podrá ser accionada desde la plataforma interna por algún operador.

filterable

Transiciones manuales

Desde: estado inicial
Hacia: RETRYING, DISPATCHED, CANCELED, FAILED, COMPLETED
RETRYING

Reintentando

Ha fallado al menos un intento de dispatch; el sistema reintentará automáticamente. Cada reintento mantiene la actividad en este estado. Pasa a DISPATCHED cuando un intento tiene éxito, o a FAILED cuando se agotan los reintentos disponibles.

filterable

Transiciones manuales

Desde: READY, RETRYING
Hacia: DISPATCHED, FAILED, RETRYING, CANCELED
DISPATCHED

Despachada

Actividad fue entregada al proveedor externo. Aplica únicamente cuando el cliente tiene un proveedor de dispatch configurado para la actividad; clientes que operan exclusivamente desde la plataforma interna de Reten no transitan por este estado. Tener proveedor de dispatch no impide que el resultado se registre desde la plataforma interna: el outcome puede llegar tanto desde el proveedor externo como desde la plataforma interna.

filterable
Desde: READY, RETRYING
Hacia: COMPLETED, FAILED
COMPLETED

Completada

Actividad alcanzó un estado terminal exitoso por uno de tres caminos: (a) el proveedor externo reportó un resultado; (b) un operador registró el resultado desde la plataforma interna de Reten; (c) un proceso de cierre de fin de día marcó como no ejecutadas los resultados de las actividades que quedaron sin outcome al cierre de la jornada. COMPLETED indica únicamente que la actividad fue finalizada, es decir, completo su ciclo independientemente de si tuvo un resultado registado por el operador o no; el outcome de negocio (positivo o negativo) se reporta por separado en el resultado de la actividad.

filterableterminal
Desde: READY, DISPATCHED
Hacia: terminal
CANCELED

Cancelada

Actividad fue cancelada explícitamente desde un estado no-terminal (READY o RETRYING) porque la razón de negocio que la motivó dejó de aplicar antes del envío (por ejemplo, el cliente ya hizo la acción objetivo por otro canal, decidió no recibirla, o el destinatario dejó de ser válido). La cancelación es terminal: no se produce resultado ni ocurre dispatch.

filterableterminal

Transiciones manuales

  • Cancelar actividad — cancelación directa de la actividad (camino canónico, usado tanto desde la plataforma interna de Reten como desde el sistema externo que creó la actividad)
Desde: READY, RETRYING
Hacia: terminal
FAILED

Fallida

Actividad alcanzó un estado terminal fallido por una de dos vías: (a) los intentos de dispatch se agotaron sin éxito; o (b) un proceso de cierre de fin de día detectó una actividad que quedó reintentando, y la marcó como FAILED con resultado NOT_EXECUTED. Aunque es terminal, una actividad FAILED puede recuperarse manualmente vía endpoint dedicado, que la reintenta una vez; el intento puede terminar en DISPATCHED, RETRYING o nuevamente FAILED.

filterableterminal

Transiciones manuales

  • Forzar reintento de despacho — reintenta el dispatch una vez; puede terminar en DISPATCHED, RETRYING o nuevamente FAILED(bypassea la state machine)
Desde: READY, RETRYING, DISPATCHED
Hacia: terminal

Subset filtrable (usable como query param status en endpoints de listado):

READY, RETRYING, DISPATCHED, COMPLETED, CANCELED, FAILED

lifecycleStatus (display, read-only)

Es un estado calculado en cada respuesta a partir del status y de información contextual de la actividad (fecha de ejecución, si tiene proveedor, si hay errores, si está en reintentos, entre otros). No es filtrable. Existe para mostrar un estado enriquecido en interfaces — tanto internas como las del proveedor — aunque el proveedor puede derivar su propio estado según sus reglas si lo prefiere.

CANCELED

Cancelada

Estado informativo que aparece cuando la actividad fue cancelada (`status` = CANCELED).

terminal
Proyectado desde: ActivityStatus.CANCELED (no condition)
Hacia: terminal
COMPLETED

Completada

Estado informativo que aparece cuando la actividad fue completada (`status` = COMPLETED).

terminal
Proyectado desde: ActivityStatus.COMPLETED (no condition)
Hacia: terminal
FAILED

Fallida

Estado informativo que aparece cuando la actividad falló definitivamente (`status` = FAILED).

terminal
Proyectado desde: ActivityStatus.FAILED (no condition)
Hacia: terminal
RETRYING_DISPATCH

Reintentando Dispatch

Estado informativo que aparece cuando la actividad está reintentando dispatch (`status` = RETRYING).

Proyectado desde: ActivityStatus.RETRYING (no condition)
Hacia: terminal
SCHEDULED

Programada

Estado informativo que aparece cuando la actividad está programada para un día futuro en el calendario del cliente. La comparación es a nivel de día completo (no de horario exacto): solo cuenta como programada desde mañana en adelante.

Proyectado desde: ActivityStatus.* (scheduledAt's local day > today in tenant timezone)
Hacia: terminal
READY

Lista

Estado informativo que aparece cuando la actividad está lista y el cliente no tiene un proveedor de dispatch configurado para ella.

Proyectado desde: ActivityStatus.READY (!hasDispatchProvider)
Hacia: terminal
PENDING_DISPATCH

Pendiente de Despacho

Estado informativo que aparece cuando la actividad está lista y el cliente tiene un proveedor de dispatch configurado para ella. El sistema aún no ha intentado el dispatch; lo intentará en su próxima pasada automática.

Proyectado desde: ActivityStatus.READY (hasDispatchProvider)
Hacia: terminal
DISPATCHED

Despachada

Estado informativo que aparece cuando la actividad fue despachada al proveedor externo (`status` = DISPATCHED).

Proyectado desde: ActivityStatus.DISPATCHED (no condition)
Hacia: terminal
UNKNOWN

Unknown

Valor de fallback cuando ningún otro estado informativo aplica. No debería ocurrir en operación normal; si aparece, indica un caso no contemplado. Para diagnosticar, consulta el `status` operativo de la actividad.

Proyectado desde: ActivityStatus.* (fallback — no rule matched)
Hacia: terminal

Estos valores NO son filtrables. Para filtrar listados, usá status con los valores de la sección anterior.

resultStatus (independiente)

Estado terminal reportado por el operador (desde la plataforma de Reten o desde un proveedor externo) una vez ejecutada — o descartada — la actividad. No deriva de status: una actividad COMPLETED puede tener cualquier resultado, y el resultado se trackea aparte para que el outcome de negocio no se confunda con la ejecución.

COMPLETED

Ejecutada

La actividad fue ejecutada por el operador — se realizó la acción asignada (visitar el comercio, contactar al cliente, etc.) según lo previsto. Se asigna SIEMPRE de forma interna al registrar un resultado (ambas audiencias: operador interno y externo); nunca lo escribe el caller. NO implica que el objetivo de negocio subyacente se haya cumplido: una visita comercial queda COMPLETED tanto si se concretó la venta como si no, mientras el operador haya ejecutado el intento. El outcome más específico (venta sí/no, respuesta del cliente, etc.) se captura en la entidad del detalle del resultado, no en el status.

filterableterminal
Desde: estado inicial
Hacia: terminal
NOT_EXECUTED

No Ejecutada

Resultado terminal que indica que la actividad fue cerrada sin haber sido ejecutada por el operador. Único productor: el job de auto-cierre de fin de día, que registra NOT_EXECUTED para actividades que cruzaron el corte de auto-cierre sin outcome. Ningún flujo interactivo lo produce. Una actividad que no pudo resolverse no queda como NOT_EXECUTED — esa falla es previa, no atribuible al operador.

filterableterminal
Desde: estado inicial
Hacia: terminal

Diagrama de transiciones

Diagrama del state machine operacional (no incluye lifecycleStatus, que es derivado, ni el resultado, que es ortogonal). Sólo se muestran las aristas válidas según el backend; cualquier transición no listada es rechazada.

  ┌─────────┐
  │  READY  │  (estado inicial)
  └────┬────┘
       │
       ├────────────► ┌──────────┐
       │              │ CANCELED │ (terminal)
       │              └──────────┘
       │
       │  ┌────────────────────────────────────────────┐
       │  │ desde READY:                               │
       │  │   → RETRYING, DISPATCHED, CANCELED,        │
       │  │     FAILED, COMPLETED                      │
       │  └────────────────────────────────────────────┘
       │
       ├─────────────► ┌───────────────┐
       │               │   RETRYING    │
       │               └───────┬───────┘
       │                       │
       │       desde RETRYING: │
       │         → DISPATCHED, │
       │           FAILED,     │
       │           RETRYING,   │
       │           CANCELED    │
       │                       │
       ├──────────────┐        │
       ▼              ▼        ▼
  ┌────────────┐   ┌────────────────┐
  │ DISPATCHED │──►│   COMPLETED    │ (terminal)
  └─────┬──────┘   └────────────────┘
        │
        └──► ┌──────────┐
             │  FAILED  │ (terminal)
             └──────────┘

Aristas literales del state machine:

  • READY → RETRYING, DISPATCHED, CANCELED, FAILED, COMPLETED (estado inicial de una actividad)
  • RETRYING → DISPATCHED, FAILED, RETRYING, CANCELED
  • DISPATCHED → COMPLETED, FAILED
  • COMPLETED, CANCELED, FAILED → terminal (sin salidas)

Las transiciones manuales (cancelaciones, force-retry-dispatch) están listadas por estado en la sección status — cada card de estado documenta sus transiciones manuales.

Roles y Permisos

Jerarquía de roles, permisos y cómo restringen los endpoints de la API.

API de Integración de Tareas

Conecta tu sistema con Reten para consultar actividades de tipo tarea, enviar resultados y recibir gestiones.