mercadopago-pix

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

Package Information

Released: 8/30/2025

Downloads: 114 weekly / 468 monthly

Latest Version: 1.2.9

Author: georgivancosta

Available Nodes

Mercado Pago

Integração com APIs do Mercado Pago

Documentation

N8N Mercado Pago Node

✅ PUBLICADO OFICIALMENTE NO NPM REGISTRY

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.

🎉 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

🔐 Autenticação

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

💳 Pagamentos (Payment) - Split Payments Suportado

Criar Pagamento: Processa pagamentos diretos via Checkout API com marketplace fee automático
Consultar Pagamento: Obtém informações detalhadas de um pagamento
Reembolsar Pagamento: Processa reembolsos totais ou parciais

🛒 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

Acesse Settings → Community Nodes no seu N8N
Clique em Install a community node
Digite: n8n-nodes-mercadopago-pix
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.2.8 ✅ 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

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

2. Configurar Credenciais no N8N

No N8N, vá para Credentials
Clique em + Add Credential
Procure por Mercado Pago API
Preencha:
- Access Token: Seu token do Mercado Pago
- Environment: Sandbox (testes) ou Production (produção)
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:

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

Publicação no NPM

Pré-requisitos para Publicação

Conta no NPM: Crie uma conta em npmjs.com
Repositório Git: Configure um repositório público no GitHub
Autenticação: Faça login no NPM via CLI

Passos para Publicar

# 1. Faça login no NPM
npm login

# 2. Atualize as informações do repositório no package.json
# Substitua "seu-usuario" pela sua conta GitHub real

# 3. Compile o projeto
npm run build

# 4. Verifique se está tudo correto
npm pack --dry-run

# 5. Publique no NPM
npm publish

Checklist de Publicação

✅ package.json configurado com campos obrigatórios
✅ Keyword "n8n-community-node-package" incluída
✅ Seção "n8n" com paths corretos para .js files
✅ README.md com documentação completa
✅ LICENSE incluído (MIT)
✅ Arquivos compilados no diretório dist/
✅ .npmignore configurado corretamente
⚠️ Repositório GitHub público (atualizar URLs)
⚠️ Informações do autor (atualizar email)

Atualizações Necessárias

Antes de publicar, atualize os seguintes campos no package.json:

{
  "repository": {
    "url": "git+https://github.com/SEU-USUARIO/n8n-nodes-mercadopago.git"
  },
  "homepage": "https://github.com/SEU-USUARIO/n8n-nodes-mercadopago#readme",
  "bugs": {
    "url": "https://github.com/SEU-USUARIO/n8n-nodes-mercadopago/issues"
  },
  "author": {
    "name": "Seu Nome",
    "email": "seu-email@exemplo.com"
  }
}

Desenvolvimento

Estrutura do Projeto

n8n-nodes-mercadopago/
├── credentials/
│   └── MercadoPagoApi.credentials.ts
├── nodes/
│   └── MercadoPago/
│       ├── MercadoPago.node.ts
│       ├── MercadoPago.node.json
│       └── mercadopago.svg
├── dist/                 # Arquivos compilados
├── examples/             # Exemplos de workflow
├── package.json
├── tsconfig.json
├── eslint.config.js
├── .npmignore
└── README.md

Scripts Disponíveis

# Compilar o projeto
npm run build

# Modo de desenvolvimento (watch)
npm run dev

# Verificar código
npm run lint

# Corrigir problemas de lint
npm run lintfix

# Formatar código
npm run format

# Simular publicação (verificar conteúdo do pacote)
npm pack --dry-run

# Publicar no NPM
npm publish

Contribuição

Fork o projeto
Crie uma branch para sua feature (git checkout -b feature/nova-funcionalidade)
Commit suas mudanças (git commit -am 'Adiciona nova funcionalidade')
Push para a branch (git push origin feature/nova-funcionalidade)
Abra um Pull Request

Licença

MIT License - veja o arquivo LICENSE para detalhes.

Suporte

Changelog

v1.2.8 (ATUAL) ✅ PUBLICADO NO NPM

🔧 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