MercadoPago Vendas

Acompanhe suas vendas do MercadoPago direto no Claude Code: pagamentos aprovados, taxas cobradas, valor líquido, recebimentos via Pix e a previsão de repasse (liberação de saldo). O plugin consulta a API do MercadoPago, organiza os números e ajuda você a conciliar o que entrou de verdade na conta.

O que faz

O MercadoPago Vendas foi feito para quem vende online no Brasil e precisa entender, sem abrir mil telas no painel, quanto vendeu, quanto pagou de taxa e quando o dinheiro cai.

Com ele você consegue:

• Listar pagamentos aprovados em um período e somar o faturamento bruto.
• Ver o detalhe das taxas do MercadoPago por venda e o valor líquido recebido.
• Separar vendas por meio de pagamento (Pix, cartão de crédito, boleto, saldo em conta).
• Acompanhar repasses e liberação de saldo: o que já está disponível, o que está retido e a data prevista de liberação.
• Conciliar um dia ou período: cruzar pagamentos aprovados com o que será (ou já foi) liberado, identificando estornos, contestações e retenções.

O plugin é voltado a leitura e conciliação. Ele não cria cobranças, não estorna pagamentos e não move saldo.

Instalação

1. Tenha o Claude Code instalado e atualizado.
2. Copie a pasta mercadopago-vendas/ para o diretório de plugins do seu projeto (ex.: .claude/plugins/).
3. Defina a variável de ambiente com o seu access token do MercadoPago (veja Configuração).
4. Reinicie a sessão do Claude Code. Os comandos /relatorio-vendas e /conciliar-repasses ficarão disponíveis.

Comandos disponíveis

• /relatorio-vendas [período] — Relatório de vendas de um dia, mês ou intervalo: total de pagamentos aprovados, faturamento bruto, taxas, valor líquido e quebra por meio de pagamento (com destaque para Pix). Inclui análise do que mudou.
• /conciliar-repasses [data] — Concilia os pagamentos de uma data com os repasses: quanto já foi liberado, quanto está retido, datas previstas de liberação de saldo e qualquer divergência (estornos, contestações, retenções).

Configuração

O plugin usa apenas uma variável de ambiente, com o nome abaixo:

• MERCADOPAGO_ACCESS_TOKEN — access token da sua aplicação/conta MercadoPago.

Recomendações de segurança:

• Use um access token de produção apenas se realmente precisar ver vendas reais; para testes, use o token de sandbox.
• Prefira criar uma aplicação dedicada no painel de desenvolvedores do MercadoPago só para relatórios, em vez de reutilizar o token de uma aplicação que processa cobranças. Assim você isola o acesso.
• Nunca cole o token em arquivos versionados ou em prompts. Defina-o no ambiente do shell ou em um gerenciador de segredos.
• Se o token vazar, revogue-o imediatamente no painel e gere um novo.

Exemplo de uso

Relatório de vendas de um mês:

/relatorio-vendas junho de 2026

Resposta esperada (resumida): total de pagamentos aprovados no mês, faturamento bruto, total de taxas, valor líquido, e a quebra por Pix / cartão / boleto, com uma análise comparando ao período anterior.

Conciliação de um dia específico:

/conciliar-repasses 12/06/2026

O plugin mostra os pagamentos aprovados naquele dia, o valor que será liberado, a data prevista de liberação de saldo e aponta divergências como estornos ou valores retidos.

Segurança e limites

• Leitura e conciliação: o plugin não cria, estorna nem altera pagamentos, e não transfere saldo. Pedidos de escrita devem ser recusados.
• Token isolado: use um MERCADOPAGO_ACCESS_TOKEN de uma aplicação dedicada a relatórios sempre que possível.
• Datas de liberação são previsões: a data de repasse/liberação de saldo informada pela API pode mudar em caso de contestação ou análise antifraude; trate como estimativa.
• Taxas variam: as taxas dependem do seu plano, do meio de pagamento e do prazo de recebimento; o plugin reporta o que a API retorna por transação, não inventa percentuais.
• Pix e prazos: Pix costuma liberar mais rápido que cartão; o relatório separa por meio justamente para deixar os prazos claros.
• Limites de API: períodos longos paginam muitos pagamentos; em contas com alto volume, prefira intervalos curtos (dia ou semana) para evitar throttling.