Saltar al contenido principal
Una llamada de servicio es una visita de un técnico contra una orden de trabajo. La Supplier API conduce todo el ciclo de vida de la visita a través de cinco endpoints de actualización de estado más expansiones de lectura. Es la parte más matizada de la API; los detalles a continuación vale la pena leerlos antes de escribir código. Todos los ejemplos asumen:

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:
La respuesta es la orden de trabajo asociada, no la llamada de servicio. Cada llamada crea o actualiza una llamada de servicio, mueve el estado de la orden de trabajo y devuelve la orden de trabajo actualizada en la envoltura. Lee el nuevo estado de la llamada de servicio desde associatedServiceCalls / lastServiceCall de la orden de trabajo.
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.
check_in, check_out y sus variantes remote_ requieren un id de llamada de servicio existente. Actualizan una visita; no la crean. Enviarlos sin id devuelve 400 InvalidInputException con "required param: id". Inicia la visita con tech_scheduled. Crea la primera llamada de servicio y devuelve la orden de trabajo con la nueva llamada en associatedServiceCalls / lastServiceCall. Reutiliza ese id en cada actualización posterior de la misma visita.La orden de trabajo también tiene que estar más allá de la aceptación antes de que tech_scheduled sea válido. Si todavía está en PendingConfirmationByServiceProvider (el estado del comprador “Open - Pending Contractor Confirmation”), acéptala primero con POST /v1/supplier/work_order/work_orders/status_update/confirm.

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.
Valores comunes de 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.
Para completar una orden de trabajo, haz check-out con 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 autoApproveWorkOrdersCompletedByThirdParty habilitado, un resultado WaitingForReview se promueve automáticamente a WorkReviewedAndCompleted.
  • 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 sobre GET /v1/supplier/work_order/service_calls/{id}:
Para reportes de tiempo a nivel de flota entre todos los técnicos, usa WrenchMode en lugar de iterar llamadas.

Trabajos multi-visita

Una orden de trabajo puede llevar muchas llamadas de servicio (diagnóstico, reparación, seguimiento). Crea cada visita con su propia llamada tech_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.