Versões

Gerenciamento de versões de decisões no Decision Engine. Cada versão contém um DMN (Decision Model and Notation) que define a lógica da decisão.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	`/api/v1/decisions/:id/versions`	Criar versão	`DECISION_VERSIONS_CREATE`
GET	`/api/v1/decisions/:id/versions`	Listar versões	`DECISION_VERSIONS_READ`
GET	`/api/v1/versions/:id`	Obter versão	`DECISION_VERSIONS_READ`
POST	`/api/v1/versions/:id/publish`	Publicar versão	`DECISION_VERSIONS_PUBLISH`
POST	`/api/v1/versions/:id/archive`	Arquivar versão	`DECISION_VERSIONS_CREATE`
POST	`/api/v1/versions/:id/execute`	Executar versão	`DECISION_EXECUTE`

Ciclo de Vida

Estados da Versão

DRAFT (Rascunho)

Versão em desenvolvimento
Pode ser editada
Não pode ser executada
Transições:
- → PUBLISHED: Chamada de publish() (publicar versão)

PUBLISHED (Publicada)

Versão ativa e pronta para uso
Não pode mais ser editada
Pode ser executada
Torna-se a versão ativa da decisão
Transições:
- → ARCHIVED: Chamada de archive() (arquivar versão)

ARCHIVED (Arquivada)

Versão desativada
Não pode mais ser editada
Não pode ser executada
Mantida para histórico e auditoria
Estado final (não permite mais transições)

Resumo de Permissões

Status	Editável	Executável	Pode Publicar	Pode Arquivar
`DRAFT`	Sim	Não	Sim	Não
`PUBLISHED`	Não	Sim	Não	Sim
`ARCHIVED`	Não	Não	Não	Não

Criar Versão

POST /api/v1/decisions/:decisionId/versions

Cria uma nova versão de uma decisão com conteúdo DMN.

Request

Campo	Tipo	Obrigatório	Descrição
`version`	string	Sim	Número da versão (semver: X.Y.Z)
`content`	string	Sim	Conteúdo DMN XML

Validação do DMN

O conteúdo DMN é validado no momento da criação. Se o XML estiver inválido ou mal-formado, a requisição será rejeitada com erro 400.

Exemplo de DMN Simples

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="https://www.omg.org/spec/DMN/20191111/MODEL/"
             id="credit_decision"
             name="Credit Decision"
             namespace="http://example.com/dmn/credit">

    <decision id="creditDecision" name="Credit Decision">
        <decisionTable id="creditTable" hitPolicy="FIRST">
            <!-- Input: Score do cliente -->
            <input id="scoreInput" label="Score">
                <inputExpression typeRef="number">
                    <text>score</text>
                </inputExpression>
            </input>

            <!-- Output: Resultado -->
            <output id="resultOutput" name="resultado" typeRef="string"/>

            <!-- Regra 1: Score muito baixo = NEGADO -->
            <rule id="rule_denied">
                <description>Score abaixo do mínimo</description>
                <inputEntry><text>&lt; 500</text></inputEntry>
                <outputEntry><text>"NEGADO"</text></outputEntry>
            </rule>

            <!-- Regra 2: Score bom = APROVADO -->
            <rule id="rule_approved">
                <description>Score aceitável</description>
                <inputEntry><text>&gt;= 500</text></inputEntry>
                <outputEntry><text>"APROVADO"</text></outputEntry>
            </rule>
        </decisionTable>
    </decision>

</definitions>

cURL
JavaScript

# Primeiro, leia o DMN de um arquivo
DMN_CONTENT=$(cat minha-decisão.dmn)

curl -X POST 'https://decision-engine.stg.catalisa.app/api/v1/decisions/660e8400-e29b-41d4-a716-446655440001/versions' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d "$(jq -n --arg dmn "$DMN_CONTENT" '{version: "1.0.0", content: $dmn}')"

const decisionId = '660e8400-e29b-41d4-a716-446655440001';

const dmnContent = `<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="https://www.omg.org/spec/DMN/20191111/MODEL/"
             id="credit_decision" name="Credit Decision"
             namespace="http://example.com/dmn/credit">
    <decision id="creditDecision" name="Credit Decision">
        <decisionTable id="creditTable" hitPolicy="FIRST">
            <input id="scoreInput" label="Score">
                <inputExpression typeRef="number"><text>score</text></inputExpression>
            </input>
            <output id="resultOutput" name="resultado" typeRef="string"/>
            <rule id="rule_denied">
                <inputEntry><text>&lt; 500</text></inputEntry>
                <outputEntry><text>"NEGADO"</text></outputEntry>
            </rule>
            <rule id="rule_approved">
                <inputEntry><text>&gt;= 500</text></inputEntry>
                <outputEntry><text>"APROVADO"</text></outputEntry>
            </rule>
        </decisionTable>
    </decision>
</definitions>`;

const response = await fetch(
  `https://decision-engine.stg.catalisa.app/api/v1/decisions/${decisionId}/versions`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      version: '1.0.0',
      content: dmnContent,
    }),
  }
);

const version = await response.json();

Response (201 Created)

{
  "data": {
    "type": "decision-versions",
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "attributes": {
      "decisionId": "660e8400-e29b-41d4-a716-446655440001",
      "version": "1.0.0",
      "status": "DRAFT",
      "publishedAt": null,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    "links": {
      "self": "/api/v1/versions/770e8400-e29b-41d4-a716-446655440002"
    }
  }
}

Listar Versões

GET /api/v1/decisions/:decisionId/versions

Lista versões de uma decisão.

Query Parameters

Parâmetro	Tipo	Descrição
`page[number]`	integer	Número da página
`page[size]`	integer	Itens por página
`filter[status]`	string	Filtrar por status

cURL
JavaScript

curl 'https://decision-engine.stg.catalisa.app/api/v1/decisions/660e8400-e29b-41d4-a716-446655440001/versions?filter[status]=PUBLISHED' \
  -H 'Authorization: Bearer SEU_TOKEN'

const decisionId = '660e8400-e29b-41d4-a716-446655440001';

const params = new URLSearchParams({
  'filter[status]': 'PUBLISHED',
});

const response = await fetch(
  `https://decision-engine.stg.catalisa.app/api/v1/decisions/${decisionId}/versions?${params}`,
  {
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  }
);

const { data, meta } = await response.json();

Response (200 OK)

{
  "data": [
    {
      "type": "decision-versions",
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "attributes": {
        "decisionId": "660e8400-e29b-41d4-a716-446655440001",
        "version": "1.0.0",
        "status": "PUBLISHED",
        "publishedAt": "2024-01-15T11:00:00Z",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T11:00:00Z"
      }
    }
  ],
  "meta": {
    "total": 3,
    "pageNumber": 1,
    "pageSize": 20,
    "totalPages": 1
  }
}

Obter Versão

GET /api/v1/versions/:versionId

Obtém detalhes de uma versão específica, incluindo o conteúdo DMN.

cURL
JavaScript

curl 'https://decision-engine.stg.catalisa.app/api/v1/versions/770e8400-e29b-41d4-a716-446655440002' \
  -H 'Authorization: Bearer SEU_TOKEN'

const versionId = '770e8400-e29b-41d4-a716-446655440002';

const response = await fetch(
  `https://decision-engine.stg.catalisa.app/api/v1/versions/${versionId}`,
  {
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  }
);

const version = await response.json();

Response (200 OK)

{
  "data": {
    "type": "decision-versions",
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "attributes": {
      "decisionId": "660e8400-e29b-41d4-a716-446655440001",
      "version": "1.0.0",
      "status": "PUBLISHED",
      "publishedAt": "2024-01-15T11:00:00Z",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T11:00:00Z"
    },
    "links": {
      "self": "/api/v1/versions/770e8400-e29b-41d4-a716-446655440002"
    }
  },
  "content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<definitions ...>...</definitions>",
  "links": {
    "self": "/api/v1/versions/770e8400-e29b-41d4-a716-446655440002"
  }
}

Publicar Versão

POST /api/v1/versions/:versionId/publish

Publica uma versão em DRAFT, tornando-a executável.

informação

Ao publicar uma nova versão, ela se torna a versão ativa da decisão. Versões anteriores podem ser arquivadas.

cURL
JavaScript

curl -X POST 'https://decision-engine.stg.catalisa.app/api/v1/versions/770e8400-e29b-41d4-a716-446655440002/publish' \
  -H 'Authorization: Bearer SEU_TOKEN'

const versionId = '770e8400-e29b-41d4-a716-446655440002';

const response = await fetch(
  `https://decision-engine.stg.catalisa.app/api/v1/versions/${versionId}/publish`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  }
);

const version = await response.json();

Response (200 OK)

{
  "data": {
    "type": "decision-versions",
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "attributes": {
      "decisionId": "660e8400-e29b-41d4-a716-446655440001",
      "version": "1.0.0",
      "status": "PUBLISHED",
      "publishedAt": "2024-01-15T11:00:00Z",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T11:00:00Z"
    }
  }
}

Arquivar Versão

POST /api/v1/versions/:versionId/archive

Arquiva uma versão publicada.

cURL
JavaScript

curl -X POST 'https://decision-engine.stg.catalisa.app/api/v1/versions/770e8400-e29b-41d4-a716-446655440002/archive' \
  -H 'Authorization: Bearer SEU_TOKEN'

const versionId = '770e8400-e29b-41d4-a716-446655440002';

const response = await fetch(
  `https://decision-engine.stg.catalisa.app/api/v1/versions/${versionId}/archive`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  }
);

const version = await response.json();

Executar Versão Específica

POST /api/v1/versions/:versionId/execute

Executa uma versão específica (deve estar PUBLISHED).

cURL
JavaScript

curl -X POST 'https://decision-engine.stg.catalisa.app/api/v1/versions/770e8400-e29b-41d4-a716-446655440002/execute' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "input": {
      "score": 720
    }
  }'

const versionId = '770e8400-e29b-41d4-a716-446655440002';

const response = await fetch(
  `https://decision-engine.stg.catalisa.app/api/v1/versions/${versionId}/execute`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      input: {
        score: 720,
      },
    }),
  }
);

const result = await response.json();

Response (200 OK)

{
  "output": "APROVADO",
  "trace": [
    {
      "decisionId": "creditDecision",
      "decisionName": "Credit Decision",
      "outcome": "APROVADO",
      "rulesEvaluated": [
        {
          "ruleId": "rule_denied",
          "triggered": false,
          "conditions": ["score: 720"],
          "outcome": null
        },
        {
          "ruleId": "rule_approved",
          "triggered": true,
          "conditions": ["score: 720"],
          "outcome": "APROVADO"
        }
      ]
    }
  ],
  "executionTimeMs": 42
}

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION`	Versão inválida (não semver) ou DMN inválido
404	`NOT_FOUND`	Versão ou decisão não encontrada
409	`CONFLICT`	Versão já existe ou não pode ser publicada

Endpoints​

Ciclo de Vida​

Estados da Versão​

Resumo de Permissões​

Criar Versão​

Request​

Exemplo de DMN Simples​

Response (201 Created)​

Listar Versões​

Query Parameters​

Response (200 OK)​

Obter Versão​

Response (200 OK)​

Publicar Versão​

Response (200 OK)​

Arquivar Versão​

Executar Versão Específica​

Response (200 OK)​

Erros Comuns​

Endpoints

Ciclo de Vida

Estados da Versão

Resumo de Permissões

Criar Versão

Request

Exemplo de DMN Simples

Response (201 Created)

Listar Versões

Query Parameters

Response (200 OK)

Obter Versão

Response (200 OK)

Publicar Versão

Response (200 OK)

Arquivar Versão

Executar Versão Específica

Response (200 OK)

Erros Comuns