Razão de comissões

Consulta e ajusta as entradas do razão: uma linha por item vendido, com a parte da loja e a parte do seller.

O razão (ledger) é o extrato da comissão. Quando um pedido de seller é concluído, a plataforma cria uma entrada por item, aplica a regra escolhida e grava quanto fica com a loja e quanto com o seller. É esse extrato que alimenta o saldo do seller e os repasses.

Listar entradas do razão

Lista as linhas do razão, da mais recente para a mais antiga, com filtro por seller e por estado. É o extrato de tudo que a loja reteve e de tudo que cada seller tem a receber.

GET/api/v1/admin/commission-entriesAdmin

Lista as entradas do razão de comissões

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

Filtra por seller. Aceita o UUID ou um trecho do nome, do slug ou do e-mail do seller (busca sem diferenciar maiúsculas).

statusstring

pendingconfirmedsettledPAS

Estado da entrada: pending, confirmed, settled ou a letra P, A, S. Outro valor não casa com nada e a lista volta vazia.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

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

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/commission-entries?status=confirmed&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Entradas devolvidas

json

{
  "entries": [
    {
      "id": "82fd7077-0479-4457-bd8e-8b21006ff207",
      "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
      "order_item_id": "a43b9f10-5590-424b-87c8-dffa34bae43d",
      "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "rule_id": "c962f0d4-b899-4055-b156-e559873970eb",
      "item_amount": 4266,
      "commission_amount": 426,
      "vendor_amount": 3840,
      "status": "P",
      "created_at": "2026-10-11T21:06:42.025492Z"
    }
  ],
  "total": 41269,
  "page": 1,
  "per_page": 20,
  "total_pages": 2064
}

Campos da resposta

entriesarray

Entradas da página.

entries[].iduuid

Identificador da entrada.

entries[].order_iduuid

Pedido do seller (sub-pedido) de origem.

entries[].order_item_iduuid | null

Item do pedido. Há no máximo uma entrada por item.

entries[].vendor_iduuid

Seller que vendeu.

entries[].rule_iduuid | null

Regra aplicada. null quando nenhuma regra casou (comissão zero).

entries[].item_amountinteger

Valor da linha do item, em centavos.

entries[].commission_amountinteger

Parte da loja, em centavos.

entries[].vendor_amountinteger

Parte do seller, em centavos (item_amount - commission_amount).

entries[].statusstring

PAS

Letra do estado: P pendente, A confirmada, S liquidada. Veja o ciclo na página inicial da seção.

entries[].created_atstring

Criação, RFC 3339 em UTC.

totalinteger

Total de entradas com o filtro.

pageinteger

Página devolvida.

per_pageinteger

Tamanho da página efetivamente 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	Falha na consulta	`{"error":"failed to list commission entries","detail":"..."}`

Alterar o estado de uma entrada

Move uma entrada entre os estados pending, confirmed e settled. É um ajuste manual do operador: o caminho normal é automático (a confirmação ocorre sozinha após a janela de retenção e a liquidação acontece quando um repasse é gerado ou concluído).

PATCH/api/v1/admin/commission-entries/{id}/statusAdmin

Altera o estado de uma entrada do razão

Parâmetros de caminho

iduuidobrigatório

Identificador da entrada.

Corpo da requisição

statusstringobrigatório

pendingconfirmedsettledPAS

Novo estado. Palavra ou letra.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/admin/commission-entries/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "confirmed"
  }'

Resposta

200Estado alterado

json

{
  "status": "confirmed"
}

A resposta ecoa o valor enviado, não a letra gravada. Um id inexistente também responde 200: nada é alterado e nenhum erro é devolvido.

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	`status` vazio, ausente ou fora de `pending`/`confirmed`/`settled` (o texto de `detail` volta em português)	`{"error":"invalid status","detail":"status de entrada de comissão inválido: ..."}`
500	`id` que não é UUID ou falha ao gravar	`{"error":"failed to update entry status","detail":"..."}`

Faturas de comissão

Rota mantida por compatibilidade com a plataforma antiga, que emitia uma fatura mensal de comissão por seller. Na plataforma atual essas faturas não são geradas: a resposta é sempre uma lista vazia. Para o extrato de comissões use a lista de entradas do razão, acima.

GET/api/v1/admin/commission-invoicesAdmin

Lista as faturas mensais de comissão (compatibilidade)

Autenticação: Authorization: Bearer <token> de um administrador. Esta rota não depende do módulo commissions.

Sem parâmetros.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/commission-invoices" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Sempre vazia

json

{
  "invoices": [],
  "total": 0,
  "source": "ec_accounting_page"
}

Campos da resposta

invoicesarray

Sempre vazio.

totalinteger

Sempre 0.

sourcestring

Nome do módulo de origem na plataforma antiga. Informativo.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`

Veja também

API atual/Referência completa/Comissões

Razão de comissões

Consulta e ajusta as entradas do razão: uma linha por item vendido, com a parte da loja e a parte do seller.

Listar entradas do razão

Lista as linhas do razão, da mais recente para a mais antiga, com filtro por seller e por estado. É o extrato de tudo que a loja reteve e de tudo que cada seller tem a receber.

GET/api/v1/admin/commission-entriesAdmin

Lista as entradas do razão de comissões

Parâmetros de consulta

vendor_idstring

Filtra por seller. Aceita o UUID ou um trecho do nome, do slug ou do e-mail do seller (busca sem diferenciar maiúsculas).

statusstring

pendingconfirmedsettledPAS

Estado da entrada: pending, confirmed, settled ou a letra P, A, S. Outro valor não casa com nada e a lista volta vazia.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

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

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/commission-entries?status=confirmed&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Entradas devolvidas

json

{
  "entries": [
    {
      "id": "82fd7077-0479-4457-bd8e-8b21006ff207",
      "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
      "order_item_id": "a43b9f10-5590-424b-87c8-dffa34bae43d",
      "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "rule_id": "c962f0d4-b899-4055-b156-e559873970eb",
      "item_amount": 4266,
      "commission_amount": 426,
      "vendor_amount": 3840,
      "status": "P",
      "created_at": "2026-10-11T21:06:42.025492Z"
    }
  ],
  "total": 41269,
  "page": 1,
  "per_page": 20,
  "total_pages": 2064
}

Campos da resposta

entriesarray

Entradas da página.

entries[].iduuid

Identificador da entrada.

entries[].order_iduuid

Pedido do seller (sub-pedido) de origem.

entries[].order_item_iduuid | null

Item do pedido. Há no máximo uma entrada por item.

entries[].vendor_iduuid

Seller que vendeu.

entries[].rule_iduuid | null

Regra aplicada. null quando nenhuma regra casou (comissão zero).

entries[].item_amountinteger

Valor da linha do item, em centavos.

entries[].commission_amountinteger

Parte da loja, em centavos.

entries[].vendor_amountinteger

Parte do seller, em centavos (item_amount - commission_amount).

entries[].statusstring

PAS

Letra do estado: P pendente, A confirmada, S liquidada. Veja o ciclo na página inicial da seção.

entries[].created_atstring

Criação, RFC 3339 em UTC.

totalinteger

Total de entradas com o filtro.

pageinteger

Página devolvida.

per_pageinteger

Tamanho da página efetivamente 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	Falha na consulta	`{"error":"failed to list commission entries","detail":"..."}`

Alterar o estado de uma entrada

PATCH/api/v1/admin/commission-entries/{id}/statusAdmin

Altera o estado de uma entrada do razão

Parâmetros de caminho

iduuidobrigatório

Identificador da entrada.

Corpo da requisição

statusstringobrigatório

pendingconfirmedsettledPAS

Novo estado. Palavra ou letra.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/admin/commission-entries/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "confirmed"
  }'

Resposta

200Estado alterado

json

{
  "status": "confirmed"
}

A resposta ecoa o valor enviado, não a letra gravada. Um id inexistente também responde 200: nada é alterado e nenhum erro é devolvido.

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	`status` vazio, ausente ou fora de `pending`/`confirmed`/`settled` (o texto de `detail` volta em português)	`{"error":"invalid status","detail":"status de entrada de comissão inválido: ..."}`
500	`id` que não é UUID ou falha ao gravar	`{"error":"failed to update entry status","detail":"..."}`

Faturas de comissão

GET/api/v1/admin/commission-invoicesAdmin

Lista as faturas mensais de comissão (compatibilidade)

Autenticação: Authorization: Bearer <token> de um administrador. Esta rota não depende do módulo commissions.

Sem parâmetros.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/commission-invoices" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Sempre vazia

json

{
  "invoices": [],
  "total": 0,
  "source": "ec_accounting_page"
}

Campos da resposta

invoicesarray

Sempre vazio.

totalinteger

Sempre 0.

sourcestring

Nome do módulo de origem na plataforma antiga. Informativo.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`