Skip to main content

​
Llamadas de servicio: programación, check-in y finalización

Conduce el ciclo de vida de la visita con la Supplier API: programa y reprograma técnicos, haz check-in y check-out, establece estados de finalización y lee registros de trabajo.
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 service call existente. Actualizan una visita; no la crean. Enviarlos sin id devuelve 400 InvalidInputException con "required param: id". Inicia la visita con tech_scheduled (que crea el primer service call y devuelve la orden de trabajo con el nuevo call en associatedServiceCalls / lastServiceCall), y luego 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 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 y 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 las integraciones en vivo pueden omitirlo; los backfills deberían pasarlo explícitamente. 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.
Opciones comunes de checkOutStatus:
  • WaitingForReview: trabajo terminado, entregar al comprador para revisión.
  • TechScheduled o PartsRequested y similares: la visita terminó pero el trabajo continúa (visita de seguimiento, esperando partes).
Las partes y stock consumidos en la visita se registran 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.