Actualizar una orden de servicio

PUThttps://carchost.fieldcontrol.com.br/orders/{id}

Actualiza los datos de una orden de servicio y las respuestas de los campos personalizados enviadas. Las actividades, los productos y los servicios tienen endpoints propios.

Requiere los headers X-Api-Key, User-Agent y Content-Type: application/json. Límite: 1 solicitud por segundo (más información).

Solicitud

Parámetros de ruta

idstringobligatorio

Identificador de la orden de servicio.

Ejemplo: NDJiMWQ0YzQtOWNmOC00NWE2LTg2MjItYjNjNzZjZjk0MmM4OjIyOTE1.

Headers

User-Agentstringobligatorio

Identificación de su aplicación.

Ejemplo: MinhaIntegracao/1.0.

Cuerpo de la solicitud

JSON, enviado con el header Content-Type: application/json.

identifierstring

Número de la orden, único en la cuenta. Si se omite, se genera según la configuración de la cuenta; en cuentas con numeración manual, es obligatorio. El carácter # en el medio está reservado.

Mínimo de 1 caracteres.Acepta: null.

descriptionstring

Descripción de la orden de servicio. Los textos de más de 2.000 caracteres se truncan.

customerobjectobligatorio

Cliente, por id o por name (búsqueda parcial, usa el primero encontrado).

Campos de customer

idstring

namestring

serviceobjectobligatorio

Tipo de orden de servicio, por id o por name (búsqueda parcial, usa el primero encontrado).

Campos de service

idstring

namestring

locationobject

Ubicación del cliente, por id o por name. Si se omite, la API usa la ubicación principal del cliente.

Campos de location

idstring

namestring

ticketobject

Solicitud de servicio atendida por esta orden. Se acepta y se archiva. Se ignora en la actualización.

Acepta: null.

Campos de ticket

idstringobligatorio

deadlineAtstring

Fecha de plazo (AAAA-MM-DD). Envíe null para quitar el plazo; si se omite en la actualización, se mantiene el valor actual.

Acepta: null.

deadlineContractobject

Contrato de plazos. Solo se aplica en la creación. No se puede enviar junto con serviceAgreement.

Campos de deadlineContract

idstringobligatorio

serviceAgreementobject

Acuerdo de servicio. Solo se aplica en la creación. No se puede enviar junto con deadlineContract.

Campos de serviceAgreement

idstringobligatorio

externalobject

Campos de external

idstring

Identificador de la orden de servicio en su sistema.

Hasta 100 caracteres.Acepta: null.

addressobjectobligatorio

Campos de address

zipCodestringobligatorio

Código postal (CEP) de 8 dígitos, solo números.

streetstringobligatorio

Calle. Los textos de más de 50 caracteres se truncan.

numberstringobligatorio

Número. Los textos de más de 10 caracteres se truncan.

neighborhoodstring

Barrio. Los textos de más de 50 caracteres se truncan.

complementstring

Complemento. Los textos de más de 50 caracteres se truncan.

Acepta: null.

citystringobligatorio

Ciudad. Los textos de más de 50 caracteres se truncan.

statestringobligatorio

Estado. Los textos de más de 30 caracteres se truncan.

coordsobjectobligatorio

Campos de coords

latitudenumberobligatorio

De -90 a 90.

longitudenumberobligatorio

De -180 a 180.

metadataobject

Metadatos internos. Solo se acepta con la clave shagrat.

customFieldslista de objetos

Respuestas de los campos personalizados del tipo de orden de servicio. Solo se modifican los campos enviados; value: null elimina la respuesta. En la actualización, cada campo se identifica por su id.

Las condiciones de visualización (condition) se evalúan con las respuestas guardadas junto con las enviadas. Responder un campo oculto devuelve 422 (hidden by condition), y un campo obligatorio con condición que queda visible sin respuesta devuelve 422 (required). Al cambiar la respuesta de un disparador, se eliminan las respuestas de los campos que quedan ocultos.

Campos de customFields

idstringobligatorio

Identificador del campo personalizado, del tipo de orden de servicio de la orden. Cada campo se puede enviar una vez.

valuestring o numberobligatorio

Respuesta, validada según el tipo del campo: question, texto de hasta 500 caracteres; number, número (o texto numérico); date, fecha AAAA-MM-DD; multiple-choice, una de las opciones registradas. Los campos checklist, attachment y multiple-photos no se pueden responder por la API. null deja el campo sin respuesta. En el formato antiguo, texto de 1 a 500 caracteres, sin validación por tipo.

Acepta: null.

taskslista de objetos

Actividades de la orden de servicio. Obligatorio en la creación, con al menos una; se ignora en la actualización.

Campos de tasks

statusstringobligatorio

Situación de la actividad.

Valores aceptados: pending, scheduled, in-progress, done, canceled, reported, on-route, paused.

employeeobject

Colaborador responsable.

Campos de employee

idstring

Identificador del colaborador.

namestring

Nombre del colaborador. Se aceptan textos, pero el vínculo se hace por el id.

taskTypeobject

Tipo de la actividad.

Campos de taskType

idstring

Identificador del tipo de actividad.

descriptionstring

Descripción de la actividad.

Acepta: null.

statusDescriptionstring

Observación sobre la situación. Hasta 6.000 caracteres.

Acepta: null.

durationinteger

Duración prevista, en minutos. Si se omite en la creación de la orden, la API usa la duración del tipo de orden de servicio.

Acepta: null.

positioninteger

Orden de la actividad dentro de la orden de servicio.

Predeterminado: 100.

archivedboolean

Archiva la actividad.

Predeterminado: false.

schedulingobjectobligatorio

Programación. type se calcula: con date y time pasa a scheduled-date-and-time, solo con date pasa a scheduled-date, y sin fecha pasa a non-scheduled.

Campos de scheduling

typestring

Se ignora; se calcula a partir de date y time.

Valores aceptados: scheduled-date, scheduled-date-and-time, non-scheduled.

datestring

Fecha (AAAA-MM-DD).

Acepta: null.

timestring

Horario (HH:MM:SS).

Acepta: null.

coordsobjectobligatorio

Coordenadas del lugar de la actividad.

Campos de coords

latitudenumberobligatorio

longitudenumberobligatorio

Respuestas

• 200

  Orden de servicio actualizada.

• 401

  Clave de API ausente (Missing API Key) o inválida (Invalid API Key). Consulte Autenticación.

• 403

  Cuenta bloqueada (Account blocked), vencida (Account expired) o con un plan que no permite integración (Account plan not allowed). Consulte Autenticación.

• 404

  Recurso no encontrado. El cuerpo de la respuesta está vacío.

• 422

  Cuerpo inválido (resourceValidationErr). Un identificador inválido o de otra cuenta en la URL también devuelve este error, con property: '@.id'.

• 429

  Se superó el límite de 1 solicitud por segundo. Consulte Límite de solicitudes.

• 500

  Error inesperado en el servidor.