Solucao de Problemas de Plugin

Este guia conduz pelos problemas mais comuns de plugin que operadores encontram e como corrigi-los.

Meu plugin mostra status "Falhando"

Isto significa que entregas recentes de webhook tiveram erros. Abra a instalacao (Configuracoes -> Plugins -> icone de engrenagem) para ver o que esta errado.

Passos

Nao estou recebendo nenhum evento

Possiveis causas, em ordem de probabilidade:

1. Plugin esta desativado. Verifique o indicador de status. Clique em Ativar se mostrar Desativado.
2. Plugin nao esta assinando o evento que voce espera. Plugins diferentes assinam eventos diferentes. Abra a pagina de detalhes do plugin para ver sua lista webhook_subscriptions.
3. O evento nao esta disparando em sua subconta. Teste disparando o evento manualmente (por exemplo, terminar uma corrida de teste para um evento ride.ended).
4. Endpoint de webhook esta inacessivel. Va para "Meu plugin mostra status Falhando" acima.
5. Token foi revogado. Rotacione o token e forneca o novo ao fornecedor.

Um evento especifico esta faltando

Se a maioria dos eventos esta chegando mas um nao:

• Verifique a taxonomia de eventos no manifesto do plugin. Se o evento nao esta em webhook_subscriptions, o plugin nao esta escutando.
• Alguns eventos ainda nao estao conectados ao nucleo Levy. Os eventos zone.entered, zone.exited e zone.violation sao definidos mas nem sempre emitidos dependendo de quais modulos de rastreamento de zonas estao ativados em sua subconta.
• Para customer.kyc_completed, o evento dispara apenas quando um plugin KYC esta instalado e escrevendo resultados de volta ativamente - sem um plugin KYC, nenhum evento e emitido.

Verificacao de assinatura de webhook falha (lado do fornecedor)

Se voce e um fornecedor e seu endpoint rejeita as assinaturas da Levy:

• Verifique se voce esta verificando a assinatura no formato correto: X-Levy-Signature: t=<unix-ts>,v1=<hex-hmac>.
• O payload assinado e ${ts}.${body} - note o separador de ponto e que body e o corpo bruto da requisicao, nao o JSON parseado.
• O segredo de assinatura e o segredo por instalacao do seu plugin, disponivel em seu painel de fornecedor para cada instalacao.
• A Levy rejeita timestamps mais antigos que 5 minutos; garanta que seu relogio esta sincronizado com NTP.

Veja Enviando um plugin - endpoint de webhook para codigo de verificacao de exemplo.

Chamadas de API do plugin estao retornando 401

O token do plugin e invalido. Razoes:

• O token foi rotacionado recentemente e o periodo de gracia de 24 horas expirou. Envie o novo token ao fornecedor.
• A instalacao foi desinstalada - o token e permanentemente revogado.
• O formato do token nao corresponde a lvy_plg_<prefixo-de-instalacao>_<aleatorio> - o fornecedor pode estar usando um token de uma conta diferente.
• A ID de subconta do plugin nao corresponde a ID de subconta do recurso - o fornecedor esta tentando ler dados de uma subconta que nao o instalou. Este e um bloqueio rigido na camada RLS, nao configuravel.

Chamadas de API do plugin estao retornando 403

O token do plugin e valido mas falta uma permissao necessaria. O corpo da resposta inclui o escopo faltante:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing permission: read:customers.pii",
    "required_scope": "read:customers.pii"
  }
}

Voce (o operador) nao pode conceder novas permissoes a um plugin instalado sem reinstalar. Se o manifesto de um fornecedor mudar para adicionar uma nova permissao, voce vera um banner pedindo que reconsensam.

Cobranca - cobranca falhou

Se uma cobranca mensal ou de uso falhar:

1. Abra Configuracoes -> Cobranca -> Faturas de plugin para ver a fatura falhada.
2. Verifique seu metodo de pagamento em Configuracoes -> Cobranca -> Metodos de pagamento. Atualize-o se expirado.
3. O Stripe tenta automaticamente em seu cronograma padrao (4 tentativas em ~2 semanas). O plugin permanece ativo durante as tentativas.
4. Se todas as tentativas falharem, o plugin e desativado (nao desinstalado - sua configuracao e preservada). Atualize seu metodo de pagamento e reative.

Cobranca - cobranca disputada

Se voce abrir um chargeback atraves do seu banco, o Stripe Connect lida com a disputa em nome da Levy:

1. A Levy coleta evidencias do log de auditoria do plugin (eventos entregues, chamadas de API feitas).
2. O fornecedor tambem pode enviar evidencias.
3. O Stripe toma a decisao final por regras de rede.
4. Se a disputa for mantida a seu favor, tanto a parcela do fornecedor quanto a taxa de plataforma da Levy sao retornadas.

Contate support@levyelectric.com se voce precisa de ajuda para preparar evidencia de disputa.

Token vazou - o que faco?

Mudanca de configuracao nao esta sendo aplicada

Quando voce salva uma mudanca de configuracao, ela entra em vigor na proxima entrega de evento - normalmente segundos a minutos. Se voce nao ve a mudanca refletida:

• Verifique se voce realmente clicou em Salvar (o formulario deve limpar seu estado modificado).
• Para plugins conectados via OAuth, reexecutar OAuth da tela de configuracao forca uma troca de token fresca.
• Verifique o log de auditoria - cada acao configure e registrada com a nova configuracao. Se estiver faltando, o salvamento nao passou.
• Para BigQuery / Snowflake, mudancas de cronograma se aplicam na proxima execucao agendada, nao imediatamente.

Plugin funciona para algumas corridas mas nao outras

Plugins sao limitados por subconta. Se voce tem multiplas subcontas (por exemplo, uma por cidade), voce precisa instalar o plugin separadamente em cada uma. Um plugin instalado na Subconta A nao processara corridas na Subconta B.

O que vem a seguir

• Configurando um plugin - para mudancas rotineiras de configuracao
• Cobranca de plugins - problemas especificos de cobranca
• FAQ - perguntas comuns e respostas rapidas