Pular para o conteúdo principal

Atualizar uma ordem de serviço

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

Atualiza os dados de uma ordem de serviço e as respostas dos campos customizados enviadas. Atividades, produtos e serviços têm endpoints próprios.

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

Requisição​

Parâmetros de caminho

idstringobrigatório

Identificador da ordem de serviço.

Exemplo: NDJiMWQ0YzQtOWNmOC00NWE2LTg2MjItYjNjNzZjZjk0MmM4OjIyOTE1.

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. Só os campos enviados são alterados; value: null remove a resposta. Na atualização, cada campo é identificado pelo id.

As condições de exibição (condition) são avaliadas com as respostas gravadas junto com as enviadas. Responder um campo oculto retorna 422 (hidden by condition), e um campo obrigatório com condição que fica visível sem resposta retorna 422 (required). Ao mudar a resposta de um gatilho, as respostas dos campos que ficarem ocultos são apagadas.

Campos de customFields
idstringobrigatório

Identificador do campo customizado, do tipo de OS da ordem. Cada campo pode ser enviado uma vez.

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 objetos

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

  • 200

    Ordem de serviço atualizada.

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

  • 404

    Recurso não encontrado. O corpo da resposta é vazio.

  • 422

    Corpo inválido (resourceValidationErr). Um identificador inválido ou de outra conta na URL também retorna este erro, com property: '@.id'.

  • 429

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

  • 500

    Erro inesperado no servidor.