Objetivo

A API permite criar modelos de aprovação utilizados nos processos do ContractPlus.

Por meio da requisição, é possível definir:

• A empresa em que o modelo será utilizado;
• O local de aprovação;
• A data de início da vigência;
• O tipo de funcionamento do modelo;
• As faixas de valores;
• As consultas condicionais;
• As sequências de aprovação;
• Os usuários aprovadores;
• As configurações adicionais de cada nível.

A API realiza a criação da estrutura completa do modelo de aprovação em uma única operação, incluindo faixas, sequências e aprovadores.

Quando algum elemento da estrutura for inválido, a operação deverá ser rejeitada integralmente, sem manter registros parciais. 

Aplicação da API

A API pode ser utilizada para criar modelos de aprovação relacionados aos locais disponíveis no ContractPlus, como:

• Contrato;
• Medição;
• Aditivo do contrato;
• Cotação de compra;
• Distrato do contrato;
• Documentos da medição;
• Alteração contratual.

O local em que o modelo será aplicado é definido pelo campo placeId.

Endpoint

POST /api/approvalPattern

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, a API deverá retornar:

401 Unauthorized

Nenhum modelo ou registro relacionado deverá ser criado.

Cabeçalhos

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

Estrutura da requisição

Exemplo de modelo com um nível de aprovação

{
  "companyId": 1,
  "placeId": 3,
  "effectiveDate": "2026-08-10",
  "flags": {
    "isAuto": false,
    "hasRange": false,
    "hasQuery": false,
    "hasSeq": true
  },
  "ranges": [
    {
      "description": "Faixa padrão",
      "sequences": [
        {
          "level": 1,
          "name": "Nível de Aprovação Padrão",
          "useSignProvider": false,
          "allowApproveLower": false,
          "users": [
            {
              "userName": "usuario.aprovador"
            }
          ]
        }
      ]
    }
  ]
}

Campos do modelo

Estrutura principal

Os campos companyId e placeId precisam identificar registros válidos.

A ausência desses campos deverá impedir a criação do modelo.

O corpo da requisição também não poderá conter apenas empresa, local e vigência. É necessário informar uma estrutura coerente com o tipo de modelo selecionado, evitando a criação de modelos vazios ou inutilizáveis.

Objeto flags

As flags devem ser coerentes com o conteúdo informado em ranges.

Objeto ranges

Cada item do array representa uma faixa ou condição de aprovação.

Formato do campo query

Quando o modelo de aprovação utilizar consulta, o conteúdo do campo query deverá ser enviado no formato Base64.

A instrução SQL não deve ser enviada diretamente em seu formato original.

Essa codificação é necessária devido a limitações de compatibilidade no envio e processamento de consultas SQL em texto puro, especialmente quando a instrução possuir:

• Aspas simples ou duplas;
• Quebras de linha;
• Caracteres especiais;
• Operadores;
• Parênteses;
• Nomes de campos ou tabelas entre aspas;
• Diferenças de sintaxe entre bancos SQL e SAP HANA.

O servidor deverá receber o conteúdo codificado e realizar o tratamento necessário durante a criação do modelo.

Objeto sequences

Cada item representa um nível da aprovação.

Cada sequência deve possuir ao menos um aprovador.

O mesmo sequenceId não deverá ser repetido dentro da mesma faixa.

Objeto users

O usuário informado precisa existir no cadastro de usuários do SAP Business One.

Quando um usuário inexistente for informado, a criação deverá ser bloqueada.

Exemplo:

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

Tipos de modelo

Modelo com sequência de aprovação

Utilizado quando o documento deverá ser encaminhado a um ou mais aprovadores.

Configuração esperada:

"flags": {
  "hasSeq": true
}

O modelo deverá possuir:

• Ao menos uma faixa ou estrutura de agrupamento;
• Ao menos uma sequência;
• Ao menos um aprovador em cada sequência.

Exemplo:

{
  "companyId": 1,
  "placeId": 1,
  "effectiveDate": "2026-08-10",
  "flags": {
    "hasSeq": true
  },
  "ranges": [
    {
      "description": "Faixa padrão",
      "sequences": [
        {
          "level": 1,
          "name": "Aprovação gerencial",
          "useSignProvider": false,
          "allowApproveLower": false,
          "users": [
            {
              "userName": "usuario.aprovador"
            }
          ]
        }
      ]
    }
  ]
}

Modelo automático

Utilizado quando o documento deverá ser aprovado automaticamente.

{
  "companyId": 1,
  "placeId": 3,
  "effectiveDate": "2026-08-10",
  "flags": {
    "isAuto": true
  },
  "ranges": []
}

Nesse formato, não é necessário informar sequências ou aprovadores.

A criação de modelos automáticos sem faixas e sem sequências foi validada com sucesso. 

Modelo por intervalo de valores

Utilizado quando o comportamento da aprovação depende do valor do documento.

{
  "companyId": 1,
  "placeId": 3,
  "effectiveDate": "2026-08-10",
  "flags": {
    "hasRange": true
  },
  "ranges": [
    {
      "description": "Reprovação automática",
      "approvalRangeTypeId": 2,
      "initialValue": 0,
      "endValue": 4999.99,
      "sequences": []
    },
    {
      "description": "Aprovação automática",
      "approvalRangeTypeId": 1,
      "initialValue": 5000,
      "endValue": 100000,
      "sequences": []
    },
    {
      "description": "Aprovação por sequência",
      "approvalRangeTypeId": 0,
      "initialValue": 100000.01,
      "endValue": 10000000,
      "sequences": [
        {
          "level": 1,
          "name": "Aprovação da diretoria",
          "users": [
            {
              "userName": "usuario.aprovador"
            }
          ]
        }
      ]
    }
  ]
}

Tipos de ação da faixa

Faixa para qualquer valor

Quando anyValue estiver habilitado, a faixa será aplicada independentemente do valor do documento.

{
  "description": "Qualquer valor",
  "anyValue": true
  "sequences": [
    {
      "level": 1,
      "name": "Aprovação padrão",
      "users": [
        {
          "userName": "usuario.aprovador"
        }
      ]
    }
  ]
}

Modelo por consulta

Utilizado quando o fluxo de aprovação depender do resultado de uma consulta.

Configuração esperada:

"flags": {
  "hasQuery": true
}

Codificação obrigatória da consulta

A consulta SQL deverá ser convertida para Base64 antes de ser incluída no campo query.

Exemplo de consulta original:

SELECT CASE
    WHEN T0."result" > 0 THEN 1
    ELSE 0
END AS "result"
FROM (
    SELECT COUNT(T0."Id") AS "result"
    FROM "IV_C1_Contract" T0
    WHERE T0."Id" = @documentId
    AND T0."CardCode" = 'FORN01') T0

A consulta acima deverá ser codificada e enviada como uma string Base64:

{
  "query": "U0VMRUNUIENBU0UgV0hFTiBUMC4icmVzdWx0IiA+IDAgVEhFTiAxIEVMU0UgMCBFTkQgQVMgInJlc3VsdCIuLi4="
}

O valor apresentado é apenas ilustrativo. A string deve ser gerada a partir da consulta completa que será utilizada no modelo.

Exemplo de modelo por consulta

{
  "companyId": 1,
  "placeId": 1,
  "effectiveDate": "2026-08-10",
  "flags": {
    "hasQuery": true
  },
  "ranges": [
    {
      "description": "Fornecedor",
      "approvalByQuery": true,
      "query": "U0VMRUNUIENBU0UgV0hFTiBUMC4icmVzdWx0IiA+IDAgVEhFTiAxIEVMU0UgMCBFTkQgQVMgInJlc3VsdCIuLi4=",
      "contractTypeId": 1,
      "sequences": [
        {
          "level": 1,
          "name": "Aprovação de fornecedor",
          "useSignProvider": false,
          "allowApproveLower": false,
          "users": [
            {
              "userName": "usuario.aprovador"
            }
          ]
        }
      ]
    }
  ]
}

Quando hasQuery ou approvalByQuery estiver habilitado:

• O campo query deverá ser preenchido;
• A consulta deverá estar codificada em Base64;
• Não deverá ser enviada uma instrução SQL em texto puro;
• A string Base64 deverá representar uma consulta válida e compatível com o banco utilizado.
• Não deverá ser enviada a propriedade "contractTypeId" quando o "placeId" for igual a 8 (Distrato)

Caso o campo esteja vazio ou ausente:

{
  "Success": false,
  "PatternId": 0,
  "Message": "Exige que a instrução SQL seja informada"
}

Múltiplos aprovadores no mesmo nível

Uma mesma sequência pode possuir vários usuários aprovadores.

"users": [
  {
    "userName": "aprovador.1"
  },
  {
    "userName": "aprovador.2"
  },
  {
    "userName": "aprovador.3"
  }
]

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

Múltiplas faixas e sequências

O modelo poderá possuir:

• Múltiplas faixas;
• Diferentes tipos de contrato;
• Diferentes consultas em Base64;
• Uma ou mais sequências por faixa;
• Um ou mais aprovadores por sequência.

Cada faixa é avaliada de acordo com sua própria configuração.

{
  "companyId": 1,
  "placeId": 8,
  "effectiveDate": "2026-08-10",
  "flags": {
    "hasQuery": true
  },
  "ranges": [
    {
      "description": "Fornecedor",
      "approvalByQuery": true,
      "query": "U0VMRUNUIENBU0UgV0hFTiBUMC4icmVzdWx0IiA+IDAgVEhFTiAxIEVMU0UgMCBFTkQgQVMgInJlc3VsdCIuLi4=",
      "sequences": [
        {
          "level": 1,
          "name": "Aprovação de fornecedor",
          "users": [
            {
              "userName": "aprovador.fornecedor"
            }
          ]
        }
      ]
    },
    {
      "description": "Cliente",
      "approvalByQuery": true,
      "query": "U0VMRUNUIENBU0UgV0hFTiBUMC4icmVzdWx0IiA+IDAgVEhFTiAxIEVMU0UgMCBFTkQgQVMgInJlc3VsdCIuLi4=",
      "sequences": [
        {
          "level": 1,
          "name": "Aprovação de cliente",
          "users": [
            {
              "userName": "aprovador.cliente"
            }
          ]
        }
      ]
    }
  ]
}

Resposta de sucesso

Status esperado

200 OK

Corpo

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

O PatternId é gerado pelo servidor e pode ser utilizado posteriormente em operações de consulta, edição, exclusão e duplicação.

Validações da API

Empresa, local e vigência obrigatórios

Os campos abaixo são obrigatórios:

{
  "companyId": 1,
  "placeId": 3,
  "effectiveDate": "2026-01-12"
}

A ausência ou invalidade desses campos deverá impedir a criação.

Vigência do modelo

O campo effectiveDate determina o início da vigência.

Para a mesma combinação de empresa e local de aprovação, a nova data não deverá ser anterior à última vigência cadastrada.

O comportamento esperado é bloquear a inclusão e retornar mensagem equivalente a:

Vigência não deve ser menor que a última vigência informada.
Empresa: {{companyId}}
Local de Aprovação: {{placeId}}

Faixa obrigatória

Quando hasRange estiver habilitado, o array ranges deverá possuir ao menos um item.

{
  "Success": false,
  "PatternId": 0,
  "Message": "O modelo exige ao menos uma faixa de aprovação"
}

Sequência obrigatória

Quando hasSeq estiver habilitado, cada faixa configurada para aprovação por sequência deverá possuir ao menos uma sequência.

{
  "Success": false,
  "PatternId": 0,
  "Message": "Cada faixa deve possuir ao menos uma sequência"
}

Aprovador obrigatório

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

{
  "Success": false,
  "PatternId": 0,
  "Message": "Cada sequência deve possuir ao menos um aprovador"
}

Usuário inexistente

O userName deve corresponder a um usuário cadastrado no SAP Business One.

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

Intervalo de valores inválido

initialValue não poderá ser maior que endValue.

{
  "Success": false,
  "PatternId": 0,
  "Message": "O Valor Inicial de uma faixa não pode ser maior que o Valor Final"
}

Consulta obrigatória e codificada

Quando o modelo utilizar consulta:

• query não poderá estar vazio;
• O conteúdo deverá estar em Base64;
• O valor deverá representar uma instrução SQL válida;
• O texto SQL original não deverá ser enviado diretamente.

Exemplo inválido:

{
  "approvalByQuery": true,
  "query": ""
}

Resposta:

{
  "Success": false,
  "PatternId": 0,
  "Message": "Exige que a instrução SQL seja informada"
}

Sequência duplicada

O mesmo sequenceId não deverá ser informado mais de uma vez dentro da mesma faixa.

A criação deverá ser rejeitada sem persistir o modelo.

Tipos de dados inválidos

Campos numéricos, booleanos, datas, objetos e coleções devem respeitar seus respectivos tipos.

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

Estrutura incompleta

A API deverá rejeitar corpos que poderiam criar modelos vazios.

Exemplo inválido:

{
  "companyId": 1,
  "placeId": 3,
  "effectiveDate": "2026-08-10"
}

A operação não deverá retornar sucesso nem persistir qualquer modelo.

Integridade da operação

A criação deve ser transacional.

Caso um erro seja identificado em qualquer parte da estrutura:

• O modelo principal não deverá ser salvo;
• As faixas não deverão ser salvas;
• As sequências não deverão ser salvas;
• Os aprovadores não deverão ser vinculados;
• Nenhum registro parcial deverá permanecer na base.

Por exemplo, se os dados principais estiverem corretos, mas uma sequência não possuir aprovadores, toda a operação deverá ser desfeita.

Pontos de atenção

• companyId, placeId e effectiveDate devem ser válidos.
• A estrutura enviada deve ser coerente com as flags selecionadas.
• Modelos automáticos não exigem faixas, sequências ou aprovadores.
• Quando hasRange estiver habilitado, ao menos uma faixa deve ser informada.
• Quando hasSeq estiver habilitado, cada faixa aplicável deve possuir uma sequência.
• Cada sequência deve possuir ao menos um aprovador.
• Os usuários informados precisam existir no SAP Business One.
• Os usuários não podem ser repetidos dentro do mesmo modelo, independente do nível de aprovação.
• Quando hasQuery estiver habilitado, a consulta deve ser informada.
• Consultas devem ser enviadas obrigatoriamente em formato Base64.
• Consultas SQL em texto puro não devem ser informadas no campo query.
• A codificação Base64 evita problemas de compatibilidade com caracteres, aspas, quebras de linha e sintaxe SQL.
• O valor inicial de uma faixa não pode ser maior que o valor final.
• O mesmo identificador de sequência não deve ser repetido dentro da mesma faixa.
• O servidor é responsável por gerar o PatternId.
• Nenhuma estrutura parcial deve ser persistida em caso de erro.
• A vigência deve respeitar os modelos já cadastrados para a mesma empresa e local.
• O modelo criado pode ser consultado posteriormente na tela Modelo de Aprovação do ContractPlus.