Ativando Cover Genius

A Cover Genius (plataforma XCover, familia de produtos Gig Cover) e a seguradora primaria por tras do Levy Cover. Ela ja subscreve seguro incorporado para Uber, Ola, Booking Holdings e Hopper. Esta licenciada em mais de 60 paises e todos os 50 estados dos EUA, e expoe uma API REST para cotacao -> vinculo -> sinistro -> pagamento com webhooks assinados e um sandbox.

Esta pagina cobre as etapas voltadas para operadores e engenharia para ativar a Cover Genius em uma implantacao da Levy Fleets.

Como a Levy se encaixa no modelo Cover Genius

A Cover Genius opera um modelo seguradora-distribuidor. A Cover Genius detem a licenca; a Levy Fleets esta registrada como parceira distribuidora sob essa licenca. Isso significa:

• A Levy nao e uma seguradora, MGA ou produtora por direito proprio.
• A Cover Genius e dona da subscricao, reservas de capital e julgamento de sinistros.
• A Levy e responsavel pela divulgacao transparente aos ciclistas, KYC preciso (tratado pelo Stripe Identity) e contabilidade correta de premios.
• O contrato de distribuicao define comissao, jurisdicoes cobertas, termos de pagamento e direitos de rescisao.

Variaveis de ambiente

O Levy Cover le duas variaveis de ambiente em tempo de execucao:

COVER_GENIUS_API_KEY=<sua chave de API do portal Cover Genius>
COVER_GENIUS_PARTNER_ID=<seu ID de parceiro do portal Cover Genius>

Ambos sao obrigatorios. Se algum estiver faltando, CoverGeniusClient lanca CarrierNotConfiguredError e recorre ao cliente mock em ambientes nao-producao. Em producao, o estado de credenciais faltando resulta em available: false para cada cotacao, e o cartao opt-in nunca aparece para os ciclistas.

Veja Configuracao de Credenciais da Seguradora para o ciclo de vida completo das credenciais (rotacao, sandbox vs producao, escopos de env do Vercel).

Endpoints que a Levy usa

Cada POST da Levy para a Cover Genius carrega um cabecalho Idempotency-Key com chave ride_id + operation. Isso protege contra vinculacoes ou sinistros duplicados se uma nova tentativa de rede acontecer no meio da chamada.

Registro de webhook

No portal Cover Genius, registre a URL do receptor de webhook:

https://fleets.levyelectric.com/api/webhooks/insurance/cover-genius

A Levy verifica a assinatura do webhook usando o segredo compartilhado da Cover Genius em cada evento de entrada. Falhas de verificacao caem em insurance_webhook_log com signature_verified = false e processed_at IS NULL, onde operacoes pode inspecionar.

Entregas duplicadas sao deduplicadas por UNIQUE (carrier, event_id) - o roteador captura o erro de chave duplicada e retorna { duplicate: true } para que a seguradora pare de tentar novamente.

UAT sandbox

A Cover Genius fornece um sandbox completo. Para exercita-lo:

1. Defina COVER_GENIUS_API_KEY sandbox em um ambiente de preview.
2. Registre a URL de webhook do ambiente de preview com o sandbox.
3. Execute de ponta a ponta:
   • Desbloqueie um veiculo, aceite o cartao opt-in.
   • Confirme que ride_insurance_policies tem uma linha com carrier_policy_id populado.
   • Encerre a viagem. Confirme que o recibo mostra o item de linha do premio.
   • Apresente um sinistro de teste do historico de viagens.
   • Acione webhooks sandbox para claim.approved e payout.completed.
   • Confirme que insurance_claims.status transita corretamente.
   • Se o destino do pagamento for levy_wallet, confirme que o credito na carteira referencia a linha insurance_claims, nao uma linha ride_refunds.

Transicao para producao

Quando o UAT sandbox estiver limpo e a Cover Genius tiver confirmado go-live:

1. Defina COVER_GENIUS_API_KEY e COVER_GENIUS_PARTNER_ID de producao na env de producao do Vercel.
2. Registre a URL de webhook de producao.
3. Acione os toggles de subconta que voce quer ao vivo em /dashboard/insurance/settings.
4. Monitore as primeiras 100 viagens seguradas:
   • insurance_webhook_log deve mostrar signature_verified = true em cada evento.
   • O cron noturno de reconciliacao da seguradora deve relatar zero discrepancias.
   • Lista de sinistros em /dashboard/insurance/claims deve estar populada com quaisquer sinistros reais.

Comportamento de falha

Se a API da Cover Genius estiver inacessivel no desbloqueio, a Levy falha aberta: a viagem e marcada como insurance_offered = false, nenhum premio e cobrado, e a viagem prossegue normalmente. Isso e deliberado. Bloquear o desbloqueio em uma falha da seguradora e inaceitavel.

Para mais sobre o que acontece com apolices vinculadas e sinistros pendentes durante uma falha, veja Solucao de Problemas.

Trocar seguradoras por jurisdicao

A matriz de jurisdicao pode rotear regioes diferentes para seguradoras diferentes. v2 introduz Slice como fallback - jurisdicoes onde a Cover Genius nao e licenciada, ou onde o preco nao e competitivo, podem ser trocadas para Slice sem mudancas de codigo. Veja Matriz de Jurisdicao.

---