Objetivo

A API permite cadastrar uma ou mais sequências de aprovação para os processos de Adiantamento de Pagamento e Retenção Técnica.

Em uma única requisição, é possível definir:

• O local de aprovação;

• A ordem funcional das sequências;

• O nome de cada nível;

• Um ou mais usuários aprovadores por sequência.

A criação é realizada de forma transacional. Caso qualquer sequência ou usuário informado seja inválido, nenhuma parte do payload deverá ser persistida.

Aplicação da API

A API é aplicável exclusivamente aos seguintes locais de aprovação:

Outros valores de placeId não são aderentes ao cadastro de sequências de aprovação.

Endpoint

POST /api/ApprovalSequence

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, a API deverá bloquear o processamento e nenhum registro deverá ser criado.

Cabeçalhos

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

Estrutura da requisição

Exemplo para Adiantamento de Pagamento

{
  "placeId": 2,
  "sequences": [
    {
      "seqId": 1,
      "name": "Adiantamento Nível 1",
      "users": [
        {
          "userName": "usuario.aprovador.1"
        }
      ]
    },
    {
      "seqId": 2,
      "name": "Adiantamento Nível 2",
      "users": [
        {
          "userName": "usuario.aprovador.2"
        }
      ]
    }
  ]
}

Exemplo para Retenção Técnica

{
  "placeId": 4,
  "sequences": [
    {
      "seqId": 1,
      "name": "Retenção Nível 1",
      "users": [
        {
          "userName": "usuario.aprovador.1"
        }
      ]
    },
    {
      "seqId": 2,
      "name": "Retenção Nível 2",
      "users": [
        {
          "userName": "usuario.aprovador.2"
        }
      ]
    }
  ]
}

Os dois locais foram validados com sucesso, incluindo a gravação das sequências e o vínculo dos respectivos usuários aprovadores.

Campos da requisição

Estrutura principal

Campo placeId

Somente os valores abaixo são aceitos:

Quando o campo não for informado ou possuir um valor não aderente, a operação deverá ser bloqueada.

Exemplo de retorno:

{
  "Success": false,
  "SequenceIds": [],
  "Message": "Local de Aprovação Inválido."
}

A ausência do placeId foi validada sem persistência de sequências ou usuários.

Objeto sequences

Cada item do array representa um nível do fluxo de aprovação.

Campo seqId

O campo seqId define a ordem lógica do fluxo de aprovação.

Exemplo:

A ordem em que os objetos aparecem no JSON não altera a ordem funcional. O processamento considera o valor informado em seqId.

Por exemplo, o payload pode enviar os níveis na ordem 3, 2, 1 e 4, mas o fluxo continuará obedecendo à ordem numérica definida pelos respectivos seqId..

O mesmo seqId não pode ser repetido dentro do mesmo placeId.

Campo name

O campo name identifica o nível de aprovação.

Exemplos:

{
  "seqId": 1,
  "name": "Adiantamento Nível 1"
}

{
  "seqId": 2,
  "name": "Retenção Nível 2"
}

O nome deve permitir que o nível seja identificado de forma clara durante a configuração e utilização do fluxo.

Objeto users

O array users contém os aprovadores vinculados à sequência.

Cada sequência deve possuir pelo menos um usuário e o usuário não poderá ser repedito dentro da mesma sequencia.

Inclusão de múltiplas sequências

A API permite cadastrar várias sequências para o mesmo local em uma única operação.

Exemplo:

{
  "placeId": 2,
  "sequences": [
    {
      "seqId": 1,
      "name": "Adiantamento Nível 1",
      "users": [
        {
          "userName": "aprovador.1"
        }
      ]
    },
    {
      "seqId": 2,
      "name": "Adiantamento Nível 2",
      "users": [
        {
          "userName": "aprovador.2"
        }
      ]
    },
    {
      "seqId": 3,
      "name": "Adiantamento Nível 3",
      "users": [
        {
          "userName": "aprovador.3"
        }
      ]
    }
  ]
}

Todas as sequências são vinculadas ao mesmo placeId, mas cada uma recebe um identificador interno próprio.

Inclusão de múltiplos usuários na mesma sequência

Uma sequência pode possuir mais de um aprovador.

Exemplo:

{
  "placeId": 2,
  "sequences": [
    {
      "seqId": 1,
      "name": "Adiantamento Nível 1",
      "users": [
        {
          "userName": "aprovador.1"
        },
        {
          "userName": "aprovador.2"
        },
        {
          "userName": "aprovador.3"
        }
      ]
    }
  ]
}

Todos os usuários serão vinculados ao mesmo nível de aprovação.

Resposta de sucesso

Status esperado

200 OK

Exemplo

{
  "Success": true,
  "SequenceIds": [
    24,
    25
  ],
  "Message": "Sequência de aprovação cadastrada com sucesso."
}

Campos da resposta

A quantidade de identificadores retornados em SequenceIds corresponde à quantidade de sequências criadas.

Validações da API

Lista de sequências vazia

O array sequences deve conter ao menos uma sequência.

Exemplo inválido:

{
  "placeId": 2,
  "sequences": []
}

Retorno:

{
  "Success": false,
  "SequenceIds": [],
  "Message": "Informe ao menos uma sequência de aprovação."
}

Nenhum registro será persistido.

Sequência sem usuários

Cada sequência deve conter ao menos um aprovador.

Exemplo inválido:

{
  "placeId": 2,
  "sequences": [
    {
      "seqId": 1,
      "name": "Adiantamento Nível 1",
      "users": []
    }
  ]
}

Retorno esperado:

{
  "Success": false,
  "SequenceIds": [],
  "Message": "Cada sequência de aprovação deve conter ao menos um usuário aprovador."
}

A sequência não será criada.

Usuário inexistente

Cada userName deve corresponder a um usuário existente na base.

Exemplo inválido:

{
  "placeId": 2,
  "sequences": [
    {
      "seqId": 1,
      "name": "Adiantamento Nível 1",
      "users": [
        {
          "userName": "qa.inexistente"
        }
      ]
    }
  ]
}

Retorno:

{
  "Success": false,
  "SequenceIds": [],
  "Message": "Usuário qa.inexistente não encontrado na base."
}

Nenhuma sequência ou vínculo de usuário deverá ser persistido.

seqId duplicado

O mesmo código de sequência não pode ser repetido dentro do mesmo local de aprovação.

Exemplo inválido:

{
  "placeId": 2,
  "sequences": [
    {
      "seqId": 1,
      "name": "Adiantamento Nível 1",
      "users": [
        {
          "userName": "aprovador.1"
        }
      ]
    },
    {
      "seqId": 1,
      "name": "Adiantamento Nível 2",
      "users": [
        {
          "userName": "aprovador.2"
        }
      ]
    }
  ]
}

A API deverá rejeitar toda a requisição e retornar SequenceIds vazio.

Usuário duplicado na mesma sequência

O mesmo usuário não pode ser informado mais de uma vez dentro do mesmo nível.

Exemplo inválido:

{
  "placeId": 2,
  "sequences": [
    {
      "seqId": 1,
      "name": "Adiantamento Nível 1",
      "users": [
        {
          "userName": "aprovador.1"
        },
        {
          "userName": "aprovador.1"
        }
      ]
    }
  ]
}

Retorno esperado:

{
  "Success": false,
  "SequenceIds": [],
  "Message": "O mesmo usuário não pode ser informado mais de uma vez na mesma sequência."
}

Nenhum registro do payload deverá ser criado.

Integridade da operação

A criação das sequências e de seus usuários é realizada como uma única operação.

Caso seja encontrado qualquer erro:

• Nenhuma sequência deverá ser criada;

• Nenhum usuário deverá ser vinculado;

• Nenhum item válido do mesmo payload deverá permanecer salvo;

• SequenceIds deverá ser retornado vazio;

• A estrutura anterior da base deverá permanecer inalterada.

Por exemplo, quando uma requisição possuir uma sequência válida e outra sequência inválida, a sequência válida também não deverá ser mantida.

Como utilizar

1. Defina o local de aprovação:

   • 2 para Adiantamento de Pagamento;

   • 4 para Retenção Técnica.

2. Monte a lista de sequências.

3. Informe um seqId exclusivo para cada nível.

4. Informe um nome para cada sequência.

5. Adicione ao menos um usuário válido em cada nível.

6. Envie a requisição para:

POST /api/ApprovalSequence

7. Utilize os identificadores retornados em SequenceIds para futuras operações de alteração ou exclusão.

Respostas esperadas

Pontos de atenção

• Apenas os placeId 2 e 4 são aderentes.

• O seqId define a ordem funcional do fluxo.

• A ordem dos objetos no JSON não substitui a ordem definida pelo seqId.

• O mesmo seqId não pode ser repetido no mesmo local.

• Cada sequência deve possuir ao menos um usuário.

• Uma sequência pode possuir vários aprovadores.

• O mesmo usuário não pode ser repetido dentro da mesma sequência.

• Todos os usuários devem existir na base.

• A API permite criar várias sequências em uma única chamada.

• A operação é transacional.

• Em caso de erro, nenhum registro parcial deverá permanecer.

• Os identificadores internos criados são retornados em SequenceIds.

• O endpoint exige autenticação Bearer.