Objetivo

A API permite duplicar um modelo de aprovação existente no ContractPlus, criando um novo modelo a partir da estrutura do registro de origem.

A duplicação preserva as configurações do modelo original, incluindo:

• Tipo do modelo;
• Faixas de aprovação;
• Intervalos de valores;
• Consultas condicionais;
• Sequências;
• Níveis de aprovação;
• Aprovadores;
• Configurações adicionais de cada nível.

O novo modelo recebe um identificador próprio e uma nova data de vigência. O modelo utilizado como origem permanece inalterado após a operação. 

Aplicação da API

A API pode ser utilizada quando for necessário reaproveitar uma configuração de aprovação já existente sem reconstruir manualmente toda a estrutura.

Alguns exemplos de utilização são:

• Criar uma nova vigência com base em um modelo anterior;
• Reaproveitar faixas, sequências e aprovadores;
• Replicar uma estrutura complexa de aprovação;
• Manter o modelo original disponível para consulta e histórico;
• Criar diferentes modelos derivados de uma mesma origem.

O modelo duplicado mantém o local e a empresa associados ao modelo de origem. A nova vigência é definida no corpo da requisição.

Locais de aprovação

Os modelos podem estar vinculados aos seguintes locais:

Endpoint

POST /api/approvalPattern/duplicate

Autenticação

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

Authorization: Bearer {{token}}

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

401 Unauthorized

Nenhum modelo deverá ser duplicado.

Cabeçalhos

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

Estrutura da requisição

Exemplo

{
  "sourcePatternId": 605,
  "effectiveDate": "2026-08-20"
}

Campos da requisição

O campo sourcePatternId deve corresponder a um modelo de aprovação existente.

O campo effectiveDate deve possuir uma data válida e não pode gerar conflito com outro modelo cadastrado para a mesma empresa, local de aprovação e vigência.

Como utilizar

1. Consulte os modelos cadastrados por meio do endpoint:

GET /api/approvalPattern

2. Localize o campo Id do modelo que será utilizado como origem.
3. Defina uma nova data de vigência que ainda não esteja cadastrada para a mesma empresa e local.
4. Monte o corpo da requisição:

{
  "sourcePatternId": "{{sourcePatternId}}",
  "effectiveDate": "{{effectiveDate}}"
}

5. Envie a requisição:

POST /api/approvalPattern/duplicate

6. Utilize o PatternId retornado para identificar o novo modelo.
7. Quando necessário, consulte novamente os modelos para verificar a estrutura duplicada.

Comportamento da duplicação

Criação de um novo modelo

A operação cria um novo modelo de aprovação com identificador diferente do modelo de origem.

Exemplo:

{
  "Success": true,
  "PatternId": 625,
  "Message": "Modelo de aprovação criado com sucesso"
}

O campo PatternId corresponde ao identificador do novo modelo.

A API não reutiliza o identificador do modelo de origem. Esse comportamento permite manter os dois modelos independentes na base. 

Preservação do modelo de origem

A duplicação não altera o modelo utilizado como origem.

Após a operação, devem permanecer preservados no modelo original:

• Empresa;
• Local de aprovação;
• Data de vigência;
• Flags de configuração;
• Faixas;
• Sequências;
• Aprovadores;
• Consultas;
• Demais configurações relacionadas.

Somente o novo modelo recebe a nova vigência e o novo identificador. 

Preservação da estrutura hierárquica

Quando o modelo de origem possuir uma estrutura completa, a duplicação deverá copiar todos os níveis relacionados.

A estrutura copiada pode incluir:

1. O modelo principal;
2. As faixas de aprovação;
3. Os intervalos de valores;
4. As consultas condicionais;
5. Os níveis ou sequências;
6. Os aprovadores de cada sequência;
7. As configurações adicionais dos níveis.

Os novos registros deverão ficar vinculados ao novo PatternId.

Nenhum registro do modelo duplicado deverá continuar dependente dos identificadores internos do modelo de origem. 

Duplicação de modelos por sequência

Quando o modelo original utilizar sequência de aprovação, o novo modelo manterá:

• A quantidade de sequências;
• A ordem dos níveis;
• A descrição de cada nível;
• Os usuários aprovadores;
• A configuração de aprovação de sequências inferiores;
• A utilização de provedor de assinatura, quando aplicável.

Exemplo de estrutura preservada:

{
  "flags": {
    "isAuto": false,
    "hasRange": false,
    "hasQuery": false,
    "hasSeq": true
  },
  "ranges": [
    {
      "sequences": [
        {
          "level": 1,
          "name": "Aprovação gerencial",
          "users": [
            {
              "userName": "usuario.aprovador"
            }
          ]
        }
      ]
    }
  ]
}

Essa estrutura não precisa ser reenviada no corpo da duplicação. A API a obtém diretamente do modelo informado em sourcePatternId.

Duplicação de modelos automáticos

Quando o modelo original estiver configurado como automático, o novo modelo também será criado como automático.

Nesse caso, serão preservadas as flags correspondentes:

{
  "isAuto": true,
  "hasRange": false,
  "hasQuery": false,
  "hasSeq": false
}

Como o modelo automático não depende de faixas, sequências ou aprovadores, a duplicação preservará apenas sua configuração principal e criará a nova vigência.

Duplicação de modelos por intervalo de valores

Quando o modelo original possuir intervalos de valores, o novo modelo manterá:

• Valores iniciais;
• Valores finais;
• Configuração de qualquer valor;
• Tipo de ação de cada faixa;
• Sequências vinculadas às faixas;
• Aprovadores relacionados.

Os tipos de comportamento das faixas também são preservados:

Duplicação de modelos por consulta

Quando o modelo original utilizar consulta, o novo modelo deverá manter as consultas e condições relacionadas às faixas.

As consultas utilizadas pelos modelos de aprovação são armazenadas em Base64, devido às limitações de compatibilidade com instruções SQL em seu formato original.

A duplicação não exige que a consulta seja enviada novamente no payload. A API copia o conteúdo existente no modelo de origem.

Após a operação, o modelo duplicado deverá manter:

• HasQuery habilitado;
• As faixas configuradas por consulta;
• O tipo de contrato de cada condição;
• A consulta codificada;
• As sequências e os aprovadores associados.

Nova vigência

O campo effectiveDate define a data de início do novo modelo.

Exemplo:

{
  "sourcePatternId": 605,
  "effectiveDate": "2026-08-20"
}

A data deve respeitar as regras de vigência aplicáveis à empresa e ao local de aprovação do modelo de origem.

A duplicação não poderá criar dois modelos com a mesma combinação de:

• Empresa;
• Local de aprovação;
• Data de vigência.

Bloqueio de vigência duplicada

Quando já existir um modelo com a mesma empresa, local e data informada, a operação será bloqueada.

Exemplo de retorno:

{
  "Success": false,
  "PatternId": 0,
  "Message": "Já existe um modelo para esta Filial, Local e Data"
}

Nesse caso:

• Nenhum novo modelo será criado;
• O modelo de origem permanecerá inalterado;
• Nenhuma faixa será duplicada;
• Nenhuma sequência será duplicada;
• Nenhum aprovador será duplicado.

Esse bloqueio foi validado nos testes do endpoint. 

Modelo de origem inexistente

Quando sourcePatternId não corresponder a um modelo cadastrado, a duplicação será rejeitada.

Exemplo:

{
  "sourcePatternId": 999999999,
  "effectiveDate": "2026-08-20"
}

Resposta:

{
  "Success": false,
  "PatternId": 0,
  "Message": "Modelo de Aprovação não encontrado"
}

Nenhuma estrutura deverá ser criada. 

Campos obrigatórios

Os campos sourcePatternId e effectiveDate são obrigatórios.

Exemplo de estrutura incompleta:

{
  "effectiveDate": "2026-08-20"
}

Como o modelo de origem não foi informado, a operação deverá ser bloqueada.

Nenhum modelo duplicado deverá ser persistido.

Tipos de dados inválidos

Os campos devem respeitar os tipos definidos pela API.

Exemplo inválido:

{
  "sourcePatternId": "abc",
  "effectiveDate": "2026-08-20"
}

Resposta esperada:

{
  "Success": false,
  "PatternId": 0,
  "Message": "A estrutura de dados informada está incorreta, valide-a e tente novamente"
}

Nenhuma estrutura parcial deverá ser criada. 

Resposta de sucesso

Status esperado

200 OK

Corpo da resposta

{
  "Success": true,
  "PatternId": 625,
  "Message": "Modelo de aprovação criado com sucesso"
}

Chamadas sucessivas para vigências diferentes geram identificadores distintos. Nos testes, duas duplicações válidas retornaram os modelos 625 e 626. 

Chamadas repetidas

O mesmo modelo de origem pode ser utilizado em mais de uma duplicação.

Para isso, cada chamada deverá informar uma data de vigência válida e sem conflito.

Exemplo da primeira chamada:

{
  "sourcePatternId": 605,
  "effectiveDate": "2026-08-20"
}

Exemplo da segunda chamada:

{
  "sourcePatternId": 605,
  "effectiveDate": "2026-08-21"
}

Cada operação gera um novo PatternId, mantendo os modelos independentes.

Quando a mesma vigência for repetida para a mesma empresa e local, a segunda operação será bloqueada por duplicidade.

Integridade da operação

A duplicação deve ser realizada de forma transacional.

Caso ocorra uma falha durante a cópia:

• O novo modelo não deverá permanecer parcialmente criado;
• As faixas não deverão ser copiadas isoladamente;
• As sequências não deverão permanecer sem faixa;
• Os aprovadores não deverão permanecer sem sequência;
• O modelo de origem não deverá sofrer alterações.

A operação deve ser concluída integralmente ou desfeita por completo.

O cenário de falha controlada durante a cópia da estrutura estava previsto no relatório, mas foi marcado como ignorado naquele ciclo. Portanto, a integridade transacional representa o comportamento esperado da API. 

Respostas esperadas

Pontos de atenção

• O modelo informado em sourcePatternId deve existir.
• A nova vigência deve ser válida e superior a data de vigência do ultimo modelo.
• A mesma empresa, local e data não podem possuir mais de um modelo.
• O modelo duplicado recebe um novo PatternId.
• O modelo de origem permanece inalterado.
• Toda a estrutura hierárquica do modelo é preservada.
• Faixas, sequências e aprovadores são copiados automaticamente.
• Não é necessário enviar a estrutura completa no corpo da requisição.
• Consultas condicionais existentes no modelo de origem também são copiadas.
• As consultas permanecem armazenadas no formato Base64.
• O endpoint exige autenticação Bearer.
• Nenhuma estrutura parcial deverá permanecer quando ocorrer erro.
• O mesmo modelo pode ser duplicado várias vezes, desde que cada destino possua uma vigência sem conflito.
• O tempo de resposta pode variar conforme a quantidade de faixas, sequências, aprovadores e consultas presentes no modelo de origem.