Carteiras de crédito
O que é a carteira de crédito do cliente, de onde vem o saldo e como o administrador consulta e movimenta.
A carteira (wallet) guarda o crédito da loja de cada cliente: um saldo em reais que ele pode gastar em compras futuras. O saldo nasce de reembolsos enviados à carteira, cashback, programas de indicação, vales-presente e ajustes manuais da equipe. No checkout o cliente aplica o saldo como forma de pagamento. Esta área é o lado do administrador.
Como funciona
- O saldo muda por eventos: reembolso, cashback, ajuste manual, uso no checkout.
- A equipe consulta saldo e extrato quando um cliente reclama.
- A equipe ajusta o saldo com justificativa, reembolsa um pedido para a carteira ou congela a carteira por suspeita de fraude.
Tipo e origem das transações
| Campo | Valores |
|---|---|
type | credit (entrada, amount positivo) e debit (saída, amount negativo). |
reference_type | O que originou o movimento: order, refund, admin, gift_cert, pos_order, cashback, cashback_reversal, referral, vendor_referral, incentive. |
created_by | Usuário que iniciou, ou system. |
Status da carteira
active (ativa) ou frozen (congelada).
Endpoints
| Método | Caminho | Para quê |
|---|---|---|
| GET | /api/v1/admin/wallets | Lista carteiras ou busca clientes |
| GET | /api/v1/admin/wallets/summary | Totais da loja |
| GET | /api/v1/admin/wallets/{user_id} | Saldo de um cliente |
| GET | /api/v1/admin/wallets/{user_id}/transactions | Extrato de um cliente |
| POST | /api/v1/admin/wallets/{user_id}/adjust | Ajuste manual |
| POST | /api/v1/admin/wallets/{user_id}/refund | Reembolso para a carteira |
| POST | /api/v1/admin/wallets/{user_id}/freeze | Congela |
| POST | /api/v1/admin/wallets/{user_id}/unfreeze | Descongela |
Erros comuns
- Usar o id da carteira em vez do
user_id. As rotas usam o id do cliente. - Mandar
user_idmal formado. Volta 500failed to get walletcom mensagem em português sobre UUID inválido (e não 400). - Ajuste sem descrição.
descriptioné obrigatória: 400. - Débito acima do saldo. Volta 400
insufficient wallet balance. - Mexer em carteira congelada. Ajuste e reembolso recusam com 400
wallet is frozen. - Achar que o reembolso para a carteira devolve dinheiro ao cartão. Ele só gera crédito na loja; o estorno financeiro é outro fluxo.