# PIX Mercado Pago — Freedom Radar

Planos aprovados: Grátis (1 análise vitalícia), Start (R$ 49 e 5 análises/mês), Pro (R$ 249 e 50 análises/mês) e Business (R$ 499 e 150 análises/mês). Cotas pagas seguem mês calendário UTC, como no sistema existente. Conteúdos já liberados permanecem acessíveis.

## Configuração

1. Na conta Mercado Pago **da Freedom**, crie uma aplicação **Checkout Transparente / API de Orders** e habilite o recebimento PIX. Configure a chave PIX no Mercado Pago conforme os pré-requisitos da conta.
2. Preencha **localmente** no `.env`: `MP_ACCESS_TOKEN`, `MP_WEBHOOK_SECRET`, `MP_COLLECTOR_ID` (ID da conta recebedora retornado por `GET https://api.mercadopago.com/users/me` com o token da Freedom). Nunca envie o token ao navegador ou publique o `.env`.
3. Em Webhooks da aplicação Mercado Pago, selecione o evento **Order (Mercado Pago) / order**. Copie a assinatura secreta para `MP_WEBHOOK_SECRET`. O tópico payment só atende cobranças antigas via Payments.
4. Cadastre a URL pública HTTPS `https://SEU-DOMINIO/api/payments/mercadopago/webhook`. Registre a mesma URL em `MP_NOTIFICATION_URL`. Orders utiliza a URL cadastrada no painel, sem enviar notification_url no pedido. `localhost` não recebe notificações externas; o endereço público depende da implantação existente.
5. Em validação, use `MP_LIVE_MODE=false` e o Access Token de teste da aplicação Orders (ele também pode começar com APP_USR). Configure o ID da conta de teste retornado por /users/me em MP_COLLECTOR_ID. O servidor verifica país MLB, identificação e tag test_user da conta autenticada, pois a resposta Orders não garante live_mode. Em produção, use `MP_LIVE_MODE=true`, token produtivo e ID da conta recebedora Freedom. Não reutilize o ID de teste em produção. Ambiente informado em webhook ou resposta, quando presente, também é validado.
6. Defina `PIX_ENABLED=true` e reinicie com `npm start`. O comando aplica a migração 005 e inicia tudo. Sem configuração completa, pagamentos ficam desabilitados; não há cobrança fictícia.

## Fluxo e regras

### Webhook em localhost

Para teste local, inicie o Radar com npm start. Em outro terminal, execute `node --env-file-if-exists=.env scripts/webhook-proxy.js`. O proxy em 127.0.0.1:3001 aceita somente POST na rota do webhook, sem publicar a interface. Com cloudflared instalado (binário local em .tools/cloudflared.exe), execute `.\.tools\cloudflared.exe tunnel --no-autoupdate --url http://127.0.0.1:3001`. Copie a URL HTTPS gerada e acrescente `/api/payments/mercadopago/webhook` no painel Mercado Pago e MP_NOTIFICATION_URL. A URL muda quando um novo túnel é criado e deixa de funcionar ao encerrar o processo. Mantenha os dois terminais ativos durante o teste; para parar, use Ctrl+C em ambos. Não precisa alterar APP_ORIGIN: a interface continua em localhost:3000.

O gestor entra em **Plano e cobrança**, seleciona um plano, informa CPF/CNPJ válido e gera o PIX. E-mail e documento são enviados ao Mercado Pago para a cobrança e armazenados na cobrança local. O servidor define o valor a partir do plano no banco. QR Code e copia e cola são retornados pelo Mercado Pago, com validade de 24 horas. O PIX deve mostrar a conta recebedora da Freedom no banco do cliente.

Novas cobranças usam POST /v1/orders, valor decimal como string (49.00, 249.00, 499.00), processing_mode automatic e uma transação PIX bank_transfer com validade PT24H. O retorno pode ser assíncrono: processing sem QR mantém cobrança em processamento até a consulta/notificação trazer os dados. O QR vem de transactions.payments[0].payment_method.

Webhook com assinatura HMAC válida (ID alfanumérico em minúsculas no manifesto) e consulta autenticada à API confirmam o status. Valor total e da transação, país brasileiro, método PIX, ID, referência, conta recebedora e ambiente precisam corresponder. Liberação exige order processed/accredited, transação processed/accredited e total_paid_amount igual ao valor esperado. Status desconhecidos e múltiplas transações não liberam acesso. Consultar uma cobrança de outra empresa é bloqueado. Repetir a geração enquanto existe uma cobrança pendente reutiliza o mesmo pedido e chave de idempotência. Se há cobrança para outro plano, é necessário aguardar a validade/conferir o status; cancelamento pelo painel ainda não implementado.

Histórico e cobranças anteriores com ID numérico continuam consultáveis via Payments; novas cobranças recebem ID ORD. A versão da API é armazenada dentro do JSON payer local, removida antes do envio ao Mercado Pago. Nenhuma migração já aplicada foi alterada.

Cada confirmação aprovada libera **um mês** (data equivalente no mês seguinte, limitada ao último dia daquele mês). Renovação do mesmo plano estende a validade existente. Alterar plano inicia um novo mês sem desconto proporcional; a interface informa isso antes de gerar o PIX. Um novo pagamento não reinicia os créditos do mês calendário. PIX não é débito automático: renovar exige pagar outra cobrança.

Um pagamento só concede acesso uma vez. Estorno, inclusive parcial, ou contestação retiram aquela concessão; se outra concessão paga ainda for válida, ela é preservada. Ao vencer o acesso gerenciado por pagamento, a API de créditos retorna ao plano gratuito; reabertura de análises permanece disponível. Atribuição manual pelo administrador desativa o controle de validade de cobrança até uma nova contratação aprovada. Uso do painel Mercado Pago para estorno é separado: o Radar não inicia estornos financeiros.

## Validação e limites

`npm test` executa testes de segurança, assinatura, correspondência do pagamento e interface. `MYSQL_TEST=true` com as configurações locais executa os testes em banco temporário isolado, incluindo migrações, geração, reutilização, confirmação repetida, isolamento, estorno e créditos. Chamadas Mercado Pago nesses testes são simuladas; não movimentam dinheiro.

A entrada pública apresenta os preços aprovados; o checkout lê preços atuais do servidor. Convites de usuários, alertas, emissão fiscal e PIX automático não foram implementados. No painel do Mercado Pago, confira o recebedor e o retorno de uma cobrança de teste antes de habilitar produção. Esta implementação não foi validada contra a conta real da Freedom sem suas credenciais.

Documentação oficial usada: [PIX via Orders API](https://www.mercadopago.com.br/developers/pt/docs/checkout-api-orders/payment-integration/websites/pix), [Webhooks de Orders](https://www.mercadopago.com.br/developers/pt/docs/checkout-api-orders/notifications) e [consulta de Orders](https://www.mercadopago.com.br/developers/pt/reference/online-payments/checkout-api/get-order/get).