[HSC MindAware] - Documentação API

A API do HSC MindAware permite integração completa com aplicativos externos através do protocolo HTTPS, retornando dados no formato JSON. Esta API fornece acesso a dashboards, campanhas educacionais e comportamentais, métricas detalhadas e relatórios estratégicos.

Arquitetura REST

A API do HSC MindAware segue o padrão REST (Representational State Transfer), uma arquitetura amplamente utilizada para desenvolvimento de APIs web que oferece simplicidade, escalabilidade e padronização.

Características principais:

Protocolo HTTP/HTTPS: Todas as comunicações utilizam o protocolo HTTPS seguro
Métodos HTTP padrão:
- GET para consultar dados
- POST para criar recursos ou executar ações
- Operações são identificadas claramente pelo método HTTP utilizado
Formato JSON: Todas as requisições e respostas utilizam o formato JSON (JavaScript Object Notation)
Stateless: Cada requisição é independente e contém todas as informações necessárias (incluindo o token de autenticação)
Endpoints baseados em recursos: URLs organizadas de forma hierárquica e intuitiva (ex: /api/my_dashboard/user_info)
Códigos de status HTTP: Respostas utilizam códigos HTTP padrão (200 para sucesso, 401 para não autorizado, 404 para não encontrado, etc.)

Como funciona:

Autenticação: O cliente faz login enviando credenciais para /api/auth/login e recebe um token de acesso
Autorização: O token deve ser incluído no cabeçalho Authorization: Bearer <token> em todas as requisições subsequentes
Requisição: O cliente faz chamadas HTTP aos endpoints desejados, incluindo o token quando necessário
Processamento: O servidor valida o token, processa a requisição e prepara a resposta
Resposta: O servidor retorna os dados solicitados em formato JSON ou códigos de erro apropriados
Logout: Quando finalizado, o cliente pode invalidar o token através de /api/auth/logout

Esta arquitetura permite que qualquer linguagem de programação ou ferramenta que suporte HTTP possa integrar facilmente com a plataforma HSC MindAware.

Pré-requisitos

Conta ativa no HSC MindAware com privilégios administrativos
Usuário criado e ativado no sistema
Token de autenticação válido para chamadas protegidas

URL Base

{{url}}/api

Autenticação

Todas as rotas marcadas como "Requer Token" necessitam do token de autenticação no cabeçalho da requisição.

Login

Obtém o token de acesso para realizar chamadas autenticadas à API.

Endpoint: POST /auth/login

Requer Token: Não

Request Body:

{
  "email": "usuario@empresa.com",
  "password": "senha_segura"
}

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "token_type": "bearer",
  "expires_in": 7200,
  "user": {
    "id": 123,
    "name": "João Silva",
    "email": "usuario@empresa.com"
  },
  "company": {
    "id": 1,
    "name": "Empresa XYZ"
  },
  "module": {},
  "two_factor_confirmed": 0
}

Logout

Invalida o token de acesso atual.

Endpoint: POST /auth/logout

Requer Token: Sim

Response:

{
  "message": "Usuário desconectado com sucesso!"
}

Formato do Header de Autenticação

Para todas as requisições que requerem autenticação, inclua o token no cabeçalho:

Authorization: Bearer <seu_token_aqui>

Dashboard do Usuário

O Dashboard do Usuário fornece uma visão consolidada das informações pessoais, progresso educacional, scores de comportamento e campanhas ativas.

Obter Dados Completos do Dashboard

Endpoint: GET /auth/my-dashboard/{id?}

Requer Token: Sim

Parâmetros:

id (opcional): ID do usuário. Se omitido, retorna dados do usuário autenticado.

Response:

{
  "success": true,
  "data": {
    "quadrantPosition": {
      "x": 85,
      "y": 90
    },
    "certifications": [
      {
        "id": 1,
        "name": "Cyber Security Awareness",
        "completed": true,
        "date": "2025-01-15"
      }
    ]
  }
}

Informações Básicas do Usuário

Endpoint: GET /my_dashboard/user_info/{id?}

Requer Token: Sim

Response:

{
  "thumbnail": "data:image/png;base64,iVBORw0KGgo...",
  "name": "João Silva",
  "mail": "joao@empresa.com",
  "groups": ["Grupo A", "Grupo B", "TI"]
}

Percentual de Cursos Concluídos

Endpoint: GET /my_dashboard/completed_course/{id?}

Requer Token: Sim

Response:

Percentual de Certificações Concluídas

Endpoint: GET /my_dashboard/completed_certification/{id?}

Requer Token: Sim

Response:

Score Educacional

Retorna o score atual do usuário baseado no progresso educacional.

Endpoint: GET /my_dashboard/edu_score/{id?}

Requer Token: Sim

Response:

Score de Comportamento Seguro

Retorna o score de comportamento baseado nas campanhas de simulação.

Endpoint: GET /my_dashboard/comp_score/{id?}

Requer Token: Sim

Response:

Percentual de Comportamento Inseguro

Endpoint: GET /my_dashboard/insec_behaviour/{id?}

Requer Token: Sim

Response:

Gráfico de Evolução de Scores

Retorna dados históricos para visualização da evolução dos scores educacional e comportamental.

Endpoint: GET /my_dashboard/edu_comp_graph/{id?}

Requer Token: Sim

Response:

{
  "xList": ["01/01/25", "02/01/25", "03/01/25", "04/01/25"],
  "edu": [80, 85, 90, 95],
  "comp": [90, 88, 92, 88]
}

Progresso Detalhado dos Cursos

Endpoint: GET /my_dashboard/course_progress/{id?}

Requer Token: Sim

Response:

[
  {
    "id": 1,
    "name": "Cyber Security Awareness Essentials",
    "progress": 90,
    "course_structure": [
      {
        "id": 101,
        "name": "Módulo 1: Fundamentos",
        "progress": 100,
        "course_content": [
          { "id": 1001, "name": "Introdução à Segurança" },
          { "id": 1002, "name": "Ameaças Comuns" }
        ]
      },
      {
        "id": 102,
        "name": "Módulo 2: Phishing",
        "progress": 80,
        "course_content": [
          { "id": 1003, "name": "Reconhecendo Phishing" },
          { "id": 1004, "name": "Estudos de Caso" }
        ]
      }
    ],
    "course_certification": [
      {
        "id": 1,
        "name": "Certificação Básica",
        "status": "pending"
      }
    ],
    "totalConteudos": 10
  }
]

Campanhas Ativas do Usuário

Endpoint: GET /my_dashboard/campaigns/{id?}

Requer Token: Sim

Response:

[
  {
    "id": 123,
    "name": "Campanha Anti-Phishing Q1 2025",
    "type": "behavioral",
    "status": "active",
    "date_start": "2025-01-10",
    "date_end": "2025-03-31",
    "progress": 45
  }
]

Campanhas de Comportamento

As Campanhas de Comportamento permitem simulações de phishing e outros ataques para testar e treinar usuários em cenários reais.

Listar Todas as Campanhas

Endpoint: GET /company_campaigns/

Requer Token: Sim

Response:

{
  "campaigns": [
    {
      "id": 1,
      "name": "Campanha de Phishing - Q1 2025",
      "date_start": "2025-01-15 00:00:00",
      "date_end": "2025-03-31 23:59:59",
      "custom_template": 0,
      "step_count": 3,
      "mail_from": "noreply@phishing-test.com",
      "mail_subject": "Atualização Urgente de Segurança",
      "mail_body": "...",
      "name_template": "Phishing Financeiro",
      "description_template": "Simulação de email de banco fraudulento",
      "thumbnail_template": "https://...",
      "campaign_categories_id": 2,
      "webpage_body": "...",
      "trigger_time": 1,
      "trigger_schedule": "[{\"date\":\"15/01/2025\",\"hour\":\"09:00\"},{\"date\":\"15/02/2025\",\"hour\":\"14:00\"}]",
      "landing_page": "https://landing.mindaware.com/campaign1",
      "date_close": "2025-04-10",
      "created_at": "2025-01-10 10:30:00",
      "updated_at": "2025-01-12 15:20:00",
      "deleted_at": null
    }
  ]
}

Detalhes da Campanha

Retorna informações completas sobre uma campanha específica.

Endpoint: GET /company_campaigns/campaigns_details/{id_campanha}

Requer Token: Sim

Response:

{
  "campaigns": {
    "id": 1,
    "name": "Campanha de Phishing - Q1 2025",
    "total_users": 250,
    "date_start": "2025-01-15",
    "date_end": "2025-03-31"
  },
  "count_templates": {
    "phishing": 5,
    "smishing": 2,
    "vishing": 1
  },
  "triggers": [
    {
      "id": 1001,
      "user_id": 50,
      "status": "email_opened",
      "timestamp": "2025-01-15 09:15:23"
    }
  ],
  "triggers_history": [
    {
      "trigger_id": 1001,
      "status": "sent",
      "timestamp": "2025-01-15 09:00:00"
    },
    {
      "trigger_id": 1001,
      "status": "opened",
      "timestamp": "2025-01-15 09:15:23"
    }
  ]
}

Relatório PDF da Campanha

Gera um relatório estratégico em PDF da campanha.

Endpoint: GET /company_campaigns/campaigns_details_pdf/{id_campanha}

Requer Token: Sim

Response:

{
  "pdf": "JVBERi0xLjcKCjEgMCBvYmoKPDwKL1R5cGUgL0NhdGFsb2cKL1BhZ2VzIDIgMCBSCj4+CmVuZG9iagoKMi..."
}

Métricas de Disparos

Retorna métricas percentuais dos disparos por status.

Endpoint: GET /company_campaigns/triggersByCampaignWithPercent/{id}/{status?}

Requer Token: Sim

Parâmetros:

id: ID da campanha
status (opcional): Filtrar por status específico

Status disponíveis:

pending - E-mail pendente
sent - E-mail enviado
opened - E-mail aberto
clicked - Link clicado
submitted - Dados submetidos
canceled - Cancelado

Response:

{
  "percent": 75.5
}

Log dos Disparos por Usuário

Endpoint: POST /company_campaigns/triggersDetailsByUser/{id_campanha}

Requer Token: Sim

Response:

[
  {
    "picture": "https://cdn.mindaware.com/avatars/user50.jpg",
    "name": "Maria Santos",
    "mail": "maria.santos@empresa.com",
    "category": "Phishing",
    "template": "Phishing Financeiro",
    "status": "Link clicado",
    "timestamp": "2025-01-15 09:15:23"
  },
  {
    "picture": "https://cdn.mindaware.com/avatars/user51.jpg",
    "name": "João Silva",
    "mail": "joao.silva@empresa.com",
    "category": "Phishing",
    "template": "Phishing Corporativo",
    "status": "E-mail aberto",
    "timestamp": "2025-01-15 09:20:45"
  }
]

Histórico Detalhado do Disparo

Retorna o histórico completo de um disparo específico, incluindo dados técnicos quando disponíveis.

Endpoint: GET /company_campaigns/getTriggerHistory/{id_trigger}

Requer Token: Sim

Response:

[
  {
    "id": 1001,
    "timestamp": "2025-01-15 09:00:00",
    "status": 1,
    "status_name": "E-mail enviado"
  },
  {
    "id": 1001,
    "timestamp": "2025-01-15 09:15:23",
    "status": 2,
    "status_name": "E-mail aberto",
    "ip": "192.168.1.100",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
    "location": "São Paulo, BR"
  },
  {
    "id": 1001,
    "timestamp": "2025-01-15 09:16:10",
    "status": 3,
    "status_name": "Link clicado",
    "ip": "192.168.1.100",
    "browser": "Chrome 120.0",
    "os": "Windows 10"
  }
]

Datatable de Disparos

Endpoint otimizado para exibição em tabelas com suporte a pesquisa avançada.

Endpoint: GET /company_campaigns/datatableTriggers?id={id_campanha}

Requer Token: Sim

Query Parameters (filtros opcionais):

date_trigger - Data do disparo (formato: YYYY-MM-DD)
user - Nome do usuário
mail - E-mail do usuário
template - Nome do template/categoria
status - Status do disparo

Exemplo de URL com filtros:

/company_campaigns/datatableTriggers?id=1&user=João&status=clicked

Response:

{
  "aaData": [
    {
      "__timestamp": "2025-01-15 09:00:00",
      "__name": "João Silva",
      "__mail": "joao.silva@empresa.com",
      "__template": "Phishing Básico",
      "__status": "E-mail aberto",
      "__user_id": 50
    },
    {
      "__timestamp": "2025-01-15 09:05:00",
      "__name": "Maria Santos",
      "__mail": "maria.santos@empresa.com",
      "__template": "Phishing Financeiro",
      "__status": "Link clicado",
      "__user_id": 51
    }
  ]
}

Campanhas Educacionais

As Campanhas Educacionais gerenciam treinamentos, cursos e certificações dos usuários.

Detalhes da Campanha Educacional

Endpoint: GET /training_company_campaigns/details/{id_campanha}

Requer Token: Sim

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Treinamento de Segurança Q1 2025",
    "description": "Programa completo de conscientização em segurança da informação",
    "certification": 1,
    "date_start": "2025-01-10",
    "date_end": "2025-03-31",
    "total_users": 150,
    "courses": [
      {
        "id": 1,
        "name": "Cyber Security Awareness Essentials"
      },
      {
        "id": 2,
        "name": "Advanced Phishing Detection"
      }
    ]
  }
}

Métricas da Campanha Educacional

Retorna métricas específicas baseadas no tipo e status solicitados.

Endpoint: GET /training_company_campaigns/{type}/{status}/{id_campanha}

Requer Token: Sim

Parâmetros:

type:
- metric - Retorna objeto com numerador e denominador
- count - Retorna apenas o valor numérico
status:
- opened - E-mails abertos
- clicked - Links clicados
- course_initiated - Cursos iniciados
- course_completed - Cursos concluídos
- cert_pending - Certificações pendentes
- cert_completed - Certificações concluídas
- users - Total de usuários

Response (type="metric"):

{
  "triggers": 25,
  "total": 50
}

Response (type="count"):

Exemplos de uso:

GET /training_company_campaigns/metric/course_completed/1
GET /training_company_campaigns/count/users/1

Relatório Detalhado CSV

Gera relatório detalhado em formato CSV/JSON com todos os dados dos usuários.

Endpoint: POST /training_company_campaigns/trainingCampaignCsv/{id_campanha}

Requer Token: Sim

Response:

[
  {
    "training_camp_name": {
      "name": "Treinamento de Segurança Q1 2025"
    },
    "Nome": "João Silva",
    "Email": "joao.silva@empresa.com",
    "Grupo": "TI",
    "Iniciaram curso": 2,
    "Concluiram curso": 1,
    "Certificação pendente": 0,
    "Certificação concluída": 1,
    "Data último acesso": "2025-01-15 14:30:00"
  },
  {
    "training_camp_name": {
      "name": "Treinamento de Segurança Q1 2025"
    },
    "Nome": "Maria Santos",
    "Email": "maria.santos@empresa.com",
    "Grupo": "RH",
    "Iniciaram curso": 1,
    "Concluiram curso": 0,
    "Certificação pendente": 0,
    "Certificação concluída": 0,
    "Data último acesso": "2025-01-14 10:15:00"
  }
]

Relatório Estratégico PDF

Gera relatório executivo em PDF da campanha educacional.

Endpoint: GET /training_company_campaigns/pdf/{id_campanha}

Requer Token: Sim

Response:

{
  "pdf": "JVBERi0xLjcKCjEgMCBvYmoKPDwKL1R5cGUgL0NhdGFsb2cKL1BhZ2VzIDIgMCBSCj4+CmVuZG9iagoKMi..."
}

Log dos Disparos (Datatable)

Retorna dados formatados para exibição em tabelas com informações dos disparos educacionais.

Endpoint: GET /training_company_campaigns/datatableTriggers?id={id_campanha}

Requer Token: Sim

Query Parameters (filtros opcionais):

name - Nome do usuário
mail - E-mail do usuário
date_trigger - Data do disparo
status - Status do progresso

Response:

{
  "aaData": [
    {
      "id": 123,
      "training_camp_id": 1,
      "user_id": 456,
      "timestamp": "2025-01-10 09:00:00",
      "name": "João Silva",
      "mail": "joao.silva@empresa.com",
      "courses": [
        "Cyber Security Awareness Essentials",
        "Advanced Phishing Detection"
      ],
      "status": 5,
      "status_name": "Curso concluído"
    },
    {
      "id": 124,
      "training_camp_id": 1,
      "user_id": 457,
      "timestamp": "2025-01-10 09:05:00",
      "name": "Maria Santos",
      "mail": "maria.santos@empresa.com",
      "courses": [
        "Cyber Security Awareness Essentials"
      ],
      "status": 4,
      "status_name": "Curso iniciado"
    }
  ]
}

Histórico do Usuário na Campanha

Retorna o histórico completo de progresso de um usuário específico em uma campanha educacional.

Endpoint: GET /training_company_campaigns/getTriggerHistory/{user_id}/{id_campanha}

Requer Token: Sim

Response:

[
  {
    "status": 1,
    "status_name": "E-mail enviado",
    "timestamp": "2025-01-10 09:00:00"
  },
  {
    "status": 2,
    "status_name": "E-mail aberto",
    "timestamp": "2025-01-10 09:15:00"
  },
  {
    "status": 3,
    "status_name": "Link clicado",
    "timestamp": "2025-01-10 09:20:00"
  },
  {
    "status": 4,
    "status_name": "Curso iniciado",
    "timestamp": "2025-01-10 09:25:00"
  },
  {
    "status": 5,
    "status_name": "Curso concluído",
    "timestamp": "2025-01-12 14:30:00"
  },
  {
    "status": 7,
    "status_name": "Certificação concluída",
    "timestamp": "2025-01-12 15:00:00"
  }
]

Relatórios

Relatório de Métricas Educacionais

Gera relatório completo com dados educacionais de todos os usuários.

Endpoint: POST /reports/users_courses

Requer Token: Sim

Response:

[
  {
    "name": "João Silva",
    "mail": "joao.silva@empresa.com",
    "type": "USER",
    "groups": "TI, Segurança",
    "certification": "Sim",
    "certification_date": "2025-01-12",
    "course_name": "Cyber Security Awareness Essentials",
    "course_status": "Concluído",
    "course_start_date": "2025-01-10",
    "course_end_date": "2025-01-12",
    "has_completed": true
  },
  {
    "name": "Maria Santos",
    "mail": "maria.santos@empresa.com",
    "type": "USER",
    "groups": "RH",
    "certification": "Não",
    "certification_date": null,
    "course_name": "Cyber Security Awareness Essentials",
    "course_status": "Em Andamento",
    "course_start_date": "2025-01-10",
    "course_end_date": null,
    "has_completed": false
  },
  {
    "name": "Carlos Oliveira",
    "mail": "carlos.oliveira@empresa.com",
    "type": "USER",
    "groups": "Grupo TODOS",
    "certification": "Não",
    "certification_date": null,
    "course_name": "Cyber Security Awareness Essentials",
    "course_status": "Não Iniciado",
    "course_start_date": null,
    "course_end_date": null,
    "has_completed": null
  }
]

Relatório de Métricas de Comportamento

Retorna dados comportamentais baseados nas campanhas de simulação.

Endpoint: POST /company_campaigns/triggersDetailsByUser/{id_campanha}

Requer Token: Sim

Response:

[
  {
    "campaign_name": "Campanha Anti-Phishing Q1",
    "user_name": "João Silva",
    "mail": "joao.silva@empresa.com",
    "category": "Phishing",
    "template": "Phishing Financeiro",
    "status": "Link clicado",
    "timestamp": "2025-01-15 09:16:10"
  },
  {
    "campaign_name": "Campanha Anti-Phishing Q1",
    "user_name": "Maria Santos",
    "mail": "maria.santos@empresa.com",
    "category": "Phishing",
    "template": "Phishing Corporativo",
    "status": "E-mail aberto",
    "timestamp": "2025-01-15 09:20:45"
  }
]

Códigos de Status

Status de Campanhas Comportamentais

Código	Status	Descrição

Código	Status	Descrição
0	Pendente	E-mail pendente de envio
1	E-mail enviado	E-mail foi enviado com sucesso
2	E-mail aberto	Usuário abriu o e-mail
3	Link clicado	Usuário clicou no link do e-mail
4	Dados submetidos	Usuário submeteu dados no formulário
5	Cancelado	Disparo foi cancelado

Status de Campanhas Educacionais

Código	Status	Descrição

Código	Status	Descrição
0	E-mail pendente	E-mail aguardando envio
1	E-mail enviado	E-mail foi enviado
2	E-mail aberto	Usuário abriu o e-mail
3	Link clicado	Usuário acessou o link do treinamento
4	Curso iniciado	Usuário iniciou o curso
5	Curso concluído	Usuário completou o curso
6	Certificação pendente	Aguardando aprovação da certificação
7	Certificação concluída	Certificação obtida com sucesso

Status de Cursos

Status	Descrição

Status	Descrição
Não Iniciado	Curso ainda não foi acessado
Em Andamento	Curso iniciado mas não concluído
Concluído	Curso finalizado com sucesso
Expirado	Prazo de conclusão expirou

Boas Práticas

Segurança

Nunca exponha o token em logs, URLs ou código cliente
Renove o token antes da expiração (válido por 7200 segundos / 2 horas)
Valide sempre as respostas da API antes de processar

Performance

Cache tokens válidos para evitar logins repetidos
Utilize filtros nos endpoints de datatable para reduzir payload
Reutilize conexões HTTP quando possível

Tratamento de Erros

A API utiliza códigos HTTP padrão para indicar o sucesso ou falha das requisições:

200 OK: Requisição processada com sucesso
401 Unauthorized: Token expirado ou inválido
403 Forbidden: Sem permissão para acessar o recurso
404 Not Found: Recurso não encontrado
500 Internal Server Error: Erro interno do servidor

Sempre valide o código de status HTTP antes de processar a resposta.

[HSC MindAware] - Documentação API

Arquitetura REST

Pré-requisitos

URL Base

Autenticação

Login

Logout

Formato do Header de Autenticação

Dashboard do Usuário

Obter Dados Completos do Dashboard

Informações Básicas do Usuário

Percentual de Cursos Concluídos

Percentual de Certificações Concluídas

Score Educacional

Score de Comportamento Seguro

Percentual de Comportamento Inseguro

Gráfico de Evolução de Scores

Progresso Detalhado dos Cursos

Campanhas Ativas do Usuário

Campanhas de Comportamento

Listar Todas as Campanhas

Detalhes da Campanha

Relatório PDF da Campanha

Métricas de Disparos

Log dos Disparos por Usuário

Histórico Detalhado do Disparo

Datatable de Disparos

Campanhas Educacionais

Detalhes da Campanha Educacional

Métricas da Campanha Educacional

Relatório Detalhado CSV

Relatório Estratégico PDF

Log dos Disparos (Datatable)

Histórico do Usuário na Campanha

Relatórios

Relatório de Métricas Educacionais

Relatório de Métricas de Comportamento

Códigos de Status

Status de Campanhas Comportamentais

Status de Campanhas Educacionais

Status de Cursos

Boas Práticas

Segurança

Performance

Tratamento de Erros

Related articles