API atual/Referência completa/Representantes comerciais

Listar e criar representantes

Lista os representantes comerciais com filtros e cadastra um novo representante, criando ou reaproveitando o login dele.

Listar representantes

Devolve os representantes do mais novo para o mais antigo, com paginação.

GET/api/v1/admin/trade-repsAdmin

Lista os representantes comerciais

Parâmetros de consulta

searchstring

Parte do nome, e-mail, região ou código interno, sem diferenciar maiúsculas.

is_activeboolean

true só ativos, false só inativos. Qualquer outro texto conta como false.

statestring

Sigla de estado (SP). Só representantes que atendem esse estado em states.

owner_vendor_iduuid

Só os representantes da equipe de campo desse seller.

internal_codestring

Código interno exato, sem diferenciar maiúsculas.

modestring

sellermarketplace

seller só os que têm owner_vendor_id; marketplace só os que não têm.

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.

Resposta

200Representantes

json

{
  "reps": [
    {
      "id": 2,
      "user_id": "fb345fc1-599a-4b4d-9fb0-93d1e7196cc0",
      "name": "João da Silva",
      "email": "joao.silva@example.com",
      "phone": "(11)99321-4444",
      "region": "Grande São Paulo",
      "states": ["SP", "RJ", "MG"],
      "is_active": true,
      "commission_rate": 500,
      "total_sales": 0,
      "total_commission": 0,
      "notes": "",
      "regional_code": "",
      "internal_code": "REP-001",
      "hierarchy_level": 0,
      "discount_limit_bp": 200,
      "credit_balance": 0,
      "created_at": "2026-05-17T04:55:18Z",
      "updated_at": "2026-07-15T01:07:07Z"
    }
  ],
  "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 quando 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 (faseamento), código da 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[].owner_vendor_iduuid

Seller dono da equipe de campo. Ausente no modo marketplace.

reps[].internal_codestring

Código do representante no sistema da loja (por exemplo, o do ERP). Ausente se não definido.

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 próprio representante excluiu a conta pelo app. 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 o filtro, em todas as páginas.

pageinteger

Página devolvida.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Número de páginas.

Cria o representante e o login dele. A plataforma procura uma conta de seller com o e-mail: se existe, reaproveita (e troca a senha, se você mandou password); se não existe, cria com a senha informada. Se o e-mail pertence a cliente ou administrador, a criação é recusada. No modo do seller (owner_vendor_id), o usuário também entra na equipe daquele seller como gerente.

POST/api/v1/admin/trade-repsAdmin

Cadastra um representante comercial

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. Esse usuário precisa ter senha ou você manda password.

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. Padrão [].

commission_rateintegerpadrão: 0

Comissão em pontos-base.

notesstring

Observações internas.

owner_vendor_iduuid

Seller dono. Preencha para o modo do seller; deixe vazio para o modo marketplace.

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 strings). Padrão [].

usergroup_idsarray

Ids de grupos de privilégio do tipo seller a conceder ao login.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/trade-reps" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Maria Souza","email":"maria.souza@example.com","password":"Senha-Forte-2026","owner_vendor_id":"94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36","internal_code":"REP-014","states":["SP"],"commission_rate":300,"discount_limit_bp":200}'

201Representante criado

json

{
  "id": 31,
  "user_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "name": "Maria Souza",
  "email": "maria.souza@example.com",
  "phone": "",
  "region": "",
  "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"
}

Erros

Status	Quando	Corpo de exemplo
400	Sem `name` ou sem `email`.	`{"error":"name is required"}`
400	E-mail com formato inválido.	`{"error":"traderep_email_invalid","detail":"traderep_email_invalid: mail: missing '@' or angle-addr"}`
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` não existe, ou `usergroup_ids` com grupo inválido.	`{"error":"user_not_found","detail":"user_not_found"}`
409	O e-mail (ou o `user_id`) pertence a conta que não é de seller.	`{"error":"email_in_use","detail":"email_in_use: email belongs to a non-vendor account"}`
503	Serviço de contas indisponível e foi enviada `password`.	`{"error":"accounts_unavailable","detail":"accounts_unavailable"}`
401 / 403	Sem token, módulo trade-reps desligado ou sem privilégio.	`{"error":"module_disabled","module":"trade-reps"}`

Veja também

Listar e criar representantes

Lista os representantes comerciais com filtros e cadastra um novo representante, criando ou reaproveitando o login dele.

Listar representantes

Devolve os representantes do mais novo para o mais antigo, com paginação.

GET/api/v1/admin/trade-repsAdmin

Lista os representantes comerciais

Parâmetros de consulta

searchstring

Parte do nome, e-mail, região ou código interno, sem diferenciar maiúsculas.

is_activeboolean

true só ativos, false só inativos. Qualquer outro texto conta como false.

statestring

Sigla de estado (SP). Só representantes que atendem esse estado em states.

owner_vendor_iduuid

Só os representantes da equipe de campo desse seller.

internal_codestring

Código interno exato, sem diferenciar maiúsculas.

modestring

sellermarketplace

seller só os que têm owner_vendor_id; marketplace só os que não têm.

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.

Resposta

200Representantes

json

{
  "reps": [
    {
      "id": 2,
      "user_id": "fb345fc1-599a-4b4d-9fb0-93d1e7196cc0",
      "name": "João da Silva",
      "email": "joao.silva@example.com",
      "phone": "(11)99321-4444",
      "region": "Grande São Paulo",
      "states": ["SP", "RJ", "MG"],
      "is_active": true,
      "commission_rate": 500,
      "total_sales": 0,
      "total_commission": 0,
      "notes": "",
      "regional_code": "",
      "internal_code": "REP-001",
      "hierarchy_level": 0,
      "discount_limit_bp": 200,
      "credit_balance": 0,
      "created_at": "2026-05-17T04:55:18Z",
      "updated_at": "2026-07-15T01:07:07Z"
    }
  ],
  "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 quando 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 (faseamento), código da 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[].owner_vendor_iduuid

Seller dono da equipe de campo. Ausente no modo marketplace.

reps[].internal_codestring

Código do representante no sistema da loja (por exemplo, o do ERP). Ausente se não definido.

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 próprio representante excluiu a conta pelo app. 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 o filtro, em todas as páginas.

pageinteger

Página devolvida.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Número de páginas.

Criar um representante

POST/api/v1/admin/trade-repsAdmin

Cadastra um representante comercial

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. Esse usuário precisa ter senha ou você manda password.

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. Padrão [].

commission_rateintegerpadrão: 0

Comissão em pontos-base.

notesstring

Observações internas.

owner_vendor_iduuid

Seller dono. Preencha para o modo do seller; deixe vazio para o modo marketplace.

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 strings). Padrão [].

usergroup_idsarray

Ids de grupos de privilégio do tipo seller a conceder ao login.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/trade-reps" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Maria Souza","email":"maria.souza@example.com","password":"Senha-Forte-2026","owner_vendor_id":"94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36","internal_code":"REP-014","states":["SP"],"commission_rate":300,"discount_limit_bp":200}'

201Representante criado

json

{
  "id": 31,
  "user_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "name": "Maria Souza",
  "email": "maria.souza@example.com",
  "phone": "",
  "region": "",
  "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"
}

Erros

Status	Quando	Corpo de exemplo
400	Sem `name` ou sem `email`.	`{"error":"name is required"}`
400	E-mail com formato inválido.	`{"error":"traderep_email_invalid","detail":"traderep_email_invalid: mail: missing '@' or angle-addr"}`
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` não existe, ou `usergroup_ids` com grupo inválido.	`{"error":"user_not_found","detail":"user_not_found"}`
409	O e-mail (ou o `user_id`) pertence a conta que não é de seller.	`{"error":"email_in_use","detail":"email_in_use: email belongs to a non-vendor account"}`
503	Serviço de contas indisponível e foi enviada `password`.	`{"error":"accounts_unavailable","detail":"accounts_unavailable"}`
401 / 403	Sem token, módulo trade-reps desligado ou sem privilégio.	`{"error":"module_disabled","module":"trade-reps"}`