Aprovação — Visão geral

Uma alçada de aprovação define quem pode aprovar ou reprovar um card em uma determinada fase, e sob quais condições. Cada alçada é composta por uma configuração base e por uma ou mais regras: cada regra estabelece os critérios que determinam quando ela se aplica a um card, e a hierarquia de aprovadores responsáveis por votar quando ela é acionada.

Este domínio possui dois grupos de endpoints bem distintos. Os seis primeiros configuram o módulo de aprovação na fase — a configuração base e as regras. Os três últimos registram o voto propriamente dito em um card específico, quando ele chega à fase de aprovação. Configurar o módulo não vota em nenhum card; registrar um voto exige que o módulo já esteja configurado.

Fluxo horizontal vs. fluxo vertical

Cada regra de aprovação define, no campo approvers.type, como os aprovadores decidem:

Tipo	Fluxo	Comportamento
`alternative`	Horizontal	Qualquer aprovador do nível decide — não é necessário seguir a ordem dos níveis definidos em `hierarchy`.
`cumulative`	Vertical	Os níveis de `hierarchy` são percorridos em cadeia sequencial — o nível 1 precisa concluir sua aprovação antes que o nível 2 seja habilitado a votar, e assim por diante.

Em ambos os casos, hierarchy[].quantity define quantos aprovadores daquele nível precisam votar para o nível ser considerado concluído, e hierarchy[].users traz os identificadores dos usuários aprovadores daquele nível.

Endpoints deste domínio

Método	Caminho	Descrição
`GET`	`/v1/flows/{flowId}/phases/{phaseId}/approval-config`	Consulta a configuração de aprovação da fase
`POST`	`/v1/flows/{flowId}/phases/{phaseId}/approval-config`	Cria a configuração base da alçada
`PUT`	`/v1/flows/{flowId}/phases/{phaseId}/approval-config`	Atualiza a configuração base da alçada
`POST`	`/v1/flows/{flowId}/phases/{phaseId}/approval-config/{approvalConfigId}/rules`	Adiciona uma regra à alçada
`PUT`	`/v1/flows/{flowId}/phases/{phaseId}/approval-config/{approvalConfigId}/rules/{ruleId}`	Atualiza uma regra existente
`DELETE`	`/v1/flows/approval-config/{id}`	Remove a configuração de aprovação inteira, com todas as suas regras
`GET`	`/v1/cards/{cardId}/phases/{phaseId}/actions/approval`	Consulta o registro de votação de um card
`POST`	`/v1/cards/{cardId}/phases/{phaseId}/actions/approval`	Registra um novo voto de aprovação
`PUT`	`/v1/cards/{cardId}/phases/{phaseId}/actions/approval/{approvalId}`	Atualiza um voto já registrado

Comportamentos importantes

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.

Aprovação — Visão Geral

Aprovação — Visão geral#

Fluxo horizontal vs. fluxo vertical#

Endpoints deste domínio#

Comportamentos importantes#

Aprovação — Visão geral

Fluxo horizontal vs. fluxo vertical

Endpoints deste domínio

Comportamentos importantes