Execução de Política via API

Esta documentação descreve como executar políticas do Wisedit via API REST, incluindo autenticação, requisição, resposta e acesso aos logs e relatórios de execução.

Endpoint de Execução

POST /api/policies/{policyId}/execute

Parâmetros:

policyId (path): Identificador da política publicada

Headers obrigatórios:

Authorization: ApiKey <API_KEY>
Content-Type: application/json

Corpo da requisição:

{
  "payload": {
    "campo1": "valor1",
    "campo2": "valor2"
  }
}

Nota: O formato do payload é dinâmico e varia conforme a configuração da política publicada. Envie apenas os dados de entrada definidos na política.

Autenticação

API Key

A autenticação é realizada via API Key enviada no header Authorization.

Formato do header:

Authorization: ApiKey <API_KEY>

Possíveis Erros de Autenticação

Header Authorization ausente

Status: 401 Unauthorized

{
  "error": "Missing Authorization header."
}

API Key inválida

Status: 404 Not Found

{
  "error": {
    "code": "",
    "message": "API key not found."
  }
}

API Key de outra organização

Status: 404 Not Found

{
  "error": {
    "code": "",
    "message": "API key not found."
  }
}

Resposta da Execução

A resposta contém dois objetos principais:

data: Informações detalhadas da execução
error: Erro técnico ou de infraestrutura (quando aplicável)

Exemplo de resposta bem-sucedida:

{
  "data": {
    "executionId": "string",
    "executionDate": "2026-01-07T16:45:56.149Z",
    "executionTime": 0,
    "organizationId": 0,
    "policyName": "string",
    "responsibleExecution": "string",
    "policyVersion": 0,
    "finalNode": {
      "stepId": "string",
      "stepName": "string",
      "responseType": "string",
      "color": "string",
      "tag": "string",
      "messageSuccess": "string",
      "messageError": "string",
      "outputFields": [
        {
          "fieldId": 0,
          "fieldName": "string",
          "value": "string"
        }
      ]
    },
    "inputFields": [
      {
        "fieldId": 0,
        "fieldName": "string",
        "value": "string"
      }
    ]
  },
  "error": null
}

Campos da Resposta

Campo	Tipo	Descrição
`executionId`	string	Identificador único da execução
`executionDate`	string (ISO 8601)	Data e hora da execução
`executionTime`	number	Tempo de execução em milissegundos
`organizationId`	number	ID da organização
`policyName`	string	Nome da política executada
`responsibleExecution`	string	Responsável pela execução
`policyVersion`	number	Versão da política executada
`finalNode`	object	Informações do nó final da execução
`inputFields`	array	Campos de entrada enviados

Erros de Negócio

A API pode retornar HTTP 200 mesmo quando há erro de negócio no fluxo da política.

Exemplo de erro de negócio:

{
  "data": null,
  "error": {
    "code": "500",
    "message": "error: cpf_user cannot be null."
  }
}

Importante: Um status HTTP 200 com error preenchido indica que a execução ocorreu, mas o fluxo da política terminou com erro de alguma regra de negócio, pode ser uma lógica errada ou o uso de uma variável nula para fazer uma operação.

Listar Execuções

Obter Lista de Execuções

GET /api/executions

Parâmetros de query (opcionais):

name (string): Filtrar por nome da política
start_date (string, formato: YYYY-MM-DD): Data inicial para filtrar execuções
end_date (string, formato: YYYY-MM-DD): Data final para filtrar execuções
sort_by (string): Campo para ordenação (ex: executionDate, policyName)
sort_order (string): Ordem de classificação (asc ou desc)
page (integer): Número da página (padrão: 1)
limit (integer): Itens por página (padrão: varia conforme configuração)

Headers obrigatórios:

Authorization: ApiKey <API_KEY>

Resposta:

{
  "data": {
    "executions": [
      {
        "executionId": "string",
        "policyName": "string",
        "policyVersion": 0,
        "type": "string",
        "executionDate": "2026-01-22T17:23:04.334Z"
      }
    ],
    "currentPage": 0,
    "perPage": 0,
    "totalPages": 0,
    "totalItems": 0
  },
  "error": {
    "code": "string",
    "message": "string"
  }
}

Campos da Resposta

Campo	Tipo	Descrição
`executions`	array	Lista de execuções retornadas
`executionId`	string	Identificador único da execução
`policyName`	string	Nome da política executada
`policyVersion`	number	Versão da política executada
`type`	string	Tipo da execução (ex: “api”, “manual”)
`executionDate`	string (ISO 8601)	Data e hora da execução
`currentPage`	number	Página atual da paginação
`perPage`	number	Itens por página
`totalPages`	number	Total de páginas
`totalItems`	number	Total de itens encontrados

Log de Execução

Obter URL do Log

GET /api/executions/{executionId}/log

Parâmetros:

executionId (path): Identificador da execução

Headers obrigatórios:

Authorization: ApiKey <API_KEY>

Resposta:

{
  "data": {
    "fileUrl": "https://exemplo.com/log/arquivo.json"
  },
  "error": null
}

O arquivo de log é acessado através da URL retornada no campo fileUrl.

Obter Log em JSON

GET /api/executions/{executionId}/log/data

Parâmetros:

executionId (path): Identificador da execução

Headers obrigatórios:

Authorization: ApiKey <API_KEY>

Resposta:

{
  "data": "string",
  "error": {
    "code": "string",
    "message": "string"
  }
}

Retorna o log de execução da política diretamente em formato JSON, sem necessidade de acessar uma URL externa.

Relatório de Execução (PDF)

Obter URL do Relatório

GET /api/executions/{executionId}/report

Parâmetros:

executionId (path): Identificador da execução

Headers obrigatórios:

Authorization: ApiKey <API_KEY>

Resposta:

{
  "data": {
    "fileUrl": "https://exemplo.com/relatorios/arquivo.pdf"
  },
  "error": null
}

O relatório em PDF é acessado através da URL retornada no campo fileUrl.

Códigos de Status HTTP

A API utiliza os seguintes códigos de status:

Status	Descrição
`200 OK`	Requisição bem-sucedida (execução realizada, lista retornada, etc.)
`400 Bad Request`	Requisição inválida (parâmetros incorretos, formato inválido)
`401 Unauthorized`	Header Authorization ausente
`404 Not Found`	API Key inválida, pertencente a outra organização ou recurso não encontrado

Exemplos de Uso

Exemplo 1: Execução Bem-Sucedida

Requisição:

POST /api/policies/123/execute
Authorization: ApiKey abc123xyz
Content-Type: application/json

{
  "payload": {
    "cpf": "12345678900",
    "nome": "João Silva"
  }
}

Resposta (200 OK):

{
  "data": {
    "executionId": "exec-456",
    "executionDate": "2026-01-08T10:30:00.000Z",
    "executionTime": 1250,
    "policyName": "Validação de CPF",
    "finalNode": {
      "stepName": "Aprovado",
      "messageSuccess": "CPF validado com sucesso",
      "outputFields": [
        {
          "fieldName": "status",
          "value": "approved"
        }
      ]
    }
  },
  "error": null
}

Exemplo 2: Erro de Negócio

Requisição:

POST /api/policies/123/execute
Authorization: ApiKey abc123xyz
Content-Type: application/json

{
  "payload": {
    "cpf": null
  }
}

Resposta (200 OK):

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "error: cpf_user cannot be null."
  }
}

Exemplo 3: Erro de Autenticação

Requisição:

POST /api/policies/123/execute
Content-Type: application/json

{
  "payload": {
    "cpf": "12345678900"
  }
}

Resposta (401 Unauthorized):

{
  "error": "Missing Authorization header."
}

Exemplo 4: Listar Execuções

Requisição:

GET /api/executions?start_date=2026-01-01&end_date=2026-01-31&sort_by=executionDate&sort_order=desc&page=1&limit=10
Authorization: ApiKey abc123xyz

Resposta (200 OK):

{
  "data": {
    "executions": [
      {
        "executionId": "exec-456",
        "policyName": "Validação de CPF",
        "policyVersion": 1,
        "type": "api",
        "executionDate": "2026-01-08T10:30:00.000Z"
      },
      {
        "executionId": "exec-455",
        "policyName": "Análise de Crédito",
        "policyVersion": 2,
        "type": "api",
        "executionDate": "2026-01-08T09:15:00.000Z"
      }
    ],
    "currentPage": 1,
    "perPage": 10,
    "totalPages": 5,
    "totalItems": 48
  },
  "error": null
}

Boas Práticas

Sempre inclua o header Authorization com uma API Key válida
Valide os campos de entrada antes de enviar a requisição
Armazene o executionId para consultar logs e relatórios posteriormente
Use paginação ao listar execuções para melhor performance
Implemente retry logic para lidar com erros temporários de rede
Monitore os tempos de resposta através do campo executionTime
Trate adequadamente os erros de negócio retornados em status 200
Filtre por data ao listar execuções para reduzir o volume de dados retornados

Fluxo Completo de Execução

1. Cliente envia POST /api/policies/{policyId}/execute
   ↓
2. Sistema valida API Key
   ↓
3. Sistema executa a política com o payload fornecido
   ↓
4. Sistema retorna resposta com executionId
   ↓
5. Cliente pode consultar:
   - GET /api/executions (listar todas as execuções)
   - GET /api/executions/{executionId}/log (URL do arquivo)
   - GET /api/executions/{executionId}/log/data (JSON direto)
   - GET /api/executions/{executionId}/report (PDF)