| name | mercado-pago |
| description | Integra e opera pagamentos Mercado Pago neste projeto. Use esta skill quando a tarefa envolver MCP oficial do Mercado Pago, Checkout Pro, Pix, webhook, validacao de x-signature, credenciais MERCADO_PAGO_*, reconciliacao por external_reference, confirmacao de pagamento, expiracao, cancelamento ou troubleshooting de pagamentos pendentes/expirados/nao reconciliados.
|
Skill: mercado-pago
Skill para trabalhar com Mercado Pago neste repositorio sem perder o contrato interno
de billing ja existente.
Regra de entrada obrigatoria
Antes de executar qualquer tarefa com Mercado Pago:
- Leia
references/repo-integration.md.
- Se a tarefa envolver MCP oficial, conexao de cliente, documentacao oficial ou escolha
entre MCP e API direta, leia
references/official-mcp-and-docs.md.
- Se houver mudanca de codigo, confira os arquivos-chave citados na secao
"Arquivos-chave do projeto".
Nunca trate "pagamento criado", "checkout aberto" ou "usuario voltou para a UI" como
sinonimo de "pagamento aprovado".
Fluxo de decisao
1. Tarefa de documentacao, onboarding ou uso do MCP
Use esta rota quando o usuario pedir:
- conectar o MCP oficial do Mercado Pago;
- descobrir tools oficiais;
- consultar docs do Mercado Pago sem sair do cliente MCP;
- configurar
.mcp.json ou .cursor/mcp.json;
- comparar quando usar MCP vs API HTTP direta.
Acao:
- Ler
references/official-mcp-and-docs.md.
- Verificar se o cliente MCP alvo esta claramente definido.
- Se a tarefa for neste repositorio, alinhar a configuracao local com a documentacao
oficial sem inventar endpoints.
2. Tarefa de implementacao no repositorio
Use esta rota quando o usuario pedir:
- checkout Pix ou Checkout Pro;
- webhook;
- polling/reconciliacao;
- ajustes em planos, ativacao ou billing;
- correcoes de
external_reference, external_payment_id ou expiracao;
- ajustes em
.env.example, config.py, testes e UI de pagamento.
Acao:
- Ler
references/repo-integration.md.
- Preservar a arquitetura interna de
billing.
- Aplicar a mudanca no backend primeiro, depois alinhar frontend/testes.
3. Tarefa de troubleshooting
Use esta rota quando houver:
- pagamento
pending que nao ativa plano;
- pagamento aprovado fora de sincronia com a base local;
- webhook chegando sem validacao;
- expiracao divergente;
- comprador de teste falhando no sandbox;
- erro por credencial
test vs live.
Acao:
- Verificar ambiente efetivo (
MERCADO_PAGO_ENVIRONMENT).
- Verificar
external_reference, external_payment_id e status salvo localmente.
- Verificar se o webhook foi validado antes do processamento.
- Confirmar se a ativacao do plano continua idempotente.
Guardrails obrigatorios
- Nunca expor
access token, webhook secret ou credencial em log, teste ou resposta.
- Nunca marcar um pagamento como aprovado apenas por retorno do frontend.
- Sempre validar
x-signature e x-request-id antes de processar o payload do webhook.
- Sempre manter a ativacao de plano idempotente.
- Sempre persistir o
external_reference local antes de redirecionar o usuario ao checkout.
- Nunca trocar o contrato interno do billing sem alinhar
routes, service e testes.
- Em sandbox, respeitar a regra do projeto para comprador de teste e
payer prefill.
- Nunca usar fallback que esconda falha de webhook, reconciliacao ou credencial.
Checklist de implementacao
Checkout
- Confirmar qual fluxo esta em uso: MCP, Checkout Pro/preference ou API de pagamentos.
- Persistir pagamento local antes de chamar Mercado Pago.
- Definir
external_reference igual ao identificador local quando o projeto depender disso.
- Salvar URL do checkout, QR, payload ou metadados retornados pelo provedor.
- Garantir expiracao coerente com configuracao local.
Webhook
- Receber corpo bruto antes de parsear JSON.
- Validar
x-signature.
- Extrair
data.id e x-request-id.
- Reconsultar o recurso oficial antes de atualizar estado local.
- Fazer processamento idempotente.
Reconciliacao
- Primeiro reconciliar por
external_payment_id quando ele ja existir.
- Se ainda nao existir, buscar por
external_reference.
- Atualizar status local com base no status real do Mercado Pago.
- So ativar plano em status terminal elegivel.
Testes
- Cobrir validacao de assinatura.
- Cobrir callback HTTP.
- Cobrir criacao de checkout com usuario autenticado.
- Cobrir reconciliacao por
external_reference.
- Cobrir regras de sandbox/test user quando aplicavel.
Arquivos-chave do projeto
apps/api/src/modules/billing/mercado_pago.pyapps/api/src/modules/billing/pix.pyapps/api/src/api/routes/billing.pyapps/api/src/core/config.pyapps/api/tests/test_phase8_mercado_pago.py.env.example
Saida esperada
Ao usar esta skill, a resposta final deve deixar claro:
- qual fluxo foi tratado (
MCP, checkout, webhook, reconciliacao ou troubleshooting);
- quais arquivos do repositorio foram alterados;
- quais testes ou verificacoes foram executados;
- quais variaveis de ambiente ou credenciais ainda faltam;
- se a pendencia restante e de codigo, ambiente, webhook publico ou operacao manual.
Referencias
references/repo-integration.mdreferences/official-mcp-and-docs.md
