API atual/Referência completa/Campo e alçadas dos representantes

Conta-corrente do representante

Consulta o extrato da conta-corrente de um representante e lança um crédito ou débito manual.

A conta-corrente (ledger) é o saldo de crédito que o representante pode gastar em descontos. Só mexem no saldo os créditos manuais, os débitos manuais e os descontos acima do livre. As comissões de pedido e os bônus aparecem no extrato, mas não alteram o saldo. O saldo atual aparece em credit_balance no cadastro do representante; aqui você vê cada lançamento e faz ajustes manuais. Valores em centavos, com sinal no extrato.

Ler o extrato

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

Extrato da conta-corrente de um representante

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Parâmetros de consulta

entry_typestring

commissiondiscountbonusmanual_creditmanual_debitreverse_commission

Só lançamentos deste tipo.

order_idstring

Só lançamentos deste pedido.

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": 2,
      "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 deste 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 da conta, em centavos.

totalinteger

Total de lançamentos que casam com o filtro.

pageinteger

Página devolvida.

per_pageinteger

Itens por página.

total_pagesinteger

Número de páginas.

Lançar crédito ou débito manual

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

Lança um crédito ou débito manual

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Corpo da requisição

amountintegerobrigatório

Valor em centavos, sempre positivo. Zero ou negativo é recusado.

scopestring

AD

A lança crédito (manual_credit). Qualquer outro valor, inclusive vazio, lança débito (manual_debit).

descriptionstring

Motivo do ajuste. Aparece no extrato.

bash

curl -X POST "$BASE_URL/api/v1/admin/trade-reps/2/ledger" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scope": "A", "amount": 5000, "description": "Bônus de meta de setembro"}'

201Lançamento criado

json

{
  "id": 119,
  "rep_id": 2,
  "entry_type": "manual_credit",
  "amount": 5000,
  "balance_after": 17999,
  "description": "Bônus de meta de setembro",
  "actor_user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "created_at": "2026-10-11T22:20:00Z"
}

Erros

Status	Quando	Corpo de exemplo
400	`id` não é inteiro.	`{"error":"invalid trade rep ID"}`
400	`amount` menor ou igual a zero.	`{"error":"ledger post failed","detail":"amount must be positive"}`
400	Corpo não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	Débito que deixaria o saldo abaixo de zero.	`{"error":"ledger post failed","detail":"insufficient credit balance"}`
400	O representante não existe.	`{"error":"ledger post failed","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

Conta-corrente do representante

Consulta o extrato da conta-corrente de um representante e lança um crédito ou débito manual.

Ler o extrato

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

Extrato da conta-corrente de um representante

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Parâmetros de consulta

entry_typestring

commissiondiscountbonusmanual_creditmanual_debitreverse_commission

Só lançamentos deste tipo.

order_idstring

Só lançamentos deste pedido.

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": 2,
      "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 deste 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 da conta, em centavos.

totalinteger

Total de lançamentos que casam com o filtro.

pageinteger

Página devolvida.

per_pageinteger

Itens por página.

total_pagesinteger

Número de páginas.

Lançar crédito ou débito manual

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

Lança um crédito ou débito manual

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Corpo da requisição

amountintegerobrigatório

Valor em centavos, sempre positivo. Zero ou negativo é recusado.

scopestring

AD

A lança crédito (manual_credit). Qualquer outro valor, inclusive vazio, lança débito (manual_debit).

descriptionstring

Motivo do ajuste. Aparece no extrato.

bash

curl -X POST "$BASE_URL/api/v1/admin/trade-reps/2/ledger" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scope": "A", "amount": 5000, "description": "Bônus de meta de setembro"}'

201Lançamento criado

json

{
  "id": 119,
  "rep_id": 2,
  "entry_type": "manual_credit",
  "amount": 5000,
  "balance_after": 17999,
  "description": "Bônus de meta de setembro",
  "actor_user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "created_at": "2026-10-11T22:20:00Z"
}

Erros

Status	Quando	Corpo de exemplo
400	`id` não é inteiro.	`{"error":"invalid trade rep ID"}`
400	`amount` menor ou igual a zero.	`{"error":"ledger post failed","detail":"amount must be positive"}`
400	Corpo não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	Débito que deixaria o saldo abaixo de zero.	`{"error":"ledger post failed","detail":"insufficient credit balance"}`
400	O representante não existe.	`{"error":"ledger post failed","detail":"trade rep not found"}`
401 / 403	Sem token, módulo desligado ou sem privilégio.	`{"error":"module_disabled","module":"trade-reps"}`