Saltar al contenido principal
WrenchMode captura qué hacen realmente los técnicos con su tiempo: conducir, trabajar, pausar. La Supplier API lo expone de dos maneras: un resumen analítico por técnico para reportería, y el registro bruto de eventos para auditoría y reconstrucción por visita. Todos los ejemplos asumen:

Analítica por técnico

GET /v1/supplier/wrench_mode/events/analytics/{fromDate}/{toDate} devuelve una fila por técnico con su tiempo de conducción, tiempo de trabajo y total en la ventana.
Restricciones:
  • Ambas fechas son yyyy-MM-dd, y la ventana puede abarcar como máximo un mes. Divide rangos más largos en llamadas del tamaño de un mes.
  • Las fechas son días UTC a menos que envíes timezone (consulta Zonas horarias). OpenWrench verifica el tope de un mes sobre las fechas tal como las envías, antes de aplicar la zona.
  • El resumen cubre la instalación de proveedor de tu clave de API. Una clave cuyo contacto no esté adjunto a una instalación de proveedor obtiene 401.
El tiempo de conducción incluye los trayectos a la dirección de casa de un técnico, como el regreso a casa al final del día o la vuelta a un taller a mitad del día. El resumen sigue ignorando los eventos sin ubicación ni dirección de casa.

El registro bruto de eventos

GET /v1/supplier/wrench_mode/events devuelve los eventos subyacentes, limitados por inquilino a tu proveedor. Filtros: Aplica la paginación estándar (offset, limit máx. 25, sort_by, order) excepto bajo scheduleId. Una trampa de formato: un filtro CSV presente pero vacío (por ejemplo eventTypes=,) se rechaza como mal formado en lugar de ignorarse.
El vocabulario de eventos se divide en eventos de viaje (began_trip hasta trip_cancelled, más drive_note) y eventos de trabajo (started_work, ended_work y los eventos de temporizador location_* que marcan pausas y reanudaciones en sitio). Los eventos de viaje pueden apuntar a una dirección de casa en lugar de a una ubicación. Un viaje a casa es un evento de viaje (began_trip, trip_paused, trip_resumed, trip_cancelled, drive_note o arrived) que tiene homeAddressId definido y no tiene locationId, workOrderId ni serviceCallId. Los eventos de trabajo nunca llevan homeAddressId. Por eso, locationId puede ser null en los eventos de viaje.

Zonas horarias

Ambas rutas de WrenchMode aceptan un parámetro de consulta opcional timezone. Define la zona en la que se leen fromDate y toDate, para que un día coincida con el día local de tus técnicos en lugar de un día UTC.
  • Envía un nombre de zona IANA, como America/Chicago, America/New_York o UTC. Los nombres distinguen mayúsculas y minúsculas.
  • fromDate empieza al inicio de ese día en la zona. toDate incluye ese día completo en la zona.
  • OpenWrench usa los límites reales de día de la zona. Un día de cambio de horario de verano dura 23 o 25 horas.
  • Sin timezone, las fechas son días UTC.
  • Los desplazamientos fijos (-05:00, GMT-5, Z, Etc/GMT+5), las abreviaturas (CST) y los nombres desconocidos devuelven 400.
Por ejemplo, un técnico en Chicago termina su trabajo a las 11:30 p. m., hora del Centro, el 9 de octubre. Eso es 04:30 UTC del 10 de octubre. Sin timezone, el evento cae el 10 de octubre. Con timezone=America/Chicago, cae el 9 de octubre:

Cuándo elegir cada uno

  • Analítica para tableros, nómina y reportes de utilización: un número por técnico por período, con la matemática de pausas ya hecha.
  • Eventos brutos para auditar un total sospechoso, reconstruir una visita minuto a minuto o alimentar tu propio warehouse analítico.
  • Las preguntas por visita suelen atenderse mejor con la expansión de llamada de servicio GET /v1/supplier/work_order/service_calls/{id}/with_work_logs. Devuelve exactamente los eventos en la ventana de check-in/check-out de la visita más trueWorkTimeMillis sin pausas. Consulta Llamadas de servicio.

Patrones aplicados

Extracción semanal de nómina. Cada lunes, llama a analítica para la semana anterior, cruza por correo del técnico contra tu sistema de nómina y usa el tiempo de trabajo + conducción como la entrada de horas pagadas. El trayecto a casa cuenta en el total de tiempo de conducción, aunque no se factura a ninguna orden de trabajo. Una llamada por semana por instalación te mantiene muy por debajo del límite de tasa. Reporte mensual de utilización. Analítica con límites de mes (2026-08-01 a 2026-08-31 está dentro del tope de un mes); divide el tiempo de trabajo entre el tiempo programado desde tu sistema de rostering. Conciliación de costo de labor en una factura. Para cada llamada de servicio en la orden de trabajo facturada, obtén /with_work_logs, suma trueWorkTimeMillis y compara contra las líneas de labor antes de que el comprador vea una disputa.