Criação em duas etapas: a configuração base da alçada (título e parâmetros gerais) é criada primeiro, sem regras e sem aprovadores. As regras são adicionadas depois, uma de cada vez, através de um endpoint próprio — enviar regras junto com a configuração base não é aceito.
Regras uma de cada vez: o endpoint de criação de regra não aceita mais de uma regra por chamada. Para cadastrar várias regras, repita a chamada uma vez para cada uma.
Campos booleanos sempre explícitos: a configuração base exige que os quatro campos — título e os três parâmetros booleanos — sejam enviados explicitamente, mesmo quando o valor desejado for false. Omitir qualquer um deles resulta em erro de validação.
Identificação dos aprovadores: os aprovadores atribuídos a um nível de hierarquia são identificados pelo seu identificador de usuário, obtido a partir da listagem de usuários da empresa (que também traz nome e e-mail). Já dentro das condições de uma regra, quando é preciso filtrar por quem realizou uma ação anterior no card — como o autor de um parecer técnico — a identificação correta é feita por nome ou e-mail, e não por um identificador interno de usuário.
Atualização é substituição completa: ao atualizar a configuração base via PUT, o objeto inteiro é substituído — não se trata de uma atualização parcial. Campos omitidos no payload voltam ao valor padrão. Recomendamos sempre consultar o estado atual antes de atualizar, e reenviar o objeto completo com as alterações aplicadas.
Sem exclusão de regra individual: não existe um endpoint para remover apenas uma regra. A única forma de remover é excluir a configuração de aprovação inteira — o que apaga todas as regras associadas — e recriá-la, se necessário, com as regras remanescentes.
Caminho de exclusão diferente dos demais: o endpoint de remoção da configuração não é aninhado sob flow e fase; ele identifica a configuração diretamente pelo seu identificador.
Consulta sem configuração existente: quando a fase ainda não tem uma configuração de aprovação, a consulta responde com sucesso e corpo vazio, em vez de um erro de recurso não encontrado.
Registro de voto exige regra prévia: para registrar um voto em um card, a fase precisa ter ao menos uma regra de aprovação cadastrada; caso contrário, a chamada retorna erro por não localizar uma regra aplicável.
Comentário sempre obrigatório no voto: ao registrar ou atualizar um voto, os três campos — decisão, valor e comentário — são obrigatórios. Quando a decisão é de reprovação, o valor deve ser exatamente zero; valores maiores que zero só se aplicam a aprovações, representando o limite ou valor aprovado.
Consulta de voto por card ignora o filtro de fase: a consulta de aprovação de um card retorna a aprovação vinculada a ele independentemente da fase informada na URL. Em cards que passam por mais de uma fase com alçada, recomendamos consultar o card completo e percorrer suas ações para identificar a votação de cada fase.
