Entendendo as Cobranças de Viagem

Este guia explica como as cobranças de viagem sao calculadas e o que os clientes veem em seus recibos. Seja voce um usuario tentando entender sua conta ou um operador resolvendo uma questao de precificacao, este artigo detalha cada componente de uma cobrança de viagem.

---

Visao Geral

Cada viagem concluida gera um detalhamento de cobrança detalhado. Entender esses componentes ajuda os operadores a explicar cobranças aos clientes, verificar se os precos estao funcionando corretamente e resolver questoes de cobrança.

O Que os Clientes Veem

Quando uma viagem termina, os clientes recebem um recibo mostrando:

• Componentes individuais de cobrança (desbloqueio, tempo, pausa, distancia)
• Quaisquer descontos aplicados (assinaturas, pacotes, promos)
• Ajustes de precos dinamicos
• Valor final cobrado

O Que os Operadores Veem

O painel fornece detalhes adicionais:

• Cobranças base antes dos descontos
• Cada fonte de desconto e valor
• Status de aplicacao do limite diario
• Trilha de auditoria completa de cobrança

---

Componentes de Cobrança

Taxa de Desbloqueio

Uma cobrança unica aplicada quando a viagem comeca.

Recibo do Cliente: "Taxa de Desbloqueio: R$ 5,00"

Quando Aplicada: Sempre cobrada no inicio da viagem (a menos que coberta por assinatura/pacote)

Como e Calculada:

Taxa de Desbloqueio = unlock_fee_cents da Regra de Preco / 100

Taxa de Tempo

Cobranças baseadas em quanto tempo o cliente andou ativamente.

Recibo do Cliente: "Tempo: 15 min × R$ 1,95/min = R$ 29,25"

Como e Calculada:

Minutos Ativos = Total de Minutos - Minutos de Pausa
Taxa de Tempo = Minutos Ativos × Tarifa por Minuto

Taxa de Pausa

Cobranças durante porcoes pausadas da viagem.

Recibo do Cliente: "Pausa: 5 min × R$ 0,50/min = R$ 2,50"

Como e Calculada:

Taxa de Pausa = Minutos de Pausa × Taxa de Pausa por Minuto

Taxa de Distancia

Cobranças baseadas na distancia percorrida (apenas para precos baseados em distancia).

Recibo do Cliente: "Distancia: 8,5 km × R$ 1,50/km = R$ 12,75"

Como e Calculada:

Taxa de Distancia = Distancia (km) × Tarifa por KM

---

O Detalhamento Completo de Cobrança

Subtotal Base

A soma de todas as cobranças brutas antes de quaisquer ajustes:

Subtotal Base = Taxa de Desbloqueio + Taxa de Tempo + Taxa de Pausa + Taxa de Distancia

Exemplo:

Desbloqueio:   R$ 5,00
Tempo:         R$ 29,25
Pausa:         R$ 2,50
Distancia:     R$ 0,00  (preco baseado em tempo)
───────────────────
Subtotal:      R$ 36,75

Apos Beneficios

Assinaturas e pacotes de viagem reduzem o subtotal:

Apos Beneficios = Subtotal Base - Desconto de Assinatura - Desconto de Pacote

Exemplo com assinatura:

Subtotal Base:           R$ 36,75
Desconto de Assinatura:  -R$ 25,00  (cobriu 10 min + desbloqueio)
───────────────────────────────────
Apos Beneficios:         R$ 11,75

Apos Precos Dinamicos

Ajustes de precos dinamicos (pico/desconto) sao aplicados a seguir:

Apos Dinamico = Apos Beneficios × Multiplicador + Ajuste Fixo

Exemplo com pico:

Apos Beneficios:     R$ 11,75
Pico (25%):          × 1,25 = R$ 14,69
Sobretaxa Fixa:      + R$ 5,00
───────────────────────────────
Apos Dinamico:       R$ 19,69

Apos Codigo Promocional

Descontos de codigo promocional sao aplicados por ultimo:

Apos Promo = Apos Dinamico - Desconto Promo

Exemplo com promo:

Apos Dinamico:  R$ 19,69
Promo (20%):    -R$ 3,94
───────────────────────
Apos Promo:     R$ 15,75

Valor Final

A cobrança final respeita limites diarios e precos minimos:

Final = MIN(Apos Promo, Limite Diario)
Final = MAX(Final, Preco Minimo)  // Apenas se nenhum beneficio usado

---

Entendendo o Recibo

Exemplo Completo de Recibo

Aqui esta o que um cliente pode ver para uma viagem de e-bike premium:

═══════════════════════════════════════════════════
          RECIBO DE VIAGEM
═══════════════════════════════════════════════════

Veiculo:           E-Bike Premium
Localizacao:       Centro SP
Data:              25 de Dezembro de 2025
Duracao:           25 minutos (20 ativos, 5 pausados)
Distancia:         6,2 km

─────────────────────────────────────────────────
COBRANÇAS
─────────────────────────────────────────────────

Taxa de Desbloqueio                     R$ 7,50
Tempo (20 min × R$ 2,45/min)           R$ 49,00
Pausa (5 min × R$ 0,75/min)             R$ 3,75
                                      ────────
Subtotal                               R$ 60,25

─────────────────────────────────────────────────
DESCONTOS E AJUSTES
─────────────────────────────────────────────────

Membro Premium (20% desbloq, 15% tempo) -R$ 8,85
Passe Semanal (10 min cobertos)        -R$ 24,50
Pico Fim de Semana (+15%)               +R$ 4,04
Codigo Promo ANDE20 (20%)               -R$ 6,19
                                      ────────
TOTAL COBRADO                          R$ 24,75

═══════════════════════════════════════════════════
Pagamento: Visa ****1234
═══════════════════════════════════════════════════

Recibo com Desbloqueio Gratis

Quando um cliente usa um de seus desbloqueios gratis mensais:

═══════════════════════════════════════════════════
          RECIBO DE VIAGEM
═══════════════════════════════════════════════════

Veiculo:           Patinete Padrao
Localizacao:       Centro
Data:              25 de Dezembro de 2025
Duracao:           12 minutos
Distancia:         3,1 km

─────────────────────────────────────────────────
COBRANÇAS
─────────────────────────────────────────────────

Taxa de Desbloqueio                     R$ 5,00
Tempo (12 min × R$ 1,95/min)           R$ 23,40
                                      ────────
Subtotal                               R$ 28,40

─────────────────────────────────────────────────
DESCONTOS E AJUSTES
─────────────────────────────────────────────────

Membro Elite - Desbloqueio Gratis       -R$ 5,00
Membro Elite (20% tempo)                -R$ 4,68
                                      ────────
TOTAL COBRADO                          R$ 18,72

═══════════════════════════════════════════════════
Desbloqueios gratis restantes este mes: 4 de 5
═══════════════════════════════════════════════════

Explicacoes dos Itens de Linha

"Membro Premium (20% desbloq, 15% tempo): -R$ 8,85"

• Desconto de nivel de fidelidade para membros Premium
• 20% de desconto na taxa de desbloqueio: R$ 7,50 × 0,20 = R$ 1,50
• 15% de desconto nas taxas de tempo: R$ 49,00 × 0,15 = R$ 7,35
• Economia total de nivel: R$ 8,85

"Membro Elite - Desbloqueio Gratis: -R$ 5,00"

• Beneficio de desbloqueio gratis mensal usado
• Nivel Elite inclui 5 desbloqueios gratis por mes
• Cliente escolheu usar um de seus desbloqueios gratis restantes
• Mostra contagem restante apos a viagem

"Taxa de Desbloqueio: R$ 7,50"

• Taxa base para desbloquear o veiculo
• Configurada por modelo de veiculo
• Pode ser coberta por assinaturas/pacotes ou beneficios de nivel

"Tempo (20 min × R$ 2,45/min): R$ 49,00"

• Apenas tempo de viagem ativo
• 5 minutos pausados excluidos deste calculo
• Usa a tarifa por minuto para este veiculo

"Pausa (5 min × R$ 0,75/min): R$ 3,75"

• Tempo que a viagem ficou pausada
• Normalmente uma tarifa menor que tempo ativo
• Incentiva usuarios a encerrar em vez de pausar indefinidamente

"Passe Semanal (10 min cobertos): -R$ 24,50"

• Beneficio de assinatura aplicado
• A assinatura do cliente cobriu 10 dos 20 minutos ativos
• Economiza dinheiro do cliente enquanto usa sua assinatura

"Pico Fim de Semana (+15%): +R$ 5,35"

• Regra de preco dinamico aplicada
• Aumento de 15% devido a demanda de fim de semana
• Aplicado ao subtotal pos-beneficio

"Codigo Promo ANDE20 (20%): -R$ 8,21"

• Cliente aplicou um codigo promocional
• 20% de desconto no valor pos-pico
• Aplicado por ultimo antes do total final

---

Protecao de Limite Diario

Como os Limites Diarios Funcionam

Limites diarios protegem os clientes de cobranças inesperadamente altas em um unico dia.

Exemplo:

• Limite Diario: R$ 150,00
• Primeira Viagem: R$ 60,00 (cobrado)
• Segunda Viagem: R$ 75,00 (cobrado)
• Terceira Viagem: R$ 50,00 → Apenas R$ 15,00 cobrado (limite atingido)

Ordem de Reducao do Limite

Quando uma unica viagem excede o limite diario, as cobranças sao reduzidas nesta ordem:

1. Taxas de tempo - Reduzidas primeiro
2. Taxas de pausa - Reduzidas segundo
3. Taxas de distancia - Reduzidas terceiro
4. Taxa de desbloqueio - Reduzida por ultimo (apenas se necessario)

Isso garante que os clientes ainda paguem pelo desbloqueio do veiculo quando possivel.

Exemplo (Limite de R$ 150, Total da Viagem R$ 210):

Detalhamento Original:
  Desbloqueio:   R$ 7,50
  Tempo:         R$ 175,00
  Pausa:         R$ 17,50
  Distancia:     R$ 10,00
  Total:         R$ 210,00

Apos Aplicacao do Limite:
  Desbloqueio:   R$ 7,50  (inalterado)
  Tempo:         R$ 115,00 (reduzido em R$ 60)
  Pausa:         R$ 17,50  (inalterado)
  Distancia:     R$ 10,00  (inalterado)
  Total:         R$ 150,00 (limitado)

Indicacao no Recibo

Quando o limite diario e aplicado, os recibos mostram:

Limite Diario Aplicado ✓
Cobrança Diaria Maxima: R$ 150,00

---

Comportamento do Preco Minimo

Como os Minimos Funcionam

Precos minimos garantem que cada viagem gere receita base.

Exemplo:

• Preco Minimo: R$ 10,00
• Total Calculado: R$ 6,00
• Cobrança Final: R$ 10,00

Quando os Minimos Nao se Aplicam

Os minimos NAO sao aplicados quando:

• Beneficios de assinatura foram usados
• Beneficios de pacote de viagem foram usados

Isso protege clientes que ja pagaram por seus beneficios.

Exemplo com Assinatura:

Subtotal Base:        R$ 25,00
Assinatura Cobre:     -R$ 25,00
Total Calculado:      R$ 0,00
Preco Minimo:         R$ 10,00 (nao aplicado - assinatura usada)
Cobrança Final:       R$ 0,00

---

Cenarios Comuns de Cobrança

Cenario 1: Viagem Simples (Sem Descontos)

Configuracao: Patinete padrao, viagem de 10 minutos

Desbloqueio:  R$ 5,00
Tempo:        10 × R$ 1,95 = R$ 19,50
───────────────────────────
Total:        R$ 24,50

Cenario 2: Viagem com Pausa

Configuracao: E-bike, 15 min (12 ativos, 3 pausados)

Desbloqueio:  R$ 7,50
Tempo:        12 × R$ 2,45 = R$ 29,40
Pausa:        3 × R$ 0,75 = R$ 2,25
───────────────────────────
Total:        R$ 39,15

Cenario 3: Cobertura de Assinatura

Configuracao: Passe semanal (60 min/dia), viagem de 25 minutos

Desbloqueio:           R$ 5,00 (coberto pela assinatura)
Tempo:                 25 × R$ 1,95 = R$ 48,75 (coberto pela assinatura)
Assinatura Economiza:  -R$ 53,75
───────────────────────────────────────────
Total:                 R$ 0,00

Cenario 4: Cobertura Parcial de Pacote

Configuracao: Pacote de 10 minutos (8 min restantes), viagem de 15 minutos

Desbloqueio:         R$ 5,00 (coberto pelo pacote)
Tempo:               15 × R$ 1,95 = R$ 29,25
Pacote Cobre:        -R$ 20,60 (8 min × R$ 1,95 + R$ 5,00 desbloqueio)
Tempo Restante:      7 × R$ 1,95 = R$ 13,65
───────────────────────────────────────────────
Total:               R$ 13,65

Cenario 5: Pico + Promo Combinados

Configuracao: Viagem de R$ 50, pico de 25%, promo de 20%

Base:           R$ 50,00
Pico (25%):     R$ 50,00 × 1,25 = R$ 62,50
Promo (20%):    R$ 62,50 × 0,80 = R$ 50,00
───────────────────────────────────────
Total:          R$ 50,00

Cenario 6: Limite Diario Atingido

Configuracao: Viagem de R$ 225 com limite diario de R$ 150

Calculado:      R$ 225,00
Limite Diario:  R$ 150,00
───────────────────────────
Total:          R$ 150,00 (limitado)

Cenario 7: Descontos de Nivel de Fidelidade

Configuracao: Membro nivel Premium (20% desbloqueio, 15% tempo), viagem de 15 minutos

Desbloqueio:           R$ 7,50
Tempo:                 15 × R$ 1,95 = R$ 29,25
Subtotal:              R$ 36,75

Nivel Premium:
  Desbloqueio (20%):   -R$ 1,50
  Tempo (15%):         -R$ 4,39
  Desconto Nivel:      -R$ 5,89
───────────────────────────────────
Total:                 R$ 30,86

Cenario 8: Desbloqueio Gratis + Desconto de Nivel

Configuracao: Nivel Elite (5 desbl. gratis/mes, 20% desconto tempo), usando desbloqueio gratis

Desbloqueio:           R$ 5,00
Tempo:                 10 × R$ 1,95 = R$ 19,50
Subtotal:              R$ 24,50

Nivel Elite:
  Desbloqueio Gratis:  -R$ 5,00 (1 de 5 usado)
  Tempo (20%):         -R$ 3,90
  Desconto Nivel:      -R$ 8,90
───────────────────────────────────
Total:                 R$ 15,60

---

Resolucao de Problemas de Cobranças

Cliente Diz "Fui Cobrado a Mais"

1. Revise os detalhes da viagem:

   • Verifique a duracao real vs. expectativa do cliente
   • Confirme que o tempo de pausa foi rastreado corretamente
   • Confirme o modelo do veiculo e seus precos

2. Verifique precos dinamicos:

   • Havia um pico ativo durante a viagem?
   • Qual foi a porcentagem de ajuste?

3. Verifique os beneficios:

   • Eles tinham uma assinatura ativa?
   • As cotas do pacote estavam disponiveis?
   • A viagem foi na localizacao correta?

4. Verifique codigo promocional:

   • Um codigo promocional foi aplicado?
   • Falhou na validacao (expirado, limite atingido)?

Cliente Diz "Minha Assinatura Nao Foi Aplicada"

1. Verifique o status da assinatura:

   • Esta marcada como 'ativa'?
   • Expirou?

2. Verifique correspondencia de localizacao:

   • A assinatura esta com escopo para uma subconta diferente?
   • O cliente andou na area correta?

3. Verifique as cotas:

   • As cotas diarias ja foram usadas?
   • E uma assinatura daily_limit que nao resetou?

4. Revise o tempo:

   • A viagem ocorreu durante o periodo da assinatura?
   • Houve um intervalo entre compra da assinatura e viagem?

Cliente Diz "Meu Codigo Promocional Nao Funcionou"

1. Verifique validade do codigo:

   • O codigo esta ativo?
   • A hora atual esta entre valid_from e valid_until?

2. Verifique limites de uso:

   • O limite global foi atingido?
   • Este cliente usou seu limite por cliente?

3. Verifique requisitos:

   • A viagem atingiu o valor minimo?
   • O codigo esta com escopo para uma localizacao/veiculo diferente?

4. Verifique tipo de aplicacao:

   • E um codigo de credito de carteira usado em uma viagem?
   • E um codigo de viagem usado em uma compra de assinatura?

Cobrança Mostra R$ 0 Mas Cliente Foi Cobrado

Isso geralmente indica uma cobrança parcial ou retencao:

1. Verifique alreadyChargedCents:

   • Um valor de retencao foi capturado no inicio da viagem?
   • O final mostra R$ 0 porque a retencao cobriu

2. Revise historico de pagamento:

   • Procure por uma retencao/autorizacao anterior
   • A "cobrança" pode ter sido a liberacao da retencao

---

Detalhes Tecnicos

Precisao do Calculo

Todos os calculos sao realizados em centavos (inteiros) para evitar erros de ponto flutuante:

// Correto (em centavos)
timeFeeCents = perMinuteCents * minutes  // 195 * 10 = 1950

// Exibicao (converter para reais)
timeFeeDollars = timeFeeCents / 100  // 1950 / 100 = R$ 19,50

Regras de Arredondamento

• Minutos sao arredondados para numeros inteiros
• Distancia e preservada ate 3 casas decimais
• Cobranças finais sao arredondadas para centavos inteiros

Trilha de Auditoria

Cada viagem armazena seu detalhamento completo de precos:

{
  "base": {
    "unlockFeeCents": 500,
    "timeFeeCents": 1950,
    "pauseFeeCents": 0,
    "distanceFeeCents": 0,
    "subtotalCents": 2450
  },
  "subscription": {
    "discountCents": 1000,
    "purchaseId": "..."
  },
  "package": null,
  "dynamic": {
    "multiplier": 1.0,
    "adjustmentCents": 0
  },
  "promo": null,
  "totals": {
    "baseSubtotalCents": 2450,
    "subscriptionDiscountCents": 1000,
    "packageDiscountCents": 0,
    "dynamicAdjustmentCents": 0,
    "promoDiscountCents": 0,
    "finalCents": 1450,
    "amountDueCents": 1450
  }
}

---

Modelos de Comunicacao com o Cliente

Explicando uma Cobrança

"Oi [Nome], revisei sua viagem do dia [data]. Aqui esta o detalhamento:

• Taxa de desbloqueio: R$ X,XX
• Tempo (X minutos): R$ X,XX
• [Quaisquer descontos/ajustes]

Total cobrado: R$ X,XX

Ha algo especifico sobre essas cobranças que posso esclarecer?"

Explicando um Pico

"Oi [Nome], sua viagem incluiu um ajuste de pico de [X%]. Isso estava ativo devido a [alta demanda/clima/horario do dia] durante sua viagem. O pico adicionou R$ X,XX a sua tarifa base de R$ X,XX."

Explicando um Limite

"Oi [Nome], boas noticias! Sua viagem foi limitada ao nosso maximo diario de R$ X,XX. Sem o limite, a viagem teria sido R$ X,XX. Isso economizou R$ X,XX."

Explicando Cobertura de Assinatura

"Oi [Nome], sua [nome da assinatura] cobriu [X minutos/a taxa de desbloqueio] nesta viagem. Sua assinatura economizou R$ X,XX nesta viagem. Voce tem [X minutos/desbloqueios] restantes para hoje."

---