Autenticação

Headers exigidos, permissões e métodos de autenticação para a API de integração.

Todos os endpoints de integração exigem autenticação. Use uma chave de API: é o método pensado para integrações, e os exemplos desta seção a usam. Os endpoints também aceitam um token de usuário (JWT) — veja Token de usuário vs chave de API.

Header exigido

Cada requisição autenticada com uma chave de API inclui o seguinte header:

Header	Valor	Descrição
`x-api-key`	`rtn_sk_...`	Chave de API gerada a partir do painel de administração

curl -X GET BASE_URL/api/integration/activities/tasks \
  -H "x-api-key: YOUR_API_KEY"

Nenhuma chave de API envia o header x-tenant-id: o tenant sempre vem da chave. Se a chave envia x-project-id depende do seu escopo — uma chave de projeto não precisa dele, uma chave de tenant o envia onde o endpoint o exige ou para restringir uma requisição a um projeto. Veja Escopo da chave.

A chave de API é exibida apenas uma vez no momento da criação. Se você perdê-la, será necessário revogá-la e criar uma nova a partir do painel de administração.

Obtendo uma chave de API

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.

As chaves de API são criadas a partir do painel de administração da Reten por um usuário com função admin ou superior:

Navegue até Configurações → Chaves de API
Clique em Criar chave de API
Atribua um nome descritivo (ex.: "Despacho de Tarefas — YOM")
Selecione as permissões necessárias de acordo com os endpoints que você usará
Copie a chave gerada e armazene-a com segurança

Permissões por endpoint

Cada endpoint de integração exige uma permissão específica na chave de API:

Endpoint	Método	Permissão exigida
`/api/integration/activities/tasks`	`GET`	`activity:view`
`/api/integration/activity-results/tasks`	`POST`	`activity-result:submit`
`/api/integration/task-result-type-configs`	`GET`	`activity:view`
`/api/integration/commerces/batch-upsert`	`POST`	`commerce:batch-upsert`
`/api/integration/operators/batch-upsert`	`POST`	`operator:batch-upsert`
`/api/integration/routes/batch-upsert`	`POST`	`route:batch-upsert`

As permissões de uma chave de API são escolhidas pelo seu dono e devem ser um subconjunto das permissões que o dono possui atualmente. Em cada requisição, as permissões efetivas da chave são a interseção do seu conjunto armazenado com as permissões vigentes do dono — se o dono perder uma permissão, a chave também a perde; se o dono ganhar uma, a chave não a ganha. Se você precisar de uma permissão adicional, o dono da chave a adiciona editando as permissões da chave com PUT /api/api-keys/:id/permissions ou em Configurações → Chaves de API.

Escopo da chave

Cada chave de API pertence a um único tenant, e o tenant sempre vem da chave — nenhuma chave envia x-tenant-id. O escopo da chave, escolhido ao criá-la (veja Criar Chave de API), define como o projeto é escolhido nos endpoints project-scoped e project-optional.

Os endpoints project-scoped trabalham em exatamente um projeto por requisição. Os endpoints project-optional aceitam x-project-id, mas não o exigem: se for enviado, restringe a requisição a esse projeto e é validado como em um endpoint project-scoped. Sem ele, uma leitura abrange todo o tenant e um resultado assume o projeto da sua atividade; um resultado sem activity_id não tem atividade da qual assumir o projeto, então precisa do header — sem ele a API responde 400. Uma chave de projeto sempre trabalha no seu próprio projeto.

	Chave de projeto (`scope: "project"`)	Chave de tenant (`scope: "tenant"`)
Projeto de cada requisição	Sempre o projeto da chave	O indicado em `x-project-id`; em um endpoint project-optional sem o header, nenhum
`x-project-id` em endpoints project-scoped	Não é necessário. Enviar o próprio projeto da chave é aceito; indicar outro projeto responde `403` — `La API key pertenece a un proyecto distinto del que declara el header x-project-id.`	Obrigatório. Sem ele a API responde `400` — `Falta el header obligatorio x-project-id.`
`x-project-id` em endpoints project-optional	Não é necessário, como nos endpoints project-scoped: indicar outro projeto responde `403`. Um resultado sem `activity_id` vai para o projeto da chave; um resultado de uma atividade de outro projeto responde `404` — `Actividad no encontrada.`	Opcional. Com ele, a requisição é restrita a esse projeto. Sem ele, uma leitura abrange todo o tenant e um resultado assume o projeto da sua atividade; um resultado sem `activity_id` responde `400` — `Falta el header obligatorio x-project-id: un resultado sin activity_id necesita proyecto.`
`x-project-id` em endpoints tenant-level	Ignorado	Ignorado

Os endpoints de integração se dividem assim:

Endpoint	Método	Tipo
`/api/integration/activities/tasks`	`GET`	Project-optional
`/api/integration/activity-results/tasks`	`POST`	Project-optional
`/api/integration/task-result-type-configs`	`GET`	Tenant-level
`/api/integration/commerces/batch-upsert`, `/api/integration/operators/batch-upsert`, `/api/integration/routes/batch-upsert`	`POST`	Tenant-level

Os exemplos da API de integração enviam apenas x-api-key, por isso funcionam como estão com uma chave de projeto e com uma chave de tenant. Com uma chave de tenant, adicione o header x-project-id para restringir uma chamada a um projeto e, sempre, para enviar um resultado sem activity_id.

As chaves de API criadas antes da existência dos projetos são chaves de tenant (projectId: null) e seguem a coluna da chave de tenant acima: enviam x-project-id nos endpoints project-scoped e para enviar um resultado sem activity_id.

Se o seu sistema recebe atividades por despacho, use uma chave de tenant para enviar os resultados delas. 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.

Se x-api-key for inválida ou estiver revogada → resposta 401 Unauthorized
Se a chave não tiver a permissão exigida → resposta 403 Forbidden
Os dados retornados sempre correspondem ao tenant da chave e, quando a requisição tem um projeto ativo (o da chave ou o de x-project-id), a esse projeto

Token de usuário vs chave de API

Característica	JWT (Token de usuário)	API Key (Chave de API)
Uso principal	Sessões interativas no app	Integrações programáticas
Duração	15 minutos (access token)	Sem expiração (ou data configurável)
Renovação	Automática via refresh token	Não aplicável — a chave é permanente
Permissões	Todas as permissões da função do usuário	Conjunto escolhido pelo dono, editável a qualquer momento; efetivas = interseção com as permissões vigentes do dono em cada requisição
Header `x-tenant-id`	Exigido	Não necessário (tenant resolvido a partir da chave)
Header `x-project-id`	Exigido em endpoints project-scoped; opcional em endpoints project-optional (veja Escopo da chave)	Chave de projeto: não necessário. Chave de tenant: igual a um token de usuário
Endpoints de integração	Aceito	Recomendado

Os endpoints em /api/integration/* aceitam os dois métodos; use uma chave de API para as integrações. Com um token de usuário, cada requisição envia Authorization: Bearer <access_token> e x-tenant-id; x-project-id segue as mesmas regras que com uma chave de tenant — veja Contexto de Projeto.