Órdenes de trabajo en la Buyer 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

​

El objeto orden de trabajo

​

Crear una orden de trabajo

curl -X POST "$BASE/v1/buyer/work_order/work_orders" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Walk-in cooler not holding temperature",
    "description": "Temp reading 48F, product at risk.",
    "locationId": 1204,
    "assetId": 5511,
    "problemTypeId": 17,
    "woPriorityId": 3,
    "nte": 500,
    "buyerFacilityId": 88,
    "buyerCompanyId": 12,
    "createdBy": "ops@example.com",
    "supplierFacilityId": 3021
  }'

• Estado inicial. Si se omite status, el estado inicial se calcula a partir de la configuración de tu empresa. Las solicitudes de servicio típicamente empiezan en PendingApproval; las órdenes de trabajo por defecto en Unassigned. Si pasas un status, aún se resuelve contra la configuración de la empresa, así que el estado efectivo puede diferir del que enviaste.
• Despachar al crear. Pasar supplierFacilityId asigna el proveedor de inmediato. Un supplierFacilityId, assetId o problemTypeId desconocido se rechaza con 400.
• Subactivos. subAssetIds es un arreglo opcional de ids de subactivos que se adjuntan junto al assetId principal. Los subactivos son activos creados con un parentId; ver Activos.
• Flag de aprobación. El campo es needApproval, no needsApproval. El objeto de respuesta usa needsApproval; la solicitud de creación no.
• Enlace a recorrido. walkThroughId y siteSurveyTaskTitleId deben suministrarse juntos o no suministrarse. Ver Recorridos de encuesta de sitio.
• Upserts. Pasar un id actualiza esa orden de trabajo existente en lugar de crear una nueva.

​

Listar, filtrar y contar

# Órdenes de trabajo más recientes de una ubicación
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/work_order/work_orders?locationId=1204&limit=25&sort_by=createdAt&order=desc"

# Cuántas coinciden, sin traerlas
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/work_order/work_orders/count_by?locationId=1204"

• 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. Pon el valor entre comillas (search="walk-in cooler") 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 ventanas 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, así que una orden de trabajo creada hace milisegundos 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.

​

Reasignar un proveedor

curl -X PATCH "$BASE/v1/buyer/work_order/work_orders/9001" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "supplierFacilityId": 3055, "supplierPrimaryContactEmail": "dispatch@newsupplier.com" }'

• supplierPrimaryContactEmail solo aplica como parte de una reasignación. Enviarlo sin un cambio de instalación de proveedor hace que todo el patch sea un no-op: nada se persiste y se devuelve la orden de trabajo actual.
• Un id inexistente y una denegación de permiso devuelven la misma respuesta 400 unauthorized, así que no uses este endpoint para sondear si una orden de trabajo existe.

​

Acciones de estado del comprador

curl -X POST "$BASE/v1/buyer/work_order/work_orders/status_update/work_reviewed_and_completed" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 9001,
    "note": {
      "text": "Verified on site, closing out.",
      "noteAddedBy": "ops@example.com",
      "noteAddedAt": "2026-08-21T09:00:00.000-07:00"
    }
  }'

​

Bloqueo de cancelación mientras un técnico tiene check-in activo

{
  "message": "You can’t cancel this work order: technician tech@supplier.com is currently checked in."
}

​

El modelo de estados

​

Notas

curl -X PATCH "$BASE/v1/buyer/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": "Access code for the back door is 4417.",
      "noteAddedBy": "ops@example.com",
      "noteAddedAt": "2026-08-21T09:00:00.000-07:00"
    }
  }'

curl -X PATCH "$BASE/v1/buyer/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": "Access code for the back door is 4417.",
      "noteAddedBy": "ops@example.com",
      "noteAddedAt": "2026-08-21T09:00:00.000-07:00"
    },
    "taggedUsers": ["tech@supplier.com", "manager@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/buyer/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 -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/work_order/work_order_labels?no_pagination=true"

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

• Un ids ausente o que no sea un array, o un id que no sea un número entero, se rechaza con 400.
• Cada id debe ser una etiqueta viva de tu propio catálogo. Los ids desconocidos o de otro inquilino responden 400 con los ids problemáticos listados.
• La escritura requiere permiso de escritura de órdenes de trabajo. Un id de orden de trabajo desconocido, eliminado o ajeno responde el mismo 400 que una escritura denegada, no un 404.

​

Tipos de problema

curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/work_order/problem_types"

​

Juntándolo todo

1. Cachea me, tipos de problema y ubicaciones al arrancar.
2. Crea la orden de trabajo con supplierFacilityId establecido (o créala sin asignar, luego jerarquiza proveedores y haz PATCH de la asignación).
3. Sigue el progreso del proveedor mediante webhooks (workorder.status_update), obteniendo cada orden de trabajo por id cuando llegue un evento. Mantén GET /work_orders?statusChangedAt=... como una pasada de conciliación poco frecuente, no como la señal principal.
4. Cuando el proveedor alcance WaitingForReview, verifica el trabajo (ver Llamadas de servicio para la evidencia de la visita) y publica work_reviewed_and_completed, o work_unsatisfactory con una nota.
5. Concilia el lado monetario mediante Cotizaciones y propuestas y Facturas.