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-onUso 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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id_subtask | inteiro | Sim (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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id_task_form_item_type | inteiro | Não | Tipo 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. |
description | texto | Não | Rótulo ou pergunta da subtarefa. Não pode estar vazia nem conter apenas espaços. |
task_form_item_group_description | texto | Não | Nome 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_unit | inteiro | Condicional | Identificador da unidade de medida. Aplica-se somente a subtarefas do tipo 5. Deve existir nas unidades da empresa. |
unit_description | texto | Condicional | Nome 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_options | array de objetos | Condicional | Opções da lista. Aplica-se somente a subtarefas do tipo 7. Mínimo de 2 elementos. Veja a estrutura na tabela seguinte. |
iterations | objeto | Não | Iterações em que a subtarefa participa, no formato { "iteration_1": true, "iteration_2": false }. Só é considerado em tarefas cíclicas. |
is_required | booleano | Não | Indica se a subtarefa é obrigatória. |
attachments_required | booleano | Não | Indica se a subtarefa exige anexos. |
is_cyclical | booleano | Não | Indica se a tarefa é cíclica. Se enviado, deve coincidir com a configuração da tarefa; este serviço não a modifica. |
num_iterations | inteiro | Não | Nú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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
description | texto | Sim | Texto 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_typeou, se não enviar, o que ela já tem.- Ao mudar para o tipo
7(Lista) você deve enviardropdown_optionscom pelo menos 2 opções.- Ao mudar para o tipo
5(Leitura de medidor) você deve enviarid_unitouunit_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, masmessagechega comoERROR_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_optionssó é aceito em subtarefas do tipo7;id_uniteunit_descriptionsó em subtarefas do tipo5.iterationsé mesclado com as iterações atuais da subtarefa: somente as iterações enviadas são alteradas. Cadaiteration_ndeve 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âmetro | Tipo | Descrição |
|---|---|---|
success | booleano | true se a subtarefa foi atualizada. |
message | texto | 200 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. |
total | inteiro | 1 quando a operação é bem-sucedida. |
data | objeto | Subtarefa atualizada. |
data.id | inteiro | Identificador da subtarefa. |
data.id_task | inteiro | Identificador da tarefa à qual pertence. |
data.id_task_form_item_type | inteiro | Tipo de subtarefa (1 a 8). |
data.id_unit | inteiro | Identificador da unidade de medida. null se a subtarefa não for do tipo 5. |
data.description | texto | Rótulo ou pergunta da subtarefa. |
data.order_number | inteiro | Posição da subtarefa dentro da tarefa. |
data.is_required | booleano | Indica se é obrigatória. |
data.attachments_required | booleano | Indica se exige anexos. |
data.id_task_form_item_group | inteiro | Identificador do grupo da subtarefa. null se não tiver grupo. |
data.iterations | objeto | Iterações em que a subtarefa participa. |
data.dropdown_options | array de objetos | Opções da lista. null se a subtarefa não for do tipo 7. |
Erros
| Código | Causa |
|---|---|
400 | body is required: falta o corpo da requisição. |
400 | at least one editable field must be sent: nenhum campo editável foi enviado. |
400 | id_task_form_item_type must be between 1 and 8: tipo de subtarefa inválido. |
400 | description cannot be empty: a descrição está vazia ou contém apenas espaços. |
400 | is_required must be a boolean, attachments_required must be a boolean ou is_cyclical must be a boolean: o valor enviado não é booleano. |
400 | task_form_item_group_description must have between 1 and 150 characters: nome de grupo vazio ou muito longo. |
400 | num_iterations must be greater than 0: num_iterations não é maior que 0. |
400 | dropdown_options only applies to list subtasks: foram enviadas opções para uma subtarefa que não é do tipo 7. |
400 | dropdown_options requires at least 2 elements for list subtasks: lista com menos de 2 opções. |
400 | every dropdown option must have a non-empty description: uma opção sem description. |
400 | id_unit must be an integer and unit_description at most 50 characters: id_unit não é inteiro ou unit_description excede 50 caracteres. |
400 | id_unit and unit_description only apply to meter reading subtasks: foi enviada unidade para uma subtarefa que não é do tipo 5. |
400 | id_unit or unit_description is required for meter reading subtasks: leitura de medidor sem unidade. |
400 | iterations must be an object ou iterations must use the format {"iteration_n": true|false}: formato de iterations inválido. |
400 | iteration_n does not exist in task (num_iterations=n): iteração fora do intervalo da tarefa. |
401 | INVALID_TOKEN: o token de autenticação não é válido. |
403 | User does not have edit permission over TASKS > PLAN_TASKS: o perfil do token não pode editar planos de tarefas. |
404 | subtask not found: a subtarefa não existe ou pertence a outra empresa. |
409 | is_cyclical does not match the task configuration: is_cyclical não coincide com a tarefa. |
409 | num_iterations does not match the task configuration: num_iterations não coincide com a tarefa. |
422 | id_unit n does not exist: id_unit não existe nas unidades da empresa. |
500 | Erro interno do sistema. |
Nota sobre os códigos de erroQuando a operação falha, o código do erro chega no campo
message(por exemplo"404"ou"409") e o detalhe emdata[0].ERROR. A resposta HTTP dos erros de validação é400, independentemente do valor demessage; usemessagepara distinguir a causa. Um token inválido responde com HTTP401.
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
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)
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)
400){
"success": false,
"message": "400",
"data": [
{
"ERROR": "dropdown_options requires at least 2 elements for list subtasks"
}
],
"total": "0"
}Response — Subtarefa inexistente (404)
404){
"success": false,
"message": "404",
"data": [
{
"ERROR": "subtask not found"
}
],
"total": "0"
}Response — is_cyclical não coincide com a tarefa (409)
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)
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
} 200