Update a work order

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

Updates the data of a work order and the custom field answers sent. Tasks, products and services have their own endpoints.

Requires the X-Api-Key, User-Agent and Content-Type: application/json headers. Limit: 1 request per second (learn more).

Request

Path parameters

idstringrequired

Work order identifier.

Example: NDJiMWQ0YzQtOWNmOC00NWE2LTg2MjItYjNjNzZjZjk0MmM4OjIyOTE1.

Headers

User-Agentstringrequired

Identification of your application.

Example: MinhaIntegracao/1.0.

Request body

JSON, sent with the Content-Type: application/json header.

identifierstring

Order number, unique in the account. If omitted, it is generated according to the account settings; in accounts with manual numbering, it is required. The # character in the middle is reserved.

At least 1 characters.Accepts: null.

descriptionstring

Work order description. Texts longer than 2,000 characters are truncated.

customerobjectrequired

Customer, by id or by name (partial match, uses the first one found).

Fields of customer

idstring

namestring

serviceobjectrequired

Work order type, by id or by name (partial match, uses the first one found).

Fields of service

idstring

namestring

locationobject

Customer location, by id or by name. If omitted, the API uses the customer's primary location.

Fields of location

idstring

namestring

ticketobject

Service request handled by this order. It is accepted and archived. Ignored on update.

Accepts: null.

Fields of ticket

idstringrequired

deadlineAtstring

Deadline date (AAAA-MM-DD). Send null to remove the deadline; if omitted on update, the current value is kept.

Accepts: null.

deadlineContractobject

Deadline contract. Only applied on creation. Cannot be sent together with serviceAgreement.

Fields of deadlineContract

idstringrequired

serviceAgreementobject

Service agreement. Only applied on creation. Cannot be sent together with deadlineContract.

Fields of serviceAgreement

idstringrequired

externalobject

Fields of external

idstring

Work order identifier in your system.

Up to 100 characters.Accepts: null.

addressobjectrequired

Fields of address

zipCodestringrequired

8-digit postal code (CEP), digits only.

streetstringrequired

Street. Texts longer than 50 characters are truncated.

numberstringrequired

Number. Texts longer than 10 characters are truncated.

neighborhoodstring

Neighborhood. Texts longer than 50 characters are truncated.

complementstring

Address complement. Texts longer than 50 characters are truncated.

Accepts: null.

citystringrequired

City. Texts longer than 50 characters are truncated.

statestringrequired

State. Texts longer than 30 characters are truncated.

coordsobjectrequired

Fields of coords

latitudenumberrequired

From -90 to 90.

longitudenumberrequired

From -180 to 180.

metadataobject

Internal metadata. Only accepted with the shagrat key.

customFieldslist of objects

Answers to the custom fields of the work order type. Only the fields sent are changed; value: null removes the answer. On update, each field is identified by its id.

Display conditions (condition) are evaluated with the stored answers together with the ones sent. Answering a hidden field returns 422 (hidden by condition), and a required field with a condition that becomes visible without an answer returns 422 (required). When the answer to a trigger changes, the answers to the fields that become hidden are deleted.

Fields of customFields

idstringrequired

Identifier of the custom field, from the order's work order type. Each field can be sent once.

valuestring or numberrequired

Answer, validated according to the field type: question, text of up to 500 characters; number, a number (or numeric text); date, a AAAA-MM-DD date; multiple-choice, one of the registered options. checklist, attachment and multiple-photos fields cannot be answered through the API. null leaves the field unanswered. In the legacy format, text of 1 to 500 characters, not validated by type.

Accepts: null.

taskslist of objects

Work order tasks. Required on creation, with at least one; ignored on update.

Fields of tasks

statusstringrequired

Task status.

Accepted values: pending, scheduled, in-progress, done, canceled, reported, on-route, paused.

employeeobject

Employee in charge.

Fields of employee

idstring

Employee identifier.

namestring

Employee name. Texts are accepted, but the link is made by id.

taskTypeobject

Task type.

Fields of taskType

idstring

Task type identifier.

descriptionstring

Task description.

Accepts: null.

statusDescriptionstring

Note about the status. Up to 6,000 characters.

Accepts: null.

durationinteger

Expected duration, in minutes. If omitted when creating the order, the API uses the duration of the work order type.

Accepts: null.

positioninteger

Order of the task within the work order.

Default: 100.

archivedboolean

Archives the task.

Default: false.

schedulingobjectrequired

Scheduling. type is calculated: with date and time it becomes scheduled-date-and-time, with only date it becomes scheduled-date, and without a date it becomes non-scheduled.

Fields of scheduling

typestring

Ignored; calculated from date and time.

Accepted values: scheduled-date, scheduled-date-and-time, non-scheduled.

datestring

Date (AAAA-MM-DD).

Accepts: null.

timestring

Time (HH:MM:SS).

Accepts: null.

coordsobjectrequired

Coordinates of the task location.

Fields of coords

latitudenumberrequired

longitudenumberrequired

Responses

• 200

  Work order updated.

• 401

  API key missing (Missing API Key) or invalid (Invalid API Key). See Authentication.

• 403

  Account blocked (Account blocked), expired (Account expired) or on a plan that does not allow integration (Account plan not allowed). See Authentication.

• 404

  Resource not found. The response body is empty.

• 422

  Invalid body (resourceValidationErr). An invalid identifier, or one from another account, in the URL also returns this error, with property: '@.id'.

• 429

  Limit of 1 request per second exceeded. See Rate limit.

• 500

  Unexpected server error.