Treinamento: Integração de API PIX

Visão Geral e Escolha do Provedor

Integrar um PIX automatizado envolve quatro atores: sua **aplicação**, seu **cliente**, o **gateway de pagamento** e o **banco do cliente**. O fluxo é simples:

1. Sua aplicação solicita a criação de uma cobrança PIX ao gateway.
2. O gateway devolve um QR Code e um "Copia e Cola".
3. Seu cliente paga usando o app do banco dele.
4. O gateway recebe a confirmação do banco e te notifica via **Webhook**.
5. Sua aplicação processa a notificação e libera o produto/serviço.

A escolha de um bom gateway é crucial. Para simplicidade e qualidade da documentação, recomendamos:

• Stripe: Padrão mundial em experiência do desenvolvedor (DX).
• Mercado Pago: Enorme confiança e popularidade no Brasil.
• Asaas: Focado em automação financeira e com uma API muito direta.

Passo 1: Cadastro e Chaves de API

O primeiro passo prático é criar sua conta no provedor escolhido (Stripe, Mercado Pago, etc.) e navegar até o painel de desenvolvedor para obter suas chaves de API.

Guarde sua chave secreta em um local seguro, como um arquivo .env no seu projeto backend.

Passo 2: Criando a Cobrança PIX (Backend)

Seu servidor é responsável por se comunicar com o gateway para criar a cobrança. Abaixo, um exemplo de como criar uma rota em um servidor Node.js com Express para fazer isso.

📄 server.js (Exemplo com Node.js + Stripe)

const express = require('express');
const app = express();
// Lembre-se de instalar o stripe: npm install stripe
const stripe = require('stripe')('SUA_CHAVE_SECRETA_AQUI');

app.post('/criar-cobranca-pix', async (req, res) => {
  try {
    // Na prática, o valor viria do corpo da requisição (req.body.amount)
    const valorEmCentavos = 1000; // R$ 10,00

    // Cria uma "Payment Intent" no Stripe, que gerará a cobrança PIX
    const paymentIntent = await stripe.paymentIntents.create({
      amount: valorEmCentavos,
      currency: 'brl',
      payment_method_types: ['pix'],
    });

    // A resposta do Stripe contém os dados do QR Code
    const qrCodeData = paymentIntent.next_action.pix_display_qr_code;
    
    res.json({
      qrCodeUrl: qrCodeData.image_url, // URL para uma imagem hospedada do QR Code
      qrCodeText: qrCodeData.data // O texto "Copia e Cola"
    });

  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000, () => console.log('Servidor rodando na porta 3000'));

Passo 3: Exibindo o QR Code (Frontend)

Seu frontend chama a rota que criamos no backend, recebe os dados do PIX e os exibe para o usuário.

📄 index.html (Exemplo de Frontend)

<div id="pix-container">
  <h3>Pague com PIX para finalizar</h3>
  <img id="qr-code-img" src="" alt="PIX QR Code" />
  <div>
    <input id="copia-e-cola" type="text" readonly />
    <button id="copy-btn">Copiar</button>
  </div>
</div>

<script>
  async function carregarPix() {
    const response = await fetch('/criar-cobranca-pix', { method: 'POST' });
    const data = await response.json();

    document.getElementById('qr-code-img').src = data.qrCodeUrl;
    document.getElementById('copia-e-cola').value = data.qrCodeText;
  }

  document.getElementById('copy-btn').addEventListener('click', () => {
    const text = document.getElementById('copia-e-cola');
    text.select();
    navigator.clipboard.writeText(text.value);
    // Adicionar feedback visual de "Copiado!"
  });

  carregarPix();
</script>

Passo 4: Recebendo a Confirmação (Webhook)

Webhooks são a peça central da automação. O gateway envia uma notificação para o seu servidor quando o pagamento é confirmado. Você precisa criar uma rota no seu backend para receber essa notificação.

📄 server.js (continuação)

// Rota para receber notificações do webhook do Stripe
app.post('/webhook-stripe', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['stripe-signature'];
  const endpointSecret = 'SUA_CHAVE_SECRETA_DO_WEBHOOK_AQUI';
  let event;

  try {
    // 1. Verifique a assinatura para garantir que a requisição é legítima
    event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret);
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  // 2. Lide com o evento de pagamento bem-sucedido
  if (event.type === 'payment_intent.succeeded') {
    const paymentIntent = event.data.object;
    console.log('Pagamento recebido!', paymentIntent.id);
    
    // 3. AQUI VAI SUA LÓGICA DE NEGÓCIO:
    // - Atualize o status do pedido no seu banco de dados.
    // - Envie um email de confirmação para o cliente.
    // - Libere o acesso ao produto.
  }

  // Responda com 200 para confirmar o recebimento do evento
  res.status(200).send();
});

Passo 5: Gerando o Comprovante

O "comprovante" não é um arquivo que a API te entrega pronto. A API te entrega os **dados** do pagamento via webhook. Sua aplicação é responsável por usar esses dados para gerar uma confirmação para o usuário.

Com os dados recebidos no webhook do Passo 4, sua lógica de negócio deve:

• Atualizar o Pedido: Encontre o pedido no seu banco de dados e mude seu status de `AGUARDANDO` para `PAGO`.
• Enviar Confirmação: Dispare um e-mail transacional para o cliente confirmando o recebimento do pagamento e os próximos passos.
• Gerar a Confirmação Visual: Crie uma página de "Obrigado" ou um painel de "Meus Pedidos" onde o usuário possa ver os detalhes da transação que você salvou no seu banco de dados (ID da transação, valor, data, etc.). Se necessário, use uma biblioteca como `PDFKit` ou `jsPDF` para gerar um recibo em PDF a partir desses dados.