Comissões
Como a loja calcula, confere e acumula a comissão sobre as vendas dos sellers, e o mapa das rotas do administrador.
Em um marketplace, o cliente paga a loja e a loja repassa ao seller (lojista) o valor da venda menos uma comissão. Esta área define quanto é essa comissão, registra o resultado de cada venda e mostra os totais. O dinheiro que a comissão libera para o seller sai pelos repasses.
São as rotas do administrador da loja. O seller consulta o próprio extrato pelo painel do seller.
Como funciona
Quando um pedido de seller é concluído, a plataforma escolhe uma regra para cada item e grava uma entrada no razão. A entrada nasce pendente, é confirmada sozinha depois de uma janela de retenção (72 horas) e vira liquidada quando entra num repasse.
| Letra | status | Significado |
|---|---|---|
P | pending | Venda registrada, ainda dentro da janela de retenção. Não conta como saldo disponível. |
A | confirmed | Passou a retenção. Já é saldo do seller e pode entrar num repasse. |
S | settled | Já foi paga num repasse. Não entra em outro. |
O fluxo por plano é separado: cada pedido de seller gera uma comissão por plano que o operador leva à mão.
| Letra | status | Significado |
|---|---|---|
O | pending | Calculada com a taxa do plano, aguardando conferência. |
A | approved | Conferida. |
C | paid | Marcada como paga. |
I | cancelled | Cancelada. Fica fora dos totais. |
Conceitos-chave
Pontos-base
Uma taxa percentual é um inteiro em pontos-base: 1000 = 10%, 250 = 2,5%. A comissão de um item é valor * taxa / 10000, com arredondamento para baixo. Uma regra fixed desconta um valor em centavos por item, limitado ao valor do item.
Quem vê o quê
O administrador vê todos os sellers. O seller só enxerga as próprias entradas e o próprio saldo, em rotas do painel do seller que não fazem parte desta seção.
Eventos que movem o razão
A criação das entradas é automática, ao concluir o pedido do seller. Pedidos de marketplaces externos não geram comissão. Para pedidos antigos que ficaram sem entrada, existe o preenchimento de histórico.
Endpoints
| Método | Caminho | Para que serve | Página |
|---|---|---|---|
| GET | /api/v1/admin/commission-rules | Listar regras | Regras |
| POST | /api/v1/admin/commission-rules | Criar regra | Regras |
| PUT | /api/v1/admin/commission-rules/{id} | Alterar regra | Regras |
| DELETE | /api/v1/admin/commission-rules/{id} | Excluir regra | Regras |
| GET | /api/v1/admin/commission-entries | Listar entradas do razão | Razão |
| PATCH | /api/v1/admin/commission-entries/{id}/status | Alterar o estado de uma entrada | Razão |
| GET | /api/v1/admin/commission-invoices | Faturas mensais (sempre vazio) | Razão |
| GET | /api/v1/admin/commission-summary | Resumo do razão | Resumos |
| GET | /api/v1/admin/commissions/summary | Resumo do razão (alternativo) | Resumos |
| GET | /api/v1/admin/commissions/workflow-summary | Resumo do fluxo por plano | Resumos |
| GET | /api/v1/admin/commissions | Listar comissões por plano | Por plano |
| PUT | /api/v1/admin/commissions/{id}/approve | Aprovar | Por plano |
| PUT | /api/v1/admin/commissions/{id}/pay | Marcar como paga | Por plano |
| POST | /api/v1/admin/commissions/backfill | Preencher histórico | Histórico |
Erros comuns
- Mudar a regra e esperar que as vendas antigas mudem. A regra vale só para vendas novas; as entradas gravadas não são recalculadas.
- Criar uma regra por categoria sem a opção ligada. A regra com
category_idé ignorada quando a comissão por categoria está desligada na loja. - Enviar
date_fromcom hora. No fluxo por plano a data éYYYY-MM-DD; outro formato dá500. - Filtrar o razão por
paidoudisputed. Esses estados não existem na coluna; a lista volta vazia. - Ler o resumo errado. O resumo do razão e o resumo do fluxo por plano têm campos diferentes.
- Tratar
PUT /commissions/{id}/paycomo pagamento. Só muda o estado; o dinheiro sai pelos repasses.