Configuracao do Fornecedor — Drover & Luna

A deteccao de calcada requer hardware no veiculo. O Levy Vision integra com Drover AI PathPilot (primario) e Luna Systems (alternativa, mais forte na UE). Este artigo percorre a pipeline de aquisicao → instalacao → provisionamento → verificacao para ambos. Tambem cobrimos Captur.ai no fim — Captur fornece um classificador de pose de estacionamento, nao hardware de calcada.

Se voce nao esta rodando deteccao de calcada, pule este artigo — capacete e pose de estacionamento funcionam sem qualquer hardware de fornecedor.

Escolhendo um fornecedor

Faixas de custo sao estimativas de reportagem publica. Sua cotacao real vem do fornecedor na sua conversa comercial. Contate seu gerente de conta na Levy para uma apresentacao.

Passo 1 — Assinar o acordo com o fornecedor

Tanto Drover quanto Luna exigem um acordo em papel antes de provisionar dispositivos para voce. A Levy nao revende hardware deles — voce compra direto, nos integramos via webhooks.

O que voce precisa do fornecedor:

• Chave API para a API de provisionamento deles
• Secret de assinatura de webhook (preferivelmente por subaccount)
• Seriais de dispositivo para as unidades que voce esta instalando
• Lista de compatibilidade de OEM para seus modelos especificos de scooter/bike

Para deteccao de calcada em OKAI ES400 especificamente, confirme com o fornecedor que o limite de velocidade no meio da viagem funciona na sua versao de hardware — firmware mais antigo do ES400 nao aceita comandos de velocidade HBLB de forma confiavel.

Passo 2 — Instalar hardware nos veiculos

Isso e trabalho mecanico e varia por fornecedor e modelo de veiculo. O fornecedor fornece guias de instalacao; o suporte da Levy tem notas de instalacao para combinacoes comuns (Drover + Segway Max Plus, Drover + OKAI ES400, Luna + maioria dos scooters).

Dicas praticas:

• Pilote 5–10 veiculos antes de instalar a frota inteira. Taxas de DOA de hardware ficam em 2–5% na primeira instalacao.
• Tire fotos de cada instalacao — util se uma unidade der problema depois e voce precisar abrir uma RMA com o fornecedor.
• Anote cada serial de dispositivo e em qual veiculo foi. Voce vai inserir isso na Levy no passo 3.

Passo 3 — Provisionar dispositivos na Levy

Abra Dashboard > Safety > Vendor devices. A pagina mostra cada dispositivo provisionado para seu subaccount.

Para adicionar um novo:

1. Clique em Provision device.
2. Escolha o fornecedor (drover ou luna).
3. Insira o serial do dispositivo (do fornecedor).
4. Escolha o veiculo no dropdown (so aparecem veiculos no seu subaccount).
5. Clique em Save.

Por baixo dos panos, isso escreve uma linha em cv_vendor_devices ligando o serial do fornecedor ao UUID do veiculo. Quando eventos fluem do webhook do fornecedor, usamos esse mapeamento para atribuir o evento ao veiculo e viagem corretos.

Voce pode fazer isso em lote enviando um CSV (device_serial,vehicle_uuid) — util para rollouts amplos de frota de mais de ~20 dispositivos.

Passo 4 — Configurar o secret do webhook

Abra Dashboard > Safety > Safety settings e encontre o campo Webhook signing secret. Cole o secret que voce recebeu do fornecedor.

Por que por subaccount? Diferentes operadores na sua plataforma podem usar diferentes fornecedores com diferentes secrets. Armazenar por subaccount significa que verificamos cada webhook recebido contra a chave correta.

Uma vez salvo, este secret e criptografado em repouso. Ele nunca e registrado, nunca retornado via API, e voce pode rota-lo a qualquer momento sem afetar eventos que ja foram ingeridos.

Passo 5 — Dizer ao fornecedor para onde enviar eventos

De ao fornecedor estas URLs de webhook:

Tambem diga a eles para incluir seu ID de subaccount no header X-Levy-Subaccount-Id em cada requisicao. Sem ele, recorremos ao secret global de webhook, o que e menos seguro para configuracoes multi-tenant.

Para o schema de assinatura HMAC:

• Drover — header X-Drover-Signature: t=<unix_ts>,v1=<hmac_sha256_hex> sobre body
• Luna — header X-Luna-Signature: <hmac_sha256_hex> sobre body
• Captur — header X-Captur-Signature: <hmac_sha256_hex> sobre body

A documentacao do fornecedor explica como o SDK deles assina requisicoes. Verificamos a assinatura em cada requisicao e rejeitamos mismatches com 401.

Passo 6 — Verificar a pipeline

Dispare um evento de teste do lado do fornecedor. Drover e Luna ambos tem um recurso "send test event" no dashboard deles.

1. Dispare um evento de teste para um dispositivo provisionado.
2. Em alguns segundos, voce deve ver uma linha em Safety > Events com event_type=sidewalk_entry e source=drover (ou luna).
3. A coluna de efeitos colaterais deve estar vazia (eventos de teste nao disparam politicas por padrao).

Se o evento nao aparece:

• Verifique a pagina Vendor devices — o mapeamento serial-para-veiculo existe?
• Verifique o artigo Solucao de problemas — a arvore de diagnostico "sem eventos de calcada" cobre falhas de webhook.
• Verifique o Sentry se voce tem acesso — falhas de assinatura de webhook do fornecedor sao registradas la.

Passo 7 — Ativar aplicacao

Quando eventos estiverem fluindo de forma confiavel por uma semana, voce esta pronto para ativar a aplicacao. Abra Safety > Safety settings:

• Mude Sidewalk detection enabled para ativado
• Deixe Throttle cut enabled desligado no primeiro mes — aplique apenas com warn + speed reduce
• Defina limiares conforme Politica de corte de aceleracao

Revise a pagina Sidewalk hotspots semanalmente. Adicione poligonos de lista de permissao de geocerca para zonas claras de falso positivo (ciclovias protegidas, pracas que sua cidade permite).

Captur.ai (apenas pose de estacionamento)

Se voce quer um classificador de pose de estacionamento premium em vez de Gemini, Captur.ai e a opcao. A configuracao e mais simples — sem hardware:

1. Assine o acordo com a Captur.ai, obtenha a chave API.
2. Abra Safety > Safety settings e defina Parking classifier para Captur.
3. Cole a chave API (o suporte da Levy adiciona ela como env var em seu nome; isso nao e exposto no painel por razoes de seguranca).
4. A proxima foto de estacionamento roda pelo Captur em vez do Gemini.

Captur roda assincronamente — o piloto nao espera. O resultado chega via webhook em /api/webhooks/captur/result e atualiza a linha de parking_validations.

Renovando ou rotacionando credenciais

Se um fornecedor rotaciona sua chave API ou secret de assinatura:

1. Obtenha as novas credenciais do fornecedor.
2. Atualize o valor em Safety > Safety settings (secret de assinatura) e contate o suporte da Levy para a chave API.
3. Verifique se o proximo evento recebido ainda processa (verificacao de assinatura e o ponto de falha mais provavel).

Nao ha downtime se voce fizer com cuidado — eventos recebidos com o secret antigo sao rejeitados durante a janela enquanto o novo secret esta no lugar. A maioria dos operadores agenda rotacoes para uma hora de baixo trafego.

E se um fornecedor cair?

Se a pipeline do fornecedor para de enviar eventos por mais de 5 minutos durante horario de pico, o Sentry alerta nossa equipe e desativamos a aplicacao para sua frota automaticamente ate eventos voltarem a fluir. O painel mostra um banner dizendo "Sidewalk detection paused — vendor outage detected" para que voce saiba o que esta acontecendo.

Quando o fornecedor volta online, a aplicacao retoma automaticamente. Nenhuma acao necessaria de sua parte.