Objetivo

A API permite consultar os aprovadores substitutos cadastrados no ContractPlus.

A listagem pode ser realizada de duas formas:

GET /api/approvalSubstitute

ou:

GET /api/approvalSubstitute?hideExpired=true

O parâmetro hideExpired é opcional e permite ocultar registros cuja data final de vigência já tenha expirado.

Endpoint

GET /api/approvalSubstitute

Com filtro opcional:

GET /api/approvalSubstitute?hideExpired=true

Autenticação

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

Authorization: Bearer {{token}}

Caso o token esteja ausente ou inválido, a API retorna:

401 Unauthorized

Cabeçalhos

Authorization: Bearer {{token}}
Accept: application/json

A requisição não possui corpo.

Consulta sem filtro

Para retornar todos os aprovadores substitutos cadastrados:

GET /api/approvalSubstitute

Essa consulta retorna registros:

• Ativos;

• Inativos;

• Vigentes;

• Vencidos.

Ou seja, nenhuma filtragem por data final é aplicada.

Consulta ocultando registros vencidos

Para ocultar regras cuja data final já tenha expirado:

GET /api/approvalSubstitute?hideExpired=true

Nesse caso, não serão retornados registros cuja DateEnd seja anterior à data atual do sistema.

Exemplo conceitual:

Data atual do sistema: 11/08/2026

Regra A:

DateEnd: 10/08/2026

Não será retornada.

Regra B:

DateEnd: 11/08/2026

Será retornada.

Regra C:

DateEnd: 31/12/2026

Será retornada.

Parâmetro hideExpired

Exemplo:

GET /api/approvalSubstitute?hideExpired=true

Registros inativos

O parâmetro hideExpired=true não filtra pelo status Active.

Uma regra com:

{
  "Active": false
}

continua sendo retornada caso sua DateEnd ainda não tenha expirado.

Portanto, o filtro considera a vigência da regra e não seu status de ativação.

Resposta de sucesso

Status esperado

200 OK

Exemplo

[
  {
    "Id": 101,
    "UserApprovalCode": "aprovador.original",
    "UserApprovalName": "Aprovador Original",
    "UserSubstituteCode": "aprovador.substituto",
    "UserSubstituteName": "Aprovador Substituto",
    "DateStart": "2026-08-01T00:00:00",
    "DateEnd": "2026-12-31T00:00:00",
    "Active": true,
    "CreateDate": "2026-08-01T10:00:00",
    "UpdateDate": "2026-08-05T14:30:00",
    "UserName": "usuario.responsavel",
    "Places": [
      1,
      3,
      5
    ]
  }
]

Estrutura da resposta

Campo Places

O campo Places retorna os identificadores dos processos vinculados à regra.

Exemplo:

{
  "Places": [
    1,
    2,
    3,
    4
  ]
}

Cada valor representa um local de aprovação vinculado à configuração do aprovador substituto.

Diferença entre Active e vigência

O status e a vigência representam conceitos diferentes.

Exemplo:

{
  "Active": false,
  "DateEnd": "2026-12-31T00:00:00"
}

Essa regra está inativa, mas ainda não está vencida.

Por isso, utilizando:

GET /api/approvalSubstitute?hideExpired=true

ela continuará aparecendo na resposta.

Já uma regra com:

{
  "Active": true,
  "DateEnd": "2026-08-01T00:00:00"
}

não será retornada se sua DateEnd for anterior à data atual do sistema.

Consulta sem registros

Caso não existam registros cadastrados, a API retorna:

200 OK

Com:

[]

A ausência de aprovadores substitutos não resulta em erro 404 ou 500.

Como utilizar

Para consultar todos os registros:

GET /api/approvalSubstitute

Para consultar apenas registros ainda não vencidos:

GET /api/approvalSubstitute?hideExpired=true

Em ambos os casos, a estrutura dos objetos retornados permanece a mesma.

Comportamento esperado

Pontos de atenção

• hideExpired é um parâmetro opcional.

• Sem o parâmetro, todos os registros são retornados.

• hideExpired=true filtra exclusivamente pela DateEnd.

• O filtro não considera o campo Active.

• Regras inativas ainda vigentes continuam visíveis.

• Regras vencidas são ocultadas quando o filtro estiver habilitado.

• A resposta é sempre um array.

• O endpoint exige autenticação Bearer.

• A consulta por identificador é realizada por outro endpoint: GET /api/approvalSubstitute/{id}.