Objetivo

A API permite consultar todos os modelos de aprovação cadastrados no ContractPlus.

O retorno apresenta a estrutura completa de cada modelo, incluindo:

• Empresa;

• Local de aprovação;

• Data de vigência;

• Tipo do modelo;

• Usuário responsável pelo cadastro;

• Faixas de aprovação;

• Sequências;

• Aprovadores;

• Configurações adicionais de cada nível.

A consulta pode ser utilizada para exibir os modelos cadastrados, localizar seus identificadores e fornecer os dados necessários para operações posteriores de edição, exclusão ou duplicação.

Aplicação da API

A API retorna os modelos configurados para os locais de aprovação disponíveis no ContractPlus.

O local ao qual cada modelo pertence é identificado pelos campos PlaceId e PlaceEnum.

Endpoint

GET /api/approvalPattern

Autenticação

A requisição exige um token de autenticação válido.

O token deve ser enviado no cabeçalho:

Authorization: Bearer {{token}}

Quando a requisição for enviada sem autenticação válida, o comportamento esperado é:

401 Unauthorized

Nenhum dado dos modelos de aprovação deverá ser retornado.

Cabeçalhos

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

Como se trata de uma operação de consulta, não é necessário enviar um corpo na requisição.

Parâmetros

O endpoint não utiliza parâmetros de rota, query string ou corpo.

Exemplo:

GET /api/approvalPattern

A resposta contém todos os modelos de aprovação cadastrados e disponíveis para o usuário autenticado.

Como realizar a consulta

1. Utilize o método GET.

2. Informe a URL:

/api/approvalPattern

3. Envie um token Bearer válido no cabeçalho.

4. Execute a requisição.

5. Analise o array retornado.

Não deve ser enviado conteúdo no corpo da requisição.

Observação sobre desempenho: a consulta retorna todos os modelos de aprovação cadastrados, incluindo suas faixas, níveis e aprovadores. Por esse motivo, o tempo de resposta pode variar conforme a quantidade e a complexidade dos modelos existentes na base consultada.

Resposta de sucesso

Status esperado

200 OK

Tipo do retorno

A resposta é um array JSON.

Cada item do array representa um modelo de aprovação cadastrado.

[
  {
    "Id": 2,
    "CompanyId": 1,
    "PlaceId": 3,
    "IsAuto": false,
    "HasRange": false,
    "HasQuery": false,
    "HasSeq": false,
    "EffectiveDate": "2023-09-04T13:57:13.637",
    "UserName": "leandro.melo",
    "PlaceEnum": 3,
    "Ranges": [
      {
        "Id": 2,
        "PatternId": 2,
        "AnyValue": 1,
        "InitialValue": 0.0,
        "EndValue": 0.0,
        "ApprovalLevels": [
          {
            "Id": 2,
            "RangeId": 2,
            "SeqId": 1,
            "UseSignProvider": 0,
            "Name": "Nível de Aprovação Padrão",
            "Approvers": [
              {
                "Id": 6,
                "SequenceId": 2,
                "UserName": "manager",
                "USER_CODE": "manager",
                "U_NAME": "manager"
              }
            ],
            "ApproveLowerSequences": false
          }
        ],
        "ApprovalRangeTypeId": 0,
        "ContractTypeId": 0,
        "ApprovalByQuery": false,
        "ApprovalRangeTypeEnum": 0,
        "ContractTypeEnum": 0
      }
    ]
  }
]

Nos testes, o endpoint retornou status 200, resposta no formato de array e a estrutura completa dos modelos cadastrados.

Estrutura do modelo

Campos principais

Identificador do modelo

O campo Id representa o identificador principal do modelo.

Exemplo:

{
  "Id": 605
}

Esse identificador pode ser utilizado em operações posteriores, como:

• Edição;

• Exclusão;

• Duplicação;

• Consulta de consistência após uma criação ou alteração.

Flags do modelo

Os campos abaixo identificam o tipo de funcionamento do modelo:

Essas flags permitem identificar como a estrutura do modelo foi configurada.

Data de vigência

O campo EffectiveDate apresenta a data e a hora de início da vigência.

Exemplo:

{
  "EffectiveDate": "2023-09-04T13:57:13.637"
}

Quando necessário, a aplicação consumidora poderá formatar o valor para exibir somente a data.

Estrutura de faixas

O array Ranges contém as faixas e condições vinculadas ao modelo.

{
  "Ranges": [
    {
      "Id": 2,
      "PatternId": 2,
      "AnyValue": 1,
      "InitialValue": 0.0,
      "EndValue": 0.0,
      "ApprovalLevels": [],
      "ApprovalRangeTypeId": 0,
      "ContractTypeId": 0,
      "ApprovalByQuery": false,
      "ApprovalRangeTypeEnum": 0,
      "ContractTypeEnum": 0
    }
  ]
}

Campos da faixa

Tipo da faixa

O campo ApprovalRangeTypeId identifica o comportamento configurado para a faixa.

Faixa para qualquer valor

Quando AnyValue indicar que qualquer valor deve ser considerado, os campos InitialValue e EndValue não representam um intervalo restritivo.

Exemplo:

{
  "AnyValue": 1,
  "InitialValue": 0.0,
  "EndValue": 0.0
}

Quando a faixa não for configurada para qualquer valor, os campos inicial e final devem ser utilizados para identificar o intervalo aplicável.

Estrutura dos níveis de aprovação

O array ApprovalLevels contém os níveis ou sequências cadastrados para a faixa.

{
  "ApprovalLevels": [
    {
      "Id": 2,
      "RangeId": 2,
      "SeqId": 1,
      "UseSignProvider": 0,
      "Name": "Nível de Aprovação Padrão",
      "Approvers": [],
      "ApproveLowerSequences": false
    }
  ]
}

Campos do nível

Estrutura dos aprovadores

O array Approvers contém os usuários vinculados ao nível de aprovação.

{
  "Approvers": [
    {
      "Id": 6,
      "SequenceId": 2,
      "UserName": "manager",
      "USER_CODE": "manager",
      "U_NAME": "manager"
    }
  ]
}

Campos do aprovador

Um nível pode possuir um ou vários aprovadores.

Modelos por consulta

Quando o modelo utilizar consulta, o campo:

{
  "HasQuery": true
}

indicará que sua lógica depende de uma instrução SQL.

Na criação e na edição do modelo, a consulta deve ser enviada em Base64, devido às limitações de compatibilidade existentes no envio de consultas em seu formato original.

O relatório de testes utilizado como base não apresenta, no exemplo do GET, um campo contendo o conteúdo da consulta. Por isso, não é possível afirmar por esse material se a consulta será retornada codificada, decodificada ou se não será incluída na resposta.

Consulta sem registros

Quando não existirem modelos cadastrados, o comportamento esperado é:

200 OK

Com um array vazio:

[]

A ausência de registros não deve ser tratada como erro.

Esse cenário consta no relatório como planejado, mas foi marcado como ignorado naquele ciclo de testes. Portanto, o array vazio representa o comportamento esperado da API.

Operação somente leitura

O endpoint realiza apenas uma consulta.

A execução não deve:

• Criar modelos;

• Alterar modelos;

• Excluir faixas;

• Modificar sequências;

• Alterar aprovadores;

• Atualizar datas de vigência;

• Produzir qualquer mudança na base.

Nos testes, o estado anterior e posterior à execução foi comparado, sem identificação de alterações provocadas pelo endpoint.

Consistência dos relacionamentos

Os identificadores retornados devem manter a relação entre as estruturas.

Exemplo:

{
  "Id": 2,
  "Ranges": [
    {
      "PatternId": 2,
      "ApprovalLevels": [
        {
          "RangeId": 2,
          "Approvers": [
            {
              "SequenceId": 2
            }
          ]
        }
      ]
    }
  ]
}

A estrutura deve respeitar os seguintes vínculos:

• Ranges[].PatternId deve corresponder ao modelo relacionado;

• ApprovalLevels[].RangeId deve corresponder à faixa relacionada;

• Approvers[].SequenceId deve corresponder ao nível relacionado.

Essa consistência permite reutilizar os dados retornados em outras operações da API.

Respostas esperadas

O relatório fornecido confirma os cenários de sucesso, estrutura do retorno, consistência e comportamento somente leitura.

Pontos de atenção

• A resposta deve ser tratada como um array.

• Um retorno vazio não representa falha.

• O endpoint não utiliza corpo na requisição.

• O token Bearer é obrigatório.

• O campo Id identifica o modelo e pode ser reutilizado em outros endpoints.

• O campo PlaceId identifica o processo ao qual o modelo pertence.

• Ranges pode conter uma ou várias faixas.

• ApprovalLevels pode conter um ou vários níveis.

• Approvers pode conter um ou vários usuários.

• Os relacionamentos entre modelo, faixa, sequência e aprovador devem ser preservados.

• A consulta não deve alterar nenhuma informação na base.

• As datas são retornadas com data e hora.

• Os nomes das propriedades retornadas utilizam inicial maiúscula, como CompanyId, EffectiveDate e Ranges.

• Modelos que utilizam consulta são identificados por HasQuery.

• O tempo de resposta pode variar conforme a quantidade de modelos de aprovação cadastrados na base.

• Bases com grande volume de faixas, níveis e aprovadores podem exigir mais tempo para concluir a consulta.

• A aplicação consumidora deve considerar esse comportamento ao definir timeout e indicador de carregamento.