Quickstart: Integración Pull

Esta guía te lleva paso a paso desde obtener tu clave de API hasta enviar tu primer resultado de gestión. Al final tendrás una integración funcional con la API de Reten.

Ambientes de Reten

Ambiente	Panel de Admin	API Base URL
Development	app-development.reten.ai	`https://api-development.reten.ai`
Staging	app-staging.reten.ai	`https://api-staging.reten.ai`
Production	app.reten.ai	`https://api.reten.ai`

Usa la URL del panel de admin para gestionar claves de API y configuraciones de dispatch. Reemplaza BASE_URL en los ejemplos de código con la API Base URL de tu ambiente.

Paso 1: Obtén una clave de API

Solicita a un administrador del tenant que cree una clave de API con los siguientes permisos:

VIEW_ACTIVITIES — para consultar actividades y configuraciones
SUBMIT_ACTIVITY_RESULT — para enviar resultados de gestiones

Una vez creada, recibirás:

Clave de API: rtn_sk_... (se muestra una sola vez)

Guarda la clave de API de forma segura. No se puede recuperar después de la creación. Si la pierdes, deberás revocarla y crear una nueva.

Paso 2: Verifica tu clave

Realiza una solicitud de prueba para confirmar que tu clave funciona correctamente:

curl -X GET BASE_URL/api/integration/task-result-type-configs \
  -H "x-api-key: YOUR_API_KEY"

const BASE_URL = "https://api.reten.ai";
const API_KEY = "YOUR_API_KEY";

const response = await fetch(
  `${BASE_URL}/api/integration/task-result-type-configs`,
  {
    headers: {
      "x-api-key": API_KEY,
    },
  }
);

if (!response.ok) {
  console.error(`Error ${response.status}: ${await response.text()}`);
  process.exit(1);
}

const configs = await response.json();
console.log("Tipos de resultado disponibles:", configs);

import requests

BASE_URL = "https://api.reten.ai"
API_KEY = "YOUR_API_KEY"

response = requests.get(
    f"{BASE_URL}/api/integration/task-result-type-configs",
    headers={
        "x-api-key": API_KEY,
    },
)

if response.status_code != 200:
    print(f"Error {response.status_code}: {response.text}")
    exit(1)

configs = response.json()
print("Tipos de resultado disponibles:", configs)

Si recibes un 200 OK con una lista de configuraciones, tu clave está funcionando. Si recibes 401, verifica que el header x-api-key sea correcto. Si recibes 403, la clave no tiene los permisos necesarios — solicita al administrador del tenant que los agregue.

Paso 3: Lista tus actividades

Consulta las actividades de tipo tarea pendientes de gestión:

curl -X GET "BASE_URL/api/integration/activities/tasks?status=PENDING&per_page=5" \
  -H "x-api-key: YOUR_API_KEY"

const params = new URLSearchParams({
  status: "PENDING",
  per_page: "5",
});

const response = await fetch(
  `${BASE_URL}/api/integration/activities/tasks?${params}`,
  {
    headers: {
      "x-api-key": API_KEY,
    },
  }
);

const { data, meta } = await response.json();
console.log(`${meta.total} actividades encontradas`);

for (const activity of data) {
  console.log(`- ${activity.id}: ${activity.commerceName} (${activity.status})`);
}

response = requests.get(
    f"{BASE_URL}/api/integration/activities/tasks",
    headers={
        "x-api-key": API_KEY,
    },
    params={
        "status": "PENDING",
        "per_page": 5,
    },
)

result = response.json()
print(f"{result['meta']['total']} actividades encontradas")

for activity in result["data"]:
    print(f"- {activity['id']}: {activity['commerceName']} ({activity['status']})")

La respuesta incluye las actividades paginadas con sus detalles: comercio asignado, operador, fecha programada, y estado actual. Consulta la referencia completa para ver todos los campos disponibles.

Paso 4: Envía un resultado

Después de gestionar una actividad, envía el resultado a Reten. Usa el id de la actividad del paso anterior y un código de resultado válido del paso 2:

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": "ACTIVITY_ID",
    "commerce_external_id": "COMMERCE_EXTERNAL_ID",
    "occurred_at": "2026-04-11T10:30:00.000Z",
    "status": "EFFECTIVE",
    "task_result": {
      "result": "SALE_COMPLETED",
      "comment": "Cliente aceptó oferta de renovación",
      "operator_external_id": "OPERATOR_EXTERNAL_ID"
    }
  }'

const activityId = "ACTIVITY_ID"; // Del paso 3
const commerceExternalId = "COMMERCE_EXTERNAL_ID"; // Del paso 3

const response = await fetch(
  `${BASE_URL}/api/integration/activity-results/tasks`,
  {
    method: "POST",
    headers: {
      "x-api-key": API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      activity_id: activityId,
      commerce_external_id: commerceExternalId,
      occurred_at: new Date().toISOString(),
      status: "EFFECTIVE",
      task_result: {
        result: "SALE_COMPLETED",
        comment: "Cliente aceptó oferta de renovación",
        operator_external_id: "OPERATOR_EXTERNAL_ID",
      },
    }),
  }
);

if (response.status === 201) {
  const result = await response.json();
  console.log("Resultado registrado:", result.id);
}

from datetime import datetime, timezone

activity_id = "ACTIVITY_ID"  # Del paso 3
commerce_external_id = "COMMERCE_EXTERNAL_ID"  # Del paso 3

response = requests.post(
    f"{BASE_URL}/api/integration/activity-results/tasks",
    headers={
        "x-api-key": API_KEY,
    },
    json={
        "activity_id": activity_id,
        "commerce_external_id": commerce_external_id,
        "occurred_at": datetime.now(timezone.utc).isoformat(),
        "status": "EFFECTIVE",
        "task_result": {
            "result": "SALE_COMPLETED",
            "comment": "Cliente aceptó oferta de renovación",
            "operator_external_id": "OPERATOR_EXTERNAL_ID",
        },
    },
)

if response.status_code == 201:
    result = response.json()
    print(f"Resultado registrado: {result['id']}")

Una respuesta 201 Created confirma que el resultado fue registrado exitosamente.

Siguientes pasos

Consulta la referencia de endpoints para ver todos los parámetros y campos disponibles
Revisa el manejo de errores para implementar reintentos y diagnósticos
Si necesitas recibir actividades en tiempo real, consulta Recibir Gestiones (Dispatch)