Crear una orden de servicio

POSThttps://carchost.fieldcontrol.com.br/orders

Crea una orden de servicio con al menos una actividad. El cliente, el tipo de orden de servicio y la ubicación se pueden informar por el identificador o por el nombre. Al informar ticket, la solicitud se acepta y se archiva.

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

Solicitud

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. Los campos del tipo de orden de servicio (con el id de cada uno) están en Listar los campos personalizados de un tipo de orden de servicio. Los campos no enviados quedan sin respuesta. También se acepta el formato antiguo, sin id y con name, type y position: la respuesta se guarda tal como se envía, sin verificar los campos del tipo de orden de servicio.

Los campos con condition solo se muestran cuando el disparador tiene la respuesta esperada. Responder un campo oculto devuelve 422 (hidden by condition), pero enviarlo con value: null se acepta. Un campo obligatorio con condición solo se exige cuando está visible; sin respuesta, devuelve 422 (required).

Campos de customFields

idstring

Identificador del campo personalizado, del tipo de orden de servicio de la orden. Cada campo se puede enviar una vez. Con id, name, type y position se ignoran.

namestring

Formato antiguo, sin id. Título del campo, de hasta 150 caracteres.

typeinteger

Formato antiguo. Tipo del campo: 0 (question), 1 (multiple-choice), 2 (date), 3 (number), 4 (checklist), 5 (attachment) o 6 (multiple-photos). El valor predeterminado es 0.

positioninteger

Formato antiguo. Posición del campo. El valor predeterminado es la posición en el array, a partir de 1.

Acepta: null.

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 objetosobligatorio

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

• 201

  Orden de servicio creada, con las actividades creadas en tasks.

• 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.

• 422

  Cuerpo inválido (resourceValidationErr): campo obligatorio ausente, tasks vacío, cliente, tipo de orden de servicio, ubicación, solicitud, contrato de plazos o acuerdo de servicio no encontrados (reason: not found), número duplicado (reason: duplicated), número obligatorio en cuentas con numeración manual, # en el medio del número, deadlineContract y serviceAgreement enviados juntos, o respuesta de campo personalizado inválida (@.customFields[n].id de otro tipo de orden de servicio o repetido, @.customFields[n].value fuera de las reglas del tipo del campo).

• 429

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

• 500

  Error inesperado en el servidor.