Receber Atividades (Dispatch)
Como a Reten despacha atividades para o endpoint do provedor configurado em tempo real.
O modo Push (Dispatch) permite que a Reten envie atividades diretamente para o endpoint do provedor configurado em tempo real, sem exigir que seu sistema consulte a API periodicamente.
O despacho exige que o tenant tenha pelo menos um provedor configurado na plataforma. Os provedores disponíveis são registrados pelo time da Reten. Se você precisa incorporar um novo provedor, entre em contato com a Reten.
Conceito
Quando um administrador do tenant configura o despacho para um provedor e canal específicos, a Reten envia automaticamente as novas atividades para o endpoint registrado do provedor. O fluxo é:
- Uma atividade é criada na Reten (manualmente pelo app da Reten ou pelo Growth Engine da Reten)
- A Reten avalia as configurações de despacho ativas para o tenant e o canal
- A Reten monta o payload com os dados da atividade
- A Reten envia o payload ao endpoint do provedor via HTTP POST
- O provedor processa a atividade e pode enviar resultados de volta à Reten via
POST /api/integration/activity-results/tasks
Configuração
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.
O despacho é configurado a partir do painel de administração do tenant:
- Navegue até Atividades → Configuração de Dispatch
- Clique em Criar configuração
- Selecione o provedor e o canal
- Informe a URL do endpoint do provedor
- Configure as credenciais de autenticação do provedor
- Ative a configuração
A configuração do despacho é de responsabilidade do administrador do tenant. Você vai precisar da URL do endpoint do provedor e das credenciais de autenticação que ele exigir.
Payload da atividade
Quando a Reten envia uma atividade ao endpoint do provedor, o corpo da requisição HTTP POST contém um objeto com a seguinte estrutura.
Esta é a estrutura padrão do payload. Se o provedor exigir um formato diferente, o administrador do tenant pode configurar um mapeamento de payload para transformar os campos antes do envio — o provedor não precisa adaptar sua interface a este formato.
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"activityOrigin": "ACTIVITY",
"projectId": "3f6c2b1a-8d4e-4f7a-9b2c-5e1d0a7f6c34",
"type": "TASK",
"status": "READY",
"score": 85,
"channel": "SALESMAN",
"scheduledAt": "2026-04-15T09:00:00.000Z",
"occurredAt": null,
"createdAt": "2026-04-15T08:30:00.000Z",
"lifecycleStatus": "READY",
"lifecycleStatusLabel": "Lista",
"lifecycleStatusDetail": null,
"canForceRetryDispatch": false,
"commerceExternalId": "COM-001",
"commerceName": "Farmacia Central",
"reason": {
"code": "CHURN_RISK",
"label": "Riesgo de fuga"
},
"userStatus": null,
"commerceAssignment": {
"commerceExternalId": "COM-001",
"assignmentReason": "Asignación por ruta",
"commerce": {
"externalId": "COM-001",
"name": "Farmacia Central"
}
},
"activityDetails": {
"type": "TASK",
"assignedRouteCode": "RUTA-NORTE-01",
"assignedOperatorExternalId": "OP-042",
"assignedRoute": {
"code": "RUTA-NORTE-01",
"name": "Ruta Norte"
},
"assignedOperator": {
"externalId": "OP-042",
"name": "Carlos Pérez",
"type": "SALESMAN"
}
},
"activityResult": null
}No momento do despacho, status é READY na primeira tentativa e em uma retentativa forçada, e RETRYING nas retentativas automáticas (veja Comportamento de retentativas). O exemplo mostra uma primeira tentativa.
A estrutura do payload é idêntica à resposta do endpoint Listar Atividades — veja essa referência para a descrição detalhada de cada campo.
Campos-chave do payload
| Campo | Uso recomendado |
|---|---|
id | Armazenar como referência para enviar resultados via activity_id |
commerceExternalId | Identificar o comércio no sistema do provedor |
commerceName | Exibir ao operador |
activityDetails.assignedOperatorExternalId | Atribuir ao operador correspondente no sistema do provedor |
activityDetails.assignedRoute | Contexto de rota para planejamento |
scheduledAt | Data agendada para a atividade |
score | Pontuação de prioridade — útil para roteamento ou ranking no sistema do provedor |
reason | Contexto sobre por que a atividade foi criada |
Comportamento de retentativas
Se o endpoint do provedor não responder com um código 2xx, a Reten tenta reenviar automaticamente:
| Status do despacho | Descrição | Ação |
|---|---|---|
| Atividade está completamente resolvida e pronta para ser acionada. Se o cliente tiver um provedor configurado para fazer o despacho das atividades, a próxima ação do sistema tenta despachá-la; caso contrário, a atividade permanece READY e poderá ser acionada na plataforma interna por algum operador. | Atividade pronta para despacho | Envio pendente |
| Atividade foi entregue ao provedor externo. Aplica-se apenas quando o cliente tem um provedor de despacho configurado para a atividade; clientes que operam exclusivamente na plataforma interna da Reten não passam por este status. Ter provedor de despacho não impede que o resultado seja registrado na plataforma interna: o outcome pode chegar tanto do provedor externo quanto da plataforma interna. | Enviada com sucesso (resposta 2xx) | Completo |
| Falhou ao menos uma tentativa de despacho; o sistema tentará novamente de forma automática. Cada nova tentativa mantém a atividade neste status. Passa a DISPATCHED quando uma tentativa tem sucesso, ou a FAILED quando as tentativas disponíveis se esgotam. | Falha temporária — reenviando | A Reten reenvia automaticamente |
| Atividade alcançou um status terminal de falha por uma de duas vias: (a) as tentativas de despacho se esgotaram sem sucesso; ou (b) um processo de fechamento de fim de dia detectou uma atividade que ficou tentando novamente e a marcou como FAILED com resultado NOT_EXECUTED. Embora seja terminal, uma atividade FAILED pode ser recuperada manualmente por um endpoint dedicado, que a tenta novamente uma vez; a tentativa pode terminar em DISPATCHED, RETRYING ou novamente FAILED. | Todas as retentativas esgotadas | Requer intervenção manual (force-retry-dispatch) |
O endpoint do provedor deve responder com um código HTTP 2xx (ex.: 200 OK) para confirmar o recebimento. Qualquer outro código é considerado uma falha e dispara o processo de retentativas.
Mapeamento de payload
O administrador do tenant pode configurar um mapeamento de payload que transforma a estrutura do objeto antes de enviá-lo ao endpoint do provedor. Isso permite adaptar os nomes de campos e a estrutura ao que o sistema do provedor espera, sem exigir mudanças adicionais.
O mapeamento é configurado durante a criação ou edição da configuração de despacho a partir do painel de administração.
Próximo passo
Depois que o provedor recebe as atividades via despacho, seu sistema pode enviar resultados de volta à Reten via POST /api/integration/activity-results/tasks. Use o campo id do payload recebido como activity_id ao enviar o resultado.
Envie esses resultados com uma chave de tenant. O despacho envia as atividades de todos os projetos do tenant, e uma chave de projeto só alcança o seu próprio projeto: com ela, o resultado de uma atividade de outro projeto responde 404 — Actividad no encontrada. Veja Escopo da chave.