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 activity-result:submit

Headers requeridos

x-project-id es opcional: este es un endpoint project-optional.

• Con una clave de tenant o un token de usuario, enviar el header acota la solicitud a ese proyecto, así que activity_id debe pertenecer a él. Sin el header, el resultado toma el proyecto de su actividad. Un header enviado se valida — ver Errores de proyecto.
• Un resultado sin activity_id no tiene actividad de la que tomar el proyecto: con una clave de proyecto toma el proyecto de la clave; con una clave de tenant o un token de usuario necesita el header, y sin él la API responde 400.
• Una clave de proyecto siempre trabaja en su propio proyecto: un activity_id de otro proyecto responde 404.

Cuerpo de la solicitud

Campos de task_result

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 activo (consulta Listar Configuraciones); en caso contrario la solicitud retorna 422 — El tipo de resultado seleccionado no está activo.
• Si el tipo de resultado tiene requiresFutureScheduledAt: true, el campo future_scheduled_at es obligatorio (si falta, 422 — Este tipo de resultado requiere una fecha comprometida.) y debe caer hoy o después en la zona horaria del tenant (si no, 422 — La fecha programada no puede ser en el pasado.)
• 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 que admita resultado (READY, DISPATCHED, RETRYING o COMPLETED — en COMPLETED, el envío sobrescribe el resultado existente); en caso contrario la solicitud retorna 422 — La actividad no está en un estado válido para registrar resultado.
• 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 — La actividad corresponde a un día ya cerrado y no admite registrar resultado. Las ejecuciones independientes (STANDALONE, sin activity_id) están exentas de esta regla

Errores