Objetivo

A API permite cadastrar uma regra de aprovador substituto no ContractPlus.

A configuração possibilita que um usuário substituto tenha acesso aos processos de aprovação destinados a um aprovador original, desde que a regra esteja:

• Ativa;

• Dentro do período de vigência;

• Vinculada ao processo correspondente.

A substituição não altera o aprovador original registrado no histórico do fluxo. O usuário substituto apenas passa a ter acesso funcional à aprovação enquanto a regra estiver válida.

Aplicação da API

A API pode ser utilizada para definir um aprovador substituto para um ou mais processos de aprovação.

Cada regra possui:

• Um aprovador original;

• Um aprovador substituto;

• Uma data inicial;

• Uma data final;

• Um ou mais processos vinculados;

• Um status de ativação.

A mesma regra pode abranger múltiplos processos por meio da propriedade places.

Endpoint

POST /api/ApprovalSubstitute

Autenticação

A requisição exige autenticação válida.

O token deve ser enviado no cabeçalho:

Authorization: Bearer {{token}}

Quando a requisição for enviada sem autenticação, o processamento será bloqueado e nenhum registro será criado.

Cabeçalhos

Content-Type: application/json
Authorization: Bearer {{token}}

Estrutura da requisição

Exemplo

{
  "userApprovalCode": "aprovador.original",
  "userSubstituteCode": "aprovador.substituto",
  "dateStart": "2026-08-10",
  "dateEnd": "2026-12-31",
  "places": [
    1, 2, 3
    ]
}

Campos da requisição

Estrutura principal

Aprovador original

O campo userApprovalCode identifica o usuário que originalmente possui responsabilidade pela aprovação.

Exemplo:

{
  "userApprovalCode": "aprovador.original"
}

Esse campo é obrigatório.

Quando não for informado, a API retornará:

{
  "Success": false,
  "SubstituteId": 0,
  "Message": "Informe o aprovador."
}

Nenhuma regra será criada.

Aprovador substituto

O campo userSubstituteCode identifica o usuário que poderá executar as aprovações em nome do aprovador original durante a vigência da regra.

Exemplo:

{
  "userSubstituteCode": "aprovador.substituto"
}

Quando não for informado:

{
  "Success": false,
  "SubstituteId": 0,
  "Message": "Informe o aprovador substituto."
}

Nenhuma regra será criada.

Usuários existentes

O aprovador original e o aprovador substituto devem corresponder a usuários existentes.

Exemplo com usuário inexistente:

{
  "userApprovalCode": "usuario.inexistente",
  "userSubstituteCode": "aprovador.substituto"
}

Resposta:

{
  "Success": false,
  "SubstituteId": 0,
  "Message": "Usuário não encontrado: usuario.inexistente."
}

A operação será bloqueada sem persistir a regra.

Aprovador e substituto não podem ser o mesmo usuário

O usuário substituto deve ser diferente do aprovador original.

Exemplo inválido:

{
  "userApprovalCode": "usuario.aprovador",
  "userSubstituteCode": "usuario.aprovador"
}

Resposta:

{
  "Success": false,
  "SubstituteId": 0,
  "Message": "O aprovador substituto não pode ser igual ao aprovador."
}

Vigência da substituição

A regra é válida dentro do intervalo definido entre dateStart e dateEnd.

Exemplo:

{
  "dateStart": "2026-08-10",
  "dateEnd": "2026-12-31"
}

O substituto somente será considerado nos fluxos quando a data atual estiver dentro desse período.

Fora da vigência, a regra é ignorada mesmo que esteja ativa.

Data inicial

O campo dateStart não precisa obrigatoriamente ser informado.

Quando estiver vazio ou ausente, o sistema utilizará a data atual do sistema como data inicial da vigência.

Exemplo:

{
  "userApprovalCode": "aprovador.original",
  "userSubstituteCode": "aprovador.substituto",
  "dateEnd": "2026-12-31",
  "places": [
    1, 2
  ]
}

Nesse caso, a data atual será utilizada automaticamente como dateStart.

Data final

O campo dateEnd é obrigatório.

Quando estiver vazio ou ausente, a criação será bloqueada.

Resposta:

{
  "Success": false,
  "SubstituteId": 0,
  "Message": "A data final do período é obrigatória. Deve ser igual ou superior a data inicial do período."
}

Período inválido

A data inicial não pode ser superior à data final.

Exemplo inválido:

{
  "dateStart": "2026-12-31",
  "dateEnd": "2026-08-10"
}

Resposta:

{
  "Success": false,
  "SubstituteId": 0,
  "Message": "A data inicial deve ser menor ou igual à data final."
}

Sobreposição de períodos

O mesmo aprovador original não pode possuir duas regras ativas com períodos sobrepostos.

Exemplo:

Uma regra existente:

01/08/2026 até 31/08/2026

Uma nova regra para o mesmo aprovador:

15/08/2026 até 30/09/2026

A nova inclusão será bloqueada.

A resposta informa que já existe uma configuração ativa para o aprovador dentro de um intervalo conflitante.

Períodos sem sobreposição

O mesmo aprovador original pode possuir mais de uma regra quando os períodos não se sobrepõem.

Exemplo:

Regra 1: 01/08/2026 até 31/08/2026
Regra 2: 01/09/2026 até 31/12/2026

Nesse caso, ambas podem coexistir.

Mesmo substituto para aprovadores diferentes

O mesmo usuário substituto pode ser utilizado em regras de aprovadores originais diferentes.

Exemplo:

Aprovador A → Substituto X
Aprovador B → Substituto X

A existência de uma regra utilizando o mesmo substituto não bloqueia automaticamente novas regras.

O controle de conflito é realizado considerando principalmente o aprovador original e o período configurado.

Processos da substituição

A propriedade places define os processos em que o usuário substituto poderá atuar.

Exemplo:

{
  "places": [
    1, 2, 3
  ]
}

Todos os placeId informados ficam vinculados à mesma regra de substituição.

Múltiplos processos

A API permite informar vários processos em uma única requisição.

Exemplo:

{
  "userApprovalCode": "aprovador.original",
  "userSubstituteCode": "aprovador.substituto",
  "dateStart": "2026-08-10",
  "dateEnd": "2026-12-31",
  "places": [
    1, 2, 3, 4
  ]
}

O substituto somente terá acesso aos fluxos correspondentes aos processos vinculados à regra.

Lista de processos obrigatória

A propriedade places deve possuir ao menos um processo.

Exemplo inválido:

{
  "places": []
}

Resposta:

{
  "Success": false,
  "SubstituteId": 0,
  "Message": "Informe ao menos um processo para a substituição."
}

Locais de aprovação

Os processos utilizam os seguintes identificadores:

A substituição somente será aplicada ao processo correspondente ao placeId vinculado.

Resposta de sucesso

Status esperado

200 OK

Exemplo

{
  "Success": true,
  "SubstituteId": 101,
  "Message": "Aprovador substituto cadastrado com sucesso."
}

Campos da resposta

O SubstituteId pode ser utilizado posteriormente nas operações relacionadas à regra, como alteração do status.

Como funciona no fluxo de aprovação

O cadastro da regra não altera o aprovador originalmente associado ao documento.

Quando existir uma regra:

• Ativa;

• Dentro da vigência;

• Vinculada ao placeId do processo;

o substituto passa a ter acesso funcional ao fluxo de aprovação destinado ao aprovador original.

O histórico continua mantendo o aprovador original como referência do fluxo.

Regra ativa e vigente

Quando todas as condições forem atendidas:

Active = true
Data atual dentro da vigência
PlaceId do processo vinculado

o substituto terá acesso ao documento para realizar a aprovação.

Regra inativa

Quando a regra estiver inativa, o substituto não terá acesso ao fluxo.

Mesmo que:

• O período esteja vigente;

• O processo esteja vinculado;

a substituição será ignorada enquanto a regra permanecer desativada.

Regra fora da vigência

Quando a data atual estiver fora do período configurado, o substituto não terá acesso ao documento.

Isso ocorre mesmo quando a regra estiver ativa.

Processo não vinculado

A substituição somente se aplica aos processos presentes em places.

Por exemplo, se a regra estiver vinculada apenas a:

{
  "places": [
    3
  ]
}

o substituto poderá atuar em Medição, mas não terá acesso automático a aprovações de Contrato, Aditivo, Distrato ou outros processos.

Comportamento esperado

Integridade da operação

A criação da regra e dos processos vinculados deve ser tratada como uma única operação.

Caso ocorra erro:

• A regra principal não deverá permanecer parcialmente criada;

• Nenhum placeId deverá ficar vinculado sem uma regra correspondente;

• Nenhuma configuração parcial deverá permanecer.

Os vínculos de processos permanecem relacionados ao mesmo identificador da regra de substituição.

Pontos de atenção

• userApprovalCode é obrigatório.

• userSubstituteCode é obrigatório.

• O aprovador e o substituto devem ser usuários diferentes.

• Os usuários informados devem existir.

• dateStart é opcional; quando ausente, será utilizada a data atual do sistema.

• dateEnd é obrigatória.

• A data inicial deve ser menor ou igual à data final.

• Não podem existir regras ativas sobrepostas para o mesmo aprovador original.

• Períodos diferentes e sem sobreposição podem coexistir.

• O mesmo substituto pode atender aprovadores diferentes.

• Ao menos um placeId deve ser informado.

• Uma mesma regra pode possuir vários processos vinculados.

• O substituto somente atua nos placeId configurados.

• A regra precisa estar ativa e vigente para produzir efeito.

• Regras inativas são ignoradas pelo fluxo.

• Regras fora da vigência são ignoradas pelo fluxo.

• O aprovador original permanece como referência histórica do processo.

• O tempo de resposta pode variar conforme a quantidade de processos informados em places.