Enviar Resultado

POST /api/integration/activity-results/tasks

Envía el resultado de una gestión de tipo tarea. El resultado se asocia a la actividad correspondiente y actualiza su estado en Reten.

La operación es un UPSERT idempotente: si la actividad aún no tiene resultado, se crea; si ya lo tiene, se sobrescriben sus detalles con el último envío (last-write-wins). Puedes re-enviar el resultado sin obtener un conflicto.

Autenticación: Requerida — permiso SUBMIT_ACTIVITY_RESULT

Headers requeridos

Header	Valor
`x-api-key`	`YOUR_API_KEY`
`Content-Type`	`application/json`

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`activity_id`	string (UUID)	No	ID de la actividad en Reten. Si se omite, el resultado se registra como ejecución independiente (STANDALONE)
`provider_activity_id`	string	No	ID de la actividad en tu sistema. Solo para correlación/tracking — no identifica ni resuelve la actividad en Reten
`commerce_external_id`	string	Condicional	ID externo del comercio. Requerido solo para ejecuciones independientes (sin `activity_id`); con actividad vinculada se deriva de ella
`occurred_at`	string (ISO 8601)	Sí	Fecha y hora en que se realizó la gestión
`task_result`	object	Sí	Detalle del resultado de la tarea (ver tabla abajo)

La actividad se resuelve únicamente por activity_id. Si se envía, el resultado se vincula a esa actividad; si se omite, se registra como ejecución independiente (STANDALONE). provider_activity_id es solo para correlación/tracking con tu sistema y no resuelve la actividad.

commerce_external_id es opcional cuando la gestión está vinculada a una actividad (activity_id): el comercio se deriva de la actividad. Solo es obligatorio en ejecuciones independientes (STANDALONE) — cuando no se envía activity_id — y en ese caso, si el comercio no existe, se crea como placeholder.

Campos de `task_result`

Campo	Tipo	Requerido	Descripción
`result`	string	Sí	Código del tipo de resultado (obtenido de Listar Configuraciones)
`comment`	string	No	Comentario del operador sobre la gestión
`operator_external_id`	string	No	ID externo del operador que realizó la gestión
`future_scheduled_at`	string (ISO 8601)	Condicional	Fecha de reprogramación. Requerido si el tipo de resultado tiene `requiresFutureScheduledAt: true`
`payload`	object	No	Datos adicionales del resultado

Ejemplo

curl -X POST BASE_URL/api/integration/activity-results/tasks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "activity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "commerce_external_id": "COM-001",
    "occurred_at": "2026-04-11T10:30:00.000Z",
    "task_result": {
      "result": "SALE_COMPLETED",
      "comment": "Cliente aceptó oferta de renovación",
      "operator_external_id": "OP-042"
    }
  }'

const response = await fetch(
  `${BASE_URL}/api/integration/activity-results/tasks`,
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      activity_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      commerce_external_id: "COM-001",
      occurred_at: "2026-04-11T10:30:00.000Z",
      task_result: {
        result: "SALE_COMPLETED",
        comment: "Cliente aceptó oferta de renovación",
        operator_external_id: "OP-042",
      },
    }),
  }
);

const data = await response.json();

import requests

response = requests.post(
    f"{BASE_URL}/api/integration/activity-results/tasks",
    headers={
        "x-api-key": "YOUR_API_KEY",
    },
    json={
        "activity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "commerce_external_id": "COM-001",
        "occurred_at": "2026-04-11T10:30:00.000Z",
        "task_result": {
            "result": "SALE_COMPLETED",
            "comment": "Cliente aceptó oferta de renovación",
            "operator_external_id": "OP-042",
        },
    },
)

data = response.json()

Respuesta `201 Created`

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "source": "RETEN_ACTIVITY",
  "origin": "EXTERNAL",
  "activityId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "providerActivityId": null,
  "commerceExternalId": "COM-001",
  "resultStatus": "COMPLETED",
  "occurredAt": "2026-04-11T10:30:00.000Z",
  "createdAt": "2026-04-11T10:30:05.000Z",
  "updatedAt": "2026-04-11T10:30:05.000Z",
  "result": {
    "code": "SALE_COMPLETED",
    "label": "Venta completada"
  },
  "comment": "Cliente aceptó oferta de renovación",
  "operatorExternalId": "OP-042",
  "futureScheduledAt": null
}

Reglas de validación

El commerce_external_id solo es obligatorio en ejecuciones independientes (sin activity_id); en ese caso, si el comercio no existe se crea como placeholder. Con una actividad vinculada el comercio se deriva de ella y este campo es opcional.
El operator_external_id es opcional, si se envía y el operador no existe se crea como placeholder.
El código de result debe ser un tipo de resultado válido (consulta Listar Configuraciones)
Si el tipo de resultado tiene requiresFutureScheduledAt: true, el campo future_scheduled_at es obligatorio y debe ser una fecha futura
Si la actividad ya tiene un resultado, el envío lo sobrescribe (UPSERT idempotente); no se retorna conflicto
La actividad vinculada debe estar en un estado accionable (READY o DISPATCHED); en caso contrario la solicitud retorna 422
No se acepta registrar un resultado para una actividad cuya fecha de ejecución ya cruzó el cierre de fin de día, en ese caso la solicitud retorna 422. Las ejecuciones independientes (STANDALONE, sin activity_id) están exentas de esta regla

Errores

Status	Descripción
`400`	Error de validación — campos faltantes, tipo de resultado inválido, o `future_scheduled_at` requerido
`401`	Clave de API faltante o inválida
`403`	La clave no tiene el permiso `SUBMIT_ACTIVITY_RESULT`
`404`	Actividad o comercio no encontrado en el tenant
`422`	Actividad en estado no accionable, o su fecha de ejecución ya cruzó el cierre de fin de día