API de gestão de frotas para Vethy VS02 PRO: REST + GraphQL para integrações personalizadas

• Tabela de conteúdo

1. API REST: endpoints para telemetria, configuração, OTA, diagnóstico
2. API GraphQL: consultas eficientes para painéis
3. Authentificação OAuth 2,0 e controle de acesso baseado em funções
4. Eventos do Webhook: em tempo real para alertas de falha e conclusão do OTA

Muitos grandes operadores de frota com mais de 500 caminhões constroem plataformas de gestão de frota proprietária internamente em vez de dependerem apenas do Geotab, Samsara ou da Webfleet. Para estas frotas, o Vethy fornece acesso direto à API REST e GraphQL a todos os diagnósticos de telemetria, configuração, gerenciamento OTA e BMS do Vethy VS02 PRO e V-FMSG-24. Esta página documenta os endpoints da API, fluxo de autenticação OAuth 2,0, assinaturas de eventos webhook, limites de taxas e padrões comuns de integração usados pelas equipes de TI da frota no Schneider National, J.B. Hunt, Mærsk, DSV, DB Schenker e Kuehne+Nagel.

API REST: endpoints para telemetria, configuração, OTA, diagnóstico

URL de base: https://api.vethy.com/v2/. Endpoints primários: **GET /fleet/ {fleet_id}/ vehicles** — lista todos os veículos com VS02 PRO. **GET /vehicles/{vin}/telemetria?de=&to=&fields=** — telemetria histórica (duração, SoC, temperatura, energia). **GET /vewicles/{vin {/telemetria/live** — estado atual. **GET / vehicles/{ven}/diagnóstico** — códigos de falha e saúde do BMS. **POST /vehicles /{vin}/ config** — ponto de ajuste de impulso, AC habilitado/ desativado, programação OTA. **GET /veicles/ {vin}/ota/ estatus** — versão firmware e histórico de atualização. Todas as respostas JSON com paginação, cronometragem ISO 8601 e cabeçalhos com limite de taxa (X- RateLimit- Remaining).

API GraphQL: consultas eficientes para painéis

Endpoint GraphQL: https://api.vethy.com/graphql. Uma única consulta pode obter o resumo AC em toda a frota, estado vivo por veículo, falhas recentes do BMS e OTA pendentes atualizações em uma ida e volta. Consulta de amostra: consulta FleetDashboard { frota(id: "abc") { vehicleCount, totalAcRuntimeHours, avgLithiumSoc, vehicles(filter: { faultCount_gt: 0 }) { vin, driverName, lithiumSoc, fallows { code, severity, from } } } . As assinaturas do GraphQL suportam atualizações em tempo real através do WebSocket — usadas pelo Schneider National para painéis de operações ao vivo.

Authentificação OAuth 2,0 e controle de acesso baseado em funções

A API Vethy usa fluxo de código de autorização OAuth 2,0 para o acesso ao contexto do usuário e fluxo de credenciais do cliente para servidor para servidor. Papéis: visualizador de frotas (leia telemetria), operador de frotas (lir + configuração escreve), administrador de frotas (léia + configuração + gestão OTA), auditor de segurança (apenas leia registros de auditoria). Os tokens expiram 1 hora com a rotação do token de atualização. Todas as chamadas da API registradas para conformidade de auditoria tipo II do SOC 2. Vethy publica a coleção OpenAPI 3,1 especificação e Postman.

Eventos do Webhook: em tempo real para alertas de falha e conclusão do OTA

Configurar URL webhook através do POST /fleet/ {fleet_id}/webhooks. Eventos: ac.fault. critique, ac.fault. warning, ac.fault, resoluted, ota. update. programed, ota. UPdate. installing, ota. UTdate. success, ota. TUPD. failed, lithium.soc. low, lithium. capacity. degraded. Carga útil assinada com HMAC-SHA256 usando segredo compartilhado. O Webhook tenta novamente com o backoff exponencial (5 tentativas ao longo de 24 horas). Usado pelo Mærsk para integração em tempo real no NOC central (centro de operações da rede).

Perguntas frequentes

O acesso à API está incluído com o VS02 PRO ou custo extra?

O acesso à API está incluído na subscrição Vethy Fleet+ (€8/truck/ mês). As compras VS02 PRO sem Fleet+ têm acesso limitado à API (telemetria de 30 dias, sem assinaturas do webhook). A integração Geotab/Samsara/ Webfleet via FMS gateway não tem custo adicional de API Vethy.

Que limites de taxa se aplicam à API?

Padrão: 100 solicitações/min por cliente OAuth, 10.000 solicitações/dia. Os assinantes da Fleet+ podem solicitar aumentos do limite de taxas até 1,000/min, 1.000,000/dia. As consultas do GráficoQL com complexidade > 1000 são agilizadas separadamente. A entrega do Webhook é ilimitada, mas está plafonada em 100 eventos/ segundo por URL do webhook.

O Vethy publica SDKs em Python, Node.js, Java ou .NET?

Sim — SDKs oficiais em github.com/vethy/vethy-sdk em Python (vethy-sdK-python), Node.js (vethy-sddk-js), Java (vethy-s dk-java) e .NET (Vethy.SDK). SDKs da comunidade disponíveis para Go, Ruby e Rust. Todos os SDKs lidam com a atualização do OAuth, a desativação do limite de taxa e a verificação da assinatura do webhook automaticamente.

Como é garantido o tempo de ativação da API?

Vethy API SLA: 99,95% tempo de ativação mensal para os assinantes da Fleet+, 99,9% para o standalone. Implementação multi-região em AWS eu- oeste-1 (Irlanda), us- leste-1 (Virginia), ap- sudeste-1 (Singapur). Página de status no status.vethy.com com tempo de ativação histórico e incidente pós- mortem.