Trabajar órdenes de trabajo con la Supplier API

export BASE="https://api.useopenwrench.com/api/external"
export KEY="<your-api-key>"        # X-API-KEY header
export SECRET="<shared-secret>"    # OW-KEY header

​

Leer tu cola

# 1. Una entrega de webhook te dice qué orden de trabajo cambió:
#    { "event_type": "workorder.create", "data": { "workOrderId": 9001, ... } }

# 2. Obtén esa orden de trabajo
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/work_order/work_orders/9001"

# Carga inicial o conciliación: filtra estrecho, pagina pequeño, recorre con offset
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/work_order/work_orders?status=PendingConfirmationByServiceProvider,ConfirmedByServiceProvider&limit=25&offset=0&sort_by=createdAt&order=asc"

# Conteo por filtro, sin traer filas
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/work_order/work_orders/count_by?status=ConfirmedByServiceProvider"

• 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.
• Los filtros de activo incluyen los subactivos. assetId= y assetIds= coinciden con órdenes de trabajo cuyo activo principal o cualquiera de sus subactivos es el id dado.
• 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 indexados se ignoran. updatedAtStartDate, updatedAtEndDate, buyerFacilityId y walkthroughId no están en el índice de búsqueda y ya no estrechan los resultados. Filtra en su lugar por una ventana de statusChangedAt u otras columnas indexadas.
• 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.

​

Aceptar o rechazar

curl -X POST "$BASE/v1/supplier/work_order/work_orders/status_update/confirm" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 9001,
    "note": {
      "text": "Accepted. Tech will be scheduled for tomorrow morning.",
      "noteAddedBy": "dispatch@supplier.com",
      "noteAddedAt": "2026-08-21T08:00:00.000-07:00"
    }
  }'

​

Mantener informado al comprador

curl -X PATCH "$BASE/v1/supplier/work_order/work_orders/9001/estimated_completion_date" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "estimatedCompletionDate": "2026-08-25T17:00:00.000-07:00" }'

curl -X PATCH "$BASE/v1/supplier/work_order/work_orders/9001/append_supplier_attachments" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "supplierAttachments": [ { "fileName": "before.jpg", "fileId": "a1b2c3d4e5" } ] }'

​

Notas

curl -X PATCH "$BASE/v1/supplier/work_order/work_orders/append_notes" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 9001,
    "note": {
      "text": "Replacement compressor is on site, starting the swap tomorrow.",
      "noteAddedBy": "dispatch@supplier.com"
    },
    "taggedUsers": ["ops@example.com"]
  }'

• 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.

curl -X PATCH "$BASE/v1/supplier/work_order/work_orders/append_notes/bulk" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 9001,
    "notes": [
      { "text": "", "photo": "https://cdn.example.com/wo-9001/before.jpg" },
      { "text": "", "photo": "https://cdn.example.com/wo-9001/after.jpg" }
    ]
  }'

​

Etiquetas

curl -X PUT "$BASE/v1/supplier/work_order/work_orders/9001/labels" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [4, 12] }'

• 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

curl -X POST "$BASE/v1/supplier/work_order/work_orders" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Damaged freezer door gasket, found during PM visit",
    "locationId": 1204,
    "description": "Gasket torn along bottom edge; recommend replacement."
  }'

​

Tipos de problema

​

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 ECD a medida que las cosas evolucionan.
4. Completa vía check-out, luego factura mediante cotizaciones y facturación.