Como Integrar o Mercado Pago e Emitir Notas Fiscais Automaticamente
Tutorial completo de integração com o Mercado Pago Checkout Pro, Webhooks em tempo real e sincronização retroativa de vendas.
O conector do Mercado Pago no NFER permite emitir NF-e (Produtos), NFS-e (Serviços) e Split Fiscal de forma automática para pagamentos aprovados via Pix, Cartão de Crédito, Boleto e Saldo em Conta.
Assim que o cliente efetua o pagamento, o Mercado Pago notifica o NFER instantaneamente e a nota fiscal é processada sem filas de espera.
Com seu Access Token, você pode puxar todo o histórico de vendas de períodos passados e executar auto-enriquecimento de cadastros pela API.
Passo a Passo de Configuração
Siga os passos abaixo para conectar sua conta do Mercado Pago à NFER em poucos minutos:
Acesse o painel oficial do Mercado Pago Developers com sua conta comercial e clique em Criar aplicação.
- Nome da aplicação:
NFER Emissor Fiscal(ou o nome da sua empresa). - Tipo de solução de pagamento: Pagamentos on-line.
- Usa plataforma de e-commerce?: Sim → Selecione Outras Plataformas.
- Qual produto está integrando?: CheckoutPro.
Concorde com os termos e clique em Criar aplicação.
Na tela da sua aplicação recém-criada, acesse Produção → Credenciais de produção:
- Preencha o campo Setor (ex.: Serviços de TI ou Varejo).
- No campo Site, informe o link da sua loja ou site institucional.
- Clique em Ativar credenciais de produção.
- Copie o Access Token (código que se inicia com
APP_USR-).
No painel da NFER, vá em Apps → Mercado Pago e cole esse Access Token no campo correspondente.
Para receber as vendas no segundo exato em que são aprovadas:
- No NFER (em Apps → Mercado Pago), copie sua URL exclusiva de Webhook.
- No Mercado Pago Developers, acesse o menu lateral Notificações Webhooks.
- Em Modo Produção, cole a URL copiada.
- No seletor de eventos, marque a opção Pagamentos (payment).
- (Opcional) Copie a Chave Secreta (Secret) do webhook e cole na NFER para ativação de verificação HMAC-SHA256.
Se você já realizou vendas no Mercado Pago antes de habilitar a NFER:
Basta definir a Data de Início no modal do Mercado Pago na NFER e clicar em Sincronizar Vendas. O NFER consultará a API oficial (/v1/payments/search) e importará todas as vendas aprovadas do período para o seu painel.
Dados Exigidos para Emissão da Nota Fiscal
Para que uma venda gere documento fiscal válido na SEFAZ ou Prefeitura, os seguintes dados devem ser repassados:
| Campo | Onde Enviar no Payload | Exemplo |
|---|---|---|
| CPF ou CNPJ Válido | payer.identification.number e metadata.cpf | 12345678909 (11 dígitos válidos) |
| Nome Completo / Razão Social | payer.name + surname e metadata.buyer_name | João da Silva |
| E-mail do Cliente | payer.email e metadata.email | cliente@email.com |
| Telefone / WhatsApp | payer.phone e metadata.telefone | (11) 98765-4321 |
| CEP | payer.address.zip_code e metadata.cep | 01310-100 |
| Endereço Completo | payer.address e metadata (logradouro, numero, bairro, cidade, uf) | Av. Paulista, 1000 - Bela Vista, SP |
Exemplo de Criação de Preferência (Checkout Pro)
Ao gerar o link de pagamento da reserva ou pedido no backend do seu site através de POST https://api.mercadopago.com/checkout/preferences, envie a estrutura completa:
Perguntas Frequentes (FAQ)
Quais dados meu site/checkout precisa enviar para o Mercado Pago não travar a nota?
Se o lojista não coletar os dados do pagador no checkout, o Mercado Pago não disponibiliza os dados pela API e a nota não pode ser emitida. Você deve coletar e enviar: Nome completo, CPF ou CNPJ válido, E-mail, Telefone e Endereço com CEP, logradouro, número, bairro, cidade e estado. A dica de ouro é enviar esses dados no objeto payer e também repeti-los no objeto metadata.
Por que algumas vendas chegam sem endereço ou com CPF inválido no NFER?
No Checkout Pro, quando o comprador paga logado na conta pessoal do Mercado Pago ou usando saldo em conta, a plataforma oculta os dados pessoais cadastrais por regras de privacidade (LGPD). Se a sua loja não injetar previamente os dados de faturamento na criação do link, o Mercado Pago omite o endereço na API e o NFER não consegue emitir a nota.
Como emitir NF-e (Produto) se o Mercado Pago não possui campo de NCM na API?
A NFER cruza automaticamente o código enviado no campo items[].id com o SKU cadastrado no menu Produtos da sua conta NFER, puxando NCM, CFOP e tributação no automático. Você também pode definir um Produto Padrão nas configurações do Mercado Pago no NFER para servir de modelo fiscal genérico.
Qual a diferença entre o Access Token e o Webhook Secret?
O Access Token (APP_USR-...) é a chave de autorização que a NFER usa para consultar a API do Mercado Pago, buscar histórico de vendas passadas (retroativas) e fazer auto-enriquecimento de dados. Já o Webhook Secret é uma assinatura criptográfica de segurança (HMAC SHA-256) que garante que as notificações de vendas recebidas em tempo real vieram autenticamente do Mercado Pago.
O NFER emite notas para transferências internas ou rendimento de saldo?
Não. O NFER possui filtros automáticos que bloqueiam transferências entre caixinhas, aplicações de rendimento, transferências entre a mesma titularidade ou saques da conta. Somente pagamentos comerciais legítimos de clientes geram faturamento.