API de gestión de flotas para VETHY VS02 PRO: REST + GraphQL para integración personalizada

• Contenido

1. API REST: Endpoints para telemetría, configuración, OTA, diagnóstico
2. API de GraphQL: consultas eficientes para tableros
3. Auth 2,0 autenticación y control de acceso basado en roles
4. Eventos de Webhook: empuje en tiempo real para alertas de fallo y finalización de OTA

Muchos grandes operadores de flotas con más de 500 camiones construyen plataformas de gestión de flotas propias en lugar de depender exclusivamente de Geotab, Samsara o Webfleet. Para estas flotas, Vethy proporciona acceso directo a la API REST y GraphQL a todos los diagnósticos Vethy VS02 PRO y V-FMSG-24 de telemetría, configuración, gestión OTA y BMS. Esta página documenta los endpoints de la API, el flujo de autenticación OAuth 2,0, las suscripciones a eventos webhook, los límites de tarifas y los patrones comunes de integración utilizados por los equipos de TI de la flota en Schneider National, J.B. Hunt, Mærsk, DSV, DB Schenker y Kuehne+Nagel.

API REST: Endpoints para telemetría, configuración, OTA, diagnóstico

La dirección de base: https://api.vethy.com/v2/. Endpoints primarios: **GET /fleet/{fleet_id}/vehículos** — enumerar todos los vehículos con VS02 PRO. **GET /vehículos/{vin}/telemetría?de=&to=&fields=** — telemetría histórica (duración, SoC, temperatura, energía). **GET /vehiculos/{vin}/telemetría/vivo** — estado actual. **GET/vehículos/ {vin}/diagnóstico** — códigos de fallo y salud del BMS. **POST /vehículos /{vin}/config** — punto de ajuste de empuje, AC habilitable/desactivable, calendario de OTA. **GET /veiches/{vin}/ota/status** — versión firmware y historia de actualización. Todas las respuestas JSON con paginación, ISO 8601 timestamps, y encabezados de velocidad-limite (X-RateLimit-Remaining).

API de GraphQL: consultas eficientes para tableros

Endpoint de GraphQL: https://api.vethy.com/graphql. Una consulta única puede obtener un resumen AC de toda la flota, estado vivo por vehículo, fallos BMS recientes, y OTA en espera de actualizaciones en una ida y vuelta. Consulta de ejemplo: consulta FleetDashboard { flota(id: "abc") { vehículoConocimiento, totalAcRuntimeHoras, avgLithiumSoc, vehículos(filtro: { failCount_gt: 0 }) { vin, driverName, lithiumSoc, fails { código, severity, since } } } . Las suscripciones a GraphQL soportan actualizaciones en tiempo real a través de WebSocket, usadas por Schneider National para los paneles de operaciones en vivo.

Auth 2,0 autenticación y control de acceso basado en roles

Vethy API utiliza el flujo de código de autorización OAuth 2,0 para el acceso al contexto de usuario y el flujo de credenciales de cliente para servidor a servidor. Papeles: visualizador de flotas (telemetría leída), operador de flotas (escribe leer + config), administrador de flotas (leer + config + gestión de OTA), auditor de seguridad (sólo leer registros de auditoría). Las fichas expiran 1 hora con la rotación de las fichas de actualización. Todas las llamadas de la API registradas para el cumplimiento de la auditoría SOC 2 tipo II. Vethy publica la colección OpenAPI 3,1 Spec y Postman.

Eventos de Webhook: empuje en tiempo real para alertas de fallo y finalización de OTA

Configurar URL webhook a través de POST /fleet/{fleet_id}/webhooks. Eventos: ac.fault.critical, ac.fault.warning, ac.fault,resolved, ota.update.programed, ota.up Date.installing, ota.updata.success, ota.up date.failed, lithium.soc.low, lithium.capacity.degraded. Carga útil firmada con HMAC-SHA256 usando secreto compartido. Webhook intenta volver con retroceso exponencial (5 intentos durante 24 horas). Utilizado por Mærsk para la integración en tiempo real en NOC central (centro de operaciones de red).

Preguntas frecuentes

¿Está incluido el acceso a la API con VS02 PRO o un costo adicional?

El acceso a la API está incluido en la suscripción Vethy Fleet+ (€8/camión/mes). Las compras VS02 PRO sin Fleet+ tienen acceso API limitado (últimos días de telemetría 30, sin suscripciones webhook). La integración de Geotab/Samsara/Webfleet a través de la puerta de entrada FMS no tiene costo adicional de la API Vethy.

¿Qué límites de tarifa se aplican a la API?

Predeterminado: solicitudes 100/min por cliente OAuth, solicitudes 10,000/día. Los suscriptores de Fleet+ pueden solicitar aumentos de la tarifa hasta 1,000/min, 1.000,000/día. Las consultas de GraphQL con complejidad > 1000 se aceleran por separado. La entrega de Webhook es ilimitada, pero se limita a eventos 100/segundo por URL de webhook.

¿Publica VETHY SDKs en Python, Node.js, Java o .NET?

Sí — SDK oficiales en github.com/vethy/vethy-sdk en Python (vethy-sdK-python), Node.js (vethy-sddk-js), Java (vethy-s dk-java) y .NET (Vethy.SDK). Los SDKs comunitarios disponibles para Go, Ruby y Rust. Todos los SDKs manejan automáticamente la actualización de OAuth, la verificación de la firma de la tasa-limite y la verificación de la firma webhook.

¿Cómo se garantiza el tiempo de uptime de la API?

Vethy API SLA: 99,95% tiempo de trabajo mensual para los suscriptores de Fleet+, 99,9% para los independientes. Despliegue de varias regiones a través de la AWS eu-oeste-1 (Irlanda), nosotros-este-1 (Virginia), en el sudeste-1 (Singapur). Página de estado en status.vethy.com con tiempo de activación histórico e incidente post-mortems.