Cómo funcionan los endpoints de actualización de estado
Los cinco comparten una misma forma de solicitud (un payload de llamada de servicio) y un comportamiento crucial: Campos compartidos de la solicitud:workOrderId y numberOfTechs siempre son requeridos. id apunta a una llamada de servicio existente (omítelo en la primera creación y luego reutilízalo para cada actualización posterior de la misma visita). leadTechnicianEmail, additionalTechnicianEmails, serviceScheduledAt, los grupos checkIn*/checkOut*, partsWithQuantity, stockLocationIds y equipmentPerStockLocationIds se van completando a medida que avanza la visita.
supplierFacilityId es requerido para claves de equipo interno de servicio; para claves de proveedor tercero se sobrescribe con el id de tu propia instalación sin importar lo que envíes.
Todas las rutas están bajo
/v1/supplier/work_order/. No hay equivalentes del lado del comprador: el check-in y el check-out no pueden dirigirse desde la Buyer API.
1. Programar la visita
serviceScheduledAt debe ser una fecha-hora ISO 8601 con separador T y un offset explícito (por ejemplo, 2026-08-22T09:00:00.000-07:00, o ...Z para UTC). Un valor separado por espacio como 2026-08-22 09:00:00+00:00 se rechaza como entrada inválida. Consulta Formatos de fecha.
leadTechnicianEmail es el correo del técnico principal en la visita y está tipado como una cadena simple en el esquema. Si una solicitud tech_scheduled falla con una excepción no controlada genérica, primero confirma que la orden de trabajo esté más allá de la aceptación. Luego confirma que serviceScheduledAt tenga el formato ISO 8601 anterior. Ambas son causas comunes de un fallo poco descriptivo de tech_scheduled.
Para mover la cita más tarde, llama a tech_rescheduled con el id de la llamada de servicio y el nuevo serviceScheduledAt.
2. Check-in
checkInTime toma por defecto la hora actual del servidor cuando estableces un checkInStatus sin hora, así que puedes omitirlo en las integraciones en vivo. Pásalo explícitamente al cargar datos históricos. checkInImages toma referencias de foto, y las coordenadas geográficas dan al comprador la prueba en sitio.
3. Check-out y establecer el resultado
El check-out es donde se decide el próximo estado de la orden de trabajo.checkOutStatus es requerido y debe ser un nombre de estado de orden de trabajo válido; se convierte en el nuevo estado de la orden de trabajo.
checkOutStatus:
Un comprador puede desactivar
allowToPlaceWorkOrdersOnHold para su equipo de servicio interno. Las claves de ese equipo no pueden entonces hacer check-out con un checkOutStatus En espera, como PartsRequested o PartsOnOrder, a menos que la orden de trabajo ya esté en espera. La llamada devuelve 403 ForbiddenException con "Placing work orders on hold is not enabled for this internal team", y la llamada de servicio no se guarda. Las claves de proveedores externos nunca están restringidas. Consulta cuando los equipos internos no pueden poner órdenes de trabajo en espera.WaitingForReview. WorkReviewedAndCompleted es un estado que pertenece al comprador. El comprador lo establece después de revisar tu trabajo, u OpenWrench lo establece automáticamente cuando aplica la auto-aprobación (ver abajo). El comprador también puede rechazar el trabajo con WorkUnsatisfactory. Te enteras de la decisión del comprador mediante el webhook workorder.status_update.
Registra las partes y el stock consumidos en la visita mediante partsWithQuantity, stockLocationIds y equipmentPerStockLocationIds en el mismo payload. Los ids vienen de tu catálogo de inventario.
En este punto se disparan dos comportamientos de automatización:
- Auto-aprobación. Para proveedores terceros cuya empresa compradora tenga
autoApproveWorkOrdersCompletedByThirdPartyhabilitado, un resultadoWaitingForReviewse promueve automáticamente aWorkReviewedAndCompleted. - Auto-publicación de facturas. Cuando el estado resultante sea
WorkReviewedAndCompleted, las reglas de auto-publicación de facturas pueden ejecutarse y publicar tu factura en borrador. Consulta Cotizaciones y facturación.
remote_check_in y remote_check_out se comportan de forma idéntica para trabajo hecho fuera del sitio.
Volver a leer una llamada de servicio
Tres expansiones sobreGET /v1/supplier/work_order/service_calls/{id}:
Trabajos multi-visita
Una orden de trabajo puede llevar muchas llamadas de servicio (diagnóstico, reparación, seguimiento). Crea cada visita con su propia llamadatech_scheduled (sin id), y mantén las actualizaciones posteriores de cada visita atadas al id de su llamada de servicio. Haz check-out de las visitas intermedias con un estado que continúa como PartsRequested o TechScheduled, y solo de la visita final con WaitingForReview.