🔄 Atualização do Sistema de Pagamento¶
📅 Data: 07/12/2024¶
🎯 Objetivo¶
Atualizar o sistema de pagamento para estar em conformidade com a API simplificada documentada em BOOKING_PAYMENT.md e adicionar validação obrigatória do campo allowCheckout antes de processar pagamentos.
✅ Alterações Realizadas¶
1. gerar_token_cartao_tool.py - API Simplificada¶
Problema: Tool tinha 9 parâmetros, mas API atualizada aceita apenas 5 campos no card object.
Solução:
- ✅ Removidos parâmetros: holder_document, brand, billing_address, label
- ✅ Mantidos parâmetros essenciais: card_number, holder_name, exp_month, exp_year, cvv
- ✅ Atualizado payload para estrutura simplificada:
payload = {
"type": "card",
"card": {
"number": card_number.replace(" ", ""),
"holder_name": holder_name,
"exp_month": exp_month,
"exp_year": exp_year,
"cvv": cvv
}
}
Impacto: - 🔹 API detecta automaticamente a bandeira do cartão - 🔹 Menos dados sensíveis trafegando na rede - 🔹 Processo de tokenização mais rápido e seguro
2. obter_reserva_tool.py - Campo allowCheckout¶
Problema: Campo allowCheckout não estava sendo retornado na resposta simplificada.
Solução:
- ✅ Adicionado campo allowCheckout na simplified_booking response:
simplified_booking = {
"id": booking_data.get("id"),
"type": booking_data.get("type"),
"confirmStatus": booking_data.get("confirmStatus"),
"confirmedStatusName": booking_data.get("confirmedStatusName"),
"paymentStatus": booking_data.get("paymentStatus"),
"paymentStatusName": booking_data.get("paymentStatusName"),
"allowCheckout": booking_data.get("allowCheckout", False), # ✅ NOVO
"totalPrice": booking_data.get("totalPrice"),
# ... outros campos
}
Impacto: - 🔹 Payment agent pode validar se reserva está elegível para pagamento - 🔹 Evita tentativas de pagamento em reservas não confirmadas/já pagas/canceladas
3. payment_agent.py - Validação allowCheckout¶
Problema: Agente não validava se reserva podia ser paga antes de iniciar fluxo.
Solução:
3.1 Import do obter_reserva_tool¶
from ifriend_agent.tools.booking.obter_reserva_tool import obter_reserva_tool
3.2 Adicionado às tools disponíveis¶
tools=[
obter_reserva_tool, # ✅ NOVO
verificar_parcelas_tool,
gerar_token_cartao_tool,
processar_pagamento_tool,
]
3.3 Nova ETAPA 0 nas instruções¶
ETAPA 0: VALIDAR SE RESERVA PODE SER PAGA
→ Perguntar: "Qual o ID da reserva que deseja pagar?"
→ Perguntar: "Qual seu email?" (para segurança)
→ CHAMAR: obter_reserva_tool(booking_id, email_usuario)
Se allowCheckout = false:
→ "❌ Esta reserva não pode ser paga no momento. Possíveis motivos:"
• Reserva ainda não foi confirmada pelo iFriend
• Reserva já foi paga
• Reserva foi cancelada
→ "Consulte o status com nosso suporte para mais informações."
→ PARAR fluxo de pagamento
Se allowCheckout = true:
→ "✅ Reserva elegível para pagamento!"
→ Seguir para ETAPA 1
Impacto: - 🔹 Evita erros na API por tentar pagar reserva inelegível - 🔹 Melhor experiência do usuário com mensagens claras - 🔹 Reduz chamadas desnecessárias à API de pagamento
4. payment_agent.py - Remoção da coleta de bandeira¶
Problema: Instruções pediam ao usuário informar a bandeira do cartão.
Solução: - ✅ Removido pergunta "Bandeira?" da ETAPA 3 - ✅ Adicionado aviso: "⚠️ IMPORTANTE: NÃO pergunte a bandeira do cartão - a API detecta automaticamente!" - ✅ Atualizada chamada do gerar_token_cartao_tool (removidos 4 parâmetros)
Nova ETAPA 3:
Perguntar UM POR VEZ:
1. "Número do cartão?" (13-19 dígitos sem espaços)
2. "Nome impresso no cartão?"
3. "Mês de validade?" (1-12)
4. "Ano de validade?" (ex: 30 ou 2030)
5. "Código de segurança (CVV)?" (3 ou 4 dígitos)
6. "Quantas parcelas deseja?" (validar se está nas opções)
Impacto: - 🔹 Fluxo mais rápido (uma pergunta a menos) - 🔹 Menos chance de erro do usuário (bandeira errada) - 🔹 Conformidade com API simplificada
5. agent.py (root_agent) - Instruções atualizadas¶
Problema: Documentação no root_agent não mencionava validação allowCheckout.
Solução: - ✅ Atualizada seção "9️⃣ PROCESSAR PAGAMENTO":
O payment_tool cuidará de:
• Validar se a reserva pode ser paga (allowCheckout = true) # ✅ NOVO
• Verificar parcelas disponíveis
• Coletar dados do cartão com segurança
• Tokenizar cartão (não armazena dados sensíveis)
• Processar pagamento
• Confirmar resultado
⚠️ O agente de pagamento verificará automaticamente se a reserva está elegível para pagamento.
Se a reserva não puder ser paga (allowCheckout = false), o usuário será informado. # ✅ NOVO
Impacto: - 🔹 Desenvolvedores sabem que validação é automática - 🔹 Documentação inline atualizada - 🔹 Comportamento esperado documentado
🧪 Cenários de Teste¶
Cenário 1: Reserva Elegível (allowCheckout = true)¶
Usuário: "Quero pagar a reserva #123"
Sistema:
1. Valida reserva → allowCheckout = true ✅
2. "✅ Reserva elegível para pagamento!"
3. Segue fluxo normal de pagamento
Cenário 2: Reserva Não Elegível (allowCheckout = false)¶
Usuário: "Quero pagar a reserva #456"
Sistema:
1. Valida reserva → allowCheckout = false ❌
2. "❌ Esta reserva não pode ser paga no momento..."
3. PARA fluxo (não pede dados do cartão)
Cenário 3: Tokenização com API Simplificada¶
Dados coletados:
- Número: 4000000000000010
- Nome: João Silva
- Validade: 10/2030
- CVV: 123
API recebe:
{
"type": "card",
"card": {
"number": "4000000000000010",
"holder_name": "João Silva",
"exp_month": 10,
"exp_year": 2030,
"cvv": "123"
}
}
✅ Bandeira detectada automaticamente: Visa
✅ Token gerado: token_abc123...
📊 Comparação Antes vs Depois¶
Tokenização (gerar_token_cartao_tool)¶
| Aspecto | ANTES | DEPOIS |
|---|---|---|
| Parâmetros | 9 | 5 |
| Dados sensíveis | CPF, endereço completo | Apenas dados do cartão |
| Bandeira | Manual (usuário informa) | Automática (API detecta) |
| Perguntas ao usuário | 7 | 5 |
| Chance de erro | Alta (bandeira errada) | Baixa |
Fluxo de Pagamento (payment_agent)¶
| Aspecto | ANTES | DEPOIS |
|---|---|---|
| Validação inicial | ❌ Não | ✅ Sim (ETAPA 0) |
| Verifica allowCheckout | ❌ Não | ✅ Sim |
| Evita chamadas inválidas | ❌ Não | ✅ Sim |
| Mensagens de erro | Genéricas | Específicas e claras |
| Tools disponíveis | 3 | 4 (+obter_reserva) |
🔒 Segurança¶
Melhorias de Segurança¶
- ✅ Menos dados sensíveis em trânsito (removidos CPF e endereço da tokenização)
- ✅ Validação de autorização ANTES de coletar dados do cartão
- ✅ Verificação dupla: email + allowCheckout
- ✅ Token expira em 60s (mantido)
- ✅ Nunca exibe número completo do cartão (mantido)
Validações Implementadas¶
# obter_reserva_tool
- Email do usuário DEVE corresponder à reserva
- allowCheckout DEVE ser true
# gerar_token_cartao_tool
- Número do cartão: 13-19 dígitos
- Mês validade: 1-12
- CVV: 3-4 dígitos
# payment_agent
- ETAPA 0: Valida eligibilidade
- ETAPA 4: Token deve ser gerado com sucesso
- ETAPA 5: Processa em até 60s (antes de token expirar)
📝 Checklist de Conformidade¶
API Atualizada (BOOKING_PAYMENT.md)¶
- [x] Tokenização usa apenas 5 campos do cartão
- [x] Bandeira é detectada automaticamente
- [x] Removidos holder_document, brand, billing_address, label
- [x] Estrutura do payload corresponde à documentação
Validação allowCheckout¶
- [x] Campo retornado em obter_reserva_tool
- [x] Payment agent valida ANTES de coletar dados
- [x] Mensagem clara se allowCheckout = false
- [x] Fluxo interrompido se inelegível
Experiência do Usuário¶
- [x] Menos perguntas (7 → 5 sobre cartão)
- [x] Validação antecipada (evita frustração)
- [x] Mensagens de erro específicas
- [x] Fluxo mais rápido
Documentação¶
- [x] Code comments atualizados
- [x] Docstrings corretas
- [x] root_agent instructions atualizadas
- [x] Este documento de atualização criado
🚀 Deploy¶
Arquivos Alterados¶
ifriend_agent/
├── tools/
│ ├── payment/
│ │ └── gerar_token_cartao_tool.py # Simplificado (5 params)
│ └── booking/
│ └── obter_reserva_tool.py # +allowCheckout field
├── agents/
│ └── payment_agent.py # +ETAPA 0, -brand collection
└── agent.py # +allowCheckout docs
docs/
└── ifriend_agent/
└── PAYMENT_SYSTEM_UPDATE.md # Este documento
Comandos¶
git add -A
git commit -m "fix: Atualiza payment system conforme API simplificada e adiciona validação allowCheckout"
git push origin feature/memory
Testes Recomendados¶
- ✅ Testar pagamento com allowCheckout = true
- ✅ Testar rejeição com allowCheckout = false
- ✅ Testar tokenização com diferentes bandeiras (Visa, Mastercard, Elo)
- ✅ Testar timeout do token (>60s entre tokenização e pagamento)
- ✅ Testar validação de email (tentativa de acesso não autorizado)
📞 Suporte¶
Se houver problemas com o sistema de pagamento:
- Verificar logs do payment_agent
- Validar que allowCheckout está sendo retornado corretamente
- Confirmar que API de tokenização aceita apenas 5 campos
- Testar com cartões de teste da documentação
📚 Referências¶
/docs/ifriend_agent/BOOKING_PAYMENT.md- Documentação oficial da API/docs/ifriend_agent/BOOKING_INFO_AND_PAYMENT.md- Estrutura completa do booking/docs/ifriend_agent/EMAIL_FEATURE.md- Sistema de emails (relacionado)
Status: ✅ Implementado e commitado (abe0573)
Responsável: GitHub Copilot
Revisão: Pendente