Saltar al contenido principal
La Supplier API de OpenWrench da a los proveedores de servicio acceso programático a su lado de la plataforma: recibir y actualizar órdenes de trabajo, programar y documentar llamadas de servicio, enviar cotizaciones y facturas, extraer datos de tiempo del técnico desde WrenchMode y gestionar compras e inventario.

URL base

Todos los endpoints del proveedor están bajo /v1/supplier/.

Autenticación

Cada solicitud debe llevar dos cabeceras: X-API-KEY (tu clave de API, emitida por contacto de proveedor) y OW-KEY (el secreto compartido de OpenWrench emitido junto a ella). La clave delimita automáticamente cada solicitud a tu instalación: solo verás órdenes de trabajo, facturas y datos que te pertenezcan. Las solicitudes a las que les falte cualquiera de las cabeceras devuelven 401.
Para obtener una clave de API y un secreto compartido, contacta a support@useopenwrench.com. Las claves no expiran por sí solas. Para rotar una, solicita a soporte un nuevo par clave/secreto compartido, despliega el nuevo par y luego pide a soporte que revoque el antiguo.

Límites de tasa

10 solicitudes por ventana de 20 segundos por clave. Al superarlo recibirás 429 Too Many Requests: espera al menos 20 segundos antes de reintentar y espacia los trabajos en segundo plano (como exportaciones paginadas completas) para que se mantengan por debajo del límite.

Mantener las órdenes de trabajo sincronizadas

La mayoría de las integraciones de proveedor existen para replicar la cola de órdenes de trabajo de OpenWrench en otro sistema. Construye eso sobre push, no sobre sondeo:
  1. Registra un endpoint de webhook. OpenWrench envía los eventos workorder.create, workorder.status_update y workorder.new_note a medida que ocurren.
  2. En cada evento, obtén esa única orden de trabajo con GET /v1/supplier/work_order/work_orders/{id}.
  3. Usa GET /v1/supplier/work_order/work_orders solo para la carga inicial única y para la conciliación ocasional, con un filtro estrecho y una página pequeña.
No sondees el endpoint de listado según un cronograma para descubrir trabajo nuevo o cambiado. Es la lectura más costosa de la API, es lenta en colas grandes y compite con tu trabajo real por el límite de tasa. Consulta Órdenes de trabajo para los detalles.

Envoltura de respuesta

Respuestas de una sola entidad:
Las respuestas de listado añaden un count total:
Errores:
401 significa clave faltante o inválida; 400 cubre entrada inválida, filtros incorrectos y denegaciones de permisos; 429 es el límite de tasa.

Paginación y filtrado

Los endpoints de listado aceptan offset, limit (por defecto 10, máx. 25), sort_by y order (asc | desc). Los parámetros de consulta adicionales se tratan como filtros. Cada endpoint admite su propio conjunto de claves de filtro, y las claves que no reconoce se ignoran en lugar de rechazarse. Los filtros de varios valores usan una clave en plural con valores separados por comas (statuses=TechScheduled,TechRescheduled). Para órdenes de trabajo, consulta la referencia de filtros.

Formatos de fecha

La mayoría de las marcas de tiempo son cadenas ISO 8601 con offset (por ejemplo 2026-08-14T13:05:22.000-07:00); algunos campos de marca de tiempo de base de datos se serializan como yyyy-MM-dd HH:mm:ss.S. Las fechas simples son yyyy-MM-dd. Cuando envíes fecha-hora, usa ISO 8601 con una T entre la fecha y la hora y un offset explícito. Un valor separado por espacio como 2026-09-10 10:43:00+00:00 no es ISO 8601 y se rechaza; envía 2026-09-10T10:43:00.000+00:00 en su lugar. UTC puede escribirse como +00:00 o Z. Los filtros de fecha de los listados de facturas, propuestas y órdenes de trabajo son la excepción. Usan MM/dd/yyyy HH:mm:ss, una hora local de reloj sin offset, por ejemplo 10/09/2026 00:00:00:
  • Zona horaria. Pasa el parámetro de consulta opcional timezone para establecer la zona en la que OpenWrench interpreta los valores. Usa un nombre de zona IANA, como America/Chicago, America/New_York o UTC. Los nombres distinguen mayúsculas y minúsculas. Sin timezone, OpenWrench interpreta los valores en UTC.
  • Zonas rechazadas. Los offsets fijos (-05:00, GMT-5, Z, Etc/GMT+5), las abreviaturas (CST) y los nombres desconocidos devuelven 400.
  • Sin offset en el valor. OpenWrench ignora un offset como -05:00 al final de un valor de filtro. Usa timezone en su lugar.
  • Los valores mal formados devuelven 400. Un valor que no coincide con el formato devuelve 400, por ejemplo Invalid markedPaidAtStartDate. Expected format MM/dd/yyyy HH:mm:ss. Eso incluye valores ISO 8601 (2026-10-09T00:00:00), fechas sin hora (10/09/2026) y valores formados solo por espacios. OpenWrench sigue leyendo un valor vacío como 1 de enero de 1970.
  • Extremos finales. Las fechas finales de facturas y propuestas cubren todo el día final: OpenWrench reemplaza la hora por 23:59:59 en esa fecha en timezone. Las fechas finales de órdenes de trabajo son exactas, así que envía 23:59:59 para incluir el día completo.
  • Horario de verano. Una hora dentro de la hora omitida en un cambio de adelanto de reloj se desplaza hacia delante la duración del salto. Una hora dentro de la hora repetida en un cambio de atraso de reloj se refiere a la ocurrencia en horario estándar, que es la segunda.
Por ejemplo, esta solicitud devuelve las facturas marcadas como pagadas el 9 de octubre de 2026, en hora central:
Para los filtros de cada listado, consulta las reglas de valores de filtro de órdenes de trabajo y de propuestas y facturas.

Datos de tiempo del técnico

Los endpoints de WrenchMode exponen el tiempo de trabajo y conducción por técnico: GET /v1/supplier/wrench_mode/events/analytics/{fromDate}/{toDate} devuelve un resumen por técnico de conducción/trabajo/total (ventana limitada a 1 mes), y GET /v1/supplier/wrench_mode/events devuelve el registro bruto de eventos que lo respalda. Las expansiones de llamada de servicio (/with_work_logs, /with_tech_details) dan la historia por visita.

Guías detalladas

Las guías de esta pestaña recorren cada parte de la API en profundidad, con payloads, modelos de estado y patrones de integración:

Órdenes de trabajo

Recibir, aceptar o rechazar, estados de partes, ECD, adjuntos y notas.

Webhooks

Trabajo nuevo, cambios de estado y notas del comprador enviados a tu endpoint.

Llamadas de servicio

Programar, hacer check-in, check-out y establecer el estado de finalización.

WrenchMode

Analítica por técnico y el registro bruto de eventos de conducción/trabajo.

Cotizaciones y facturación

Enviar propuestas, borradores de facturas y publicar con un PDF.

Compras e inventario

Desde solicitudes de compra hasta órdenes y recibos, catálogos y stock.

Datos de referencia

Empresas compradoras, ubicaciones, activos y cómo funciona el enmascaramiento de datos.

Archivos y usuarios

El almacén de archivos detrás de los adjuntos y el aprovisionamiento de técnicos.