Comissões por plano

Fluxo manual de aprovação e pagamento das comissões calculadas com a taxa do plano de cada seller.

Além do razão por item, a plataforma mantém um segundo livro: as comissões por plano. Cada pedido concluído de um seller gera uma linha, com a taxa do plano contratado pelo seller. O operador confere a linha e a leva por pendente > aprovada > paga. Esse fluxo é de conferência; ele não movimenta saldo.

Listar comissões por plano

Lista as comissões do fluxo de aprovação: uma linha por pedido de seller, calculada com a taxa do plano do seller (commission_bps e taxa fixa) no dia da conclusão do pedido. A linha nasce pendente e passa pelas etapas manuais de aprovar e pagar, descritas abaixo.

GET/api/v1/admin/commissionsAdmin

Lista as comissões por plano

Autenticação: Authorization: Bearer <token> de um administrador com o privilégio view_vendors ou manage_vendors (as escritas exigem manage_vendors). O módulo commissions precisa estar ativo na loja; com o módulo desligado a resposta é 403.

Parâmetros de consulta

vendor_idstring

UUID do seller, ou trecho do nome, slug ou e-mail dele.

statusstring

pendingapprovedpaidcancelledOACI

pending, approved, paid, cancelled ou a letra O, A, C, I.

date_fromstring

Data inicial, YYYY-MM-DD, inclusive. Formato diferente dá 500.

date_tostring

Data final, YYYY-MM-DD, inclusive (o dia inteiro entra).

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

De 1 a 100. Fora disso vale 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/commissions?status=pending&date_from=2026-10-01&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Comissões devolvidas

json

{
  "commissions": [
    {
      "id": 36975,
      "order_id": "4d4d79f4-f71b-4706-a303-bc79d48df101",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "plan_id": 8,
      "order_amount": 129990,
      "commission_bps": 700,
      "fixed_fee_cents": 0,
      "commission_amount": 9099,
      "status": "O",
      "created_at": "2026-10-11T21:02:32.618401Z",
      "updated_at": "2026-10-11T21:02:32.618401Z"
    }
  ],
  "total": 36927,
  "page": 1,
  "per_page": 20,
  "total_pages": 1847
}

Campos da resposta

commissionsarray

Comissões da página, da mais recente para a mais antiga.

commissions[].idinteger

Identificador numérico (não é UUID).

commissions[].order_iduuid

Pedido do seller.

commissions[].vendor_iduuid

Seller.

commissions[].vendor_namestring

Nome do seller. Omitido se vazio.

commissions[].plan_idinteger

Plano do seller no momento. Omitido se o seller não tinha plano.

commissions[].order_amountinteger

Parte do seller no pedido, em centavos.

commissions[].commission_bpsinteger

Taxa aplicada, em pontos-base, copiada do plano (700 = 7%).

commissions[].fixed_fee_centsinteger

Taxa fixa aplicada, em centavos.

commissions[].commission_amountinteger

order_amount * commission_bps / 10000 + fixed_fee_cents, em centavos.

commissions[].statusstring

OACI

Letra do estado: O pendente, A aprovada, C paga, I cancelada.

commissions[].paid_atstring

Quando foi marcada como paga. Só nas pagas.

commissions[].created_atstring

Criação, RFC 3339 em UTC.

commissions[].updated_atstring

Última alteração.

totalinteger

Total com o filtro.

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página usado.

total_pagesinteger

Total de páginas.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"commissions"}` / `{"error":"insufficient privileges","required":"manage_vendors"}`
500	`date_from`/`date_to` fora de `YYYY-MM-DD` ou falha na consulta (a mensagem do campo `detail` pode sugerir outro formato, ignore: vale `YYYY-MM-DD`)	`{"error":"failed to list commissions","detail":"..."}`

Aprovar comissão

Move uma comissão de pending (O) para approved (A). Só funciona a partir de pendente. É o primeiro passo do fluxo manual de conferência.

PUT/api/v1/admin/commissions/{id}/approveAdmin

Aprova uma comissão por plano pendente

Parâmetros de caminho

idintegerobrigatório

Identificador numérico da comissão, o id da lista.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/commissions/36975/approve" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Aprovada

json

{
  "status": "approved"
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"commissions"}` / `{"error":"insufficient privileges","required":"manage_vendors"}`
400	`id` zero ou negativo, `id` que não é número, comissão inexistente ou fora do estado pendente	`{"error":"invalid id parameter"}` / `{"error":"invalid commission id"}` / `{"error":"failed to approve commission","detail":"commission 36975 not found or not in pending status"}`

Marcar como paga

Move de approved (A) para paid (C) e grava paid_at. Só funciona a partir de aprovada: não dá para pular a aprovação.

PUT/api/v1/admin/commissions/{id}/payAdmin

Marca uma comissão por plano aprovada como paga

Parâmetros de caminho

idintegerobrigatório

Identificador numérico da comissão.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/commissions/36975/pay" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Marcada como paga

json

{
  "status": "paid"
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"commissions"}` / `{"error":"insufficient privileges","required":"manage_vendors"}`
400	`id` zero, negativo ou não numérico, comissão inexistente ou fora do estado aprovada	`{"error":"invalid id parameter"}` / `{"error":"failed to mark commission as paid","detail":"commission 36975 not found or not in approved status"}`

Veja também

API atual/Referência completa/Comissões

Comissões por plano

Fluxo manual de aprovação e pagamento das comissões calculadas com a taxa do plano de cada seller.

Listar comissões por plano

GET/api/v1/admin/commissionsAdmin

Lista as comissões por plano

Parâmetros de consulta

vendor_idstring

UUID do seller, ou trecho do nome, slug ou e-mail dele.

statusstring

pendingapprovedpaidcancelledOACI

pending, approved, paid, cancelled ou a letra O, A, C, I.

date_fromstring

Data inicial, YYYY-MM-DD, inclusive. Formato diferente dá 500.

date_tostring

Data final, YYYY-MM-DD, inclusive (o dia inteiro entra).

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

De 1 a 100. Fora disso vale 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/commissions?status=pending&date_from=2026-10-01&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Comissões devolvidas

json

{
  "commissions": [
    {
      "id": 36975,
      "order_id": "4d4d79f4-f71b-4706-a303-bc79d48df101",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "plan_id": 8,
      "order_amount": 129990,
      "commission_bps": 700,
      "fixed_fee_cents": 0,
      "commission_amount": 9099,
      "status": "O",
      "created_at": "2026-10-11T21:02:32.618401Z",
      "updated_at": "2026-10-11T21:02:32.618401Z"
    }
  ],
  "total": 36927,
  "page": 1,
  "per_page": 20,
  "total_pages": 1847
}

Campos da resposta

commissionsarray

Comissões da página, da mais recente para a mais antiga.

commissions[].idinteger

Identificador numérico (não é UUID).

commissions[].order_iduuid

Pedido do seller.

commissions[].vendor_iduuid

Seller.

commissions[].vendor_namestring

Nome do seller. Omitido se vazio.

commissions[].plan_idinteger

Plano do seller no momento. Omitido se o seller não tinha plano.

commissions[].order_amountinteger

Parte do seller no pedido, em centavos.

commissions[].commission_bpsinteger

Taxa aplicada, em pontos-base, copiada do plano (700 = 7%).

commissions[].fixed_fee_centsinteger

Taxa fixa aplicada, em centavos.

commissions[].commission_amountinteger

order_amount * commission_bps / 10000 + fixed_fee_cents, em centavos.

commissions[].statusstring

OACI

Letra do estado: O pendente, A aprovada, C paga, I cancelada.

commissions[].paid_atstring

Quando foi marcada como paga. Só nas pagas.

commissions[].created_atstring

Criação, RFC 3339 em UTC.

commissions[].updated_atstring

Última alteração.

totalinteger

Total com o filtro.

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página usado.

total_pagesinteger

Total de páginas.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"commissions"}` / `{"error":"insufficient privileges","required":"manage_vendors"}`
500	`date_from`/`date_to` fora de `YYYY-MM-DD` ou falha na consulta (a mensagem do campo `detail` pode sugerir outro formato, ignore: vale `YYYY-MM-DD`)	`{"error":"failed to list commissions","detail":"..."}`

Aprovar comissão

Move uma comissão de pending (O) para approved (A). Só funciona a partir de pendente. É o primeiro passo do fluxo manual de conferência.

PUT/api/v1/admin/commissions/{id}/approveAdmin

Aprova uma comissão por plano pendente

Parâmetros de caminho

idintegerobrigatório

Identificador numérico da comissão, o id da lista.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/commissions/36975/approve" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Aprovada

json

{
  "status": "approved"
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"commissions"}` / `{"error":"insufficient privileges","required":"manage_vendors"}`
400	`id` zero ou negativo, `id` que não é número, comissão inexistente ou fora do estado pendente	`{"error":"invalid id parameter"}` / `{"error":"invalid commission id"}` / `{"error":"failed to approve commission","detail":"commission 36975 not found or not in pending status"}`

Marcar como paga

Move de approved (A) para paid (C) e grava paid_at. Só funciona a partir de aprovada: não dá para pular a aprovação.

PUT/api/v1/admin/commissions/{id}/payAdmin

Marca uma comissão por plano aprovada como paga

Parâmetros de caminho

idintegerobrigatório

Identificador numérico da comissão.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/commissions/36975/pay" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Marcada como paga

json

{
  "status": "paid"
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido, ou módulo desligado	`{"error":"module_disabled","module":"commissions"}` / `{"error":"insufficient privileges","required":"manage_vendors"}`
400	`id` zero, negativo ou não numérico, comissão inexistente ou fora do estado aprovada	`{"error":"invalid id parameter"}` / `{"error":"failed to mark commission as paid","detail":"commission 36975 not found or not in approved status"}`