API atual/Referência completa/Representantes comerciais

Comissões de representantes

Lista as comissões de um representante, lança uma comissão manual e avança o status (pendente, aprovada, paga).

A comissão é o valor que o representante ganha por pedido. Cada linha liga um representante, um seller e um pedido. Aqui você consulta, lança manualmente e muda o status. Valores em centavos.

Listar comissões

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

Lista as comissões de um representante

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Parâmetros de consulta

vendor_iduuid

Só comissões deste seller.

statusstring

pendingapprovedpaid

Filtra pelo status. A palavra é convertida na letra guardada.

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100.

200Comissões

json

{
  "commissions": [
    {
      "id": 14,
      "rep_id": 2,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "order_id": "4cb4cd7c-e817-48b3-b4a0-2f99f856a50b",
      "amount": 3999,
      "status": "P",
      "vendor_name": "Loja Seller Teste",
      "created_at": "2026-09-07T02:10:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

commissionsarray

Comissões da página.

commissions[].idinteger

Id da comissão (inteiro).

commissions[].rep_idinteger

Representante.

commissions[].vendor_iduuid

Seller do pedido.

commissions[].order_idstring

Pedido que gerou a comissão.

commissions[].amountinteger

Valor em centavos.

commissions[].statusstring

PAC

Status em letra: P pendente, A aprovada, C paga.

commissions[].vendor_namestring

Razão social do seller.

commissions[].created_atstring

Quando foi lançada (RFC 3339).

totalinteger

Total que casa com o filtro.

Cria uma comissão pending e soma o valor aos totais do representante (total_commission) e o total do pedido a total_sales. Normalmente o sistema lança comissões sozinho; use este lançamento para ajustes manuais.

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

Lança uma comissão manual

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Corpo da requisição

vendor_iduuidobrigatório

Seller do pedido.

order_idstringobrigatório

Id do pedido.

amountintegerobrigatório

Valor em centavos, maior que zero.

bash

curl -X POST "$BASE_URL/api/v1/admin/trade-reps/2/commissions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "order_id": "4cb4cd7c-e817-48b3-b4a0-2f99f856a50b", "amount": 3999}'

201Comissão lançada

json

{
  "id": 15,
  "rep_id": 2,
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "order_id": "4cb4cd7c-e817-48b3-b4a0-2f99f856a50b",
  "amount": 3999,
  "status": "P",
  "created_at": "2026-10-11T22:05:00Z"
}

Mudar o status de uma comissão

PATCH/api/v1/admin/trade-reps/commissions/{commId}/statusAdmin

Muda o status de uma comissão

Parâmetros de caminho

commIdintegerobrigatório

Id da comissão (de commissions[].id).

Corpo da requisição

statusstringobrigatório

pendingapprovedpaid

Novo status, em palavra.

200Status atualizado

json

{ "status": "approved" }

Erros

Status	Quando	Corpo de exemplo
400	`id` ou `commId` não é inteiro.	`{"error":"invalid commission ID"}`
400	Falta `vendor_id` ou `order_id`.	`{"error":"vendor_id is required"}`
400	`amount` menor ou igual a zero.	`{"error":"amount must be positive"}`
400	Falta `status`, ou valor fora de `pending`/`approved`/`paid`, ou comissão inexistente.	`{"error":"failed to update commission status","detail":"invalid status: must be pending, approved, or paid"}`
500	Falha ao gravar (por exemplo, seller ou representante inexistente).	`{"error":"failed to record commission","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

Comissões de representantes

Lista as comissões de um representante, lança uma comissão manual e avança o status (pendente, aprovada, paga).

A comissão é o valor que o representante ganha por pedido. Cada linha liga um representante, um seller e um pedido. Aqui você consulta, lança manualmente e muda o status. Valores em centavos.

Listar comissões

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

Lista as comissões de um representante

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Parâmetros de consulta

vendor_iduuid

Só comissões deste seller.

statusstring

pendingapprovedpaid

Filtra pelo status. A palavra é convertida na letra guardada.

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100.

200Comissões

json

{
  "commissions": [
    {
      "id": 14,
      "rep_id": 2,
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "order_id": "4cb4cd7c-e817-48b3-b4a0-2f99f856a50b",
      "amount": 3999,
      "status": "P",
      "vendor_name": "Loja Seller Teste",
      "created_at": "2026-09-07T02:10:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

commissionsarray

Comissões da página.

commissions[].idinteger

Id da comissão (inteiro).

commissions[].rep_idinteger

Representante.

commissions[].vendor_iduuid

Seller do pedido.

commissions[].order_idstring

Pedido que gerou a comissão.

commissions[].amountinteger

Valor em centavos.

commissions[].statusstring

PAC

Status em letra: P pendente, A aprovada, C paga.

commissions[].vendor_namestring

Razão social do seller.

commissions[].created_atstring

Quando foi lançada (RFC 3339).

totalinteger

Total que casa com o filtro.

Lançar uma comissão

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

Lança uma comissão manual

Parâmetros de caminho

idintegerobrigatório

Id do representante.

Corpo da requisição

vendor_iduuidobrigatório

Seller do pedido.

order_idstringobrigatório

Id do pedido.

amountintegerobrigatório

Valor em centavos, maior que zero.

bash

curl -X POST "$BASE_URL/api/v1/admin/trade-reps/2/commissions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "order_id": "4cb4cd7c-e817-48b3-b4a0-2f99f856a50b", "amount": 3999}'

201Comissão lançada

json

{
  "id": 15,
  "rep_id": 2,
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "order_id": "4cb4cd7c-e817-48b3-b4a0-2f99f856a50b",
  "amount": 3999,
  "status": "P",
  "created_at": "2026-10-11T22:05:00Z"
}

Mudar o status de uma comissão

PATCH/api/v1/admin/trade-reps/commissions/{commId}/statusAdmin

Muda o status de uma comissão

Parâmetros de caminho

commIdintegerobrigatório

Id da comissão (de commissions[].id).

Corpo da requisição

statusstringobrigatório

pendingapprovedpaid

Novo status, em palavra.

200Status atualizado

json

{ "status": "approved" }

Erros

Status	Quando	Corpo de exemplo
400	`id` ou `commId` não é inteiro.	`{"error":"invalid commission ID"}`
400	Falta `vendor_id` ou `order_id`.	`{"error":"vendor_id is required"}`
400	`amount` menor ou igual a zero.	`{"error":"amount must be positive"}`
400	Falta `status`, ou valor fora de `pending`/`approved`/`paid`, ou comissão inexistente.	`{"error":"failed to update commission status","detail":"invalid status: must be pending, approved, or paid"}`
500	Falha ao gravar (por exemplo, seller ou representante inexistente).	`{"error":"failed to record commission","detail":"..."}`
401 / 403	Sem token, módulo desligado ou sem privilégio.	`{"error":"module_disabled","module":"trade-reps"}`