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

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
}

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

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}'

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

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}'

Erros

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

Veja também

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.

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

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
}

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

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}'

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

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}'

Erros

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