API atual/Referência completa/Representantes comerciais

Carteira de clientes

Lista, atribui e remove clientes da carteira de um representante, e descobre qual representante atende um cliente.

A carteira é a lista de clientes que um representante atende. Cada item é um vínculo cliente-representante com um tipo (permanent, temporary ou copy). Estas rotas mexem num cliente de cada vez; para operações em massa veja Importar e mover carteira.

Listar a carteira

GET/api/v1/admin/trade-reps/{id}/customersAdmin

Lista os clientes da carteira de um representante

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página.

200Carteira

json

{
  "customers": [
    {
      "rep_id": 2,
      "customer_id": "472e2c31-fa7a-4d06-84c9-f832619bcdbd",
      "link_kind": "copy",
      "source": "copy",
      "customer_name": "Mariana Cavalcanti",
      "email": "mariana.cavalcanti@example.com",
      "assigned_at": "2026-07-20T02:51:25Z"
    }
  ],
  "total": 7,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

customersarray

Vínculos da página.

customers[].customer_iduuid

Id do cliente.

customers[].link_kindstring

permanenttemporarycopy

Tipo do vínculo.

customers[].sourcestring

Origem: manual, import, transfer, copy.

customers[].vendor_iduuid

Seller do vínculo. Ausente nos vínculos globais.

customers[].original_rep_idinteger

Em vínculo temporário, o representante a quem o cliente volta no fim.

customers[].valid_untilstring

Fim da validade, em vínculos temporários.

customers[].customer_namestring

Nome do cliente.

customers[].emailstring

E-mail do cliente.

customers[].assigned_atstring

Quando o vínculo foi criado ou atualizado.

totalinteger

Total de vínculos.

pageinteger

Página devolvida.

per_pageinteger

Itens por página.

total_pagesinteger

Número de páginas.

Atribuir um cliente

Cria um vínculo permanent (origem manual). No modo do seller, o vínculo já nasce preso ao seller dono do representante. Repetir a chamada para um cliente já na carteira atualiza o vínculo, sem erro.

POST/api/v1/admin/trade-reps/{id}/customersAdmin

Atribui um cliente à carteira

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Corpo da requisição

customer_iduuidobrigatório

Id do cliente.

bash

curl -X POST "$BASE_URL/api/v1/admin/trade-reps/2/customers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "472e2c31-fa7a-4d06-84c9-f832619bcdbd"}'

201Cliente atribuído

json

{
  "rep_id": 2,
  "customer_id": "472e2c31-fa7a-4d06-84c9-f832619bcdbd",
  "link_kind": "permanent",
  "source": "manual",
  "assigned_at": "2026-10-11T21:55:00Z"
}

Remover um cliente

DELETE/api/v1/admin/trade-reps/{id}/customers/{customerId}Admin

Remove um cliente da carteira

Parâmetros de caminho

idintegerobrigatório

Id do representante.

customerIduuidobrigatório

Id do cliente.

200Removido

json

{ "status": "unassigned" }

Remove todos os vínculos desse cliente com esse representante, de qualquer seller e tipo.

Qual representante atende um cliente

GET/api/v1/admin/trade-reps/by-customerAdmin

Devolve o representante de um cliente

Parâmetros de consulta

customer_iduuidobrigatório

Id do cliente.

Devolve o objeto do representante (como na lista). Se o cliente estiver em mais de uma carteira, só um deles é devolvido.

Emissor de pedido de um cliente

Devolve o id do usuário do representante, que é o valor usado para atribuir um pedido ao representante (emissor).

GET/api/v1/admin/trade-reps/issuerAdmin

Devolve o emissor (usuário) que atende um cliente

Parâmetros de consulta

customer_iduuidobrigatório

Id do cliente.

200Emissor

json

{ "customer_id": "472e2c31-fa7a-4d06-84c9-f832619bcdbd", "issuer_id": "fb345fc1-599a-4b4d-9fb0-93d1e7196cc0", "has_rep": true }

Campos da resposta

customer_iduuid

O cliente consultado.

issuer_iduuid

Id do usuário (login) do representante. Vazio quando não há representante ou quando o representante não tem login vinculado.

has_repboolean

true quando issuer_id não está vazio.

Erros

Status	Quando	Corpo de exemplo
400	`id` não é inteiro.	`{"error":"invalid trade rep ID"}`
400	Falta `customer_id` (corpo ou consulta).	`{"error":"customer_id is required"}`
404	`by-customer` sem representante.	`{"error":"no trade rep assigned to this customer"}`
404	Remoção de vínculo inexistente.	`{"error":"customer assignment not found"}`
500	Representante ou cliente não existem (UUID inválido ou chave estrangeira).	`{"error":"failed to assign customer","detail":"..."}`
401 / 403	Sem token, módulo desligado ou sem privilégio.	`{"error":"module_disabled","module":"trade-reps"}`

Veja também

API atual/Referência completa/Representantes comerciais

Carteira de clientes

Lista, atribui e remove clientes da carteira de um representante, e descobre qual representante atende um cliente.

Listar a carteira

GET/api/v1/admin/trade-reps/{id}/customersAdmin

Lista os clientes da carteira de um representante

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página.

200Carteira

json

{
  "customers": [
    {
      "rep_id": 2,
      "customer_id": "472e2c31-fa7a-4d06-84c9-f832619bcdbd",
      "link_kind": "copy",
      "source": "copy",
      "customer_name": "Mariana Cavalcanti",
      "email": "mariana.cavalcanti@example.com",
      "assigned_at": "2026-07-20T02:51:25Z"
    }
  ],
  "total": 7,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

customersarray

Vínculos da página.

customers[].customer_iduuid

Id do cliente.

customers[].link_kindstring

permanenttemporarycopy

Tipo do vínculo.

customers[].sourcestring

Origem: manual, import, transfer, copy.

customers[].vendor_iduuid

Seller do vínculo. Ausente nos vínculos globais.

customers[].original_rep_idinteger

Em vínculo temporário, o representante a quem o cliente volta no fim.

customers[].valid_untilstring

Fim da validade, em vínculos temporários.

customers[].customer_namestring

Nome do cliente.

customers[].emailstring

E-mail do cliente.

customers[].assigned_atstring

Quando o vínculo foi criado ou atualizado.

totalinteger

Total de vínculos.

pageinteger

Página devolvida.

per_pageinteger

Itens por página.

total_pagesinteger

Número de páginas.

Atribuir um cliente

POST/api/v1/admin/trade-reps/{id}/customersAdmin

Atribui um cliente à carteira

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Corpo da requisição

customer_iduuidobrigatório

Id do cliente.

bash

curl -X POST "$BASE_URL/api/v1/admin/trade-reps/2/customers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "472e2c31-fa7a-4d06-84c9-f832619bcdbd"}'

201Cliente atribuído

json

{
  "rep_id": 2,
  "customer_id": "472e2c31-fa7a-4d06-84c9-f832619bcdbd",
  "link_kind": "permanent",
  "source": "manual",
  "assigned_at": "2026-10-11T21:55:00Z"
}

Remover um cliente

DELETE/api/v1/admin/trade-reps/{id}/customers/{customerId}Admin

Remove um cliente da carteira

Parâmetros de caminho

idintegerobrigatório

Id do representante.

customerIduuidobrigatório

Id do cliente.

200Removido

json

{ "status": "unassigned" }

Remove todos os vínculos desse cliente com esse representante, de qualquer seller e tipo.

Qual representante atende um cliente

GET/api/v1/admin/trade-reps/by-customerAdmin

Devolve o representante de um cliente

Parâmetros de consulta

customer_iduuidobrigatório

Id do cliente.

Devolve o objeto do representante (como na lista). Se o cliente estiver em mais de uma carteira, só um deles é devolvido.

Emissor de pedido de um cliente

Devolve o id do usuário do representante, que é o valor usado para atribuir um pedido ao representante (emissor).

GET/api/v1/admin/trade-reps/issuerAdmin

Devolve o emissor (usuário) que atende um cliente

Parâmetros de consulta

customer_iduuidobrigatório

Id do cliente.

200Emissor

json

{ "customer_id": "472e2c31-fa7a-4d06-84c9-f832619bcdbd", "issuer_id": "fb345fc1-599a-4b4d-9fb0-93d1e7196cc0", "has_rep": true }

Campos da resposta

customer_iduuid

O cliente consultado.

issuer_iduuid

Id do usuário (login) do representante. Vazio quando não há representante ou quando o representante não tem login vinculado.

has_repboolean

true quando issuer_id não está vazio.

Erros

Status	Quando	Corpo de exemplo
400	`id` não é inteiro.	`{"error":"invalid trade rep ID"}`
400	Falta `customer_id` (corpo ou consulta).	`{"error":"customer_id is required"}`
404	`by-customer` sem representante.	`{"error":"no trade rep assigned to this customer"}`
404	Remoção de vínculo inexistente.	`{"error":"customer assignment not found"}`
500	Representante ou cliente não existem (UUID inválido ou chave estrangeira).	`{"error":"failed to assign customer","detail":"..."}`
401 / 403	Sem token, módulo desligado ou sem privilégio.	`{"error":"module_disabled","module":"trade-reps"}`