Saltar al contenido principal
Para una integración de proveedor, la cola de órdenes de trabajo es el inbox. Esta guía cubre los endpoints bajo /v1/supplier/work_order/ para recibir trabajos, responder a ellos y mantener informados a los compradores mientras avanza el trabajo. Programar visitas y completar el trabajo se hace a través de las llamadas de servicio. Todos los ejemplos asumen:

Leer tu cola

No construyas tu integración sobre el endpoint de listado. GET /v1/supplier/work_order/work_orders es la lectura más costosa de la Supplier API, y sondearlo para descubrir órdenes de trabajo nuevas o cambiadas es el patrón equivocado. Es lento en colas grandes, quema tu límite de tasa y aun así pierde los cambios entre sondeos. Usa webhooks para enterarte de que una orden de trabajo te fue asignada, cambió de estado o recibió una nota. Luego obtén esa única orden de trabajo por id. Reserva el listado para una carga inicial única y una conciliación ocasional, con un filtro estrecho y una página pequeña.
El patrón que escala es push, y luego obtener por id:
Los endpoints de listado y conteo son para los dos momentos que un webhook no puede cubrir. Úsalos para la primera carga del trabajo que ya existía antes de registrar tu endpoint. Úsalos también para una comprobación periódica de que nada se perdió:
Aplica la paginación estándar (offset, limit por defecto 10, máx. 25, sort_by, order). Cualquier otro parámetro de consulta se lee como un filtro de la referencia de filtros que aparece más abajo. Los filtros se combinan con AND, y todo está limitado por inquilino a tu instalación. El listado y el conteo resuelven qué órdenes de trabajo coinciden en el índice de búsqueda de OpenWrench y luego cargan los registros completos desde la base de datos. El endpoint de conteo ejecuta la misma consulta que el listado, así que los dos siempre concuerdan. Comportamiento a conocer:
  • Búsqueda de texto completo. search= coincide con palabras (con coincidencia por prefijo y por raíz) en el título, la descripción, el nombre de la ubicación, las notas, las notas de check-in y check-out de las llamadas de servicio, y el nombre del tipo de problema. También coincide con números de referencia como el número de orden de trabajo, el número de PO y el número de serie del activo. Envuelve el valor en comillas dobles para exigir la frase exacta.
  • Ordenamiento. sort_by admite createdAt, locationName, woPriority (por el tiempo de resolución esperado de la prioridad) y lastServiceCallServiceScheduledAt. Cualquier otro valor, o la ausencia de sort_by, ordena por createdAt descendente.
  • Los filtros no reconocidos se ignoran. Solo se admiten las claves de la referencia de filtros que aparece más abajo. Cualquier otro parámetro de consulta se ignora en lugar de rechazarse, y la solicitud igualmente tiene éxito. Esto incluye las claves mal escritas y updatedAtStartDate, updatedAtEndDate, statusChangedAt, assignedAt, buyerFacilityId y walkthroughId, que no están en el índice de búsqueda. Antes de depender de un filtro nuevo, compara count_by con y sin él.
  • Frescura. Las actualizaciones del índice de búsqueda y de la réplica van un momento por detrás de las escrituras. Tu propio cambio recién escrito, o una orden de trabajo asignada hace segundos, puede estar brevemente ausente de los resultados de listado y de los conteos.
  • Profundidad de paginación. offset + limit no puede exceder la ventana de resultados de búsqueda de 10.000. Estrecha el filtro en lugar de paginar tan profundo.
  • Enmascaramiento de datos. Si eres un proveedor tercero (no el equipo interno del comprador), los campos privados del comprador se ponen en blanco en órdenes de trabajo, ubicaciones y facturas antes de devolver la respuesta. Los campos faltantes son usualmente enmascaramiento, no bugs. Consulta Datos de referencia para más detalles.

Referencia de filtros

Las claves distinguen entre mayúsculas y minúsculas. Una clave en singular (status) toma un valor; la clave en plural (statuses) toma una lista separada por comas y coincide con cualquiera de los valores; notStatuses excluye todos los estados listados. Los filtros de fecha se explican en las reglas de valores de filtro. Estado Qué y dónde Quién Fechas y plazos

Reglas de valores de filtro

  • Usa la clave en plural para varios valores. statuses=TechScheduled,TechRescheduled coincide con cualquiera de los dos estados. status=TechScheduled,TechRescheduled busca un único estado con ese nombre literal y no devuelve nada.
  • Un valor por clave. Si repites un parámetro (statuses=TechScheduled&statuses=TechRescheduled), solo se usa el primero. Separa los valores con comas en su lugar.
  • Las fechas usan MM/dd/yyyy HH:mm:ss, por ejemplo 08/01/2026 00:00:00. El valor es una hora local de reloj, interpretada en la zona que pases en timezone, o en UTC si no lo pasas. La hora es obligatoria, y ambos extremos de una ventana son inclusivos. Los extremos finales son exactos: OpenWrench no los redondea al final del día, así que envía 23:59:59 para incluir un día completo. Codifica el valor para URL (curl -G --data-urlencode lo hace por ti). No añadas un offset como -05:00 al valor: OpenWrench lo ignora.
  • Una fecha que no se puede interpretar devuelve 400 con Invalid <key>. 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.
  • timezone acepta un nombre de zona IANA, como America/Chicago o UTC. Los offsets fijos (-05:00, GMT-5), las abreviaturas (CST) y los nombres desconocidos devuelven 400. Consulta Formatos de fecha para el horario de verano.
  • Los booleanos son true o false. unscheduledOrPastSchedule solo actúa con true.
  • Los valores deben estar bien formados. Un id no numérico, o un booleano distinto de true o false, puede hacer fallar la solicitud con un 500 en lugar de un 400.
  • El alcance por inquilino no se puede anular. La visibilidad de instalación aplicada a partir de tu clave de API siempre se mantiene, sean cuales sean los filtros que pases.
Para obtener un único día local, envía 00:00:00 y 23:59:59 en la misma fecha junto con tu zona. Esta solicitud devuelve las órdenes de trabajo completadas el 9 de octubre de 2026, en hora central:

Aceptar o rechazar

Acepta con POST /v1/supplier/work_order/work_orders/status_update/confirm, que establece el estado a ConfirmedByServiceProvider. Una orden de trabajo ya en un display status completado o cerrado no puede aceptarse (400).
Rechaza con POST .../status_update/decline. Solo los contactos de la instalación de proveedor asignada a la orden de trabajo pueden rechazar. La orden de trabajo abandona tu cola a través del flujo de cambio de proveedor: su estado vuelve a PendingApproval, o se elige automáticamente un proveedor de red privada, según la configuración del comprador. El text de la nota se registra como motivo del rechazo y se refleja en lo que el comprador ve, así que hazlo específico. Ambas llamadas toman { "id": ..., "note": { ... } } y devuelven la orden de trabajo actualizada. id es el id numérico de la orden de trabajo (un int64 que debe existir), no la cadena de visualización woNumber. Envíalo como un número JSON, no como una cadena entre comillas. Para verificar el valor antes de enviarlo, obtenlo con GET /v1/supplier/work_order/work_orders/{id}. No existe un endpoint status_update de orden de trabajo para completar un trabajo. Completas el trabajo mediante el check-out de la llamada de servicio.

Mantener informado al comprador

Tres señales ligeras mientras el trabajo está en marcha: Seguimiento de partes. Tres endpoints de estado, con la misma forma de cuerpo { id, note } que arriba:

Cuando los equipos internos no pueden poner órdenes de trabajo en espera

Un comprador puede impedir que su equipo de servicio interno ponga órdenes de trabajo en espera. La configuración por equipo es allowToPlaceWorkOrdersOnHold. Está activada de forma predeterminada, y el comprador puede desactivarla para un equipo interno. Cuando la configuración está desactivada, las claves de la Supplier API que pertenecen a ese equipo interno no pueden mover una orden de trabajo a un estado En espera. Los estados En espera son WaitingForProposal, WaitingForProposalApproval, PartsRequested, PartsOnOrder y DelayedByThirdParty. El bloqueo se aplica a:
  • POST .../status_update/parts_requested y POST .../status_update/parts_ordered.
  • El check-out de la llamada de servicio y el check-out remoto con un checkOutStatus En espera.
Una llamada bloqueada devuelve 403 y no cambia nada:
Lo que sigue permitido:
  • Movimientos dentro de En espera o para salir de él. Una orden de trabajo que ya está en espera puede pasar a otro estado En espera, como de PartsRequested a PartsOnOrder. También puede salir de En espera, por ejemplo con parts_received.
  • Proveedores externos. Las claves de proveedores externos nunca están restringidas. Los equipos internos sin la configuración tampoco están restringidos.
  • Otros flujos. La creación de órdenes de trabajo, los estados de subcontratación y los flujos automáticos, como las solicitudes de propuesta y las cotizaciones, no se ven afectados.
Fecha estimada de finalización. PATCH /v1/supplier/work_order/work_orders/{id}/estimated_completion_date lee solo estimatedCompletionDate (ISO 8601) del cuerpo:
Adjuntos. PATCH /v1/supplier/work_order/work_orders/{id}/append_supplier_attachments añade referencias de archivo a supplierAttachments, preservando lo que ya está ahí. Sube el archivo primero (ver Archivos y usuarios) y luego:

Notas

Añade al hilo compartido comprador-proveedor con PATCH /v1/supplier/work_order/work_orders/append_notes ({ "id": ..., "note": { "text", "noteAddedBy", "noteAddedAt" } }), y lee el hilo de una orden de trabajo con GET /v1/supplier/work_order/work_order_notes/{woId}. La lectura actualiza los acuses de recibo para tu contacto, y una lectura denegada devuelve una lista vacía en lugar de un error. Para @mencionar a personas en la nota, añade taggedUsers junto a note: una lista de correos electrónicos de contactos. OpenWrench incorpora cada correo en note.elements como un elemento user, la misma forma que las apps escriben para una @mención, así que no necesitas construir la estructura elements tú mismo. Los contactos etiquetados se añaden a la lista de suscriptores de la orden de trabajo si aún no están suscritos.
Reglas de taggedUsers:
  • Los correos se recortan y se pasan a minúsculas antes de compararse. Una nota puede mencionar como máximo a 25 usuarios.
  • Los correos duplicados en la lista, y los usuarios ya etiquetados en note.elements, se omiten en lugar de mencionarse dos veces.
  • Una entrada que no sea un correo electrónico válido, o una lista de más de 25 correos, se rechaza con un 400 de tipo invalidInputDataException. No se persiste nada.
  • Una lista vacía se ignora. Enviar taggedUsers sin un objeto note se rechaza con 400.
Para publicar un lote de fotos (el conjunto de antes/después de un técnico, por ejemplo), usa PATCH /v1/supplier/work_order/work_orders/append_notes/bulk con { "id": ..., "notes": [ ... ] }. Cada nota debe llevar una URL en photo y ningún otro contenido: text debe estar vacío y video, audio, otherFile y elements deben estar ausentes. Una solicitud acepta de 1 a 25 notas, las URL de foto duplicadas se rechazan con 400, y el lote conserva su orden bajo un único noteAddedAt fijado por el servidor. Los suscriptores reciben una única notificación agrupada en lugar de una notificación por foto.

Etiquetas

Las etiquetas de órdenes de trabajo son marcadores ligeros (un nombre más un color opcional) usados para segmentar la cola. A través de la API puedes leer el catálogo de etiquetas y reemplazar las etiquetas aplicadas a una orden de trabajo. La creación y edición de las etiquetas en sí permanece en la app de OpenWrench. Qué catálogo ves depende de tu clave: una clave que pertenece al equipo de servicio interno de un comprador ve el catálogo de esa empresa compradora, y la clave de un proveedor tercero ve el catálogo de su propia instalación. Explora el catálogo con GET /v1/supplier/work_order/work_order_labels, u obtén una con GET /v1/supplier/work_order/work_order_labels/{id}. El listado está paginado a 10 por página por defecto y acepta filtros search y label sobre el texto de la etiqueta. Pasa no_pagination=true para traer el catálogo completo en una sola llamada. Reemplaza las etiquetas de una orden de trabajo con PUT /v1/supplier/work_order/work_orders/{woId}/labels. El cuerpo es { "ids": [...] } y es un reemplazo completo: las etiquetas no listadas se eliminan, y un array vacío las borra todas. La respuesta lista los mapeos de etiquetas ahora activos en la orden de trabajo.
Comportamiento a conocer:
  • Cada id debe ser una etiqueta viva de tu propio catálogo; un ids ausente o que no sea un array, un id no entero, y los ids desconocidos o de otro inquilino se rechazan todos con 400.
  • La escritura requiere permiso de escritura de órdenes de trabajo: una clave que solo puede ver la orden de trabajo (un postor, o una instalación con visibilidad de solo lectura) recibe 400. En una orden de trabajo sin asignar, solo una instalación con visibilidad de lectura-escritura puede etiquetarla.
  • Un id de orden de trabajo desconocido, eliminado o ajeno responde el mismo 400 que una escritura denegada, no un 404.

Crear una orden de trabajo iniciada por el proveedor

Los proveedores pueden abrir órdenes de trabajo ellos mismos (un técnico ve una puerta rota mientras está en sitio por otra cosa). POST /v1/supplier/work_order/work_orders requiere title y locationId; la ubicación determina la instalación y empresa compradora.
Valores por defecto cuando se omiten: problemTypeId cae al primer tipo de problema hoja de la empresa compradora de la ubicación, y woPriorityId a una prioridad por defecto para esa empresa. Un assetId, si se da, debe existir, y su área se hereda cuando no se establece areaId. El campo es needApproval (sin “s”) en este cuerpo de creación. Un id en el cuerpo se ignora: esta llamada siempre crea una orden de trabajo nueva. El servidor fija el estado inicial. Para una clave de proveedor tercero, cualquier status o isSupplierInitiated en el cuerpo se ignora. El servidor crea la orden de trabajo como SupplierInitiatedPendingApproval con isSupplierInitiated: true. La configuración de aprobaciones del comprador decide después dónde queda. Cuando el comprador aprueba automáticamente las órdenes de trabajo iniciadas por el proveedor, OpenWrench la confirma de inmediato a tu instalación como ConfirmedByServiceProvider. De lo contrario, permanece en SupplierInitiatedPendingApproval hasta que un comprador la apruebe. Dos tipos de claves pueden fijar status: las claves que pertenecen al equipo de servicio interno de un comprador y los proveedores de pago que crean una orden de trabajo en una ubicación de un cliente que gestionan. Si estas claves omiten status, OpenWrench deriva el estado inicial de la configuración de la empresa compradora. Un equipo interno queda en AssignedToInternalTech. Traspasos del equipo interno. Una clave del equipo de servicio interno puede crear una orden de trabajo para otra instalación de proveedor enviando el supplierFacilityId de esa instalación. Esto solo funciona si la configuración de tu instalación permite transferir trabajo. OpenWrench trata la creación como un traspaso, igual que una transferencia. Si la solicitud no envía status, o envía SupplierInitiatedPendingApproval (como hace siempre la app móvil de contratistas), OpenWrench fija PendingConfirmationByServiceProvider. La orden de trabajo va al proveedor de destino para que la confirme, en lugar de a la cola de aprobación de trabajos iniciados por el proveedor del comprador. Una instalación de destino privada sigue correspondiendo a AssignedToInternalTech. OpenWrench conserva el status tal como se envió en estos casos:
  • La solicitud envía cualquier otro status explícito.
  • El supplierFacilityId es tu propia instalación.
  • La configuración de tu instalación no permite transferir trabajo.

Tipos de problema

GET /v1/supplier/work_order/problem_types lista los tipos de problema entre tus empresas compradoras relacionadas (sin límite de tasa). Úsalo para clasificar correctamente las órdenes de trabajo iniciadas por el proveedor por comprador.

Ciclo de integración típico

  1. Registra un endpoint de webhook para workorder.create y workorder.status_update. En cada entrega, obtén la orden de trabajo por id. Haz la carga inicial única desde el endpoint de listado y mantenlo fuera del ciclo en régimen estable, salvo como un sondeo de red de seguridad poco frecuente y con filtros estrechos.
  2. confirm o decline dentro de tu SLA.
  3. Programa la visita vía llamadas de servicio; publica estados de partes y una fecha estimada de finalización a medida que las cosas evolucionan.
  4. Completa vía check-out, luego factura mediante cotizaciones y facturación.