Pular para o conteúdo principal

Sistema de Recarga e Reabastecimento

O sistema de recarga do OmniCRM fornece um portal de recarga pré-paga de autoatendimento para clientes adicionarem crédito ou estenderem a validade do serviço através do Portal de Autoatendimento. Esse recurso é comumente utilizado para:

  • Serviços de dados móveis - Cartões SIM pré-pagos e serviços apenas de dados
  • Serviços de hotspot - Dongles de hotspot WiFi e dispositivos de internet portáteis
  • Serviços fixos sem fio - Acesso à internet pré-pago

Visão Geral​

O sistema de recarga permite que os clientes comprem dias adicionais de serviço através de um processo de checkout simplificado e em várias etapas com processamento de pagamento integrado via Stripe.

Principais Recursos:

  • Portal de autoatendimento para clientes (sem intervenção de funcionários necessária)
  • Seleção de duração flexível (1-30 dias)
  • Exibição de uso em tempo real antes da compra
  • Processamento de pagamento seguro com Stripe
  • Reembolsos automáticos se a recarga falhar
  • Geração de faturas e transações
  • Integração com sistema de provisionamento para ativação do serviço

Acessar o Portal de Recarga​

O portal de recarga é acessado através de uma URL pública que os clientes podem visitar sem fazer login no CRM:

Como os Clientes Acessam:

  • Link direto enviado via SMS quando o saldo está baixo
  • Código QR em materiais impressos
  • Link no portal de autoatendimento
  • Compartilhado via suporte ao cliente

O portal detecta automaticamente o serviço do cliente com base no endereço IP ou IMSI solicitado.

Processo de Recarga​

O fluxo de recarga consiste em 4 etapas:

Etapa 1: Seleção de Dados​

Os clientes selecionam quantos dias de serviço desejam comprar.

Interface:

  • Controle deslizante - Selecione de 1 a 30 dias
  • Cálculo de preço ao vivo - Mostra o custo total com base na seleção
  • Exibição da data de expiração - Calcula e mostra quando o serviço expirará
  • Exibição do uso atual - Mostra o saldo restante/data de expiração antes da recarga

Exemplo de Exibição:

Configuração de Preços:

  • O preço por dia é configurado via variável de ambiente REACT_APP_TOPUP_PRICE_PER_DAY
  • Padrão: $10 USD por dia
  • A moeda é definida via REACT_APP_CURRENCY_CODE

Etapa 2: Informações de Cobrança​

Os clientes fornecem seus dados de contato para a transação:

  • Primeiro Nome
  • Último Nome
  • Endereço de E-mail

Essas informações são usadas para:

  • Geração de fatura
  • E-mail de recibo de pagamento
  • Registros de transação
  • Processamento de reembolso (se necessário)

Etapa 3: Pagamento​

Processamento de pagamento seguro via Stripe Elements.

Métodos de Pagamento Suportados:

  • Cartões de crédito (Visa, Mastercard, Amex)
  • Cartões de débito
  • Carteiras digitais (Apple Pay, Google Pay) se habilitado no Stripe

Recursos de Segurança:

  • Integração Stripe em conformidade com PCI
  • Nenhum detalhe do cartão armazenado no OmniCRM
  • Suporte à autenticação 3D Secure
  • Transmissão de pagamento criptografada

Fluxo de Pagamento:

  1. Formulário Stripe Elements exibido com entrada do cartão
  2. O cliente insere os detalhes do pagamento
  3. Intenção de pagamento criada para o valor exato
  4. Cartão cobrado imediatamente
  5. Sucesso/falha do pagamento tratado

::: note ::: title Nota :::

Se o pagamento for bem-sucedido, mas o provisionamento da recarga falhar (por exemplo, erro de rede, OCS inacessível), o sistema inicia automaticamente um reembolso total para o método de pagamento do cliente. :::

Etapa 4: Conclusão​

Tela de Sucesso:

Seu serviço foi estendido. Nova data de expiração: 17 Jan 2025

Recibo enviado para: <customer@example.com> ID da Transação: TXN-123456

Tela de Falha:

Se a recarga falhar, o sistema exibe um erro e processa automaticamente um reembolso:

Não conseguimos completar sua recarga. Seu pagamento foi reembolsado.

Erro: Não foi possível conectar ao sistema de cobrança

Por favor, tente novamente ou entre em contato com o suporte.

Processamento em Segundo Plano​

Quando um cliente completa o pagamento, o seguinte acontece automaticamente:

1. Validação do Pagamento

O sistema valida:

  • O status da Intenção de Pagamento é succeeded
  • O valor do pagamento corresponde aos dias selecionados (days × price_per_day)
  • A Intenção de Pagamento não foi processada antes (previne recarga dupla)

2. Operação de Recarga

- API endpoint: POST /oam/topup_dongle
- Valida service_uuid e IMSI
- Chama OCS/CGRateS para adicionar saldo
- Cria trabalho de provisionamento (play_topup_hotspot)

3. Criação de Registro

O sistema cria múltiplos registros no banco de dados:

  • Registro HotspotTopup - Rastreia a transação de recarga
    • payment_intent_id
    • service_uuid
    • imsi
    • dias comprados
    • topup_amount
    • status (Sucesso/Falhou/Reembolsado)
  • Registro de Transação - Transação financeira
    • Título: "Recarga de Hotspot - 7 Dias"
    • Valor: topup_amount (positivo)
    • Vinculado a service_id e customer_id
  • Registro de Fatura - Fatura de pagamento
    • Contém a transação de recarga
    • Marcada como paga imediatamente
    • Referência de pagamento: Stripe payment_intent_id
  • Transação de pagamento - Transação de crédito compensatória
    • Título: "Pagamento por [Título da Fatura]"
    • Valor: topup_amount (negativo - crédito)
    • Vincula o pagamento da fatura à conta do cliente

4. Trabalho de Provisionamento

Um trabalho de provisionamento é criado com o playbook play_topup_hotspot que:

  • Conecta-se à API OCS/CGRateS
  • Adiciona saldo à conta
  • Estende a data de expiração
  • Cria entrada de log de atividade
  • Envia notificação de confirmação (se configurado)

A API aguarda a conclusão do provisionamento (polling com intervalos de 0,2s, máximo 25 iterações) antes de retornar sucesso ao cliente.

5. Reembolso Automático em Caso de Falha

Se qualquer etapa falhar após o pagamento:

if topup_provisioning_failed:
    refund = stripe.Refund.create(
        payment_intent=payment_intent_id,
        reason='requested_by_customer'  # Reembolso automático do sistema
    )
    status_message = "Recarga Falhou. Reembolsando pagamento..."

O reembolso é processado automaticamente e o cliente é notificado na tela.

Endpoints da API​

Endpoint de Recarga​

POST /oam/topup_dongle
Content-Type: application/json

{
  "service_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "imsi": "310120123456789",
  "days": 7,
  "payment_intent_id": "pi_1234567890abcdef",
  "topup_amount": 70.00
}

Resposta (Sucesso):

{
  "result": "OK",
  "status": 200,
  "provision_id": 456,
  "payment_intent_id": "pi_1234567890abcdef",
  "service_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "invoice_id": 789
}

Resposta (Falha):

{
  "result": "Failed",
  "Reason": "Timeout de conexão com OCS",
  "status": 500
}

Verificações de Validação:

  • Todos os campos obrigatórios presentes (service_uuid, imsi, days, payment_intent_id, topup_amount)
  • topup_amount corresponde a days: topup_amount × 100 == days × 1000 (em centavos)
  • A Intenção de Pagamento existe no Stripe
  • O valor da Intenção de Pagamento corresponde a: payment_intent.amount == topup_amount × 100
  • O status da Intenção de Pagamento é succeeded
  • A Intenção de Pagamento não foi processada anteriormente (verifica a tabela HotspotTopup)

Endpoint de Uso​

Recupera informações de uso e serviço atuais para o cliente:

GET /oam/usage

Resposta:

{
  "imsi": "310120123456789",
  "service": {
    "service_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "service_name": "Dados Móveis - 0412345678",
    "service_status": "Ativo"
  },
  "balance": {
    "expiry": "2025-01-10T23:59:59Z",
    "unlimited": true
  },
  "requestingIp": "203.0.113.45"
}

Este endpoint usa o endereço IP solicitado para identificar automaticamente o serviço do cliente.

Configuração​

Variáveis de Ambiente​

Configure estas no arquivo .env do OmniCRM-UI:

# Configuração do Portal de Recarga
REACT_APP_TOPUP_PRICE_PER_DAY=10
REACT_APP_CURRENCY_CODE=AUD
REACT_APP_SELF_CARE_NAME="SuaEmpresa"

# Configuração do Stripe
REACT_APP_STRIPE_PUBLISHABLE_KEY=pk_live_...

Configuração do Stripe​

O sistema de recarga utiliza Intenções de Pagamento do Stripe:

  1. Ativar Intenções de Pagamento no seu Painel do Stripe
  2. Configurar Webhook para receber atualizações de status de pagamento (opcional, mas recomendado)
  3. Configurar métodos de pagamento (cartões, carteiras, etc.)
  4. Modo de teste - Use chaves de teste para desenvolvimento
# Desenvolvimento
REACT_APP_STRIPE_PUBLISHABLE_KEY=pk_test_...

# Produção
REACT_APP_STRIPE_PUBLISHABLE_KEY=pk_live_...

Configuração do Playbook​

O playbook de provisionamento play_topup_hotspot.yaml deve ser configurado para:

  • Aceitar a variável days
  • Conectar-se à API OCS/CGRateS
  • Adicionar saldo à conta
  • Atualizar a data de expiração do serviço

Estrutura de exemplo do playbook:

- name: Recarga do serviço de hotspot
  hosts: localhost
  tasks:
    - name: Adicionar saldo ao OCS
      uri:
        url: "{{ ocs_api_url }}/add_balance"
        method: POST
        body:
          imsi: "{{ imsi }}"
          days: "{{ days }}"
          service_uuid: "{{ service_uuid }}"

Notificações de Saldo Baixo​

O sistema pode enviar notificações automáticas quando o saldo do cliente estiver baixo:

Notificações por SMS:

Quando acionadas por eventos do OCS (Action_Balance_Low, Action_Balance_Out, Action_Balance_Expired):

Notificações por E-mail:

Configuradas nos planos de ação do OCS/CGRateS para enviar alertas de saldo.

Gatilhos de Notificação:

  • Action_Balance_Low - Saldo abaixo do limite (por exemplo, 2 dias restantes)
  • Action_Balance_Out - Saldo esgotado
  • Action_Balance_Expired - Serviço expirado

Cada notificação inclui o link do portal de recarga para fácil acesso do cliente.

Resolução de Problemas​

Problemas Comuns​

"Sistema de pagamento indisponível"

  • Causa: A biblioteca Stripe falhou ao carregar ou chave publicável inválida
  • Solução:
    • Verifique se REACT_APP_STRIPE_PUBLISHABLE_KEY está configurado corretamente
    • Verifique se a conta Stripe está ativa
    • Verifique o console do navegador em busca de erros de JavaScript

"Recarga falhou. Reembolsando pagamento..."

  • Causa: Trabalho de provisionamento falhou (OCS inacessível, erro no playbook, etc.)
  • Solução:
    • Verifique os logs de provisionamento: GET /crm/provision/provision_id/<id>
    • Verifique se a API OCS/CGRateS é acessível
    • Revise o playbook play_topup_hotspot.yaml em busca de erros
    • Verifique os logs do Ansible

"Intenção de pagamento já processada"

  • Causa: Cliente tentando reutilizar o mesmo pagamento (por exemplo, atualizar após sucesso)
  • Solução: Isso está funcionando conforme o planejado para evitar cobrança dupla. O cliente deve iniciar uma nova recarga, se necessário.

"O valor da intenção de pagamento não corresponde"

  • Causa: Desvio entre o cálculo da UI e a validação do backend
  • Solução:
    • Verifique se REACT_APP_TOPUP_PRICE_PER_DAY corresponde à expectativa do backend (padrão $10)
    • Verifique se a configuração da moeda é consistente
    • Limpe o cache do navegador e tente novamente

Monitoramento de Recargas​

Visualizar Registros de Recarga:

Consulta a tabela HotspotTopup para ver todas as tentativas de recarga:

SELECT
  hotspot_topup_id,
  service_uuid,
  days,
  topup_amount,
  status,
  payment_intent_id,
  created
FROM hotspot_topup
WHERE status = 'Failed'
ORDER BY created DESC;

Verificar Status de Provisionamento:

GET /crm/provision/provision_id/<provision_id>

Mostra o status detalhado do trabalho de provisionamento da recarga.

Painel do Stripe:

Monitore pagamentos, reembolsos e transações falhadas no seu Painel do Stripe em <https://dashboard.stripe.com>

Considerações de Segurança​

Segurança de Pagamento:

  • Todos os dados do cartão são tratados pelo Stripe (conforme PCI Nível 1)
  • Nenhum dado sensível de pagamento armazenado no banco de dados do OmniCRM
  • Intenções de Pagamento previnem cobranças não autorizadas
  • Validação de valores em ambos os lados, cliente e servidor

Prevenção de Fraude:

  • Detecção de Intenção de pagamento duplicada previne cobrança dupla
  • Rastreamento de endereço IP para correlação de uso
  • Validação de IMSI garante que a recarga vá para o serviço correto
  • Reembolsos automáticos limitam a exposição financeira

Controle de Acesso:

  • O portal de recarga é público (por design - os clientes precisam de acesso)
  • O endpoint de uso requer identificação de serviço válida (IP ou IMSI)
  • A validação em segundo plano previne recargas arbitrárias de serviços
  • O administrador pode visualizar todos os registros de recarga através da interface do CRM

Melhores Práticas​

Para Operadores:

  1. Teste o fluxo de reembolso - Teste regularmente cenários de falha para garantir que os reembolsos funcionem
  2. Monitore recargas falhadas - Configure alertas para altas taxas de falha
  3. Mantenha os playbooks simples - Os playbooks de recarga devem ser rápidos e confiáveis
  4. Verifique a conectividade do OCS - Certifique-se de que a API OCS esteja sempre acessível
  5. Revise os preços - Atualize REACT_APP_TOPUP_PRICE_PER_DAY conforme necessário

Para Clientes:

  1. Adicione o URL de recarga aos favoritos - Acesso rápido quando necessário
  2. Salve notificações de saldo baixo - O SMS contém um link direto
  3. Mantenha o e-mail atualizado - Recibos enviados para o e-mail cadastrado
  4. Verifique a expiração antes de viajar - Recarregue antes de sair da área de cobertura

Para Desenvolvedores:

  1. Gerencie webhooks do Stripe - Implemente manipuladores de webhook para atualizações de status de pagamento
  2. Implemente idempotência - Sempre verifique payment_intent_id antes de processar
  3. Registre extensivamente - Falhas de recarga precisam de informações detalhadas para resolução de problemas
  4. Teste caminhos de erro - Verifique se a automação de reembolso funciona corretamente
  5. Monitore o desempenho - O polling de provisionamento deve ser concluído em <5 segundos

Documentação Relacionada​

  • payments_process - Processamento geral de pagamentos
  • concepts_provisioning - Visão geral do sistema de provisionamento
  • integrations_stripe - Detalhes da integração com o Stripe
  • payments_transaction - Gerenciamento de transações
  • payments_invoices - Manipulação de faturas