mercadopago-pix

Node personalizado do N8N para integração com APIs do Mercado Pago

Package Information

Downloads: 252 weekly / 882 monthly
Latest Version: 1.6.9
Author: Georgivan Costa

Available Nodes

Mercado Pago icon
Mercado Pago
Integração com APIs do Mercado Pago para processamento de pagamentos

Documentation

N8N Mercado Pago Node

NPM Version
NPM Downloads
Node.js Compatibility

⚠️ VERSÃO BETA - Este projeto está em fase de testes e desenvolvimento ativo. Algumas funcionalidades podem estar instáveis ou incompletas.

✅ PUBLICADO OFICIALMENTE NO NPM REGISTRY

🎯 TESTE GRATUITO DISPONÍVEL!

🚀 QUER TESTAR TODAS AS FUNCIONALIDADES PREMIUM GRATUITAMENTE?

✨ É possível testar TODAS as funcionalidades premium sem custo!

  • 🔍 Consultar Pagamentos: Verificar status e detalhes
  • 🔎 Buscar Pagamentos: Filtros avançados por critérios
  • ✏️ Atualizar Pagamentos: Modificar pagamentos existentes
  • 💰 Reembolsar Pagamentos: Processar reembolsos totais/parciais

📱 Solicite seu teste gratuito agora:

Teste completo das funcionalidades premium por tempo limitado - sem compromisso!

Node personalizado do N8N para integração com as APIs do Mercado Pago, permitindo processar pagamentos PIX, criar preferências de checkout e gerenciar transações.

🔑 CONFIGURAÇÃO OBRIGATÓRIA - TOKEN API

⚠️ ATENÇÃO: Para funcionar, você DEVE configurar um token válido do Mercado Pago!

🧪 Como Obter Token de Teste (GRATUITO)

1. Acesse sua Conta Mercado Pago

2. Crie uma Aplicação

  • Clique em "Criar aplicação"
  • Escolha "Pagamentos online"
  • Preencha os dados básicos

3. Obtenha suas Credenciais

  • Na aba "Credenciais"
  • Para Testes: Copie o Access Token de Teste (começa com TEST-)
  • Para Vendas Reais: Copie o Access Token de Produção (começa com APP_USR-)

⚠️ IMPORTANTE: Para processar pagamentos reais e receber o dinheiro, você DEVE usar o token de produção!

🔧 Configuração no N8N

1. Adicionar Credencial

  1. No N8N, vá em Credentials
  2. Clique em + Add Credential
  3. Procure por Mercado Pago API
  4. Preencha os campos:

Para Testes:

Access Token: TEST-1234567890123456-123456-abcdef1234567890abcdef1234567890-123456789
Environment: Sandbox (Testes)

Para Vendas Reais:

Access Token: APP_USR-1234567890123456-123456-abcdef1234567890abcdef1234567890-123456789
Environment: Production (Produção)

2. Exemplos de Tokens Válidos

Token de Teste:

TEST-1234567890123456-123456-abcdef1234567890abcdef1234567890-123456789

Token de Produção:

APP_USR-1234567890123456-123456-abcdef1234567890abcdef1234567890-123456789

3. Configurar no Workflow

  1. Adicione o nó Mercado Pago
  2. Selecione a credencial criada
  3. Configure a operação desejada

💡 Dicas Importantes

  • ✅ Token de Teste: Gratuito, para desenvolvimento e testes (começa com TEST-)
  • 🚀 Token de Produção: OBRIGATÓRIO para vendas reais (começa com APP_USR-)
  • ⚠️ ATENÇÃO: Para processar pagamentos reais, você DEVE usar o token de produção
  • 🔒 Nunca compartilhe seus tokens
  • 🔄 Tokens expiram: Verifique periodicamente
  • 💰 Vendas Reais: Apenas com token de produção os pagamentos são processados de verdade

🚀 Testando a Configuração

Workflow de Teste Simples:

{
  "description": "Pagamento PIX - Teste",
  "transaction_amount": 10.50,
  "payment_method_id": "pix",
  "payer_email": "teste@exemplo.com",
  "payer_first_name": "João",
  "external_reference": "TESTE-001"
}

🆘 Problemas Comuns

Erro: "Access Token é obrigatório"

  • Solução: Configure a credencial do Mercado Pago

Erro: "Token muito curto"

  • Solução: Verifique se copiou o token completo

Erro: "Formato inválido"

  • Solução: Token de teste deve começar com TEST-

Lembre-se: O token é como uma "chave" que permite ao N8N se comunicar com o Mercado Pago. Sem ele, não é possível processar pagamentos! 🔐

🔒 Funcionalidades

🆓 Funcionalidades Gratuitas

  • ✅ Criar Pagamentos PIX: Ilimitado e sem restrições
  • ✅ Configuração de Credenciais: Acesso completo

💎 Funcionalidades Premium

  • 🔍 Consultar Pagamentos: Verificar status e detalhes
  • 🔎 Buscar Pagamentos: Filtros avançados por critérios
  • ✏️ Atualizar Pagamentos: Modificar pagamentos existentes
  • 💰 Reembolsar Pagamentos: Processar reembolsos totais/parciais

📱 Adquirir Licença Premium

WhatsApp: +55 84 99976-4273
Contato: Georgivan Costa
Licenças: Individuais por instância N8N

💝 Apoie o Projeto

Se este projeto te ajudou, considere fazer uma doação PIX para apoiar o desenvolvimento:

PIX para Doações

Sua contribuição ajuda a manter este projeto ativo e em constante evolução! 🚀

👨‍💻 Autor

Georgivan Costa - Especialista em Automações com IA

Siga para mais conteúdo sobre automações, IA e desenvolvimento!

📞 Contato

Desenvolvedor

WhatsApp: +55 84 99976-4273

Para suporte técnico ou dúvidas sobre licenciamento, entre em contato via WhatsApp.

Sistema de Proteção de Licenças N8N - Mercado Pago

Este projeto implementa um sistema completo de proteção de licenças para o nó N8N do Mercado Pago, incluindo:

  • ✅ Sistema de licenças criptografadas
  • ✅ Controle de instâncias únicas
  • ✅ Ofuscação de código
  • ✅ Validação rigorosa de licenças

Desenvolvido com foco em segurança e proteção contra uso não autorizado.

🎉 VERSÃO 1.2.8 - CORREÇÕES CRÍTICAS IMPLEMENTADAS

  • 🔧 PROBLEMA RESOLVIDO: Marketplace fee automático removido (causava erros OAuth)
  • ✅ PIX FUNCIONANDO: Estrutura do payer corrigida conforme documentação oficial
  • 🚀 COMPATIBILIDADE: Suporte completo para Node.js v24+
  • 📦 INSTALAÇÃO DIRETA: Disponível via npm install n8n-nodes-mercadopago-pix

Funcionalidades

🎯 INTERFACE INTELIGENTE (Novidade v1.5.2)

  • Campo de Licença Dinâmico: Aparece apenas quando necessário
  • "Criar Pagamentos": Interface limpa, sem campos de licença (100% gratuito)
  • Operações Premium: Campo de licença obrigatório e visível automaticamente
  • Experiência Otimizada: Menos confusão, mais produtividade

🔐 Autenticação

  • Suporte para Access Token do Mercado Pago
  • Configuração de ambiente (Sandbox/Production)
  • Autenticação automática via Bearer Token

💳 Pagamentos (Payment) - Modelo Freemium

  • ✨ Criar Pagamento: 100% GRATUITO - Processa pagamentos PIX sem limitações
  • 🔒 Consultar Pagamento: PREMIUM - Obtém informações detalhadas (requer licença)
  • 🔒 Buscar Pagamentos: PREMIUM - Busca por critérios específicos (requer licença)
  • 🔒 Atualizar Pagamento: PREMIUM - Modifica pagamentos existentes (requer licença)
  • 🔒 Reembolsar Pagamento: PREMIUM - Processa reembolsos totais ou parciais (requer licença)

🛒 Preferências (Preference) - Checkout Pro + Split Payments

  • Criar Preferência: Cria preferências para Checkout Pro com marketplace fee automático
  • Consultar Preferência: Obtém dados de uma preferência existente
  • Atualizar Preferência: Modifica preferências existentes com marketplace fee automático

Instalação

Pré-requisitos

  • N8N instalado (versão compatível com community nodes)
  • Node.js ≥18.17.0 (compatível até v24+)
  • Conta no Mercado Pago (sandbox ou produção)
  • Access Token do Mercado Pago

🚀 Instalação via NPM (RECOMENDADO)

O pacote está publicado oficialmente no NPM Registry!

Método 1: Via Interface do N8N

  1. Acesse Settings → Community Nodes no seu N8N
  2. Clique em Install a community node
  3. Digite: n8n-nodes-mercadopago-pix
  4. Clique em Install

Método 2: Via Linha de Comando

# No diretório do N8N
npm install n8n-nodes-mercadopago-pix

Método 3: Via Docker

# No Dockerfile do N8N
RUN npm install -g n8n-nodes-mercadopago-pix

Versão Atual: 1.5.2 ✅ PUBLICADO

Instalação Manual

# Clone o repositório
git clone https://github.com/seu-usuario/n8n-nodes-mercadopago.git
cd n8n-nodes-mercadopago

# Instale as dependências
npm install

# Compile o projeto
npm run build

# Publique no npm (opcional)
npm publish

Configuração

1. Obter Credenciais do Mercado Pago

  1. Acesse Mercado Pago Developers
  2. Faça login na sua conta
  3. Vá para Suas integrações > Credenciais
  4. Copie o Access Token (sandbox ou produção)

2. Configurar Credenciais no N8N

  1. No N8N, vá para Credentials
  2. Clique em + Add Credential
  3. Procure por Mercado Pago API
  4. Preencha:
    • Access Token: Seu token do Mercado Pago
    • Environment: Sandbox (testes) ou Production (produção)
  5. Teste a conexão e salve

Como Usar

Exemplo 1: Criar um Pagamento

{
  "resource": "payment",
  "operation": "create",
  "transactionAmount": 100.50,
  "paymentMethodId": "pix",
  "payerEmail": "cliente@email.com"
}

Exemplo 2: Criar Preferência de Checkout

{
  "resource": "preference",
  "operation": "create",
  "items": [
    {
      "title": "Produto Exemplo",
      "quantity": 1,
      "unit_price": 100.50
    }
  ]
}

Exemplo 3: Consultar Status de Pagamento

{
  "resource": "payment",
  "operation": "get",
  "paymentId": "123456789"
}

Métodos de Pagamento Suportados

Brasil

  • PIX: pix
  • Cartão de Crédito: visa, master, amex, elo, hipercard
  • Boleto: bolbradesco, boletobancario
  • Débito: debvisa, debmaster

Argentina

  • Cartão de Crédito: visa, master, amex
  • Transferência: rapipago, pagofacil

México

  • Cartão de Crédito: visa, master, amex
  • OXXO: oxxo
  • SPEI: bancomer, banamex

Estrutura de Resposta

Pagamento Criado

{
  "id": 123456789,
  "status": "approved",
  "status_detail": "accredited",
  "transaction_amount": 100.50,
  "currency_id": "BRL",
  "payment_method_id": "pix",
  "payer": {
    "email": "cliente@email.com"
  },
  "date_created": "2024-01-15T10:30:00.000Z"
}

Preferência Criada

{
  "id": "123456789-abcd-1234-efgh-567890123456",
  "init_point": "https://www.mercadopago.com.br/checkout/v1/redirect?pref_id=123456789-abcd-1234-efgh-567890123456",
  "sandbox_init_point": "https://sandbox.mercadopago.com.br/checkout/v1/redirect?pref_id=123456789-abcd-1234-efgh-567890123456",
  "items": [
    {
      "title": "Produto Exemplo",
      "quantity": 1,
      "unit_price": 100.50
    }
  ]
}

Status de Pagamento

Status Descrição
pending Pagamento pendente
approved Pagamento aprovado
authorized Pagamento autorizado
in_process Pagamento em processamento
in_mediation Pagamento em mediação
rejected Pagamento rejeitado
cancelled Pagamento cancelado
refunded Pagamento reembolsado
charged_back Pagamento com chargeback

Tratamento de Erros

O node trata automaticamente os seguintes tipos de erro:

  • 401 Unauthorized: Token inválido ou expirado
  • 400 Bad Request: Dados inválidos na requisição
  • 404 Not Found: Recurso não encontrado
  • 500 Internal Server Error: Erro interno do Mercado Pago

Webhooks

Para receber notificações de mudança de status dos pagamentos:

  1. Configure um webhook no Mercado Pago
  2. Use o node Webhook do N8N para receber as notificações
  3. Configure a URL do webhook: https://seu-n8n.com/webhook/mercadopago

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou pull requests.

Licença

MIT License - veja o arquivo LICENSE para detalhes.

Suporte

Changelog

v1.5.2 (ATUAL) ✅ PUBLICADO NO NPM

  • 🎯 INTERFACE INTELIGENTE: Campo de licença dinâmico - só aparece quando necessário
  • ✨ EXPERIÊNCIA APRIMORADA: "Criar Pagamentos" sem obstáculos visuais (campo oculto)
  • 🔒 LICENÇA CONTEXTUAL: Campo obrigatório apenas para operações premium
  • 🛡️ SISTEMA DE PROTEÇÃO: Código ofuscado e sistema de licenças criptografadas
  • 📱 CONTATO INTEGRADO: WhatsApp +55 84 99976-4273 para licenças premium
  • 🔐 VALIDAÇÃO INTELIGENTE: Sistema de licenças por operação específica
  • ⚡ OTIMIZAÇÕES: Melhorias de performance e estabilidade

v1.5.1

  • 📖 DOCUMENTAÇÃO COMPLETA: Guia detalhado de configuração do token
  • 🚀 WORKFLOW DE EXEMPLO: Template completo com instruções passo-a-passo
  • ✅ CONFIGURAÇÃO SIMPLIFICADA: README atualizado com seção destacada

v1.5.0

  • 🔧 VALIDAÇÕES FLEXÍVEIS: Credenciais simplificadas para melhor compatibilidade
  • ✨ MODELO FREEMIUM: Criação de pagamentos PIX 100% gratuita
  • 🔒 FUNCIONALIDADES PREMIUM: Buscar, consultar, atualizar e reembolsar requerem licença

v1.2.9

  • 🔧 CORREÇÃO CRÍTICA: Corrigida configuração de URL base nas credenciais que causava erro "URL inválida"
  • ✅ VALIDAÇÕES ROBUSTAS: Adicionadas validações obrigatórias para parâmetros de pagamento PIX
  • ✅ MARKETPLACE FEE: Removido completamente da operação 'update' de preferências
  • ✅ TRATAMENTO DE ERROS: Melhorado tratamento de erros com mensagens mais específicas

v1.2.8

  • 🔧 CORREÇÃO CRÍTICA: Removido marketplace fee automático (causava erros OAuth)
  • 🔧 COMPATIBILIDADE: Suporte para Node.js v24+ (removido limite <22.0.0)
  • 🔧 DEPENDÊNCIAS: Removida dependência circular problemática
  • ✅ ESTRUTURA PAYER: Corrigida conforme documentação oficial MercadoPago
  • ✅ ENDPOINTS: Validados todos os endpoints da API
  • ✅ PIX: Funcionamento 100% testado e validado
  • ✅ PUBLICAÇÃO: Disponível oficialmente no NPM Registry
  • ✅ INSTALAÇÃO: Compatível com instalação direta no N8N

v1.2.7

  • 🔧 Correções na estrutura do payer
  • 🔧 Ajustes nos endpoints da API
  • ⚠️ Problemas com marketplace fee (corrigido em v1.2.8)

v1.0.0

  • ✅ Implementação inicial
  • ✅ Suporte para pagamentos diretos
  • ✅ Suporte para preferências de checkout
  • ✅ Gestão básica de clientes
  • ✅ Autenticação via Access Token
  • ✅ Suporte para ambientes sandbox e produção

Discussion