271 lines
No EOL
7.2 KiB
Markdown
271 lines
No EOL
7.2 KiB
Markdown
# Implementação Mercado Pago - Checkout SaveInMed
|
|
|
|
## Visão Geral
|
|
|
|
Implementação completa da integração com Mercado Pago na aplicação SaveInMed, seguindo a estrutura da API BFF existente e o curl fornecido.
|
|
|
|
## Arquivos Implementados
|
|
|
|
### 1. Serviço Mercado Pago (`src/services/mercadoPagoService.ts`)
|
|
|
|
**Responsabilidades:**
|
|
- Criar preferências de pagamento via BFF
|
|
- Verificar status de pagamentos
|
|
- Processar notificações de webhook
|
|
- Validar dados antes do envio
|
|
- Formatar valores e dados
|
|
|
|
**Principais Métodos:**
|
|
```typescript
|
|
// Criar preferência de pagamento
|
|
criarPreferencia(pedidoId, itens, dadosComprador)
|
|
|
|
// Verificar status do pagamento
|
|
verificarStatusPagamento(paymentId)
|
|
|
|
// Processar notificação webhook
|
|
processarNotificacao(notificationData)
|
|
|
|
// Validar dados da preferência
|
|
validarDadosPreferencia(pedidoId, itens)
|
|
```
|
|
|
|
**Endpoint BFF Utilizado:**
|
|
- `POST https://bff-dev.saveinmed.com.br/mercadopago/preference`
|
|
- `GET https://bff-dev.saveinmed.com.br/mercadopago/payment/{id}`
|
|
- `POST https://bff-dev.saveinmed.com.br/mercadopago/webhook`
|
|
|
|
### 2. Componente Botão Mercado Pago (`src/components/MercadoPagoButton.tsx`)
|
|
|
|
**Funcionalidades:**
|
|
- Botão estilizado para pagamento via Mercado Pago
|
|
- Validação automática dos dados
|
|
- Estados de loading e erro
|
|
- Redirecionamento automático para o checkout do Mercado Pago
|
|
- Callbacks para sucesso e erro
|
|
|
|
**Props:**
|
|
```typescript
|
|
interface MercadoPagoButtonProps {
|
|
pedidoId: string
|
|
itens: Array<{produto, quantidade}>
|
|
dadosComprador?: {nome, email}
|
|
onSuccess?: (preference_id, init_point) => void
|
|
onError?: (error) => void
|
|
disabled?: boolean
|
|
}
|
|
```
|
|
|
|
### 3. Páginas de Retorno
|
|
|
|
#### Página de Sucesso (`src/app/pagamento/sucesso/page.tsx`)
|
|
- Processa retorno de pagamento aprovado
|
|
- Exibe detalhes do pagamento e pedido
|
|
- Atualiza status do pedido
|
|
- Interface amigável com próximos passos
|
|
|
|
#### Página de Erro (`src/app/pagamento/erro/page.tsx`)
|
|
- Trata erros de pagamento
|
|
- Explica motivos comuns de falha
|
|
- Oferece sugestões e alternativas
|
|
- Botões para tentar novamente ou escolher outro método
|
|
|
|
### 4. Integração no Checkout (`src/app/checkout/page.tsx`)
|
|
|
|
**Modificações Realizadas:**
|
|
- Adicionada opção "Mercado Pago" na seleção de pagamento
|
|
- Lógica específica para processar pagamento via Mercado Pago
|
|
- Botão personalizado na etapa de confirmação
|
|
- Fluxo diferenciado para redirecionamento externo
|
|
|
|
## Estrutura de Dados
|
|
|
|
### Preferência Mercado Pago
|
|
```json
|
|
{
|
|
"back_urls": {
|
|
"failure": "https://saveinmed.com.br/pagamento/erro",
|
|
"success": "https://saveinmed.com.br/pagamento/sucesso"
|
|
},
|
|
"external_reference": "pedido-123",
|
|
"items": [
|
|
{
|
|
"currency_id": "BRL",
|
|
"id": "item-123",
|
|
"quantity": 1,
|
|
"title": "Nome do Produto",
|
|
"unit_price": 99.90
|
|
}
|
|
],
|
|
"notification_url": "https://bff.saveinmed.com.br/mercadopago/webhook",
|
|
"payer": {
|
|
"email": "cliente@example.com",
|
|
"name": "Cliente",
|
|
"surname": "Teste"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Resposta da API
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {...},
|
|
"preference_id": "123456789-abc123",
|
|
"init_point": "https://www.mercadopago.com.br/checkout/v1/redirect?pref_id=123456789-abc123",
|
|
"sandbox_init_point": "https://sandbox.mercadopago.com.br/checkout/v1/redirect?pref_id=123456789-abc123"
|
|
}
|
|
```
|
|
|
|
## Fluxo de Pagamento
|
|
|
|
### 1. Usuário Seleciona Mercado Pago
|
|
- Na etapa 2 do checkout, seleciona "Mercado Pago"
|
|
- Sistema avança para etapa 3 (confirmação)
|
|
|
|
### 2. Confirmação e Redirecionamento
|
|
- Usuário confirma dados na etapa 3
|
|
- Clica no botão "Pagar via Mercado Pago"
|
|
- Sistema cria preferência via BFF
|
|
- Redireciona para checkout do Mercado Pago
|
|
|
|
### 3. Processamento no Mercado Pago
|
|
- Usuário escolhe método (cartão, PIX, boleto)
|
|
- Completa o pagamento
|
|
- Mercado Pago processa transação
|
|
|
|
### 4. Retorno e Notificação
|
|
- Usuário retorna para URLs configuradas
|
|
- Webhooks notificam status via BFF
|
|
- Sistema atualiza pedido conforme resultado
|
|
|
|
## URLs de Retorno
|
|
|
|
### Sucesso
|
|
`https://saveinmed.com.br/pagamento/sucesso`
|
|
|
|
**Parâmetros recebidos:**
|
|
- `payment_id`: ID do pagamento no Mercado Pago
|
|
- `status`: Status do pagamento (approved, pending, etc.)
|
|
- `external_reference`: ID do pedido no sistema
|
|
- `preference_id`: ID da preferência criada
|
|
|
|
### Erro
|
|
`https://saveinmed.com.br/pagamento/erro`
|
|
|
|
**Parâmetros recebidos:**
|
|
- `payment_id`: ID do pagamento (se disponível)
|
|
- `status`: Status do erro (rejected, cancelled, etc.)
|
|
- `status_detail`: Detalhes específicos do erro
|
|
- `external_reference`: ID do pedido
|
|
|
|
## Webhook de Notificação
|
|
|
|
**Endpoint:** `https://bff.saveinmed.com.br/mercadopago/webhook`
|
|
|
|
**Responsabilidade do BFF:**
|
|
- Receber notificações do Mercado Pago
|
|
- Validar autenticidade das notificações
|
|
- Atualizar status dos pagamentos no sistema
|
|
- Processar ações automáticas (aprovação de pedidos, etc.)
|
|
|
|
## Validações Implementadas
|
|
|
|
### 1. Dados da Preferência
|
|
- Pedido ID obrigatório
|
|
- Pelo menos um item obrigatório
|
|
- Preços maiores que zero
|
|
- Quantidades válidas
|
|
- IDs de produtos presentes
|
|
|
|
### 2. Estados do Botão
|
|
- Desabilitado se dados inválidos
|
|
- Loading durante criação da preferência
|
|
- Erro em caso de falha na API
|
|
|
|
### 3. Tratamento de Erros
|
|
- Mensagens específicas por tipo de erro
|
|
- Sugestões de correção
|
|
- Informações técnicas para debug
|
|
|
|
## Benefícios da Implementação
|
|
|
|
### 1. Para o Usuário
|
|
- Múltiplas opções de pagamento em um só lugar
|
|
- Interface familiar do Mercado Pago
|
|
- Segurança e confiabilidade
|
|
- Parcelamento flexível
|
|
|
|
### 2. Para o Sistema
|
|
- Reduz complexidade de PCI compliance
|
|
- Aproveitamento da infraestrutura do Mercado Pago
|
|
- Notificações automáticas de status
|
|
- Integração via BFF existente
|
|
|
|
### 3. Para o Negócio
|
|
- Maior conversão de vendas
|
|
- Redução de abandono de carrinho
|
|
- Suporte a diversos métodos de pagamento
|
|
- Gestão centralizada via Mercado Pago
|
|
|
|
## Configurações Necessárias
|
|
|
|
### 1. No BFF
|
|
- Configurar credenciais do Mercado Pago
|
|
- Implementar endpoints de preferência e webhook
|
|
- Validar autenticidade das notificações
|
|
|
|
### 2. No Mercado Pago
|
|
- Configurar URLs de retorno
|
|
- Configurar URL de webhook
|
|
- Configurar métodos de pagamento aceitos
|
|
|
|
### 3. No Frontend
|
|
- URLs de sucesso e erro configuradas
|
|
- Componente de botão implementado
|
|
- Serviço de API implementado
|
|
|
|
## Monitoramento e Debug
|
|
|
|
### 1. Logs Implementados
|
|
- Criação de preferências
|
|
- Respostas da API
|
|
- Erros e exceções
|
|
- Redirecionamentos
|
|
|
|
### 2. Informações para Debug
|
|
- IDs de transação
|
|
- Status detalhados
|
|
- Parâmetros de retorno
|
|
- Dados técnicos nas páginas de erro
|
|
|
|
## Próximos Passos
|
|
|
|
### 1. Testes
|
|
- Testar fluxo completo em sandbox
|
|
- Validar webhooks
|
|
- Testar cenários de erro
|
|
|
|
### 2. Monitoramento
|
|
- Implementar métricas de conversão
|
|
- Monitorar erros e falhas
|
|
- Acompanhar performance
|
|
|
|
### 3. Melhorias
|
|
- Implementar retry automático
|
|
- Adicionar analytics
|
|
- Otimizar UX baseado em dados
|
|
|
|
## Conclusão
|
|
|
|
A implementação do Mercado Pago está completa e seguindo as melhores práticas:
|
|
|
|
- ✅ Integração via BFF existente
|
|
- ✅ Componentes reutilizáveis
|
|
- ✅ Tratamento completo de erros
|
|
- ✅ Páginas de retorno implementadas
|
|
- ✅ Validações robustas
|
|
- ✅ Logging detalhado
|
|
- ✅ Interface intuitiva
|
|
|
|
O sistema está pronto para testes e deploy, oferecendo uma experiência de pagamento moderna e segura aos usuários do SaveInMed. |