VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Equipe de campo do seller

Cadastro de representantes

Lista, consulta, cadastra e altera os representantes comerciais do seller, com região, comissão, alçada de desconto e login de acesso.

Estas quatro rotas cuidam do cadastro da equipe de campo do seller. Tudo é fixado ao seller do token: a lista só traz os representantes dele, e o owner_vendor_id enviado no corpo é ignorado. Os ids dos representantes são inteiros.

Listar

GET/api/v1/vendor/trade-repsSeller

Lista os representantes do seller

Parâmetros de consulta

searchstring
Parte do nome, e-mail, região ou código interno, sem diferenciar maiúsculas.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100. Fora disso volta a 20.
200Representantes do seller

Campos da resposta

repsarray
Representantes da página. Vem [] quando não há nenhum.
reps[].idinteger
Id do representante (inteiro, não UUID).
reps[].user_iduuid
Usuário de login vinculado. Vazio se o representante não tem login.
reps[].namestring
Nome.
reps[].emailstring
E-mail, normalizado (minúsculas, sem espaços).
reps[].phonestring
Telefone, texto livre.
reps[].regionstring
Território comercial, texto livre.
reps[].regional_codestring
Regional de distribuição, código definido pela loja. Coisa diferente de region. Vazio se não atribuído.
reps[].statesarray
Siglas de estado atendidas.
reps[].is_activeboolean
Se o representante está ativo.
reps[].commission_rateinteger
Comissão do representante em pontos-base (500 = 5%). 0 usa a regra do seller.
reps[].total_salesinteger
Vendas acumuladas, em centavos.
reps[].total_commissioninteger
Comissão acumulada, em centavos.
reps[].notesstring
Observações internas.
reps[].owner_vendor_iduuid
Seller dono da equipe; é sempre o seu.
reps[].internal_codestring
Código do representante no sistema do seller (por exemplo, o do ERP).
reps[].hierarchy_levelinteger
01234
0 representante de campo; 1 a 4 níveis de aprovação de desconto.
reps[].discount_limit_bpinteger
Desconto máximo que ele concede sozinho, em pontos-base.
reps[].credit_balanceinteger
Saldo da conta-corrente, em centavos (pode ser negativo).
reps[].deactivated_atstring
Quando o representante excluiu a própria conta pelo aplicativo. Ausente se ativo.
reps[].email_invalid_atstring
Marcado quando o e-mail antigo era inválido. Apagado ao corrigir o e-mail.
totalinteger
Total que casa com a busca, em todas as páginas.
pageinteger
Página devolvida.
per_pageinteger
Itens por página aplicados.
total_pagesinteger
Número de páginas.

Consultar

GET/api/v1/vendor/trade-reps/{id}Seller

Consulta um representante do seller

Devolve um representante, com os mesmos campos de cada item da lista. Representante de outro seller, inexistente ou com id que não é número responde 404.

Parâmetros de caminho

idintegerobrigatório
Id do representante.

Cadastrar

POST/api/v1/vendor/trade-repsSeller

Cadastra um representante da equipe do seller

Cria o representante já vinculado ao seu seller e cria, ou reaproveita, o login dele como usuário seller. Se o e-mail ainda não tem login, password é obrigatória.

Corpo da requisição

namestringobrigatório
Nome completo. Dividido em nome e sobrenome no login.
emailstringobrigatório
E-mail válido. Vira o login do representante.
passwordstring
Senha do login. Obrigatória quando ainda não existe usuário seller com esse e-mail. Senha fraca devolve password_too_weak.
user_iduuid
Vincular a um usuário seller que já existe, em vez de procurar pelo e-mail.
phonestring
Telefone.
regionstring
Território comercial, texto livre.
regional_codestring
Regional de distribuição. Se a loja já cadastrou regionais, o código precisa existir.
statesarray
Siglas de estado atendidas. Padrão [].
commission_rateintegerpadrão: 0
Comissão em pontos-base.
notesstring
Observações internas.
internal_codestring
Código interno (ERP).
hierarchy_levelintegerpadrão: 0
01234
Nível hierárquico.
discount_limit_bpintegerpadrão: 0
Alçada própria de desconto, em pontos-base.
destination_idsarray
Ids de destinos de venda (lista de textos). Padrão [].
usergroup_idsarray
Ids de grupos de privilégio do tipo seller a conceder ao login.
notify_on_ordersboolean
Se o representante recebe aviso dos pedidos da carteira dele.

Exemplo de requisição: cadastrar

A resposta de sucesso é 201 com o representante completo, no formato de um item da lista.

Alterar

PUT/api/v1/vendor/trade-reps/{id}Seller

Altera parcialmente um representante

Altera só os campos enviados. A resposta é o representante atualizado. Para desligar um representante sem apagar o histórico, envie is_active: false.

Parâmetros de caminho

idintegerobrigatório
Id do representante.

Corpo da requisição

namestring
Nome.
emailstring
Novo e-mail, validado como no cadastro. Corrigir o e-mail limpa a marca email_invalid_at.
phonestring
Telefone.
regionstring
Território comercial.
regional_codestring
Regional de distribuição.
statesarray
Siglas de estado. Substitui a lista inteira.
is_activeboolean
Ativa ou desativa.
commission_rateinteger
Comissão em pontos-base.
notesstring
Observações.
internal_codestring
Código interno.
hierarchy_levelinteger
01234
Nível hierárquico.
discount_limit_bpinteger
Alçada própria, em pontos-base.
destination_idsarray
Destinos de venda. Substitui a lista inteira.
passwordstring
Troca a senha do login vinculado.
usergroup_idsarray
Grupos de privilégio a conceder (soma aos que já tem).
notify_on_ordersboolean
Aviso dos pedidos da carteira.

Exemplo de requisição: alterar

Erros

StatusQuandoCorpo de exemplo
400Corpo não é JSON.{"error":"invalid body","detail":"..."}
400Sem name ou sem email no cadastro.{"error":"name is required"}
400E-mail com formato inválido.{"error":"traderep_email_invalid","detail":"..."}
400Não existe login para o e-mail e faltou password.{"error":"password_required","detail":"password_required"}
400Senha fraca.{"error":"password_too_weak","detail":"..."}
400user_id inexistente.{"error":"user_not_found","detail":"user_not_found"}
400Grupo de privilégio inválido em usergroup_ids.{"error":"usergroup_invalid","detail":"..."}
400Outra falha de validação ao criar ou alterar.{"error":"create failed","detail":"..."} ou {"error":"update failed","detail":"..."}
401Sem token.{"error":"authentication required"}
403Módulo desligado.{"error":"module_disabled","module":"trade-reps"}
403Falta um dos privilégios de representantes ou de pedidos.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_manage_trade_reps","vendor_view_trade_reps","vendor_view_orders"]}
403Usuário sem seller.{"error":"vendor not found for user"}
404Representante inexistente, de outro seller ou com id inválido.{"error":"not found"}
409O e-mail pertence a uma conta que não é de seller.{"error":"email_in_use","detail":"..."}
503Serviço de contas indisponível e foi enviada password.{"error":"accounts_unavailable","detail":"accounts_unavailable"}
Reaproveitar um e-mail troca a senha

Se já existe um usuário seller com esse e-mail e você manda password, a senha dele é substituída. Mande password apenas quando a intenção for essa.

Desligue em vez de apagar

Esta API não tem rota para apagar representante. Use is_active: false: o histórico de vendas, comissões e conta-corrente continua consultável.

Veja também

  • Carteira, conta-corrente e alçadas
  • Visão geral
Anterior
Equipe de campo do seller
Próxima
Carteira, conta-corrente e alçadas
Nesta página
  • Listar
  • Consultar
  • Cadastrar
  • Exemplo de requisição: cadastrar
  • Alterar
  • Exemplo de requisição: alterar
  • Erros
  • Veja também
json
{
  "reps": [
    {
      "id": 31,
      "user_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
      "name": "Maria Souza",
      "email": "maria.souza@example.com",
      "phone": "+5511988887777",
      "region": "Grande São Paulo",
      "states": ["SP"],
      "is_active": true,
      "commission_rate": 300,
      "total_sales": 0,
      "total_commission": 0,
      "notes": "",
      "regional_code": "",
      "owner_vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "internal_code": "REP-014",
      "hierarchy_level": 0,
      "discount_limit_bp": 200,
      "credit_balance": 0,
      "created_at": "2026-10-11T21:50:00Z",
      "updated_at": "2026-10-11T21:50:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}
bash
curl -X POST "$BASE_URL/api/v1/vendor/trade-reps" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Maria Souza","email":"maria.souza@example.com","password":"Senha-Forte-2026","internal_code":"REP-014","states":["SP"],"commission_rate":300,"discount_limit_bp":200}'
bash
curl -X PUT "$BASE_URL/api/v1/vendor/trade-reps/31" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"discount_limit_bp": 300}'