Mercado Fácil

Wrapper simples e intuitivo para a API do Mercado Pago. Sintaxe em português clara e fácil.

🚀 Instalação

npm install mercado-facil

🔑 Uso Básico

IMPORTANTE: Use apenas no backend. Nunca exponha seu access token no frontend.

import MercadoFacil from 'mercado-facil';

const mp = new MercadoFacil('SEU_ACCESS_TOKEN');

🛒 Criar Checkout (Item Único)

const pagamento = await mp.criarCheckout({
  titulo: 'VIP Premium',
  preco: 10,
  quantidade: 1,
  sucesso: 'https://site.com/sucesso',
  falha: 'https://site.com/falha',
  pendente: 'https://site.com/pendente',
  referencia: 'pedido123'
});

console.log(pagamento.link); // URL para pagamento

🛒 Criar Checkout (Múltiplos Itens)

const pagamento = await mp.criarCheckout({
  itens: [
    { titulo: 'VIP', preco: 10, quantidade: 1 },
    { titulo: 'Moedas', preco: 5, quantidade: 2 }
  ],
  sucesso: 'https://site.com/sucesso',
  referencia: 'pedido456'
});

✅ Verificar Pagamento

const info = await mp.verificarPagamento('ID_DO_PAGAMENTO');
console.log(info.status); // approved, pending, rejected...
console.log(info.valor);

📋 Parâmetros do criarCheckout

Item Único:

• titulo (obrigatório): Nome do produto
• preco (obrigatório): Valor unitário
• quantidade (opcional): padrão 1

Múltiplos Itens:

• itens (obrigatório): Array de objetos com titulo, preco, quantidade?

Gerais:

• sucesso: URL após pagamento aprovado
• falha: URL após falha
• pendente: URL após pendente
• referencia: Seu ID interno do pedido
• retornoAutomatico: 'approved' | 'pending' (padrão approved se sucesso existir)

📤 Retorno do criarCheckout

{
  id: 'preferencia_123',
  link: 'https://www.mercadopago.com.br/checkout/v1/...',
  sandbox: 'https://sandbox...',
  raw: { /* resposta completa API */ }
}

🔍 Retorno do verificarPagamento

{
  id: 123456,
  status: 'approved',
  statusDetalhe: 'accredited',
  valor: 10.00,
  descricao: 'PIX - PIX +2202',
  metodo: 'pix',
  tipo: 'ticket',
  raw: { /* resposta completa API */ }
}

⚠️ Segurança

• ✅ Use apenas no backend (Node.js)
• ❌ NUNCA use access token no frontend
• ✅ Obtenha token em: Painel Mercado Pago

🚫 Erros Comuns

Informe o access token do Mercado Pago
Informe o titulo e preco do produto
Cada item precisa de titulo e preco
Preco e quantidade invalidos
Erro ao criar checkout: [motivo da API]

💡 Dicas Importantes

• Teste primeiro no sandbox (use pagamento.sandbox)
• URLs de retorno devem ser HTTPS em produção
• auto_return redireciona automaticamente se pagamento aprovado
• Guarde o id da preferência para tracking
• Verifique sempre o status real do pagamento via API

📖 Licença

MIT