Create a work order

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

Creates a work order with at least one task. Customer, work order type and location can be given by identifier or by name. When ticket is given, the request is accepted and archived.

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

Request

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. The fields of the work order type (with the id of each one) are in List the custom fields of a work order type. Fields not sent stay unanswered. The legacy format is also accepted, without id and with name, type and position: the answer is saved as sent, without checking the fields of the work order type.

Fields with condition are only shown when the trigger has the expected answer. Answering a hidden field returns 422 (hidden by condition), but sending it with value: null is accepted. A required field with a condition is only required when it is visible; without an answer, it returns 422 (required).

Fields of customFields

idstring

Identifier of the custom field, from the work order type of the order. Each field can be sent once. With id, name, type and position are ignored.

namestring

Legacy format, without id. Title of the field, up to 150 characters.

typeinteger

Legacy format. Field type: 0 (question), 1 (multiple-choice), 2 (date), 3 (number), 4 (checklist), 5 (attachment) or 6 (multiple-photos). Default is 0.

positioninteger

Legacy format. Position of the field. Default is the position in the array, starting at 1.

Accepts: null.

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 objectsrequired

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

• 201

  Work order created, with the created tasks in tasks.

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

• 422

  Invalid body (resourceValidationErr): required field missing, empty tasks, customer, work order type, location, request, deadline contract or service agreement not found (reason: not found), duplicate number (reason: duplicated), number required in accounts with manual numbering, # in the middle of the number, deadlineContract and serviceAgreement sent together, or an invalid custom field answer (@.customFields[n].id from another work order type or repeated, @.customFields[n].value outside the rules of the field type).

• 429

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

• 500

  Unexpected server error.