API atual/Referência completa/Equipe de campo do seller

Carteira, conta-corrente e alçadas

Consulta a carteira de clientes e o extrato da conta-corrente de um representante, transfere clientes entre representantes e ajusta os parâmetros financeiros de desconto do seller.

Depois de cadastrar os representantes, estas cinco rotas respondem às perguntas do dia a dia: quem atende quais clientes, quanto crédito de desconto cada um ainda tem e até onde cada um pode ir sem pedir aprovação. Todas valem só para o seu seller e para representantes dele.

Carteira de clientes de um representante

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

Lista os clientes da carteira de um representante

Lista os vínculos entre o representante e os clientes, com o tipo de vínculo. A carteira é montada pelo administrador da loja e por transferências.

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Parâmetros de consulta

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora disso volta a 20.

200Carteira

json

{
  "customers": [
    {
      "rep_id": 31,
      "customer_id": "472e2c31-fa7a-4d06-84c9-f832619bcdbd",
      "link_kind": "permanent",
      "source": "manual",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "customer_name": "Mariana Cavalcanti",
      "email": "mariana.cavalcanti@example.com",
      "assigned_at": "2026-07-20T02:51:25Z"
    }
  ],
  "total": 1,
  "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

permanent: definitivo. temporary: cobertura com data final, depois volta ao representante original. copy: o cliente fica com este representante e com outro.

customers[].sourcestring

Origem: manual, import, transfer, copy.

customers[].vendor_iduuid

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

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.

Extrato da conta-corrente

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

Extrato da conta-corrente de um representante

A conta-corrente é o saldo de crédito que o representante pode gastar em descontos acima do livre. O extrato mostra cada lançamento, do mais novo ao mais antigo. Aqui só há leitura: ajustes manuais são feitos pelo administrador da loja.

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Parâmetros de consulta

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora disso volta a 20.

200Extrato

json

{
  "entries": [
    {
      "id": 118,
      "rep_id": 31,
      "entry_type": "commission",
      "amount": 3999,
      "balance_after": 12999,
      "order_id": "4cb4cd7c-e817-48b3-b4a0-2f99f856a50b",
      "description": "commission order 4cb4cd7c-e817-48b3-b4a0-2f99f856a50b",
      "actor_user_id": "system",
      "created_at": "2026-09-07T02:10:00Z"
    }
  ],
  "balance": 12999,
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

entriesarray

Lançamentos da página.

entries[].idinteger

Id do lançamento.

entries[].entry_typestring

commissiondiscountbonusmanual_creditmanual_debitreverse_commission

Tipo do lançamento.

entries[].amountinteger

Valor com sinal, em centavos. Positivo é crédito; negativo é débito.

entries[].balance_afterinteger

Saldo logo depois do lançamento.

entries[].order_idstring

Pedido de origem, quando há.

entries[].order_item_idstring

Item do pedido, quando há.

entries[].descriptionstring

Texto do lançamento.

entries[].actor_user_idstring

Quem lançou: id de usuário, ou system quando é automático.

entries[].created_atstring

Quando foi lançado (RFC 3339).

balanceinteger

Saldo atual, em centavos.

totalinteger

Total de lançamentos.

pageinteger

Página devolvida.

per_pageinteger

Itens por página.

total_pagesinteger

Número de páginas.

Só mexem no saldo os créditos e débitos manuais e os descontos acima do livre. Comissões de pedido e bônus aparecem no extrato, mas não alteram o saldo.

Transferir clientes entre representantes

POST/api/v1/vendor/trade-reps/transferSeller

Transfere clientes de um representante para outro

Move clientes da carteira de um representante para outro, por exemplo quando alguém sai da equipe. Os dois representantes precisam ser do seu seller; senão a resposta é 403. A transferência age sobre os vínculos do seu seller.

Corpo da requisição

from_rep_idintegerobrigatório

Representante de origem.

to_rep_idintegerobrigatório

Representante de destino. Diferente da origem.

customer_idsarray

Clientes a mover. Vazio (ou all_filtered: true) move toda a carteira ativa da origem.

all_filteredboolean

true ignora customer_ids e move tudo.

kindstringpadrão: permanent

permanenttemporarypt

temporary (ou t) exige valid_until; ao vencer, o cliente pode voltar ao representante de origem.

valid_untilstring

Data final (RFC 3339) da transferência temporária.

200Resultado

json

{ "moved": 1, "copied": 0, "skipped": 0 }

Campos da resposta

movedinteger

Clientes movidos.

copiedinteger

Sempre 0 aqui (só a cópia preenche).

skippedinteger

Clientes que não estavam na carteira de origem.

errorsarray

Mensagens de linhas que falharam. Ausente quando não há.

Parâmetros financeiros do seller

GET/api/v1/vendor/trade-reps/finance-settingsSeller

Lê os parâmetros financeiros de desconto do seller

Devolve a configuração do seu seller. Sem configuração salva, todos os campos vêm 0, vazio ou false.

PUT/api/v1/vendor/trade-reps/finance-settingsSeller

Grava os parâmetros financeiros de desconto do seller

Grava (cria ou substitui) a configuração. É um upsert completo: todo campo não enviado é gravado como 0, vazio ou false. O vendor_id do corpo é ignorado; vale o seu. A resposta é o objeto gravado.

Corpo da requisição

order_commission_bpintegerpadrão: 0

Comissão sobre o pedido, em pontos-base, creditada ao representante na conta-corrente.

global_free_discount_bpintegerpadrão: 0

Desconto livre padrão do seller, usado quando nem o produto nem a categoria têm limite próprio.

approval_limit_1_bpintegerpadrão: 0

Excesso sobre o desconto livre até o qual o nível 1 aprova. Acima disso o nível exigido é 2 (ou mais, com níveis estendidos). 0 significa que o nível 1 resolve tudo.

approval_limit_2_bpintegerpadrão: 0

Excesso até o qual o nível 2 aprova. Só vale com extended_approval_levels.

approval_limit_3_bpintegerpadrão: 0

Excesso até o qual o nível 3 aprova. Só vale com extended_approval_levels. Acima disso o nível exigido é 4, que a plataforma bloqueia (não há quem aprove).

blocked_order_statusstring

Código do status em que o pedido fica retido esperando a aprovação de desconto. Vazio usa o status de espera padrão da loja.

extended_approval_levelsbooleanpadrão: false

false: só existem os níveis 1 e 2. true: níveis 1 a 3 e o nível 4 como bloqueio.

200Parâmetros

json

{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "order_commission_bp": 300,
  "global_free_discount_bp": 200,
  "approval_limit_1_bp": 500,
  "approval_limit_2_bp": 1000,
  "approval_limit_3_bp": 1500,
  "blocked_order_status": "",
  "extended_approval_levels": false
}

Exemplo de requisição

bash

# carteira do representante 31
curl "$BASE_URL/api/v1/vendor/trade-reps/31/customers" \
  -H "Authorization: Bearer $TOKEN"

# transferir toda a carteira do 31 para o 32
curl -X POST "$BASE_URL/api/v1/vendor/trade-reps/transfer" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from_rep_id": 31, "to_rep_id": 32, "all_filtered": true}'

# gravar os parâmetros financeiros (corpo completo)
curl -X PUT "$BASE_URL/api/v1/vendor/trade-reps/finance-settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"order_commission_bp": 300, "global_free_discount_bp": 200, "approval_limit_1_bp": 500}'

Erros

Status	Quando	Corpo de exemplo
400	Corpo não é JSON.	`{"error":"invalid body","detail":"..."}`
400	Transferência recusada (origem igual ao destino, `temporary` sem `valid_until`, nenhum cliente, tipo inválido).	`{"error":"transfer failed","detail":"origin and destination must differ"}`
400	Falha ao gravar os parâmetros financeiros.	`{"error":"save 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":["..."]}`
403	Algum dos representantes da transferência não é do seu seller (ou não existe).	`{"error":"reps must belong to your store"}`
404	Carteira ou extrato de representante inexistente, de outro seller ou com id inválido.	`{"error":"not found"}`
500	Falha ao consultar a carteira, o extrato ou os parâmetros.	`{"error":"list failed","detail":"..."}`

Veja também

API atual/Referência completa/Equipe de campo do seller

Carteira, conta-corrente e alçadas

Consulta a carteira de clientes e o extrato da conta-corrente de um representante, transfere clientes entre representantes e ajusta os parâmetros financeiros de desconto do seller.

Carteira de clientes de um representante

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

Lista os clientes da carteira de um representante

Lista os vínculos entre o representante e os clientes, com o tipo de vínculo. A carteira é montada pelo administrador da loja e por transferências.

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Parâmetros de consulta

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora disso volta a 20.

200Carteira

json

{
  "customers": [
    {
      "rep_id": 31,
      "customer_id": "472e2c31-fa7a-4d06-84c9-f832619bcdbd",
      "link_kind": "permanent",
      "source": "manual",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "customer_name": "Mariana Cavalcanti",
      "email": "mariana.cavalcanti@example.com",
      "assigned_at": "2026-07-20T02:51:25Z"
    }
  ],
  "total": 1,
  "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

permanent: definitivo. temporary: cobertura com data final, depois volta ao representante original. copy: o cliente fica com este representante e com outro.

customers[].sourcestring

Origem: manual, import, transfer, copy.

customers[].vendor_iduuid

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

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.

Extrato da conta-corrente

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

Extrato da conta-corrente de um representante

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Parâmetros de consulta

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora disso volta a 20.

200Extrato

json

{
  "entries": [
    {
      "id": 118,
      "rep_id": 31,
      "entry_type": "commission",
      "amount": 3999,
      "balance_after": 12999,
      "order_id": "4cb4cd7c-e817-48b3-b4a0-2f99f856a50b",
      "description": "commission order 4cb4cd7c-e817-48b3-b4a0-2f99f856a50b",
      "actor_user_id": "system",
      "created_at": "2026-09-07T02:10:00Z"
    }
  ],
  "balance": 12999,
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

entriesarray

Lançamentos da página.

entries[].idinteger

Id do lançamento.

entries[].entry_typestring

commissiondiscountbonusmanual_creditmanual_debitreverse_commission

Tipo do lançamento.

entries[].amountinteger

Valor com sinal, em centavos. Positivo é crédito; negativo é débito.

entries[].balance_afterinteger

Saldo logo depois do lançamento.

entries[].order_idstring

Pedido de origem, quando há.

entries[].order_item_idstring

Item do pedido, quando há.

entries[].descriptionstring

Texto do lançamento.

entries[].actor_user_idstring

Quem lançou: id de usuário, ou system quando é automático.

entries[].created_atstring

Quando foi lançado (RFC 3339).

balanceinteger

Saldo atual, em centavos.

totalinteger

Total de lançamentos.

pageinteger

Página devolvida.

per_pageinteger

Itens por página.

total_pagesinteger

Número de páginas.

Só mexem no saldo os créditos e débitos manuais e os descontos acima do livre. Comissões de pedido e bônus aparecem no extrato, mas não alteram o saldo.

Transferir clientes entre representantes

POST/api/v1/vendor/trade-reps/transferSeller

Transfere clientes de um representante para outro

Corpo da requisição

from_rep_idintegerobrigatório

Representante de origem.

to_rep_idintegerobrigatório

Representante de destino. Diferente da origem.

customer_idsarray

Clientes a mover. Vazio (ou all_filtered: true) move toda a carteira ativa da origem.

all_filteredboolean

true ignora customer_ids e move tudo.

kindstringpadrão: permanent

permanenttemporarypt

temporary (ou t) exige valid_until; ao vencer, o cliente pode voltar ao representante de origem.

valid_untilstring

Data final (RFC 3339) da transferência temporária.

200Resultado

json

{ "moved": 1, "copied": 0, "skipped": 0 }

Campos da resposta

movedinteger

Clientes movidos.

copiedinteger

Sempre 0 aqui (só a cópia preenche).

skippedinteger

Clientes que não estavam na carteira de origem.

errorsarray

Mensagens de linhas que falharam. Ausente quando não há.

Parâmetros financeiros do seller

GET/api/v1/vendor/trade-reps/finance-settingsSeller

Lê os parâmetros financeiros de desconto do seller

Devolve a configuração do seu seller. Sem configuração salva, todos os campos vêm 0, vazio ou false.

PUT/api/v1/vendor/trade-reps/finance-settingsSeller

Grava os parâmetros financeiros de desconto do seller

Corpo da requisição

order_commission_bpintegerpadrão: 0

Comissão sobre o pedido, em pontos-base, creditada ao representante na conta-corrente.

global_free_discount_bpintegerpadrão: 0

Desconto livre padrão do seller, usado quando nem o produto nem a categoria têm limite próprio.

approval_limit_1_bpintegerpadrão: 0

Excesso sobre o desconto livre até o qual o nível 1 aprova. Acima disso o nível exigido é 2 (ou mais, com níveis estendidos). 0 significa que o nível 1 resolve tudo.

approval_limit_2_bpintegerpadrão: 0

Excesso até o qual o nível 2 aprova. Só vale com extended_approval_levels.

approval_limit_3_bpintegerpadrão: 0

Excesso até o qual o nível 3 aprova. Só vale com extended_approval_levels. Acima disso o nível exigido é 4, que a plataforma bloqueia (não há quem aprove).

blocked_order_statusstring

Código do status em que o pedido fica retido esperando a aprovação de desconto. Vazio usa o status de espera padrão da loja.

extended_approval_levelsbooleanpadrão: false

false: só existem os níveis 1 e 2. true: níveis 1 a 3 e o nível 4 como bloqueio.

200Parâmetros

json

{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "order_commission_bp": 300,
  "global_free_discount_bp": 200,
  "approval_limit_1_bp": 500,
  "approval_limit_2_bp": 1000,
  "approval_limit_3_bp": 1500,
  "blocked_order_status": "",
  "extended_approval_levels": false
}

Exemplo de requisição

bash

# carteira do representante 31
curl "$BASE_URL/api/v1/vendor/trade-reps/31/customers" \
  -H "Authorization: Bearer $TOKEN"

# transferir toda a carteira do 31 para o 32
curl -X POST "$BASE_URL/api/v1/vendor/trade-reps/transfer" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"from_rep_id": 31, "to_rep_id": 32, "all_filtered": true}'

# gravar os parâmetros financeiros (corpo completo)
curl -X PUT "$BASE_URL/api/v1/vendor/trade-reps/finance-settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"order_commission_bp": 300, "global_free_discount_bp": 200, "approval_limit_1_bp": 500}'

Erros

Status	Quando	Corpo de exemplo
400	Corpo não é JSON.	`{"error":"invalid body","detail":"..."}`
400	Transferência recusada (origem igual ao destino, `temporary` sem `valid_until`, nenhum cliente, tipo inválido).	`{"error":"transfer failed","detail":"origin and destination must differ"}`
400	Falha ao gravar os parâmetros financeiros.	`{"error":"save 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":["..."]}`
403	Algum dos representantes da transferência não é do seu seller (ou não existe).	`{"error":"reps must belong to your store"}`
404	Carteira ou extrato de representante inexistente, de outro seller ou com id inválido.	`{"error":"not found"}`
500	Falha ao consultar a carteira, o extrato ou os parâmetros.	`{"error":"list failed","detail":"..."}`