API de Integração de Tarefas
Conecte seu sistema com a Reten para consultar atividades do tipo tarefa, enviar resultados e receber atividades.
A API de integração de tarefas da Reten permite que os desenvolvedores do tenant consultem atividades do tipo tarefa atribuídas, enviem resultados e recebam atividades em tempo real. Esta seção cobre exclusivamente a integração para atividades do tipo TASK. Existem dois modos de integração de acordo com a direção do fluxo de dados.
Esta documentação é destinada a desenvolvedores do tenant que integram seus sistemas com a Reten usando um provedor disponível na plataforma (por exemplo, YOM). Se você precisa incorporar um novo provedor à plataforma, entre em contato com o time da Reten.
Modos de integração
| Modo | Direção | Descrição | Caso de uso |
|---|---|---|---|
| Pull | Seu sistema → Reten | Seu sistema consulta atividades e envia resultados via API REST | Integração assíncrona, processamento em lote, sistemas que preferem controlar o ritmo de consulta |
| Push (Dispatch) | Reten → Provedor | A Reten envia as atividades ao endpoint do provedor em tempo real | Integração em tempo real, sistemas que precisam receber atividades imediatamente ao serem criadas |
Autenticação rápida
As integrações se autenticam com uma chave de API, enviada no header x-api-key:
x-api-key: YOUR_API_KEYA chave de API autentica sua integração, define as permissões disponíveis e resolve automaticamente o tenant associado. Não é necessário enviar o header x-tenant-id. Listar tarefas e enviar resultados são endpoints project-optional: uma chave de projeto sempre trabalha no seu próprio projeto, enquanto uma chave de tenant abrange todos os projetos do tenant e envia x-project-id apenas para restringir uma requisição a um projeto ou para enviar um resultado sem activity_id — veja Escopo da chave.
Os endpoints de integração também aceitam um token de usuário (JWT), mas a chave de API é o método pensado para integrações. Veja Autenticação para mais detalhes.
Ambientes
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.
Primeiros passos
Quickstart: Integração Pull
Configure sua primeira integração em 4 passos com exemplos prontos para executar.
Receber Atividades (Dispatch)
Aprenda como a Reten despacha atividades para o endpoint do provedor configurado.
Autenticação
Detalhes sobre headers exigidos, permissões e chaves de API.
Tratamento de Erros
Formato de erros, códigos de status e soluções.
Endpoints disponíveis
| Método | Caminho | Descrição |
|---|---|---|
GET | /api/integration/activities/tasks | Listar atividades do tipo tarefa visíveis para sua chave de API |
POST | /api/integration/activity-results/tasks | Enviar o resultado de uma atividade do tipo tarefa |
GET | /api/integration/task-result-type-configs | Listar configurações de tipos de resultado disponíveis |
POST | /api/integration/commerces/batch-upsert | Criar ou atualizar até 500 comércios em uma única requisição — veja Upsert por Lote |
POST | /api/integration/operators/batch-upsert | Criar ou atualizar até 500 operadores em uma única requisição — veja Upsert por Lote |
POST | /api/integration/routes/batch-upsert | Criar ou atualizar até 500 rotas em uma única requisição — veja Upsert por Lote |