Reembolsos de Premio via Viagem

A viagem e a fonte da verdade para toda a contabilidade financeira. Um reembolso de premio Levy Cover e uma correcao de viagem primeiro. Qualquer credito na carteira e a jusante.

Por que esta regra existe

O premio e um item de linha na viagem. Contribui para rides.insurance_premium_amount, para o total da viagem, para net_deposited (apos a rede da seguradora ser deduzida) e para o calculo de repasse ao parceiro (comissao Levy e comissao do operador).

Se a carteira for creditada sem a viagem ser ajustada:

• A contabilidade da viagem ainda pensa que o premio foi mantido.
• net_deposited esta superestimado.
• O cron de repasse ao parceiro paga ao operador sua parte de um premio que foi efetivamente reembolsado.
• O arquivo de liquidacao da seguradora ainda inclui o premio.
• A remessa fiscal e relatada erroneamente.

Quando o reembolso flui atraves da viagem, todos esses efeitos a jusante sao corretamente recalculados pelo pipeline contabil existente.

Quando um reembolso de premio e valido

Um reembolso de premio Levy Cover so e valido nestes casos:

1. A viagem nunca comecou. O motor nao engatou dentro de 5 minutos do desbloqueio. O cartao opt-in foi aceito, mas o ciclista foi embora.
2. A chamada de vinculacao falhou retroativamente. A Levy obteve uma resposta 200 da seguradora, mas a seguradora depois relata "nenhuma apolice em arquivo" para essa viagem. O cron noturno de reconciliacao da seguradora sinaliza estes para operacoes.
3. A seguradora invalidou a apolice. Raro. A seguradora emite um webhook booking.voided; a Levy o recebe, sinaliza a viagem para reembolso de premio.
4. Um erro genuino de cobranca. O ciclista foi cobrado por um premio que nao optou - tipicamente um bug de UI ou uma preferencia desatualizada. Estes sao diagnosticados antes de qualquer reembolso.

Reembolsos de premio nao sao acionados por:

• Um pagamento de sinistro. O premio foi corretamente cobrado; a seguradora esta pagando em uma apolice valida. Veja Pagamentos da Seguradora e a Carteira.
• Um ciclista pedindo gentilmente. Nao reembolsamos premios por cortesia.
• Um sinistro sendo negado. Negacao significa que a seguradora nao pagou; nao significa que a apolice era invalida.

A mecanica

Reembolsos de premio delegam a infraestrutura existente de reembolso de viagem. O fluxo:

1. Operacoes ou o cron de reconciliacao identifica um premio que precisa ser reembolsado.
2. A Levy chama (ou prepara uma chamada para) /api/admin/insurance/policies/[id]/premium-refund.
3. Esse endpoint:
   • Invalida a apolice da seguradora via interface CarrierClient (se a seguradora ainda nao a invalidou).
   • Retorna um corpo de solicitacao que o chamador deve POSTar para a API de reembolso de viagem padrao: /api/rides/[ride_id]/refunds com { destination, mode: "partial", amount: <premium_amount>, reason: "Reembolso de premio Levy Cover - <razao>" }.
4. A API de reembolso de viagem:
   • Registra uma linha ride_refunds.
   • Chama o RPC update_ride_net_deposited para que net_deposited esteja correto.
   • Emite o credito na carteira (se destination = "wallet") via o helper de reembolso padrao que requer uma linha ride_refunds real.
   • Recalcula repasses de parceiros.

O helper de reembolso de premio src/lib/insurance/premium-refund.ts nao chama creditWalletForRefund diretamente. Ele retorna o corpo de solicitacao de reembolso. O credito real na carteira acontece dentro da API de reembolso de viagem, com auditabilidade completa.

O que o operador ve

Um reembolso de premio aparece no detalhe da viagem como:

• Uma linha ride_refunds com razao "Reembolso de premio Levy Cover - <razao especifica>".
• Um net_deposited atualizado que exclui o premio.
• Um credito na carteira (se o destino do reembolso foi a carteira) vinculado a linha ride_refunds, nao a uma linha insurance_claims.

Importante, insurance_premium_amount da viagem nao e zerado. O premio original ainda e registrado para fins de auditoria; o reembolso e registrado como um ajuste separado. Isso espelha como ajustes parciais de tarifa funcionam em outras partes da plataforma.

Apolices invalidadas pela seguradora

Quando a seguradora invalida uma apolice, a Levy recebe um webhook booking.voided. O handler do webhook:

1. Define ride_insurance_policies.voided_at = now().
2. Registra a razao da invalidacao.
3. Cria uma tarefa premium_refund_required para operacoes.
4. Nao reembolsa o premio automaticamente. Um humano revisa a invalidacao e roteia o reembolso atraves da API de reembolso de viagem.

A razao para o humano no loop: invalidacoes da seguradora podem ser acionadas por sinais de fraude, falhas de KYC do ciclista ou erros de apolice. Alguns desses cenarios justificam um reembolso; alguns nao. O reembolso automatico padrao corre risco de pagar em invalidacoes fraudulentas.

O que voce absolutamente nao pode fazer

O seguinte sao violacoes diretas do CLAUDE.md e quebram o modelo contabil:

• UPDATE direto em customers.wallet_balance para adicionar o valor do premio de volta.
• INSERT direto em wallet_transactions com o valor do premio como um credito manual.
• Chamar creditWalletForRefund sem ride_refund_id, sem insurance_claim_id e sem uma correcao de viagem envolvente.
• Inserir uma linha insurance_claims como solucao alternativa para criar um credito na carteira insurance_claim_payout para o que e realmente um reembolso de premio. Estes sao eventos categoricamente diferentes e o esquema impoe a distincao.

Se voce esta tentado a fazer qualquer um destes porque a API esta inacessivel, a resposta certa e esperar ou escalar, nao contornar.

Por que esta diretriz e nao negociavel

Esta e a mesma regra que protege todos os outros fluxos de reembolso na plataforma: correcoes de tarifa de viagem, reembolsos automaticos, recompensas Rider Score, cobrancas de danos. O padrao e consistente em todo o codigo. Premios de seguro nao sao especiais - sao um item de linha na viagem e reembolsam como um item de linha na viagem.

A diretriz completa esta documentada no CLAUDE.md do projeto sob "Refunds & Fare Adjustments". Esta pagina e a aplicacao especifica de seguro dessa regra.

---