Referência da API - Brasilware

Esta documentação fornece informações detalhadas sobre todos os endpoints disponíveis na API REST do Brasilware. A API permite interagir programaticamente com o sistema para gerenciar módulos, relatórios, configurações e outros recursos.

Informações Básicas

Todos os endpoints da API usam o seguinte URL base:

https://seu-dominio.com/api

Todas as requisições e respostas da API são formatadas em JSON, a menos que indicado de outra forma.

Endpoints

Gestão de Módulos

GET /api/modules

Retorna a lista de todos os módulos instalados.

Parâmetros

Esta requisição não requer parâmetros.

Resposta

[
  {
    "id": 1,
    "name": "Analisador JavaScript",
    "description": "Analisa código JavaScript buscando comportamentos maliciosos",
    "content": "...",
    "createdAt": "2025-03-10T14:30:00.000Z"
  },
  {
    "id": 2,
    "name": "Visualizador de Tráfego",
    "description": "Visualiza e analisa capturas de tráfego de rede",
    "content": "...",
    "createdAt": "2025-03-12T09:15:00.000Z"
  }
]

GET /api/modules/:id

Retorna detalhes de um módulo específico.

Parâmetros de URL

Parâmetro	Tipo	Descrição
id	number	Identificador único do módulo

Resposta

{
  "id": 1,
  "name": "Analisador JavaScript",
  "description": "Analisa código JavaScript buscando comportamentos maliciosos",
  "content": "...",
  "createdAt": "2025-03-10T14:30:00.000Z"
}

POST /api/modules/upload

Faz upload e instala um novo módulo a partir de um arquivo.

Parâmetros de Formulário

Parâmetro	Tipo	Descrição
name	string	Nome do módulo
description	string	Descrição do módulo
file	file	Arquivo HTML do módulo

Resposta

{
  "id": 3,
  "name": "Scanner de Phishing",
  "description": "Analisa URLs para detectar tentativas de phishing",
  "content": "...",
  "createdAt": "2025-03-17T10:45:00.000Z"
}

POST /api/modules/url

Instala um novo módulo a partir de uma URL.

Parâmetros de Corpo (JSON)

Parâmetro	Tipo	Descrição
name	string	Nome do módulo
description	string	Descrição do módulo
url	string	URL do módulo (deve apontar para um arquivo HTML)

Resposta

{
  "id": 4,
  "name": "Analisador de Pacotes",
  "description": "Ferramenta para análise de pacotes de rede",
  "content": "...",
  "createdAt": "2025-03-17T11:20:00.000Z"
}

DELETE /api/modules/:id

Remove um módulo instalado.

Parâmetros de URL

Parâmetro	Tipo	Descrição
id	number	Identificador único do módulo

Resposta

204 No Content (sem corpo de resposta)

Gestão de Relatórios PDF

GET /api/pdfs

Retorna a lista de todos os relatórios PDF armazenados.

Parâmetros

Esta requisição não requer parâmetros.

Resposta

[
  {
    "id": 1,
    "filename": "relatorio-malware-01.pdf",
    "filepath": "/uploads/pdfs/relatorio-malware-01.pdf",
    "filesize": 1258000,
    "createdAt": "2025-03-15T16:30:00.000Z",
    "isMerged": false,
    "sourceIds": null
  },
  {
    "id": 2,
    "filename": "merged-1234567890.pdf",
    "filepath": "/uploads/pdfs/merged-1234567890.pdf",
    "filesize": 3560000,
    "createdAt": "2025-03-16T10:15:00.000Z",
    "isMerged": true,
    "sourceIds": "1,3,4"
  }
]

POST /api/pdfs/upload

Faz upload de um ou mais arquivos PDF.

Parâmetros de Formulário

Parâmetro	Tipo	Descrição
files	file[]	Arquivos PDF a serem enviados (multiplos arquivos são permitidos)

Resposta

[
  {
    "id": 5,
    "filename": "analise-botnet-2025.pdf",
    "filepath": "/uploads/pdfs/analise-botnet-2025.pdf",
    "filesize": 2450000,
    "createdAt": "2025-03-17T14:25:00.000Z",
    "isMerged": false,
    "sourceIds": null
  },
  {
    "id": 6,
    "filename": "ransomware-estudo-de-caso.pdf",
    "filepath": "/uploads/pdfs/ransomware-estudo-de-caso.pdf",
    "filesize": 1850000,
    "createdAt": "2025-03-17T14:25:00.000Z",
    "isMerged": false,
    "sourceIds": null
  }
]

POST /api/pdfs/merge

Mescla múltiplos PDFs em um único arquivo.

Parâmetros de Corpo (JSON)

Parâmetro	Tipo	Descrição
pdfIds	number[]	Array de IDs dos PDFs a serem mesclados, na ordem desejada

Resposta

{
  "id": 7,
  "filename": "merged-1735896042.pdf",
  "filepath": "/uploads/pdfs/merged-1735896042.pdf",
  "filesize": 4300000,
  "createdAt": "2025-03-17T15:00:00.000Z",
  "isMerged": true,
  "sourceIds": "5,6"
}

GET /api/pdfs/download/:id

Baixa um arquivo PDF específico.

Parâmetros de URL

Parâmetro	Tipo	Descrição
id	number	Identificador único do PDF

Resposta

O arquivo PDF como um stream binário (Content-Type: application/pdf)

DELETE /api/pdfs/:id

Remove um arquivo PDF.

Parâmetros de URL

Parâmetro	Tipo	Descrição
id	number	Identificador único do PDF

Resposta

204 No Content (sem corpo de resposta)

Regeneração com IA

POST /api/pdfs/:id/regenerate

Regenera um relatório PDF usando análise de IA.

Parâmetros de URL

Parâmetro	Tipo	Descrição
id	number	Identificador único do PDF a ser regenerado

Parâmetros de Corpo (JSON)

Parâmetro	Tipo	Descrição
language	string	Código do idioma para o relatório (e.g., "pt-BR", "en-US", "es-ES")

Resposta

{
  "id": 8,
  "filename": "ai-report-pt-BR-1735896500.pdf",
  "filepath": "/uploads/pdfs/ai-report-pt-BR-1735896500.pdf",
  "filesize": 3750000,
  "createdAt": "2025-03-17T16:15:00.000Z",
  "isMerged": false,
  "sourceIds": "7"
}

Configurações

GET /api/settings

Obtém as configurações atuais do sistema.

Parâmetros

Esta requisição não requer parâmetros.

Resposta

{
  "id": 1,
  "theme": "light",
  "language": "pt-BR",
  "apiKey": "sk-************************************",
  "notificationsEnabled": true
}

PUT /api/settings

Atualiza as configurações do sistema.

Parâmetros de Corpo (JSON)

Parâmetro	Tipo	Descrição
theme	string	Tema da interface ("light" ou "dark")
language	string	Código do idioma da interface (e.g., "pt-BR", "en-US", "es-ES")
apiKey	string	Chave de API para integração com serviços de IA (opcional)
notificationsEnabled	boolean	Habilitar/desabilitar notificações (opcional)

Resposta

{
  "id": 1,
  "theme": "dark",
  "language": "en-US",
  "apiKey": "sk-************************************",
  "notificationsEnabled": true
}

Códigos de Status

A API do Brasilware utiliza os seguintes códigos de status HTTP:

Código	Descrição
200 OK	A requisição foi processada com sucesso e o resultado foi retornado.
201 Created	O recurso foi criado com sucesso (usado após POST bem-sucedido).
204 No Content	A requisição foi processada com sucesso, mas não há conteúdo para retornar.
400 Bad Request	A requisição tem parâmetros inválidos ou está mal formatada.
401 Unauthorized	Autenticação é necessária ou falhou.
403 Forbidden	O cliente não tem permissão para acessar o recurso.
404 Not Found	O recurso solicitado não foi encontrado.
500 Internal Server Error	Ocorreu um erro interno no servidor.

Tratamento de Erros

Quando ocorre um erro, a API retorna um objeto JSON com informações sobre o erro:

{
  "error": {
    "message": "Descrição do erro",
    "code": "ERROR_CODE"
  }
}

Limitações e Boas Práticas

Implemente cache do lado do cliente para reduzir o número de requisições.
Para uploads de arquivos grandes, considere dividir em partes menores.
A API pode ter limites de taxa (rate limits) para prevenir sobrecarga do servidor.