Primeiros Passos

Aprenda os conceitos básicos da API da Reten — URL base, headers comuns, paginação e tratamento de erros.

O que é a API da Reten?

A API da Reten é uma API REST para a plataforma SaaS multi-tenant Reten. Ela permite gerenciar atividades em campo atribuídas a comércios (negócios e lojas), acompanhar resultados e configurar provedores de despacho.

Capacidades principais:

Gerenciamento de Atividades — Criar, despachar e acompanhar tarefas para comércios
Rastreamento de Resultados — Enviar e consultar os resultados de execução de tarefas
Gerenciamento de Comércios e Operadores — Operações CRUD em comércios, operadores e rotas
Isolamento Multi-Tenant — Cada tenant opera em um ambiente totalmente isolado

URL Base

A API da Reten está disponível em múltiplos ambientes. Use a URL base apropriada de acordo com sua etapa de integração:

Ambiente	URL Base
Produção	`https://api.reten.ai/api`
Staging	`https://api-staging.reten.ai/api`
Desenvolvimento	`https://api-development.reten.ai/api`
Local	`http://localhost:3000/api`

Todos os exemplos de código nesta documentação usam a URL de produção. Substitua https://api.reten.ai/api pela URL do ambiente correspondente ao trabalhar em staging ou desenvolvimento.

Headers Comuns

Header	Obrigatório	Descrição
`Authorization`	Sim (auth JWT)	`Bearer <access_token>`
`x-api-key`	Sim (auth API Key)	`rtn_sk_<key>` — alternativa ao Bearer token
`x-tenant-id`	Sim (auth JWT, rotas com escopo de tenant)	UUID do tenant ativo. Não necessário com auth por API Key
`x-project-id`	Sim (rotas project-scoped); opcional (rotas project-optional)	UUID do projeto ativo. Não necessário com uma chave de projeto — veja Autenticação → Contexto de Projeto
`Content-Type`	Sim (para corpos de requisição)	`application/json`

Paginação

Os endpoints de listagem suportam paginação por meio de parâmetros de consulta:

Parâmetro	Tipo	Padrão	Descrição
`page`	number	1	Número da página (indexado a partir de 1)
`per_page`	number	25	Itens por página (máx. `100`)

A resposta inclui metadados de paginação:

{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 150,
    "total_pages": 6,
    "has_next": true,
    "has_previous": false
  }
}

Respostas de Erro

Os erros seguem um formato consistente:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Campo	Tipo	Descrição
`statusCode`	number	Código de status HTTP
`message`	string \| string[]	Descrição do problema
`error`	string	Nome do erro HTTP
`code`	string	Presente apenas nos erros sobre os quais um cliente precisa ramificar. É um valor estável em `UPPER_SNAKE`: ramifique por `code`, nunca pelo texto de `message`, que pode mudar. Hoje o único é `DEFAULT_ROOT_CONFIRMATION_REQUIRED` (veja Publicar Config)

Códigos de Status Comuns

Código	Descrição
`200`	Sucesso
`201`	Criado
`204`	Sem Conteúdo (operações de desativação e exclusão)
`400`	Requisição Inválida (erros de validação)
`401`	Não Autorizado (token ausente ou inválido)
`403`	Proibido (permissões insuficientes ou tenant incorreto)
`404`	Não Encontrado
`409`	Conflito (chave de idempotência duplicada, violação de restrição única)

Próximos Passos

Autenticação — Aprenda a se autenticar com API keys ou JWT
Funções e Permissões — Entenda a hierarquia de funções e o controle de permissões
Integração de Tarefas — Comece a integrar com o módulo de atividades de tarefa