Quickstart: Integração Pull

Este guia leva você passo a passo desde obter sua chave de API até enviar seu primeiro resultado de atividade. Ao final você terá uma integração funcional com a API da Reten.

Ambientes da Reten

Ambiente	Painel 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`

Use a URL do painel de admin para gerenciar chaves de API e configurações de dispatch. Substitua BASE_URL nos exemplos de código pela API Base URL do seu ambiente.

Passo 1: Obtenha uma chave de API

Solicite a um administrador do tenant que crie uma chave de API com as seguintes permissões:

activity:view — para consultar atividades e configurações
activity-result:submit — para enviar resultados de atividades

Após a criação, você receberá:

Chave de API: rtn_sk_... (exibida apenas uma vez)

Armazene a chave de API com segurança. Ela não pode ser recuperada após a criação. Se você perdê-la, será necessário revogá-la e criar uma nova.

Passo 2: Verifique sua chave

Faça uma requisição de teste para confirmar que sua chave funciona corretamente:

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 disponíveis:", 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 disponíveis:", configs)

Se você receber um 200 OK com uma lista de configurações, sua chave está funcionando. Se receber 401, verifique se o header x-api-key está correto. Se receber 403, a chave não tem as permissões necessárias — o dono da chave as adiciona editando as permissões dela com PUT /api/api-keys/:id/permissions ou em Configurações → Chaves de API.

Passo 3: Liste suas atividades

Consulte as atividades do tipo tarefa pendentes:

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

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

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

const { data, pagination } = await response.json();
console.log(`${pagination.total} atividades 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": "READY",
        "per_page": 5,
    },
)

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

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

A resposta inclui as atividades paginadas com seus detalhes: comércio atribuído, operador, data agendada e status atual. Veja a referência completa para todos os campos disponíveis.

Passo 4: Envie um resultado

Depois de tratar uma atividade, envie o resultado para a Reten. Use o id da atividade do passo anterior e um código de resultado válido do passo 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",
    "task_result": {
      "result": "SALE_COMPLETED",
      "comment": "Customer accepted renewal offer",
      "operator_external_id": "OPERATOR_EXTERNAL_ID"
    }
  }'

const activityId = "ACTIVITY_ID"; // Do passo 3
const commerceExternalId = "COMMERCE_EXTERNAL_ID"; // Do passo 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(),
      task_result: {
        result: "SALE_COMPLETED",
        comment: "Customer accepted renewal offer",
        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"  # Do passo 3
commerce_external_id = "COMMERCE_EXTERNAL_ID"  # Do passo 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(),
        "task_result": {
            "result": "SALE_COMPLETED",
            "comment": "Customer accepted renewal offer",
            "operator_external_id": "OPERATOR_EXTERNAL_ID",
        },
    },
)

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

Uma resposta 201 Created confirma que o resultado foi registrado com sucesso.

Próximos passos

Consulte a referência de endpoints para todos os parâmetros e campos disponíveis
Revise o tratamento de erros para implementar retentativas e diagnósticos
Se você precisa receber atividades em tempo real, veja Receber Atividades (Dispatch)