Spanish English German Portuguese
Spanish English German Portuguese

GlobalSuite API: casos de uso

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
A API não deve ser entendida apenas como uma lista de endpoints técnicos. Cada endpoint representa uma capacidade funcional do GlobalSuite: inventário, riscos, tickets, fornecedores, evidências, processos, serviços, utilizadores ou configuração.

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
Testar sempre num ambiente de demo ou laboratório antes de conectar sistemas produtivos. O primeiro objetivo não deve ser automatizar tudo, mas validar um fluxo pequeno e controlado com dados representativos.

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
Em ativos e tickets podem existir campos ou estruturas configuráveis. O mapeamento de dados deve ser validado com a configuração concreta do cliente e com a documentação Swagger do ambiente.

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
A API de tickets é ampla porque depende de tipos configuráveis, permissões, relações e campos dinâmicos. Convém começar por um único tipo de ticket e expandir depois.

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
As operações de cálculo devem ser tratadas como processos de negócio. Antes de automatizá-las, é recomendável validar quando devem ser executadas e quais dados serão modificados ou recalculados.

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
Esses cálculos dependem da configuração funcional do BIA. Devem ser testados com dados controlados antes de automatizar execuções em massa.

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
Convém definir qual sistema é o principal para cada dado. A API deve sincronizar informações, não gerar conflitos entre fontes.

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
Antes de criar fornecedores de forma automática, definir regras de deduplicação: NIF/CIF, DUNS, nome normalizado, país, grupo empresarial ou outros identificadores disponíveis.

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
A integração deve respeitar permissões, sensibilidade documental e critérios de validade das evidências.

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
Se for usado SCIM ou outro fluxo de identidade, a API deve ser considerada como complemento e não como mecanismo paralelo que gere incoerências.

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:

  1. Definir o objetivo funcional: que dado se quer consultar, criar, atualizar ou relacionar e por que traz valor ao processo.

  2. Identificar o sistema mestre de cada dado: por exemplo, CMDB para ativos técnicos, compras para fornecedores ou IAM para utilizadores.

  3. Revisar o modelo no Swagger: campos obrigatórios, parâmetros, exemplos de resposta, erros e relações disponíveis.

  4. 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.

  5. Validar permissões e alcance da API Key: entidade, subentidade, vigência, operações permitidas e dados visíveis.

  6. Testar com um subconjunto reduzido: poucos registos, ambiente de demonstração e validação funcional por utilizadores-chave.

  7. Incorporar controlos técnicos: paginação, tentativas, tratamento de erros 403/429, logs e alertas de integração.

  8. 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
Em integrações de alta criticidade, utilizar primeiro GET para validar o estado atual, depois POST apenas se o registo não existir e PUT unicamente quando o registo objetivo tiver sido confirmado. Este padrão reduz duplicados e atualizações indesejadas.

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:

Swagger demo Europa

Manual do Utilizador GlobalSuite

Changelog GlobalSuite