Comecando com Levy Compliance

Este artigo conduz voce pelo onboarding de uma unica jurisdicao (uma cidade) de ponta a ponta. O estado final: endpoints MDS estao ativos, o feed de politica da cidade e consultado a cada 60 segundos, geofences ativam-se conforme programado e o contato municipal recebe e-mails de digest diarios/semanais/mensais.

Pre-requisitos

Antes de comecar, confirme o seguinte:

Passo 1 -- Criar a jurisdicao

Passo 2 -- Confirmar que endpoints MDS respondem

Cada jurisdicao herda a mesma base de endpoint MDS sob sua subconta:

GET /api/mds/{subaccountId}/provider/v2/vehicles
GET /api/mds/{subaccountId}/provider/v2/vehicles/status
GET /api/mds/{subaccountId}/provider/v2/trips
GET /api/mds/{subaccountId}/provider/v2/events
GET /api/mds/{subaccountId}/provider/v2/telemetry/{vehicle_id}
GET /api/mds/{subaccountId}/provider/v2/stops
GET /api/mds/{subaccountId}/provider/v2/reports
GET /api/mds/{subaccountId}/.well-known/jwks.json

Acesse vehicles/status com seu token bearer para confirmar:

curl -H "Authorization: Bearer <YOUR_MDS_TOKEN>" \
  https://fleets.levyelectric.com/api/mds/<subaccountId>/provider/v2/vehicles/status

Uma resposta bem-sucedida carrega:

• HTTP 200
• Content-Type: application/vnd.mds+json;version=2.0
• Header MDS-JWT (prova assinada do sha256 do corpo da resposta)
• Um campo version definido como 2.0.1 no envelope JSON

Veja Configuracao do MDS Provider para a referencia completa de endpoints.

Passo 3 -- Entregar as URLs a cidade

Envie ao contato municipal um e-mail curto com estas quatro informacoes:

A instancia Populus / Ride Report / Lacuna da cidade validara os endpoints contra o validador GBFS da MobilityData e o validador mds-provider-validator do OMF antes de marcar sua frota como ativa em seu dashboard. Ambos os validadores devem passar sem avisos.

Passo 4 -- Observar o primeiro poll de politica

O cron mds-policy-poll roda a cada minuto. Em 60 segundos apos salvar a jurisdicao:

1. O poller acessa o feed de politica da cidade.
2. O payload bruto e hasheado em sha256 e comparado ao ultimo hash conhecido.
3. Se mudou, o validador Zod faz parse de policies[] e geographies[].
4. Politicas sao upsertadas; regras sao substituidas; linhas policy_geofences sao materializadas das geografias referenciadas.
5. Uma linha cai em mds_policy_audit com run_id, JSON diff e applied_at.

Abra /dashboard/compliance/{jurisdiction-id} e voce deve ver a lista de politicas ativas povoada. Veja Ingestao de Politica de Cidades para o visualizador de diff.

Passo 5 -- Configurar contatos municipais

Contatos municipais recebem acesso por magic link ao Portal da Cidade e recebem e-mails de digest em uma cadencia que voce define.

Passo 6 -- Definir condicoes de licenca

Se sua licenca especifica condicoes aplicaveis (cap de frota, percentual de zonas de equidade, SLA de reclamacoes), registre cada uma em permit_conditions. O reporter de conformidade as avalia em cada execucao de digest.

Veja Relatorios de Condicoes de Licenca para detalhes do avaliador.

Passo 7 -- Verificar o primeiro digest

O cron compliance-digest roda horariamente e percorre cada linha de city_contacts cuja janela de cadencia expirou. Para um contato daily criado hoje, o primeiro e-mail chega dentro de uma hora apos o fechamento do periodo de digest (tipicamente meia-noite na hora local da jurisdicao).

Quando o e-mail sai:

• Uma linha e gravada em city_compliance_reports com payload (o JSON renderizado) e pdf_url se um PDF mensal foi anexado.
• O last_digest_sent_at do contato e atualizado.

Se a cidade nao ve o e-mail apos a janela esperada, verifique spam, depois verifique last_digest_sent_at em city_contacts -- se estiver desatualizado, o cron nao disparou ou o sender deu erro. Veja Solucao de Problemas.

O que voce realizou

Depois dos passos 1-7:

• Sua subconta publica um feed MDS 2.0 Provider conformante
• Um feed GBFS 3.0 (com vehicle_type_id por regra de zona) esta ativo ao lado do feed 2.x legado
• O feed de politica da cidade e consultado a cada minuto e comparado ao ultimo conhecido
• Geofences empilhados com a prioridade correta materializam-se das regras municipais
• O contato municipal pode logar no portal via magic link
• E-mails de digest fluirao na cadencia configurada
• Pass/fail de condicoes de licenca e computado diariamente e mostrado tanto no dashboard do operador quanto no portal municipal

Voce pode agora apontar seu oficial de licenca municipal para os endpoints MDS publicos e a raiz GBFS 3.0.

Proximos passos

• Configuracao do MDS Provider -- referencia de endpoint e detalhes de assinatura.
• Ingestao de Politica de Cidades -- visualizador de diff, auditoria, ativacao.
• Prioridade de Geofences Empilhados -- como regras municipais sobrescrevem suas zonas de operador.
• Solucao de Problemas -- quando polls ou digests nao disparam.