Guia rápido

Tudo que você precisa pra começar a receber PIX em 30 minutos.

1 Cadastrar sua empresa

1. Acesse a página /cadastro.
2. Selecione o tipo: Pessoa jurídica (CNPJ) ou Pessoa física (CPF).
3. Preencha nome/razão social, email, documento e telefone.
4. Marque o aceite dos Termos de Uso e Política de Privacidade.
5. Clique em Solicitar cadastro.

2 Ativar seu acesso

1. Quando o admin aprovar, você recebe um email com link de ativação.
2. Abre o link e cria uma senha (mínimo 8 caracteres).
3. Você é logado automaticamente no painel da empresa.

3 Conectar Mercado Pago

Pra começar a receber PIX, você precisa autorizar a plataforma a operar em nome da sua conta MP.

1. No painel da empresa, vai em Mercado Pago (menu lateral).
2. Clica em Conectar com Mercado Pago.
3. Você é redirecionado pro MP. Loga com sua conta MP normal e autoriza.
4. Volta pro painel com badge verde Conectado.

Importante: chave PIX cadastrada

Sua conta MP precisa ter pelo menos uma chave PIX cadastrada no app do Mercado Pago (CPF, CNPJ, email, telefone ou aleatória). Sem chave PIX, o MP rejeita a criação de cobrança com erro "collector user without key".

4 Criar a primeira cobrança

Pelo painel:

1. Aba Dashboard ou Cobranças → botão Nova cobrança.
2. Preenche: valor (ex: R$ 1,00 pra teste), descrição, e validade do QR (default 30min).
3. Clica Criar. O sistema gera o QR e o código copia-cola.
4. Aparece um modal com o link /pay/<id> que você pode mandar pro pagador.

5 Receber pagamento e ver no painel

1. O pagador escaneia o QR (ou cola o código) no app do banco dele.
2. Mercado Pago confirma o pagamento.
3. Em ~1 segundo, o painel atualiza automaticamente (Socket.IO real-time):
   • Status da cobrança vira approved
   • Se você ativou notificação instantânea → email chega na hora
   • Webhook outbound dispara (se configurado)
4. O dinheiro cai na sua conta Mercado Pago, descontados:
   • Taxa do MP (~0,99% PIX)
   • Taxa da plataforma (2,99%, com mínimo R$ 0,49 e máximo R$ 9,99)

6 Cadastrar dispositivo IoT

Se você vai usar ESP32 ou outra placa embarcada com tela:

1. Aba Dispositivos → Novo dispositivo.
2. Preenche nome (ex: "Caixa 1 - Loja Centro"), tipo (esp32) e local.
3. O sistema gera um device token (única vez visível — copie agora!).
4. Use esse token no firmware da placa, no header X-Device-Token.

Veja o Manual ESP32 pra detalhes do hardware e firmware.

7 Configurar webhook (opcional)

Se você quer que seu sistema próprio receba notificações em tempo real:

1. Aba Webhooks → preenche a URL pública do seu sistema.
2. Clica Gerar novo secret e copia o valor (única vez visível).
3. Salva o secret no .env do seu sistema.
4. No seu sistema, valida o header X-MPP-Signature com HMAC SHA256.

Eventos enviados: charge.created, charge.approved, charge.rejected, charge.cancelled, charge.expired.

Retry automático com backoff exponencial em caso de falha (30s, 2min, 10min, 30min, 2h, 6h).

8 Ativar relatórios e notificações

Aba Relatórios:

Notificação instantânea

• Toggle "Receber email a cada pagamento aprovado" — recomendado pro dia-a-dia.
• Email destinatário pode ser diferente do email principal.

Relatórios automáticos

7 tipos disponíveis, cada um com horário e dia configuráveis:

• Diário — resumo das últimas 24h
• Semanal — comparação com semana anterior
• Mensal — fechamento mensal com taxas detalhadas
• Erros — cobranças rejeitadas/canceladas + webhooks falhos
• Cobranças expiradas — quem abriu o QR e não pagou
• Dispositivos offline — placa sem heartbeat há > 6h
• Anomalias — volume 50%+ acima/abaixo da média

9 Integrar com seu sistema (API)

Se você tem ERP, sistema de PDV ou outro software:

1. Aba API Key → copia sua chave.
2. Documentação completa em /docs (Swagger UI).
3. Cria cobrança via POST /api/v1/charges com header X-API-Key.

Exemplo cURL:

curl -X POST 'https://SEU-DOMINIO/api/v1/charges' \
  -H 'X-API-Key: SUA_API_KEY' \
  -H 'Idempotency-Key: '$(uuidgen) \
  -H 'Content-Type: application/json' \
  -d '{"amount": 100.00, "description": "Pedido #123"}'

10 Suporte e dúvidas

• Documentação API: /docs
• Política e Termos: /privacidade
• Manual hardware ESP32: /manual-esp32
• Email de suporte: contato@plataforma.com