Consulta de Gestores

Lista os gestores (managers) vinculados à conta, com os contadores de base de afiliados e o cadastro de cada um.


Método	`GET`
Endpoint	`https://api.rockty.com/orders/v1/managers`
Autenticação	`Authorization: Bearer <TOKEN>`
Resposta	`application/json`

Quando usar

Para obter a relação de gestores da conta com seus indicadores — quantos afiliados cada um recrutou, quantos saíram, qual a comissão configurada e o status do vínculo. É a mesma fonte que alimenta a tela de gestores do painel.

Todos os filtros são opcionais: uma chamada sem parâmetros devolve todos os gestores da conta.

Autenticação e escopo

Envie o token no header Authorization (o mesmo usado nas demais rotas da API).

Sem o header Authorization, a chamada é recusada com 401 antes de chegar ao backend.

Requisição

Todos os parâmetros vão na query string e todos são opcionais.

Parâmetro	Tipo	Descrição
`q`	`string`	Busca livre por nome, e-mail ou documento do gestor. Sem acento-sensibilidade e sem case-sensibilidade; aceita termo parcial. Ausente ou vazio = lista todos.
`status`	`string`	Filtra pelo status do vínculo do gestor. Valores em uso: `pending`, `approved`, `active`, `inactive`.
`sellerType`	`string`	Perspectiva da consulta. `producer` (padrão) = os gestores da minha conta. `manager` = o próprio cadastro de gestor de quem chama.
`willStartOn`	`string` (ISO-8601)	Início do período. Recorta os contadores pela data de cadastro do gestor (`createdAt`).

Sobre o período

O recorte é aplicado no fuso de Brasília (UTC−3) pelo backend — envie a data no formato ISO-8601, com ou sem offset. Sem willStartOn, nenhum filtro de data é aplicado e os contadores cobrem todo o histórico.

Exemplo — cURL

Exemplo — listar todos

Resposta

Sucesso (HTTP 200)

{
  "results": [
    {
      "commission": 0,
      "createdAt": "2026-08-13T15:14:46.57+00:00",
      "deactivatedAt": null,
      "managerDocument": "75754061153",
      "managerEmail": "wadsgestor@gmail.com",
      "managerName": "Waleson Alves Ferreira",
      "managerTelephone": "5562994507037",
      "managerTenantId": "uu05syhlrkm3zivw7c7bha",
      "newAffiliates": 557,
      "refundedSales": null,
      "removedAffiliates": 401,
      "status": "approved",
      "totalAffiliates": 958
    }
  ]
}

results é sempre um array. Nenhum gestor encontrado = { "results": [] } — nunca null.

Campos

Campo	Tipo	Descrição
`commission`	`integer`	Comissão configurada para o gestor, em percentual (0 a 70). `0` = sem comissão definida.
`createdAt`	`string` (ISO-8601)	Data de cadastro do gestor.
`deactivatedAt`	`string` (ISO-8601) \| `null`	Data de desativação do vínculo. `null` = vínculo ativo.
`managerDocument`	`string`	CPF/CNPJ do gestor, somente dígitos.
`managerEmail`	`string`	E-mail do gestor.
`managerName`	`string`	Nome do gestor.
`managerTelephone`	`string`	Telefone somente dígitos, com DDI e DDD (ex.: `5562994507037`).
`managerTenantId`	`string`	Identificador do gestor na plataforma. Use este valor para relacionar o gestor nas demais rotas.
`newAffiliates`	`integer`	Afiliados recrutados pelo gestor no período.
`refundedSales`	`integer` \| `null`	Vendas estornadas atribuídas ao gestor. `null` = sem registro no período.
`removedAffiliates`	`integer`	Afiliados removidos da base do gestor no período.
`status`	`string`	Status do vínculo do gestor. Valores em uso: `pending`, `approved`, `active`, `inactive`.
`totalAffiliates`	`integer`	Base movimentada no período — a soma de `newAffiliates` + `removedAffiliates`. Não é a quantidade de afiliados ativos agora.

Atenção em totalAffiliates: no exemplo acima, 557 + 401 = 958. Para "afiliados ativos hoje", use newAffiliates - removedAffiliates.

Regras de comportamento

Escopo por token. Sempre restrito ao tenant do token. sellerType=producer (padrão) devolve os gestores da conta; sellerType=manager devolve o cadastro do próprio gestor autenticado.

Contadores são do período; cadastro é do registro mais recente. Quando há período, newAffiliates, removedAffiliates e totalAffiliates são somas dos dias no intervalo. Nome, e-mail, documento, telefone, comissão e status vêm sempre do cadastro atual.

Gestor sem movimento aparece na listagem. Numa chamada sem q, gestores cadastrados que ainda não têm movimento no índice entram no resultado com todos os contadores em 0.

Busca sem correspondência devolve lista vazia. Com q preenchido e nenhum gestor casando por nome/e-mail/documento, a resposta é { "results": [] }.

Sem paginação. A rota devolve o conjunto completo de gestores da conta numa única resposta. pageIndex e pageSize não fazem parte do contrato — a query GraphQL de origem os aceita, mas o backend os ignora nesta consulta.

status e managerEmail vêm do cadastro. Quando o gestor existe no cadastro e no índice, esses dois campos são sobrescritos pelo valor do cadastro — são a fonte de verdade.

Códigos de erro

HTTP	Corpo	Quando acontece	O que fazer
`401`	`{"errors":[{"message":"missing_authorization_header"}]}`	Header `Authorization` ausente ou vazio.	Enviar `Authorization: Bearer <TOKEN>`.
`401`	(do backend)	Token inválido, expirado ou com assinatura incorreta.	Renovar o token.
`403`	`{"errors":[{"message":"..."}]}`	Token válido, mas sem permissão para a consulta (`RCK_USER`).	Verificar as permissões do usuário/aplicação.
`502`	`{"errors":[{"message":"..."}]}`	Falha no backend de busca (indisponibilidade, erro de query).	Tentar novamente em instantes; se persistir, acionar o suporte.

Em 200 a resposta sempre tem results. Falha nunca chega como {"results":[]} — se houver results, a consulta foi executada.

Consulta de Gestores

Quando usar#

Autenticação e escopo#

Requisição#

Sobre o período#

Exemplo — cURL#

Exemplo — listar todos#

Resposta#

Sucesso (HTTP 200)#

Campos#

Regras de comportamento#

Códigos de erro#