API atual/Referência completa/Representantes comerciais

Desempenho dos representantes

Resumo e painel de um representante, os pedidos atribuídos a ele e a busca de representantes por estado.

Quatro leituras para acompanhar quanto cada representante vendeu. Os valores em dinheiro são inteiros em centavos.

Resumo

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

Totais de vendas e comissão de um representante

Parâmetros de caminho

idintegerobrigatório

Id do representante.

200Resumo

json

{
  "total_sales": 1250000,
  "total_commission": 62500,
  "pending_commission": 20000,
  "approved_commission": 12500,
  "paid_commission": 30000,
  "vendor_count": 1,
  "order_count": 18,
  "credit_balance": 0
}

Campos da resposta

total_salesinteger

Vendas acumuladas, em centavos.

total_commissioninteger

Comissão acumulada, em centavos.

pending_commissioninteger

Comissão ainda pendente.

approved_commissioninteger

Comissão aprovada e não paga.

paid_commissioninteger

Comissão paga.

vendor_countinteger

Sellers atendidos.

order_countinteger

Pedidos atribuídos ao representante.

credit_balanceinteger

Saldo da conta-corrente, em centavos.

Painel

O resumo mais os números do mês corrente.

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

Resumo e números do mês de um representante

Parâmetros de caminho

idintegerobrigatório

Id do representante.

200Painel

json

{
  "total_sales": 0,
  "total_commission": 0,
  "pending_commission": 0,
  "approved_commission": 0,
  "paid_commission": 0,
  "vendor_count": 1,
  "order_count": 0,
  "credit_balance": 0,
  "customer_count": 7,
  "orders_this_month": 0,
  "sales_this_month": 0,
  "commission_this_month": 0
}

Os campos novos em relação ao resumo: customer_count (clientes na carteira), orders_this_month, sales_this_month e commission_this_month (em centavos).

Pedidos do representante

Pedidos atribuídos ao representante, do mais novo para o mais antigo.

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

Lista os pedidos atribuídos a um representante

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Parâmetros de consulta

statusstring

Status do pedido, do jeito que a loja o grava.

customer_iduuid

Só pedidos deste cliente.

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 20

Itens por página.

200Pedidos

json

{
  "orders": [
    {
      "order_id": "4cb4cd7c-e817-48b3-b4a0-2f99f856a50b",
      "order_number": "19611",
      "customer_id": "b2495fbb-8e8d-4d18-b370-b30f880bfd71",
      "customer_name": "Bruno Gomes",
      "customer_email": "bruno.gomes@example.com",
      "status": "processing",
      "total": 79990,
      "currency": "BRL",
      "created_at": "2026-09-07T02:04:51Z"
    }
  ],
  "total": 118,
  "page": 1,
  "per_page": 20,
  "total_pages": 6
}

Campos da resposta

ordersarray

Pedidos da página.

orders[].order_iduuid

Id do pedido.

orders[].order_numberstring

Número mostrado ao cliente.

orders[].customer_iduuid

Cliente.

orders[].statusstring

Status do pedido.

orders[].totalinteger

Total em centavos (79990 = R$ 799,90).

orders[].currencystring

Moeda (BRL).

orders[].created_atstring

Criação (RFC 3339).

orders[].parent_idstring

Em pedido dividido, o pedido de origem.

orders[].split_kindstring

Tipo da divisão, quando há.

orders[].customer_cnpjstring

Documento do cliente PJ.

totalinteger

Total de pedidos.

Representantes por estado

Procura os representantes que atendem um estado, por exemplo para escolher a quem encaminhar um cliente novo.

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

Lista representantes que atendem um estado

Parâmetros de consulta

statestringobrigatório

Sigla do estado, como SP.

200Representantes do estado

json

{ "reps": [], "total": 0, "state": "SP" }

reps traz os mesmos objetos da lista de representantes.

Erros

Status	Quando	Corpo de exemplo
400	`id` não é inteiro.	`{"error":"invalid trade rep ID"}`
400	`by-state` sem `state`.	`{"error":"state query parameter is required"}`
500	Resumo ou painel de um representante que não existe.	`{"error":"failed to get rep summary","detail":"trade rep not found"}`
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

Desempenho dos representantes

Resumo e painel de um representante, os pedidos atribuídos a ele e a busca de representantes por estado.

Quatro leituras para acompanhar quanto cada representante vendeu. Os valores em dinheiro são inteiros em centavos.

Resumo

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

Totais de vendas e comissão de um representante

Parâmetros de caminho

idintegerobrigatório

Id do representante.

200Resumo

json

{
  "total_sales": 1250000,
  "total_commission": 62500,
  "pending_commission": 20000,
  "approved_commission": 12500,
  "paid_commission": 30000,
  "vendor_count": 1,
  "order_count": 18,
  "credit_balance": 0
}

Campos da resposta

total_salesinteger

Vendas acumuladas, em centavos.

total_commissioninteger

Comissão acumulada, em centavos.

pending_commissioninteger

Comissão ainda pendente.

approved_commissioninteger

Comissão aprovada e não paga.

paid_commissioninteger

Comissão paga.

vendor_countinteger

Sellers atendidos.

order_countinteger

Pedidos atribuídos ao representante.

credit_balanceinteger

Saldo da conta-corrente, em centavos.

Painel

O resumo mais os números do mês corrente.

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

Resumo e números do mês de um representante

Parâmetros de caminho

idintegerobrigatório

Id do representante.

200Painel

json

{
  "total_sales": 0,
  "total_commission": 0,
  "pending_commission": 0,
  "approved_commission": 0,
  "paid_commission": 0,
  "vendor_count": 1,
  "order_count": 0,
  "credit_balance": 0,
  "customer_count": 7,
  "orders_this_month": 0,
  "sales_this_month": 0,
  "commission_this_month": 0
}

Os campos novos em relação ao resumo: customer_count (clientes na carteira), orders_this_month, sales_this_month e commission_this_month (em centavos).

Pedidos do representante

Pedidos atribuídos ao representante, do mais novo para o mais antigo.

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

Lista os pedidos atribuídos a um representante

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Parâmetros de consulta

statusstring

Status do pedido, do jeito que a loja o grava.

customer_iduuid

Só pedidos deste cliente.

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 20

Itens por página.

200Pedidos

json

{
  "orders": [
    {
      "order_id": "4cb4cd7c-e817-48b3-b4a0-2f99f856a50b",
      "order_number": "19611",
      "customer_id": "b2495fbb-8e8d-4d18-b370-b30f880bfd71",
      "customer_name": "Bruno Gomes",
      "customer_email": "bruno.gomes@example.com",
      "status": "processing",
      "total": 79990,
      "currency": "BRL",
      "created_at": "2026-09-07T02:04:51Z"
    }
  ],
  "total": 118,
  "page": 1,
  "per_page": 20,
  "total_pages": 6
}

Campos da resposta

ordersarray

Pedidos da página.

orders[].order_iduuid

Id do pedido.

orders[].order_numberstring

Número mostrado ao cliente.

orders[].customer_iduuid

Cliente.

orders[].statusstring

Status do pedido.

orders[].totalinteger

Total em centavos (79990 = R$ 799,90).

orders[].currencystring

Moeda (BRL).

orders[].created_atstring

Criação (RFC 3339).

orders[].parent_idstring

Em pedido dividido, o pedido de origem.

orders[].split_kindstring

Tipo da divisão, quando há.

orders[].customer_cnpjstring

Documento do cliente PJ.

totalinteger

Total de pedidos.

Representantes por estado

Procura os representantes que atendem um estado, por exemplo para escolher a quem encaminhar um cliente novo.

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

Lista representantes que atendem um estado

Parâmetros de consulta

statestringobrigatório

Sigla do estado, como SP.

200Representantes do estado

json

{ "reps": [], "total": 0, "state": "SP" }

reps traz os mesmos objetos da lista de representantes.

Erros

Status	Quando	Corpo de exemplo
400	`id` não é inteiro.	`{"error":"invalid trade rep ID"}`
400	`by-state` sem `state`.	`{"error":"state query parameter is required"}`
500	Resumo ou painel de um representante que não existe.	`{"error":"failed to get rep summary","detail":"trade rep not found"}`
401 / 403	Sem token, módulo desligado ou sem privilégio.	`{"error":"module_disabled","module":"trade-reps"}`