Atualizar uma subtarefa de uma tarefa de um plano de tarefas

Modifica uma subtarefa existente de uma tarefa de um plano de tarefas. A atualização é parcial: somente o que você enviar no corpo é alterado e o restante da subtarefa mantém seu valor atual. Uma subtarefa é editada por requisição. Para criar subtarefas use Criar subtarefas em uma tarefa de um plano de tarefas.

Add-on

Uso geral — sem add-on específico. O token deve pertencer a um perfil com permissão de edição em Tarefas > Planos de tarefas.

PUT https://app.fracttal.com/api/tasks_subtasks/{id_subtask}

Parâmetros de entrada

ParâmetroTipoObrigatórioDescrição
id_subtaskinteiroSim (na rota)Identificador da subtarefa. É obtido no campo id da resposta de Criar subtarefas em uma tarefa de um plano de tarefas. A tarefa à qual pertence é deduzida da subtarefa.

Parâmetros do corpo

Enviados em formato JSON. Todos são opcionais, mas você deve enviar pelo menos um dos campos editáveis (id_task_form_item_type, description, task_form_item_group_description, id_unit, unit_description, dropdown_options, iterations, is_required ou attachments_required).

ParâmetroTipoObrigatórioDescrição
id_task_form_item_typeinteiroNãoTipo de subtarefa, de 1 a 8: 1 Texto, 2 Sim/Não, 3 Número, 4 Verificação, 5 Leitura de medidor, 6 Localização GPS, 7 Lista, 8 Data e hora.
descriptiontextoNãoRótulo ou pergunta da subtarefa. Não pode estar vazia nem conter apenas espaços.
task_form_item_group_descriptiontextoNãoNome do grupo ao qual a subtarefa pertence (entre 1 e 150 caracteres). É buscado por similaridade entre os grupos existentes; se não houver correspondência, o grupo é criado.
id_unitinteiroCondicionalIdentificador da unidade de medida. Aplica-se somente a subtarefas do tipo 5. Deve existir nas unidades da empresa.
unit_descriptiontextoCondicionalNome da unidade de medida (máximo de 50 caracteres). Aplica-se somente a subtarefas do tipo 5. É buscado por similaridade entre as unidades existentes; se não houver correspondência, a unidade é criada.
dropdown_optionsarray de objetosCondicionalOpções da lista. Aplica-se somente a subtarefas do tipo 7. Mínimo de 2 elementos. Veja a estrutura na tabela seguinte.
iterationsobjetoNãoIterações em que a subtarefa participa, no formato { "iteration_1": true, "iteration_2": false }. Só é considerado em tarefas cíclicas.
is_requiredbooleanoNãoIndica se a subtarefa é obrigatória.
attachments_requiredbooleanoNãoIndica se a subtarefa exige anexos.
is_cyclicalbooleanoNãoIndica se a tarefa é cíclica. Se enviado, deve coincidir com a configuração da tarefa; este serviço não a modifica.
num_iterationsinteiroNãoNúmero de iterações da tarefa. Se enviado, deve ser maior que 0 e coincidir com a configuração da tarefa; este serviço não a modifica.

Estrutura de cada elemento em dropdown_options:

ParâmetroTipoObrigatórioDescrição
descriptiontextoSimTexto da opção. Não pode estar vazio.

Regras da edição

  • As regras por tipo são aplicadas sobre o tipo efetivo da subtarefa: o que você envia em id_task_form_item_type ou, se não enviar, o que ela já tem.
  • Ao mudar para o tipo 7 (Lista) você deve enviar dropdown_options com pelo menos 2 opções.
  • Ao mudar para o tipo 5 (Leitura de medidor) você deve enviar id_unit ou unit_description, a menos que a subtarefa já tenha uma unidade atribuída.
  • Se a tarefa tiver ativos vinculados e a subtarefa mudar para o tipo 5, a subtarefa é atualizada, mas message chega como ERROR_CONFIG_METERS_ASSETS: ainda falta configurar o medidor de cada ativo no Fracttal.
  • Ao sair do tipo 7, as opções da lista da subtarefa são removidas.
  • Ao sair do tipo 5, a unidade da subtarefa e os medidores associados a ela são removidos.
  • dropdown_options só é aceito em subtarefas do tipo 7; id_unit e unit_description só em subtarefas do tipo 5.
  • iterations é mesclado com as iterações atuais da subtarefa: somente as iterações enviadas são alteradas. Cada iteration_n deve estar entre 1 e o número de iterações da tarefa. Em uma tarefa que não é cíclica, iterations é ignorado.
  • Uma subtarefa de outra empresa é tratada da mesma forma que uma inexistente (404).

Parâmetros de saída

ParâmetroTipoDescrição
successbooleanotrue se a subtarefa foi atualizada.
messagetexto200 quando a operação é bem-sucedida, ou ERROR_CONFIG_METERS_ASSETS se a subtarefa foi atualizada, mas ainda falta configurar os medidores dos ativos vinculados. Em caso de erro, contém o código do erro.
totalinteiro1 quando a operação é bem-sucedida.
dataobjetoSubtarefa atualizada.
data.idinteiroIdentificador da subtarefa.
data.id_taskinteiroIdentificador da tarefa à qual pertence.
data.id_task_form_item_typeinteiroTipo de subtarefa (1 a 8).
data.id_unitinteiroIdentificador da unidade de medida. null se a subtarefa não for do tipo 5.
data.descriptiontextoRótulo ou pergunta da subtarefa.
data.order_numberinteiroPosição da subtarefa dentro da tarefa.
data.is_requiredbooleanoIndica se é obrigatória.
data.attachments_requiredbooleanoIndica se exige anexos.
data.id_task_form_item_groupinteiroIdentificador do grupo da subtarefa. null se não tiver grupo.
data.iterationsobjetoIterações em que a subtarefa participa.
data.dropdown_optionsarray de objetosOpções da lista. null se a subtarefa não for do tipo 7.

Erros

CódigoCausa
400body is required: falta o corpo da requisição.
400at least one editable field must be sent: nenhum campo editável foi enviado.
400id_task_form_item_type must be between 1 and 8: tipo de subtarefa inválido.
400description cannot be empty: a descrição está vazia ou contém apenas espaços.
400is_required must be a boolean, attachments_required must be a boolean ou is_cyclical must be a boolean: o valor enviado não é booleano.
400task_form_item_group_description must have between 1 and 150 characters: nome de grupo vazio ou muito longo.
400num_iterations must be greater than 0: num_iterations não é maior que 0.
400dropdown_options only applies to list subtasks: foram enviadas opções para uma subtarefa que não é do tipo 7.
400dropdown_options requires at least 2 elements for list subtasks: lista com menos de 2 opções.
400every dropdown option must have a non-empty description: uma opção sem description.
400id_unit must be an integer and unit_description at most 50 characters: id_unit não é inteiro ou unit_description excede 50 caracteres.
400id_unit and unit_description only apply to meter reading subtasks: foi enviada unidade para uma subtarefa que não é do tipo 5.
400id_unit or unit_description is required for meter reading subtasks: leitura de medidor sem unidade.
400iterations must be an object ou iterations must use the format {"iteration_n": true|false}: formato de iterations inválido.
400iteration_n does not exist in task (num_iterations=n): iteração fora do intervalo da tarefa.
401INVALID_TOKEN: o token de autenticação não é válido.
403User does not have edit permission over TASKS > PLAN_TASKS: o perfil do token não pode editar planos de tarefas.
404subtask not found: a subtarefa não existe ou pertence a outra empresa.
409is_cyclical does not match the task configuration: is_cyclical não coincide com a tarefa.
409num_iterations does not match the task configuration: num_iterations não coincide com a tarefa.
422id_unit n does not exist: id_unit não existe nas unidades da empresa.
500Erro interno do sistema.

Nota sobre os códigos de erro

Quando a operação falha, o código do erro chega no campo message (por exemplo "404" ou "409") e o detalhe em data[0].ERROR. A resposta HTTP dos erros de validação é 400, independentemente do valor de message; use message para distinguir a causa. Um token inválido responde com HTTP 401.


Exemplo

Request body

PUT /api/tasks_subtasks/6102

{
  "description": "Estado do rolamento após a inspeção",
  "is_required": true,
  "attachments_required": true,
  "id_task_form_item_type": 7,
  "dropdown_options": [
    { "description": "Bom" },
    { "description": "Desgastado" },
    { "description": "Substituir" }
  ]
}

Response 200

{
  "success": true,
  "message": "200",
  "data": {
    "id": 6102,
    "id_task": 5001,
    "id_task_form_item_type": 7,
    "id_unit": null,
    "description": "Estado do rolamento após a inspeção",
    "order_number": 3,
    "is_required": true,
    "attachments_required": true,
    "id_task_form_item_group": null,
    "iterations": {},
    "dropdown_options": [
      { "description": "Bom" },
      { "description": "Desgastado" },
      { "description": "Substituir" }
    ]
  },
  "total": 1
}

Response — Mudança para leitura de medidor em uma tarefa com ativos vinculados (200)

Request body:

{
  "id_task_form_item_type": 5,
  "unit_description": "Graus Celsius"
}

Response:

{
  "success": true,
  "message": "ERROR_CONFIG_METERS_ASSETS",
  "data": {
    "id": 6103,
    "id_task": 5002,
    "id_task_form_item_type": 5,
    "id_unit": 215,
    "description": "Temperatura do motor",
    "order_number": 1,
    "is_required": false,
    "attachments_required": false,
    "id_task_form_item_group": null,
    "iterations": {},
    "dropdown_options": null
  },
  "total": 1
}

Response — Lista com menos de 2 opções (400)

{
  "success": false,
  "message": "400",
  "data": [
    {
      "ERROR": "dropdown_options requires at least 2 elements for list subtasks"
    }
  ],
  "total": "0"
}

Response — Subtarefa inexistente (404)

{
  "success": false,
  "message": "404",
  "data": [
    {
      "ERROR": "subtask not found"
    }
  ],
  "total": "0"
}

Response — is_cyclical não coincide com a tarefa (409)

{
  "success": false,
  "message": "409",
  "data": [
    {
      "ERROR": "is_cyclical does not match the task configuration"
    }
  ],
  "total": "0"
}

Response — Unidade inexistente (422)

{
  "success": false,
  "message": "422",
  "data": [
    {
      "ERROR": "id_unit 999999 does not exist"
    }
  ],
  "total": "0"
}

OpenAPI definition

{
  "openapi": "3.1.0",
  "info": {
    "title": "tasks_subtasks",
    "version": "3-pt"
  },
  "servers": [
    { "url": "https://app.fracttal.com/api/tasks_subtasks" }
  ],
  "security": [{}],
  "paths": {
    "/{id_subtask}": {
      "put": {
        "summary": "Atualizar uma subtarefa de uma tarefa de um plano de tarefas",
        "description": "",
        "operationId": "atualizar-uma-subtarefa-de-uma-tarefa-de-um-plano-de-tarefas",
        "deprecated": false,
        "security": []
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": false,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
Path Params
integer
required
Response
200
Language
LoadingLoading…