Carteiras e Bonus de Clientes

O Levy Fleets fornece um sistema flexivel de carteira e bonus que permite que os clientes armazenem creditos para viagens e possibilita que os operadores recompensem clientes com bonus promocionais. Este guia cobre desde a compreensao dos tipos de saldo ate o gerenciamento de transacoes de carteira e creditos de bonus.

Entendendo Carteiras vs. Bonus

O sistema mantem dois tipos de saldo separados para cada cliente:

Como os Pagamentos Sao Aplicados

Exemplo: Cliente tem R$ 25,00 de bonus, R$ 50,00 de carteira, e a viagem custa R$ 60,00

1. Bonus aplicado primeiro: R$ 25,00 bonus -> R$ 0,00 bonus restante
2. Carteira aplicada segundo: R$ 35,00 da carteira -> R$ 15,00 carteira restante
3. Cartao cobrado: R$ 0,00 (viagem totalmente coberta por creditos)

Se a viagem custasse R$ 100,00:

1. Bonus: R$ 25,00 -> R$ 0,00 restante
2. Carteira: R$ 50,00 -> R$ 0,00 restante
3. Cartao cobrado: R$ 25,00

Requisitos de Saldo Minimo

Para iniciar uma viagem, os clientes devem ter um saldo minimo de R$ 2,50 na carteira, a menos que se qualifiquem para uma isencao de verificacao de carteira (veja Elegibilidade de Viagem abaixo).

Elegibilidade de Viagem e Isencoes de Verificacao de Carteira

Os clientes podem pular a verificacao de saldo da carteira se TODAS as seguintes condicoes forem verdadeiras:

1. O cliente tem uma assinatura ativa OU um pacote de viagem ativo com viagens/minutos restantes
2. O cliente tem um metodo de pagamento salvo em arquivo

Isso permite que clientes de assinatura e pacotes viajem mesmo com saldo R$ 0 na carteira, ja que suas viagens sao cobertas pelo plano adquirido.

Saldos Negativos

Saldos de carteira podem ficar negativos em certas situacoes:

• Quando operadores cobram uma taxa que excede o saldo atual
• Quando o custo da viagem excede os creditos disponiveis e a cobranca do cartao falha

Acessando Informacoes da Carteira

Na Lista de Clientes

A lista de clientes exibe saldos de carteira e bonus em colunas separadas:

• Carteira: Mostra o valor atual de credito na carteira
• Bonus: Mostra o valor atual de bonus

Na Pagina de Detalhes do Cliente

Navegue ate Painel > Clientes > [Cliente] para ver:

• Cartao de Saldo da Carteira: Saldo atual com botao "Adicionar Credito"
• Cartao de Saldo de Bonus: Valor atual de bonus
• Ver Atividade da Carteira: Link para historico detalhado de transacoes

Pagina de Atividade da Carteira

Acesse o historico detalhado de transacoes em: Painel > Clientes > [Cliente] > Atividade da Carteira

Esta pagina exibe:

• Lista completa de transacoes de credito da carteira
• Data e hora de cada transacao
• Descricao da transacao
• Fonte/metodo do credito
• Valor (creditos mostrados em verde, debitos em vermelho)
• Saldo atual apos cada transacao

Adicionando Creditos na Carteira

Credito Manual (Cliente Individual)

1. Navegue ate a pagina de detalhes do cliente
2. Na secao Carteira, clique em Adicionar Credito (ou o botao "+")
3. Digite o valor do credito
4. Adicione uma observacao opcional explicando o motivo
5. Clique em Adicionar Credito para aplicar

O credito aparece imediatamente em:

• Saldo da carteira do cliente
• Historico de atividade da carteira
• Aplicativo movel do cliente

Motivos Comuns para Creditos Manuais

Cobrando Taxas e Reduzindo Saldo

Cobrar Taxa

Use "Cobrar Taxa" para aplicar cobrancas por danos, equipamento perdido, violacoes de estacionamento ou outras penalidades.

Como Cobrar uma Taxa:

1. Navegue ate a pagina de detalhes do cliente
2. Clique no menu suspenso Carteira na barra de acoes
3. Selecione Cobrar Taxa
4. Digite o valor
5. Adicione uma descricao/motivo
6. Clique em Cobrar Taxa

Endpoint da API: POST /api/customers/charge

{
  "customerIdentityId": "customer-identity-uuid",
  "amount_usd": 25.00,
  "description": "Taxa de violacao de estacionamento"
}

Reduzir Saldo (Debito Manual)

Use "Reduzir Saldo" para correcoes, ajustes ou debitos silenciosos que nao devem notificar o cliente.

Como Reduzir Saldo:

1. Navegue ate a pagina de detalhes do cliente
2. Clique no menu suspenso Carteira na barra de acoes
3. Selecione Reduzir Saldo
4. Digite o valor
5. Adicione um motivo/observacao
6. Clique em Reduzir Saldo

Comportamentos Importantes:

• Sem notificacao: O cliente nao e notificado da deducao
• Nao pode ficar negativo: O saldo para em R$ 0 (diferente de Cobrar Taxa)
• Cria registro de transacao: Registrado como tipo debit com referencia manual_reduce_balance

Endpoint da API: POST /api/customers/reduce-balance

{
  "customerUuid": "customer-uuid",
  "amount_usd": 10.00,
  "description": "Correcao por credito duplicado"
}

Cobrar Taxa vs. Reduzir Saldo

Processamento em Massa de Carteira

Para adicionar creditos a varios clientes de uma vez:

1. Navegue ate Painel > Clientes
2. Clique em Processamento em Massa de Carteira no cabecalho da pagina
3. Prepare seu arquivo CSV com o formato necessario
4. Envie o arquivo CSV
5. Revise a pre-visualizacao mostrando todas as alteracoes
6. Clique em Processar para aplicar todos os creditos

Formato CSV para Processamento em Massa:

identifier,identifier_type,amount,note
cust_abc123,id,10.00,Promocao de feriado
user@email.com,email,5.00,Credito de servico
+5511999999999,phone,7.50,Bonus de indicacao
12345,customer_number,15.00,Recompensa de fidelidade

Tipos de Identificador Suportados:

• id: UUID interno do cliente
• email: Endereco de e-mail do cliente
• phone: Numero de telefone do cliente (inclua codigo do pais)
• customer_number: Numero do cliente atribuido pelo sistema

Adicionando Creditos de Bonus

Via API

Creditos de bonus sao tipicamente adicionados via endpoint da API de bonus:

Endpoint: POST /api/customers/bonus

Corpo da Requisicao:

{
  "customerId": "customer-uuid-here",
  "amount": 5.00,
  "reason": "Bonus de indicacao"
}

Resposta:

{
  "success": true,
  "newBalance": 5.00,
  "previousBalance": 0.00
}

Via Painel

Na pagina de detalhes do cliente:

1. Localize a secao Saldo de Bonus
2. Clique em Adicionar Bonus (se disponivel)
3. Digite o valor do bonus
4. Adicione um motivo/observacao
5. Clique em Aplicar Bonus

Bonus vs. Carteira: Quando Usar Cada Um

Tipos de Transacao de Carteira

Transacoes de Credito

Creditos aumentam o saldo da carteira:

Transacoes de Debito

Debitos diminuem o saldo da carteira:

Detalhes da Atividade da Carteira

Cada transacao na pagina de atividade da carteira mostra:

Coluna de Data

• Timestamp da transacao
• Exibido no fuso horario do usuario
• Ordenavel por data

Coluna de Descricao

• Descricao legivel da transacao
• Mostra o tipo de transacao (rotulo Credito/Debito)
• Pode incluir contexto adicional

Coluna de Origem

Indica de onde a transacao se originou:

• Manual: Adicionado pelo operador no painel
• Stripe: Cobranca ou reembolso de cartao
• Sistema: Automatizado (promo, indicacao, etc.)
• Viagem: Associado a uma viagem especifica
• Massa: De operacao de processamento em massa

Coluna de Valor

• Verde com +: Credito (dinheiro adicionado)
• Vermelho com -: Debito (dinheiro removido)
• Exibido na moeda do cliente

Coluna de Saldo Apos

• Mostra o saldo atual apos esta transacao
• Util para auditoria e reconciliacao

Sistema de Recarga Automatica

O recurso de recarga automatica reabastece automaticamente a carteira de um cliente quando o saldo cai abaixo de um limite configurado.

Como a Recarga Automatica Funciona

1. O saldo da carteira do cliente cai abaixo do limite
2. O sistema detecta saldo baixo durante inicio de viagem ou pagamento
3. Cobranca automatica e processada no metodo de pagamento padrao do cliente
4. A carteira e creditada com o valor de recarga configurado
5. O cliente recebe uma notificacao push confirmando a recarga

Requisitos de Configuracao

Configuracoes do Cliente:

• auto_topup_enabled: O cliente deve habilitar isso nas configuracoes do aplicativo

Configuracoes da Subconta:

• auto_topup_enabled: A subconta deve ter o recurso de recarga automatica habilitado
• auto_topup_amount_cents: Valor a adicionar (padrao: R$ 75,00 / 7500 centavos)
• auto_topup_threshold_cents: Ponto de gatilho do saldo (padrao: R$ 25,00 / 2500 centavos)

Configuracao Padrao

Exemplo: Com as configuracoes padrao, quando o saldo de um cliente cai abaixo de R$ 25,00, o sistema automaticamente cobra R$ 75,00 do cartao e credita a carteira.

Gatilhos de Recarga Automatica

A recarga automatica e acionada durante:

• Inicio da viagem (quando o saldo e verificado)
• Processamento de pagamento (quando a carteira e esgotada)

Mecanismos de Seguranca

O sistema inclui multiplas protecoes:

1. Bloqueios de Banco de Dados: Previne tentativas de recarga automatica concorrentes de cobrar duas vezes
2. Chaves de Idempotencia: Chaves de idempotencia do Stripe previnem cobranças duplicadas mesmo com problemas de rede
3. Verificacao de Limite: So aciona quando o saldo esta realmente abaixo do limite
4. Modo de Teste: Contas com e-mails @levyelectric.com usam modo de teste do Stripe

Visualizando Transacoes de Recarga Automatica

Transacoes de recarga automatica aparecem na atividade da carteira do cliente com:

• Tipo: stripe_topup ou auto_topup
• Descricao: "Recarga automatica" ou "Recarga automatica de carteira"
• Origem: Gerada pelo sistema

Solucao de Problemas de Recarga Automatica

Recarga automatica nao esta funcionando?

1. Verifique se o cliente habilitou a recarga automatica nas configuracoes do aplicativo
2. Confirme se a subconta tem recarga automatica habilitada
3. Verifique se o cliente tem um metodo de pagamento padrao valido
4. Verifique se o metodo de pagamento nao foi recusado
5. Verifique se ha transacoes de recarga automatica pendentes existentes

Integracao com Metodos de Pagamento

Hierarquia de Pagamento

Quando um cliente faz uma compra:

1. Verificar assinaturas ativas com viagens incluidas
2. Aplicar saldo de bonus (se disponivel)
3. Aplicar saldo da carteira (se disponivel)
4. Acionar recarga automatica (se habilitada e saldo abaixo do limite)
5. Cobrar metodo de pagamento (pelo valor restante)

Uso Parcial de Carteira

Se uma viagem custa mais do que os creditos disponiveis:

• Creditos sao totalmente consumidos
• Valor restante cobrado no cartao
• Transacao aparece como "Pagamento parcial com carteira"

Integracao com Stripe

Creditos de carteira interagem com pagamentos Stripe:

• Reembolsos: Podem ir para a carteira em vez do cartao
• Cobranças falhas: Nenhum credito de carteira consumido
• Disputas: Podem resultar em debito na carteira

Saldo da Carteira no Aplicativo Movel

Os clientes veem suas informacoes de carteira no aplicativo:

Exibicao de Saldo

• Saldo atual da carteira exibido com destaque
• Saldo de bonus pode ser mostrado separadamente
• Saldo de "credito" combinado em algumas visualizacoes

Adicionando Fundos (Se Habilitado)

• O cliente pode adicionar creditos de carteira via cartao
• Valores minimos/maximos configuraveis
• Credito instantaneo apos cobranca bem-sucedida

Historico de Transacoes

• Os clientes podem ver atividade recente da carteira
• Limitado a creditos e debitos que afetam o saldo
• Mostra data, descricao e valor

Politicas de Carteira da Subconta

Diferentes subcontas podem ter diferentes politicas de carteira:

Configuracoes de Recarga de Carteira

• Habilitado/Desabilitado: Permitir auto-recarga do cliente
• Valor Minimo: Menor recarga permitida
• Valor Maximo: Maior recarga permitida
• Valores Sugeridos: Opcoes de selecao rapida no aplicativo

Limites de Saldo

• Saldo Maximo: Prevenir acumulo excessivo de creditos
• Aviso de Saldo Baixo: Notificar quando estiver acabando

Relatorios e Analises

Metricas de Resumo

O cabecalho da lista de clientes mostra:

• Valor Total da Carteira: Soma de todos os saldos de carteira
• Total de Bonus: Soma de todos os saldos de bonus

Opcoes de Exportacao

Exporte dados de carteira para analise:

1. Navegue ate a lista de clientes
2. Aplique os filtros desejados
3. Clique em Exportar (se disponivel)
4. Selecione campos incluindo colunas de carteira e bonus

Auditando Alteracoes na Carteira

Para auditoria financeira:

1. Acesse a atividade da carteira individual do cliente
2. Revise o historico de transacoes com timestamps
3. Faca referencia cruzada com o historico de viagens
4. Verifique creditos manuais contra logs de operadores

Referencia da API

Obter Saldo da Carteira do Cliente

Endpoint: GET /api/customers/{id}

Retorna objeto do cliente incluindo:

{
  "id": "customer-uuid",
  "wallet_balance": 25.00,
  "bonus": 10.00
}

Adicionar Credito na Carteira (API)

Endpoint: POST /api/customers/{id}/wallet

Requisicao:

{
  "amount": 10.00,
  "reason": "Credito de servico",
  "type": "credit"
}

Adicionar Credito de Bonus (API)

Endpoint: POST /api/customers/bonus

Requisicao:

{
  "customerId": "customer-uuid",
  "amount": 5.00,
  "reason": "Bonus promocional"
}

Obter Transacoes da Carteira

Endpoint: GET /api/customers/{id}/wallet/transactions

Parametros de Query:

• limit: Numero de transacoes (padrao 50)
• offset: Offset de paginacao
• type: Filtrar por credito/debito

Melhores Praticas

Para Operadores

1. Documente todos os creditos manuais: Sempre inclua um motivo/observacao
2. Use bonus para promocoes: Reserve a carteira para reembolsos/compensacao
3. Auditorias regulares: Revise creditos grandes ou incomuns periodicamente
4. Politicas consistentes: Aplique creditos similares para problemas similares
5. Limite o acesso: Restrinja permissoes de adicao de credito apropriadamente

Para Atendimento ao Cliente

1. Verifique o saldo primeiro: Antes de adicionar credito, verifique o saldo atual
2. Referencie problemas: Vincule creditos a tickets de suporte ou IDs de viagem
3. Explique ao cliente: Diga como os creditos serao aplicados
4. Defina expectativas: Creditos se aplicam a proxima viagem automaticamente

Para Equipes Financeiras

1. Reconcilie regularmente: Combine creditos de carteira com compensacoes aprovadas
2. Monitore operacoes em massa: Revise grandes lotes de creditos
3. Rastreie por motivo: Categorize creditos para relatorios
4. Consciencia de passivo: Saldos de carteira sao um passivo da empresa

Solucao de Problemas

Credito nao aparece no aplicativo do cliente

• Verifique se o credito foi aplicado (verifique atividade da carteira)
• Peca ao cliente para atualizar o aplicativo ou fechar/reabrir
• Verifique se o credito foi para a conta correta do cliente
• Verifique se o cliente esta logado na conta correta

Saldo da carteira mostrando incorretamente

• Verifique transacoes recentes para debitos inesperados
• Verifique se nao foram aplicados creditos duplicados
• Revise o historico de viagens para deducoes automaticas
• Verifique ajustes gerados pelo sistema

Erros de processamento em massa

• Verifique se o formato CSV corresponde a estrutura esperada
• Verifique se o tipo de identificador esta correto para cada linha
• Certifique-se de que os identificadores de clientes sao validos
• Revise mensagens de erro para falhas especificas

Cliente diz que o credito nao foi aplicado na viagem

• Verifique o detalhamento do pagamento da viagem nos detalhes da viagem
• Verifique se o credito estava na conta antes da viagem comecar
• Confirme a ordem de aplicacao bonus vs. carteira
• Revise se o credito expirou (apenas bonus)