Execuções

Execução de decisões orquestradas pela plataforma com suporte a modos síncrono e assíncrono.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	`/api/v1/decision-platform/execute`	Executar decisão	`DECISIONS_EXECUTE`
GET	`/api/v1/decision-platform/executions`	Listar execuções	`DECISIONS_READ`
GET	`/api/v1/decision-platform/executions/:id`	Obter execução	`DECISIONS_READ`
GET	`/api/v1/decision-platform/executions/:id/status`	Obter status (leve)	`DECISIONS_READ`

Atributos da Execução

Campo	Tipo	Descrição
`configId`	string (UUID)	ID da configuração
`versionId`	string (UUID)	ID da versão usada
`mode`	enum	Modo: `SYNC`, `ASYNC`
`status`	enum	Status da execução
`input`	object	Input original enviado
`mergedInput`	object	Input após merge com data sources
`output`	object	Resultado da decisão
`error`	string	Mensagem de erro (se houver)
`timing`	object	Métricas de tempo
`callbackUrl`	string	URL do callback (async)
`callbackDeliveredAt`	datetime	Quando o callback foi entregue
`callbackAttempts`	number	Tentativas de callback
`traceId`	string	ID para correlação
`executedBy`	string	ID do usuário
`startedAt`	datetime	Início da execução
`completedAt`	datetime	Fim da execução
`createdAt`	datetime	Data de criação

Status da Execução

Status	Descrição
`PENDING`	Aguardando início
`RUNNING`	Em execução
`COMPLETED`	Finalizada com sucesso
`FAILED`	Falhou
`TIMEOUT`	Timeout excedido
`CANCELLED`	Cancelada

Modos de Execução

Modo	Descrição
`SYNC`	Síncrono - aguarda resultado na resposta
`ASYNC`	Assíncrono - retorna imediatamente, resultado via callback

Executar Decisão (Síncrono)

POST /api/v1/decision-platform/execute

Executa uma decisão e aguarda o resultado.

Atributos

Campo	Tipo	Obrigatório	Descrição
`configKey`	string	Sim	Chave da configuração
`versionId`	string	Não	Versão específica (default: última publicada)
`mode`	enum	Não	Modo de execução (default: `SYNC`)
`input`	object	Não	Dados de entrada para a decisão
`timeoutMs`	number	Não	Timeout em ms (override)
`traceId`	string	Não	ID para correlação/rastreamento

cURL
JavaScript

curl -X POST 'https://decision-platform.stg.catalisa.app/api/v1/decision-platform/execute' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "configKey": "credit-analysis",
    "mode": "SYNC",
    "input": {
      "cpf": "12345678900",
      "requestedAmount": 50000,
      "income": 15000
    },
    "traceId": "req-12345"
  }'

const response = await fetch('https://decision-platform.stg.catalisa.app/api/v1/decision-platform/execute', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    configKey: 'credit-analysis',
    mode: 'SYNC',
    input: {
      cpf: '12345678900',
      requestedAmount: 50000,
      income: 15000,
    },
    traceId: 'req-12345',
  }),
});

const { data } = await response.json();
console.log(`Decisão: ${data.attributes.output.decision}`);
console.log(`Tempo total: ${data.attributes.timing.totalMs}ms`);

Response (200 OK)

{
  "data": {
    "type": "platform-execution",
    "id": "550e8400-e29b-41d4-a716-446655440100",
    "attributes": {
      "status": "COMPLETED",
      "mode": "SYNC",
      "output": {
        "decision": "APPROVED",
        "maxAmount": 45000,
        "interestRate": 1.5,
        "riskLevel": "MEDIUM"
      },
      "timing": {
        "totalMs": 245,
        "dataFetchMs": 180,
        "dmnExecutionMs": 65
      }
    }
  },
  "links": {
    "self": "/api/v1/executions/550e8400-e29b-41d4-a716-446655440100"
  }
}

Executar Decisão (Assíncrono)

Executa uma decisão de forma assíncrona. O resultado é enviado via callback.

cURL
JavaScript

curl -X POST 'https://decision-platform.stg.catalisa.app/api/v1/decision-platform/execute' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "configKey": "credit-analysis",
    "mode": "ASYNC",
    "input": {
      "cpf": "12345678900",
      "requestedAmount": 50000
    },
    "callbackUrl": "https://api.empresa.com/webhooks/decision-result",
    "callbackHeaders": {
      "X-API-Key": "secret-key"
    },
    "traceId": "req-12345"
  }'

const response = await fetch('https://decision-platform.stg.catalisa.app/api/v1/decision-platform/execute', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    configKey: 'credit-analysis',
    mode: 'ASYNC',
    input: {
      cpf: '12345678900',
      requestedAmount: 50000,
    },
    callbackUrl: 'https://api.empresa.com/webhooks/decision-result',
    callbackHeaders: {
      'X-API-Key': 'secret-key',
    },
    traceId: 'req-12345',
  }),
});

const { data } = await response.json();
console.log(`Execution ID: ${data.id}`);
console.log(`Status: ${data.attributes.status}`); // PENDING

Response (202 Accepted)

{
  "data": {
    "type": "platform-execution",
    "id": "550e8400-e29b-41d4-a716-446655440100",
    "attributes": {
      "status": "PENDING",
      "mode": "ASYNC",
      "callbackUrl": "https://api.empresa.com/webhooks/decision-result",
      "traceId": "req-12345"
    }
  },
  "links": {
    "self": "/api/v1/executions/550e8400-e29b-41d4-a716-446655440100"
  }
}

Callback Payload

Quando a execução termina, um POST é enviado para o callbackUrl:

{
  "type": "platform-execution-callback",
  "executionId": "550e8400-e29b-41d4-a716-446655440100",
  "traceId": "req-12345",
  "status": "COMPLETED",
  "output": {
    "decision": "APPROVED",
    "maxAmount": 45000
  },
  "timing": {
    "totalMs": 245
  },
  "completedAt": "2024-01-15T10:30:00.245Z"
}

Listar Execuções

GET /api/v1/decision-platform/executions

Lista execuções com suporte a filtros.

Query Parameters

Parâmetro	Tipo	Descrição
`page[number]`	integer	Número da página
`page[size]`	integer	Itens por página
`filter[configId]`	UUID	Filtrar por configuração
`filter[versionId]`	UUID	Filtrar por versão
`filter[status]`	enum	Filtrar por status
`filter[mode]`	enum	Filtrar por modo
`filter[from]`	datetime	Data inicial
`filter[to]`	datetime	Data final

cURL
JavaScript

curl 'https://decision-platform.stg.catalisa.app/api/v1/decision-platform/executions?filter[status]=COMPLETED&filter[from]=2024-01-01T00:00:00Z' \
  -H 'Authorization: Bearer SEU_TOKEN'

const params = new URLSearchParams({
  'filter[status]': 'COMPLETED',
  'filter[from]': '2024-01-01T00:00:00Z',
  'page[size]': '50',
});

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

const { data, meta } = await response.json();
console.log(`Total de execuções: ${meta.totalItems}`);

Obter Status da Execução

GET /api/v1/decision-platform/executions/:id/status

Endpoint leve para verificar apenas o status de uma execução assíncrona.

cURL
JavaScript

curl 'https://decision-platform.stg.catalisa.app/api/v1/decision-platform/executions/550e8400-e29b-41d4-a716-446655440100/status' \
  -H 'Authorization: Bearer SEU_TOKEN'

const executionId = '550e8400-e29b-41d4-a716-446655440100';

// Polling para verificar status
async function waitForCompletion(executionId, maxAttempts = 30) {
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://decision-platform.stg.catalisa.app/api/v1/decision-platform/executions/${executionId}/status`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    );

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

    if (data.attributes.status === 'COMPLETED') {
      return data;
    }

    if (['FAILED', 'TIMEOUT', 'CANCELLED'].includes(data.attributes.status)) {
      throw new Error(`Execution ${data.attributes.status}: ${data.attributes.error}`);
    }

    await new Promise(r => setTimeout(r, 1000)); // Wait 1s
  }

  throw new Error('Timeout waiting for execution');
}

Response (200 OK)

{
  "data": {
    "type": "platform-execution-status",
    "id": "550e8400-e29b-41d4-a716-446655440100",
    "attributes": {
      "status": "RUNNING",
      "startedAt": "2024-01-15T10:30:00Z",
      "completedAt": null,
      "error": null
    }
  }
}

Fluxo de Execução

Recebimento - A plataforma recebe a requisição e valida o input
Resolução - Identifica a configuração e versão a usar
Data Fetch - Executa os data sources em paralelo (por prioridade)
Merge - Combina o input original com dados dos data sources
DMN - Chama o Decision Engine com o input mesclado
Resultado - Retorna o output (sync) ou dispara callback (async)
Registro - Armazena a execução completa para auditoria

Métricas de Tempo

O objeto timing fornece métricas de performance:

Campo	Descrição
`totalMs`	Tempo total da execução
`dataFetchMs`	Tempo gasto buscando data sources
`dmnExecutionMs`	Tempo da execução DMN

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION`	Input inválido ou configKey não encontrada
404	`NOT_FOUND`	Execução não encontrada
408	`TIMEOUT`	Execução excedeu o timeout
409	`CONFLICT`	Configuração não está publicada
429	`RATE_LIMIT`	Limite de execuções concorrentes atingido
502	`DATA_SOURCE_ERROR`	Erro ao buscar data source obrigatório

Endpoints​

Atributos da Execução​

Status da Execução​

Modos de Execução​

Executar Decisão (Síncrono)​

Atributos​

Response (200 OK)​

Executar Decisão (Assíncrono)​

Response (202 Accepted)​

Callback Payload​

Listar Execuções​

Query Parameters​

Obter Status da Execução​

Response (200 OK)​

Fluxo de Execução​

Métricas de Tempo​

Erros Comuns​

Endpoints

Atributos da Execução

Status da Execução

Modos de Execução

Executar Decisão (Síncrono)

Atributos

Response (200 OK)

Executar Decisão (Assíncrono)

Response (202 Accepted)

Callback Payload

Listar Execuções

Query Parameters

Obter Status da Execução

Response (200 OK)

Fluxo de Execução

Métricas de Tempo

Erros Comuns