Referencia API

Introducción#

El servidor de Trucks-MDT expone una API HTTP con JSON, más un WebSocket para eventos en vivo. La usan la tablet, el cliente de escritorio y el panel web. La versión actual de la API es 1.0.

Errores#

Toda respuesta de error usa el mismo formato, con el código HTTP correspondiente:

{
  "error": {
    "code": "BAD_CSRF",
    "message": "Token CSRF inválido o ausente",
    "details": null
  }
}

Autenticación#

Cada ruta acepta uno de estos mecanismos, indicado en la columna Auth de las tablas:

Sesión (cookie)#

Se inicia con POST /api/auth/login, que responde con el usuario y un csrf_token y guarda una cookie HttpOnly. Las peticiones que modifican datos (POST, PATCH, DELETE) deben enviar ese token en la cabecera X-CSRF-Token. Puedes recuperarlo con GET /api/auth/me.

POST /api/auth/login
Content-Type: application/json

{ "email": "conductor@ejemplo.com", "password": "********" }

→ 200
{ "user": { … }, "csrf_token": "…" }

Si la cuenta usa verificación en dos pasos, añade el campo totp con el código.

Token de instalación (Bearer)#

El cliente de escritorio se identifica con un token de instalación, que empieza por ets2_ y se envía como Authorization: Bearer ets2_…. Opcionalmente puede enviar X-Client-Version. El token se crea desde la sesión con POST /api/integration/installations y solo se muestra en claro esa vez; caduca a los 90 días por defecto y puede rotarse o revocarse.

Límites de uso#

El servidor limita las peticiones. Estos son los valores por defecto, ajustables en la configuración del servidor:

Algunas rutas tienen además su propio límite: por ejemplo, 10 instalaciones por hora, 30 invitaciones por hora, 30 envíos de mercado por minuto y 20 cambios de avatar por hora.

Estado del servidor#

Marca y licencia#

La marca (nombre, logotipo, textos y colores) y la licencia del modo empresa se leen y se cambian con estas rutas. Solo el dueño puede modificarlas.

Las rutas del modo empresa responden 402 LICENSE_REQUIRED mientras la licencia no esté ok. Cada pocas horas el servidor avisa a PHILIP Studio con su licencia, su versión y cuatro contadores (conductores, dueños, empresas y trabajos de 30 días); si la licencia fue revocada, el estado pasa a revocada. Mira Instalación.

Cuenta y sesión#

Steam#

Empresa#

Estas rutas dependen del rol del usuario dentro de la empresa; el servidor responde con error si no tiene permiso. :id es el id de la empresa.

Trabajos y despacho#

Conductor#

Mercado de fletes#

Filtros de GET /api/driver/market: q, origin, destination, cargo, group, body, adr, fragile, valuable, heavy, km_min, km_max, weight_min, weight_max, min_game_min, value_min, sort (value, expires, km, -km, weight, -weight, cargo) y limit.

Subir ofertas#

POST /api/driver/market
Authorization: Bearer ets2_…

{
  "game": "ets2",
  "profile": "Mi perfil",
  "save_name": "quicksave",
  "game_time": 123456,
  "saved_at": "2026-09-29T18:00:00Z",
  "offers": [
    {
      "src_company": "…", "src_city": "…",
      "dst_company": "…", "dst_city": "…",
      "cargo": "…", "km": 412.5,
      "expires_in_min": 300, "urgency": 1, "units": 1,
      "truck": "…", "trailer": "…"
    }
  ]
}

Solo src_company, src_city, dst_company, dst_city, cargo y km son obligatorios en cada oferta; el resto es opcional.

Billetera#

Mensajes y notificaciones#

Integración del cliente#

Telemetría#

El cliente de escritorio abre una sesión de telemetría por cada partida y le envía eventos. Todas estas rutas usan el token de instalación.

Abrir una sesión#

POST /api/telemetry/session
Authorization: Bearer ets2_…

{
  "api_version": "1.0",
  "client_version": "2.0.0",
  "game": { "name": "ets2", "version": "1.55" },
  "plugin": { "name": "…", "version": "…" },
  "environment": {
    "profile": "Mi perfil",
    "mods": [ { "name": "…", "package": "…" } ]
  }
}

game.name puede ser ets2 o ats. plugin y environment son opcionales.

Enviar eventos#

POST /api/telemetry/events
Authorization: Bearer ets2_…

{
  "session_id": 42,
  "seq": 1,
  "events": [
    { "t": "2026-09-29T18:00:05Z", "type": "sample", "data": { … } }
  ]
}

Latido y cierre#

POST /api/telemetry/heartbeat
{ "session_id": 42, "rtt_ms": 80, "state": { "game_connected": true, "telemetry_active": true } }

POST /api/telemetry/end
{ "session_id": 42 }