O que é a API do GlobalSuite e quando utilizá-la
A API do GlobalSuite permite conectar a plataforma com outros sistemas corporativos para consultar, criar, atualizar ou relacionar informações de negócio. Na prática, evita trabalhos manuais repetitivos e facilita que o GlobalSuite se mantenha sincronizado com ferramentas como CMDB, ITSM, soluções de compras, repositórios documentais, data lakes, dashboards ou plataformas de conformidade.
|
Necessidade |
O que a API oferece |
|
Importar informações |
Criar ou atualizar registos no GlobalSuite a partir de dados mantidos em outro sistema, por exemplo ativos, empregados, fornecedores ou evidências. |
|
Consultar informações |
Extrair dados do GlobalSuite para analisá-los, consolidá-los ou exibi-los em outros sistemas corporativos. |
|
Manter relações |
Vincular registos entre si, por exemplo fornecedores com serviços, ativos com ameaças, tickets com responsáveis ou evidências com controlos. |
|
Executar processos |
Lançar ações ou cálculos específicos, como solicitações de cálculo de risco ou cálculos de impacto associados à continuidade. |
|
Automatizar relatórios |
Preparar integrações com repositórios de dados, dashboards ou relatórios executivos sem depender exclusivamente de exportações manuais. |
|
Ideia-chave
|
Antes de começar: acesso, segurança e limites
Antes de desenhar uma integração, é conveniente validar quatro aspetos: ambiente, autenticação, alcance dos dados e limites de uso.
|
Aspeto |
O que deve ser validado |
|
Ambiente de documentação |
A documentação de referência é consultada no Swagger UI. Na demo Europa pode ser utilizada https://demo-eu.globalsuitesolutions.com/docs. Em outros ambientes, deve ser substituída pela URL publicada para o cliente ou região correspondente. |
|
URL de integração |
As chamadas reais devem ser direcionadas para a URL da API do ambiente correspondente, por exemplo https://api-demo-eu.globalsuitesolutions.com/v1/ para demo Europa. |
|
API Key |
As chamadas autenticadas requerem uma API Key ou token com validade definida. Se a chave estiver fora do seu intervalo de validade, a API retornará um erro 403. |
|
Subentidades |
Se o cliente trabalhar com várias subentidades, normalmente deve ser gerada uma API Key específica para cada entidade que se deseja integrar, já que os dados são próprios de cada uma. |
|
Rate limit |
O limite indicado na página atual é de 180 chamadas por minuto por API Key. Se for excedido, a API pode responder com 429 “Too Many Attempts”. |
|
Versionamento |
A API é oferecida na versão Current. Se ocorrer uma alteração disruptiva, a versão anterior pode passar a Deprecated para dar tempo para adaptar as integrações. |
|
Recomendação inicial
|
Como ler a documentação Swagger
O Swagger UI exibe os modelos e operações disponíveis. Para utilizadores funcionais, o importante não é memorizar a sintaxe, mas entender o que cada operação representa e qual o impacto que tem sobre os dados.
|
Item |
Como interpretá-lo |
|
Recurso ou modelo |
Objeto de negócio do GlobalSuite: ativo, ticket, fornecedor, empregado, evidência, serviço, processo, controlo, etc. |
|
Método GET |
Consulta um ou vários registos. Geralmente utilizado para listagens, filtros, validações prévias e extração de dados. |
|
Método POST |
Cria um registo ou executa uma ação de negócio. Também pode ser utilizado para associar objetos ou lançar cálculos. |
|
Método PUT |
Atualiza um registo ou uma relação existente. Deve ser utilizado com especial cuidado para não sobrescrever informações. |
|
Método DELETE |
Elimina ou desassocia um registo. Deve ser limitado a processos controlados e com validações prévias. |
|
Parâmetros na rota |
Valores como {modelId}, {objectId}, {analysisId} ou {riskId} identificam o registo específico sobre o qual se atua. |
|
Parâmetros de consulta |
Filtros, ordenação, paginação ou relações ampliadas. Em algumas listagens pode ser usado expand para trazer informações relacionadas, se o endpoint permitir. |
Referência Swagger: API GlobalSuite - Swagger UI
Casos de uso por área funcional
Os seguintes exemplos servem para entender que problemas de negócio a API pode resolver e quais endpoints revisar no Swagger para concretizar cada integração.
1. Sincronizar o inventário de ativos a partir de uma CMDB ou ferramenta ITSM
|
Objetivo de negócio |
Manter no GlobalSuite um inventário atualizado de ativos, categorias, dimensões e dependências sem realizar cargas manuais recorrentes. |
|
Exemplo de cenário |
A equipa de IT mantém servidores, aplicações ou serviços técnicos numa CMDB. O GlobalSuite necessita desses ativos para análises de riscos, BIA, conformidade ou relatórios. |
|
Fluxo recomendado |
1) Consultar catálogos e dimensões disponíveis. 2) Verificar se o ativo já existe. 3) Criar ou atualizar o ativo. 4) Manter dependências e dimensões. 5) Registrar rastreabilidade no sistema de origem. |
|
Benefício para o utilizador |
Reduz a duplicidade de inventários, melhora a qualidade dos dados e permite que análises de riscos, continuidade e conformidade partam de uma base comum. |
|
Método |
Endpoint |
Uso orientativo |
|
GET |
/assets |
Consultar ativos existentes e evitar duplicados. |
|
POST |
/assets |
Criar novos ativos que devem ser geridos no GlobalSuite. |
|
PUT |
/assets/{modelId} |
Atualizar atributos de um ativo já existente. |
|
GET |
/categories |
Consultar categorias de ativos disponíveis. |
|
GET |
/dimensions |
Consultar dimensões e níveis aplicáveis. |
|
POST |
/assets/{modelId}/dependency/{objectId} |
Criar dependências entre ativos. |
|
PUT |
/assets/{modelId}/dimensions/{objectId} |
Atualizar valores de dimensão do ativo. |
|
Recomendação
|
2. Criar e atualizar tickets a partir de ferramentas externas
|
Objetivo de negócio |
Conectar o GlobalSuite com ferramentas de suporte, auditoria, conformidade ou gestão de ações para que os tickets sejam criados e mantidos sincronizados. |
|
Exemplo de cenário |
Uma ferramenta externa deteta uma incidência, constatação ou ação corretiva. A organização deseja gerenciá-la no GlobalSuite com responsáveis, evidências, relações e acompanhamento. |
|
Fluxo recomendado |
1) Identificar o tipo de ticket e os seus campos. 2) Criar o ticket. 3) Associar responsáveis, empregados, ficheiros ou relações. 4) Atualizar o ticket quando o estado mudar no sistema externo. |
|
Benefício para o utilizador |
Permite centralizar o acompanhamento no GlobalSuite sem obrigar as equipas a introduzir manualmente informações que já existem em outras ferramentas. |
|
Método |
Endpoint |
Uso orientativo |
|
GET |
/ticketTypes |
Consultar tipos de ticket disponíveis. |
|
GET |
/ticketTypes/{modelId}/fields |
Consultar campos configurados para um tipo de ticket. |
|
GET |
/tickets |
Procurar tickets existentes ou consultar o seu estado. |
|
POST |
/tickets |
Criar um novo ticket. |
|
PUT |
/tickets/{modelId} |
Atualizar dados do ticket. |
|
POST |
/tickets/{modelId}/owners/{objectId} |
Associar responsáveis ao ticket. |
|
POST |
/tickets/{modelId}/files |
Anexar documentação ou evidências ao ticket. |
|
POST |
/tickets/{modelId}/ticketRelations/{objectId} |
Relacionar o ticket com outros registos. |
|
Recomendação
|
3. Consultar análises de riscos e automatizar cálculos
|
Objetivo de negócio |
Extrair informações de análises de riscos ou iniciar cálculos a partir de processos automatizados, por exemplo, para alimentar relatórios, auditorias ou dashboards. |
|
Exemplo de cenário |
Uma equipa precisa consolidar ativos, ameaças, controlos e riscos num repositório corporativo ou iniciar um recálculo quando informações-chave são atualizadas. |
|
Fluxo recomendado |
1) Identificar a análise. 2) Consultar ativos incluídos. 3) Consultar ameaças, controlos e riscos relacionados. 4) Executar pedidos de cálculo quando aplicável. 5) Explorar resultados em relatórios. |
|
Benefício para o utilizador |
Melhora a rastreabilidade da análise, permite a automação de relatórios e reduz o tempo em revisões periódicas de riscos. |
|
Método |
Endpoint |
Uso orientativo |
|
GET |
/analysis/{modelId}/assets |
Consultar ativos incluídos numa análise. |
|
GET |
/analysis/{modelId}/controls |
Consultar controlos associados à análise. |
|
POST |
/analysis/{modelId}/controls |
Incorporar controlos à análise, se aplicável. |
|
POST |
/analysis/{modelId}/assets/{assetId}/threats/{threatId}/calculateRequest |
Solicitar cálculo associado a uma ameaça. |
|
POST |
/analysis/{modelId}/calculateThreatSimulationRequest |
Iniciar uma simulação de ameaças. |
|
POST |
/analysis/{modelId}/calculateControlSimulationRequest |
Iniciar uma simulação de controlos. |
|
GET |
/analysisCatalogs/{modelId}/threats/{threatId}/controls |
Consultar controlos de catálogo associados a ameaças. |
|
Recomendação
|
4. Consolidar resultados de BIA e cálculos de impacto
|
Objetivo de negócio |
Automatizar cálculos relacionados com continuidade de negócio, como MTPD ou RTO impactado, a partir de critérios configurados no GlobalSuite. |
|
Exemplo de cenário |
A organização precisa recalcular impactos após alterações em processos, ativos ou dependências, ou consolidar resultados para relatórios de continuidade. |
|
Fluxo recomendado |
1) Verificar a configuração BIA e os critérios de cálculo. 2) Enviar o pedido de cálculo correspondente. 3) Revisar o resultado no GlobalSuite e nos relatórios associados. |
|
Benefício para o utilizador |
Ajuda a manter atualizados os indicadores de continuidade sem depender exclusivamente de revisões manuais. |
|
Método |
Endpoint |
Uso orientativo |
|
POST |
/calculateAccumulatedMtpd |
Calcular MTPD acumulado. |
|
POST |
/calculateImpactedMtpd |
Calcular MTPD impactado. |
|
POST |
/calculateImpactedRto |
Calcular RTO impactado. |
|
Recomendação
|
5. Sincronizar processos, serviços e relações de negócio
|
Objetivo de negócio |
Conectar o mapa de processos e serviços do GlobalSuite com inventários corporativos, catálogos de serviços ou repositórios de arquitetura empresarial. |
|
Exemplo de cenário |
A área de negócio mantém processos e serviços numa ferramenta corporativa, mas o GlobalSuite precisa deles para continuidade, riscos, conformidade e dashboards. |
|
Fluxo recomendado |
1) Consultar processos e serviços existentes. 2) Criar ou atualizar informações básicas quando aplicável. 3) Manter empregados, stakeholders, entradas, ações e saídas. 4) Consolidar métricas para relatórios. |
|
Benefício para o utilizador |
Facilita uma visão comum entre gestão de serviços, continuidade, riscos e relatórios executivos. |
|
Método |
Endpoint |
Uso orientativo |
|
GET |
/processes |
Consultar processos de negócio. |
|
GET |
/processes/{modelId} |
Consultar o detalhe de um processo. |
|
GET |
/processes/{modelId}/employees |
Consultar empregados associados ao processo. |
|
GET |
/processes/{modelId}/inputActionOutput |
Consultar entradas, ações e saídas do processo. |
|
GET |
/services |
Consultar serviços. |
|
POST |
/services |
Criar serviços. |
|
PUT |
/services/{modelId} |
Atualizar dados de um serviço. |
|
Recomendação
|
6. Manter fornecedores, acordos, serviços e SLAs
|
Objetivo de negócio |
Integrar a gestão de fornecedores do GlobalSuite com ferramentas de compras, TPRM, due diligence ou sistemas principais de terceiros. |
|
Exemplo de cenário |
Compras mantém o sistema principal de fornecedores, enquanto o GlobalSuite gere riscos, evidências, acordos, contactos, serviços afetados e acompanhamento. |
|
Fluxo recomendado |
1) Procurar ou criar fornecedor. 2) Manter contactos e acordos. 3) Associar serviços e SLAs. 4) Anexar documentação. 5) Registar rastreios de acompanhamento. |
|
Benefício para o utilizador |
Permite conectar a governação de terceiros, compras e risco operacional, evitando que as equipas mantenham dados de fornecedores em silos separados. |
|
Método |
Endpoint |
Uso orientativo |
|
GET |
/suppliers |
Consultar fornecedores existentes. |
|
POST |
/suppliers |
Criar um fornecedor. |
|
PUT |
/suppliers/{modelId} |
Atualizar informações do fornecedor. |
|
GET |
/suppliers/{modelId}/agreements |
Consultar acordos do fornecedor. |
|
POST |
/suppliers/{modelId}/contacts |
Criar contactos associados. |
|
POST |
/suppliers/{modelId}/files |
Anexar documentação. |
|
GET |
/suppliers/{modelId}/services |
Consultar serviços relacionados. |
|
POST |
/suppliers/{modelId}/slas |
Criar SLAs do fornecedor. |
|
POST |
/suppliers/{modelId}/tracings |
Registar acompanhamentos ou rastreios. |
|
Recomendação
|
7. Gerir evidências e conformidade a partir de repositórios externos
|
Objetivo de negócio |
Automatizar o carregamento ou atualização de evidências e a sua associação com controlos, papéis ou empregados responsáveis. |
|
Exemplo de cenário |
Um repositório documental, ferramenta de auditoria ou solução de compliance gera evidências que devem ser vinculadas com controlos geridos no GlobalSuite. |
|
Fluxo recomendado |
1) Consultar tipos de evidência. 2) Criar ou atualizar evidência. 3) Anexar ficheiros, se necessário. 4) Associar a evidência a controlos e responsáveis. 5) Rever rastreabilidade e permissões. |
|
Benefício para o utilizador |
Melhora a preparação de auditorias e reduz a perda de evidências dispersas em pastas ou ferramentas não conectadas. |
|
Método |
Endpoint |
Uso orientativo |
|
GET |
/evidenceTypes |
Consultar tipos de evidência. |
|
GET |
/evidences |
Procurar evidências existentes. |
|
POST |
/evidences |
Criar uma evidência. |
|
PUT |
/evidences/{modelId} |
Atualizar uma evidência. |
|
POST |
/evidences/{modelId}/files |
Anexar ficheiros à evidência. |
|
POST |
/evidences/{modelId}/controls/{objectId} |
Associar evidência a um controlo. |
|
POST |
/evidences/{modelId}/roles/{objectId}/employees/{employeeId} |
Atribuir empregados a papéis relacionados com a evidência. |
|
Recomendação
|
8. Manter utilizadores, empregados e papéis alinhados
|
Objetivo de negócio |
Garantir que as pessoas e papéis usados no GlobalSuite estão alinhados com fontes corporativas de identidade ou recursos humanos. |
|
Exemplo de cenário |
RH ou IAM mantém registos de entrada, saída e alterações de empregados. O GlobalSuite necessita desses dados para responsáveis, permissões, filtros, aprovações ou atribuições em módulos funcionais. |
|
Fluxo recomendado |
1) Consultar empregados e utilizadores existentes. 2) Criar ou atualizar registos. 3) Rever papéis e atribuições. 4) Gerir saídas de forma controlada. |
|
Benefício para o utilizador |
Evita desalinhamentos entre pessoas reais, responsáveis funcionais e utilizadores registados no GlobalSuite. |
|
Método |
Endpoint |
Uso orientativo |
|
GET |
/users |
Consultar utilizadores da aplicação. |
|
POST |
/users |
Criar utilizadores se o fluxo definido o permitir. |
|
PUT |
/users/{modelId} |
Atualizar dados de um utilizador. |
|
GET |
/employees |
Consultar empregados. |
|
POST |
/employees |
Criar empregados. |
|
PUT |
/employees/{modelId} |
Atualizar dados de um empregado. |
|
GET |
/configRoles |
Consultar roles configurados. |
|
Recomendação
|
Design recomendado de uma integração
Para passar de um caso de uso para uma integração estável, recomenda-se seguir uma abordagem incremental:
-
Definir o objetivo funcional: que dado se quer consultar, criar, atualizar ou relacionar e por que traz valor ao processo.
-
Identificar o sistema mestre de cada dado: por exemplo, CMDB para ativos técnicos, compras para fornecedores ou IAM para utilizadores.
-
Revisar o modelo no Swagger: campos obrigatórios, parâmetros, exemplos de resposta, erros e relações disponíveis.
-
Preparar o mapeamento de dados: equivalências entre campos do sistema de origem e campos do GlobalSuite, incluindo catálogos, dimensões e valores configuráveis.
-
Validar permissões e alcance da API Key: entidade, subentidade, vigência, operações permitidas e dados visíveis.
-
Testar com um subconjunto reduzido: poucos registos, ambiente de demonstração e validação funcional por utilizadores-chave.
-
Incorporar controlos técnicos: paginação, tentativas, tratamento de erros 403/429, logs e alertas de integração.
-
Documentar a integração: responsável, frequência, endpoints usados, regras de deduplicação, sistema mestre e procedimento em caso de erros.
|
Padrão recomendado
|
Boas práticas de exploração
|
Prática |
Por que é importante |
|
Uma API Key por integração |
Facilita rastreabilidade, revogação e controlo de limites. Evita reutilizar a mesma chave para processos com finalidades distintas. |
|
Rotação periódica de chaves |
Planear renovação antes da data de expiração para evitar interrupções. |
|
Controlo do rate limit |
Agrupar chamadas, paginar corretamente e espaçar processos batch para não exceder 180 chamadas por minuto por API Key. |
|
Não automatizar DELETE sem validação |
As eliminações ou desassociações devem requerer controlos adicionais ou fluxos de aprovação. |
|
Registar rastreabilidade |
Guardar em logs o que foi enviado, quando, por qual endpoint e qual foi a resposta. |
|
Desenhar regras de deduplicação |
Antes de criar registos, procurar correspondências por identificadores funcionais. |
|
Validar catálogos e configuração |
Não assumir que categorias, campos, dimensões ou tipos de ticket são iguais em todos os clientes. |
|
Gerir erros de negócio |
Distinguir erros de autenticação, permissões, limites, validação de dados e recursos não encontrados. |
Mapa de áreas funcionais e endpoints
A tabela seguinte resume as áreas funcionais identificadas no guia comercial e mostra exemplos de endpoints que podem ser revisados no Swagger. Não é um catálogo exaustivo de parâmetros nem de respostas.
|
Área funcional |
N.º ops. |
Exemplos de endpoints |
|
Utilizadores e segurança de conta |
5 |
GET /users, POST /users, GET /users/{modelId}, DELETE /users/{modelId}... |
|
Tickets |
28 |
GET /tickets, POST /tickets, GET /tickets/{modelId}, PUT /tickets/{modelId}... |
|
Ativos (inventário) |
32 |
GET /assetAttributes, GET /assetAttributes/{modelId}, GET /assets, POST /assets... |
|
Análise de riscos |
23 |
GET /analysis/{modelId}/assets, POST /analysis/{modelId}/assets/{assetId}/controls/{controlId}/calculateRequest, POST /analysis/{modelId}/assets/{assetId}/threats/{threatId}/calculateRequest, GET /analysis/{modelId}/assets/{assetId}/threats/{threatId}/controls... |
|
BIA, inquéritos e cálculos de impacto |
3 |
POST /calculateAccumulatedMtpd, POST /calculateImpactedMtpd, POST /calculateImpactedRto |
|
Processos, serviços e consolidação |
12 |
GET /processes, GET /processes/{modelId}, GET /processes/{modelId}/employees, GET /processes/{modelId}/inputActionOutput... |
|
Empregados e roles |
12 |
GET /configRoles, GET /employees, POST /employees, GET /employees/{modelId}... |
|
Empresas |
5 |
POST /companies/copyCompany, GET /companies/{modelId}/analysis, PUT /companies/{modelId}/analysis, GET /companies/{modelId}/roles... |
|
Conformidade ENS e avaliações |
17 |
PUT /controls/{modelId}, GET /evidenceTypes, GET /evidences, POST /evidences... |
|
Dashboards |
1 |
GET /dashboard/{modelId}/updatedDate/{objectId} |
|
Relatórios, métricas e projetos |
1 |
DELETE /testplans/{modelId}/processes/{objectId} |
|
Fornecedores |
30 |
GET /suppliers, POST /suppliers, PUT /suppliers/{modelId}, GET /suppliers/{modelId}... |
|
Catálogos e árvore de riscos |
1 |
GET /risks |
|
Configuração, metodologia e regras |
11 |
GET /connectionsPrefixes, GET /controlLevels, GET /controlLevels/{modelId}, GET /methodologies/{modelId}... |
Ajuda e referências
-
A documentação Swagger deve ser a referência final para parâmetros obrigatórios, estrutura do corpo da requisição, respostas e erros.
-
Antes de utilizar a API, é recomendável revisar o Manual do Utilizador do GlobalSuite para entender a lógica funcional do módulo que será integrado.
-
Se um endpoint não responder como esperado, validar primeiro a API Key, ambiente, entidade/subentidade, permissões, rate limit e dados de teste.
-
Para dúvidas ou incidentes, canalizar a consulta através do fornecedor ou do Centro de Suporte a Clientes do GlobalSuite.
Links de referência: