Criar uma ordem de serviço

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

Cria uma ordem de serviço com ao menos uma atividade. Cliente, tipo de OS e localização podem ser informados pelo identificador ou pelo nome. Ao informar ticket, a solicitação é aceita e arquivada.

Requer os headers X-Api-Key, User-Agent e Content-Type: application/json. Limite: 1 requisição por segundo (saiba mais).

Requisição

Headers

User-Agentstringobrigatório

Identificação da sua aplicação.

Exemplo: MinhaIntegracao/1.0.

Corpo da requisição

JSON, enviado com o header Content-Type: application/json.

identifierstring

Número da ordem, único na conta. Se omitido, é gerado conforme a configuração da conta; em contas com numeração manual, é obrigatório. O caractere # no meio é reservado.

Mínimo de 1 caracteres.Aceita: null.

descriptionstring

Descrição da ordem de serviço. Textos com mais de 2.000 caracteres são truncados.

customerobjectobrigatório

Cliente, por id ou por name (busca parcial, usa o primeiro encontrado).

Campos de customer

idstring

namestring

serviceobjectobrigatório

Tipo de OS, por id ou por name (busca parcial, usa o primeiro encontrado).

Campos de service

idstring

namestring

locationobject

Localização do cliente, por id ou por name. Se omitida, a API usa a localização primária do cliente.

Campos de location

idstring

namestring

ticketobject

Solicitação de serviço atendida por esta ordem. Ela é aceita e arquivada. Ignorado na atualização.

Aceita: null.

Campos de ticket

idstringobrigatório

deadlineAtstring

Data de prazo (AAAA-MM-DD). Envie null para remover o prazo; omitido na atualização, o valor atual é mantido.

Aceita: null.

deadlineContractobject

Contrato de prazos. Só é aplicado na criação. Não pode ser enviado junto com serviceAgreement.

Campos de deadlineContract

idstringobrigatório

serviceAgreementobject

Acordo de atendimento. Só é aplicado na criação. Não pode ser enviado junto com deadlineContract.

Campos de serviceAgreement

idstringobrigatório

externalobject

Campos de external

idstring

Identificador da ordem de serviço no seu sistema.

Até 100 caracteres.Aceita: null.

addressobjectobrigatório

Campos de address

zipCodestringobrigatório

CEP com 8 dígitos, somente números.

streetstringobrigatório

Logradouro. Textos com mais de 50 caracteres são truncados.

numberstringobrigatório

Número. Textos com mais de 10 caracteres são truncados.

neighborhoodstring

Bairro. Textos com mais de 50 caracteres são truncados.

complementstring

Complemento. Textos com mais de 50 caracteres são truncados.

Aceita: null.

citystringobrigatório

Cidade. Textos com mais de 50 caracteres são truncados.

statestringobrigatório

Estado. Textos com mais de 30 caracteres são truncados.

coordsobjectobrigatório

Campos de coords

latitudenumberobrigatório

De -90 a 90.

longitudenumberobrigatório

De -180 a 180.

metadataobject

Metadados internos. Só é aceito com a chave shagrat.

customFieldslista de objetos

Respostas dos campos customizados do tipo de OS. Os campos do tipo de OS (com o id de cada um) estão em Listar os campos customizados de um tipo de OS. Campos não enviados ficam sem resposta. Também é aceito o formato antigo, sem id e com name, type e position: a resposta é gravada como enviada, sem conferir os campos do tipo de OS.

Campos com condition só são exibidos quando o gatilho tem a resposta esperada. Responder um campo oculto retorna 422 (hidden by condition), mas enviá-lo com value: null é aceito. Um campo obrigatório com condição só é exigido quando está visível; sem resposta, retorna 422 (required).

Campos de customFields

idstring

Identificador do campo customizado, do tipo de OS da ordem. Cada campo pode ser enviado uma vez. Com id, name, type e position são ignorados.

namestring

Formato antigo, sem id. Título do campo, com até 150 caracteres.

typeinteger

Formato antigo. Tipo do campo: 0 (question), 1 (multiple-choice), 2 (date), 3 (number), 4 (checklist), 5 (attachment) ou 6 (multiple-photos). Padrão é 0.

positioninteger

Formato antigo. Posição do campo. Padrão é a posição no array, a partir de 1.

Aceita: null.

valuestring ou numberobrigatório

Resposta, validada conforme o tipo do campo: question, texto de até 500 caracteres; number, número (ou texto numérico); date, data AAAA-MM-DD; multiple-choice, uma das opções cadastradas. Campos checklist, attachment e multiple-photos não podem ser respondidos pela API. null deixa o campo sem resposta. No formato antigo, texto de 1 a 500 caracteres, sem validação pelo tipo.

Aceita: null.

taskslista de objetosobrigatório

Atividades da ordem de serviço. Obrigatório na criação, com ao menos uma; ignorado na atualização.

Campos de tasks

statusstringobrigatório

Situação da atividade.

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

employeeobject

Colaborador responsável.

Campos de employee

idstring

Identificador do colaborador.

namestring

Nome do colaborador. Textos são aceitos, mas o vínculo é feito pelo id.

taskTypeobject

Tipo da atividade.

Campos de taskType

idstring

Identificador do tipo de atividade.

descriptionstring

Descrição da atividade.

Aceita: null.

statusDescriptionstring

Observação sobre a situação. Até 6.000 caracteres.

Aceita: null.

durationinteger

Duração prevista, em minutos. Se omitida na criação da ordem, a API usa a duração do tipo de OS.

Aceita: null.

positioninteger

Ordem da atividade dentro da ordem de serviço.

Padrão: 100.

archivedboolean

Arquiva a atividade.

Padrão: false.

schedulingobjectobrigatório

Agendamento. type é calculado: com date e time vira scheduled-date-and-time, só com date vira scheduled-date, e sem data vira non-scheduled.

Campos de scheduling

typestring

Ignorado; calculado a partir de date e time.

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

datestring

Data (AAAA-MM-DD).

Aceita: null.

timestring

Horário (HH:MM:SS).

Aceita: null.

coordsobjectobrigatório

Coordenadas do local da atividade.

Campos de coords

latitudenumberobrigatório

longitudenumberobrigatório

Respostas

• 201

  Ordem de serviço criada, com as atividades criadas em tasks.

• 401

  Chave de API ausente (Missing API Key) ou inválida (Invalid API Key). Ver Autenticação.

• 403

  Conta bloqueada (Account blocked), expirada (Account expired) ou com plano que não permite integração (Account plan not allowed). Ver Autenticação.

• 422

  Corpo inválido (resourceValidationErr): campo obrigatório ausente, tasks vazio, cliente, tipo de OS, localização, solicitação, contrato de prazos ou acordo de atendimento não encontrados (reason: not found), número duplicado (reason: duplicated), número obrigatório em contas com numeração manual, # no meio do número, deadlineContract e serviceAgreement enviados juntos, ou resposta de campo customizado inválida (@.customFields[n].id de outro tipo de OS ou repetido, @.customFields[n].value fora das regras do tipo do campo).

• 429

  Limite de 1 requisição por segundo excedido. Ver Limite de requisições.

• 500

  Erro inesperado no servidor.