--- title: API slug: api docTags: createdAt: 2026-10-23T17:04:30.431Z --- ## API e contas de integração ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/M_4OVM2m8kMRFQxW5UkSL_image.png" size="137" isUploading="false" width="1366" height="860" darkWidth="1366" darkHeight="860" showCaption="false"} Tela: API e contas de integração (1/2) ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/w1Wnedfzd0LAsWa0nZDTk_image.png" size="137" isUploading="false" width="1366" height="860" darkWidth="1366" darkHeight="860" showCaption="false"} Tela: API e contas de integração (2/2) Tudo o que você vê e faz no Hive está disponível na API REST (OpenAPI 3.1, /api/v1 ). Outras plataformas usam uma **conta de integração** com um token enviado como Authorization: Bearer \ . As contas ficam em **Integrações › Central de integrações › API e contas de integração **(pede permissão para administrar a API); a documentação de todas as rotas está em **Documentação da API (Swagger)**. ### O que você pode fazer aqui Criar uma conta de integração por plataforma, escolhendo os domínios de dados, o modo, a validade do token, IPs permitidos, mTLS e um limite de chamadas. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/jMiALMygJtNrNld9lI4WA_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} Trocar (rotacionar) ou revogar um token. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/SMHMTVfGGMM1uBDZf96Qh_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} Ligar o **Webhook de CI** de uma conta, pausá-lo, trocar o segredo e reenviar entregas. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/HtX5Y7nthpeYObna1JhWe_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} Navegar e experimentar todas as rotas na **Documentação da API** e baixar o openapi.json . ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/rTzxQl8mJjPItM04TAai6_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} ### Criar uma conta de integração Clique em **Nova conta de integração**. Dê à conta um nome com letras minúsculas, números e hífens, como cmdb-servicenow , e diga para que serve. O nome aparece na trilha de auditoria de cada chamada. Escolha os **Domínios de dados** que a conta pode usar: Ativos e detalhes, Software e uso, Relacionamentos e mapas, Rede, Nuvem/virtualização/Kubernetes, Contratos e licenças, Vulnerabilidades e insights, Alertas e eventos, Chamados e mudanças, Relatórios, Trilha de auditoria, Pessoas e identidade, Sinal de confiança do dispositivo, Telemetria (OpenTelemetry) e Plano de controle do provedor. Escolha o **Modo**: **Somente leitura (recomendado)** ou **Leitura e envio **(necessário para importar ativos, mudar alertas ou enviar chamados e mudanças). Se quiser, escolha o **Modelo de CMDB das respostas** (modelo do Hive, ServiceNow CSDM ou DMTF CIM) e um **Webhook para avisos de mudança** (https). Escolha a **Validade do token** (90, 180 ou 365 dias) e, se quiser, os **IPs permitidos** (faixas como 198.51.100.0/24), **Exigir certificado do cliente (mTLS)** e o **Limite de chamadas por minuto** (padrão 600; acima dele a API responde 429 com Retry-After). Clique em **Criar conta e gerar token**. **Copie o token agora**: ele aparece uma única vez, e o Hive guarda só uma impressão digital dele. **Testar o token agora** confere; **Exemplo de chamada** mostra uma requisição pronta. ### A lista de contas Colunas: **Conta de integração**, **Pode acessar**, **Modo**, **Token** (vencimento; aviso 15 dias antes),**Último uso** e **Webhook de CI** (ligado, configurar ou pausado). **Trocar token** cria um token novo (válido por 365 dias); o antigo continua funcionando por 7 dias para a outra plataforma se atualizar e depois vence sozinho. Nesse período a linha mostra "Dois tokens valendo durante a troca (7 dias)." ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/q6AtTFx_wXdQ3xUprtBct_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} **Revogar** para todas as chamadas na hora e não pode ser desfeito; para conectar de novo, crie uma conta nova. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/2Cj6SjJ8YVxRMTLQ6k8qM_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} **Webhook de CI**: **Endereço que recebe**, **Ligar webhook**, **Pausar**/**Retomar**, **Trocar segredo**, **Enviar teste** e as entregas com **Enviar de novo**. Valide X-Hive-Signature : HMAC-SHA256 de "timestamp.corpo" com o segredo mostrado uma vez. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/TNrTRcB-xvF-BZh0CU079_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} A mesma aba tem **Popular a CMDB da sua plataforma**, as **Rotas de entrada (POST)** e o **Proxy de leitura (opcional)**, um pequeno programa na DMZ que serve só rotas GET. ### Documentação da API **Documentação da API (Swagger)** abre a documentação de todas as rotas, agrupadas por área, com parâmetros, corpos e respostas (pede permissão de leitura de integrações ou de administração da API). Use a caixa de filtro para achar uma área (tag). ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/Gx8HRceia-P-LtTzZzLGS_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} **Try it out** chama a API com **a sua sessão**, com as suas permissões. Por padrão só dá para experimentar GET; marque **Permitir experimentar POST, PUT, PATCH e DELETE** e confirme para rodar requisições de escrita de verdade (elas vão para a auditoria). ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/FJFTxnTli1APTdXKmLrxP_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} **Baixar openapi.json** salva o contrato para importar no Postman ou no Bruno. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/X3oXPUfnN4zY8FrvmKhuu_image.png" size="10" isUploading="false" width="16" height="16" darkWidth="16" darkHeight="16" showCaption="false"} **Exemplo prático: conta somente leitura para o CMDB do ServiceNow** 1. **API e contas de integração › Nova conta de integração**. **Nome da conta**cmdb-servicenow , **Para que serve** "Sincronização noturna do CMDB". 2. **Domínios de dados** Ativos e detalhes, Software e uso, Relacionamentos e mapas; **Modo **somente leitura; **Modelo de CMDB das respostas** ServiceNow CSDM. 3. **Validade do token** 365 dias, **IPs permitidos**198.51.100.0/24 (a faixa do MID server do ServiceNow), limite 600. 4. **Criar conta e gerar token**, **Copiar token**, **Testar o token agora**: "O token funciona: o Hive reconheceu a conta de integração." Clique em **Copiei o token — fechar**. 5. O ServiceNow chama GET /api/v1/cis?changed\_since=0\&limit=500 com Authorization: Bearer hive\_tk\_… . Uma chamada de outro IP é recusada. 6. Onze meses depois a linha mostra o aviso de vencimento. Clique em **Trocar token** e passe o token novo ao administrador do ServiceNow; o antigo para sozinho 7 dias depois. **Exemplo prático: achar e experimentar uma rota na documentação** 1. **Documentação da API (Swagger)**, filtre alerts . 2. Abra GET /api/v1/alerts , **Try it out**, digite asset=\ e **Execute**: a resposta mostra os alertas abertos daquela máquina, com a duração da requisição. 3. Para testar POST /api/v1/assets/lookup , marque **Permitir experimentar POST, PUT, PATCH e DELETE**, confirme com **Permitir** e execute; a chamada fica na auditoria com o seu nome. 4. Clique em **Baixar openapi.json** e importe no Bruno para a equipe de integração. ### Cuidados e limites | :inlineImage[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/3PuL4LwT1hYZGeuqnpFvm_image.png" alt caption size="10" width="16" height="16"} | O limite vale por conta e por nó do núcleo; as respostas trazem RateLimit-Limit , RateLimit- | | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | Remaining e RateLimit-Reset . Uma conta revogada não pode ser restaurada. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/n_qzzFI4rISiJkHL4QZzA_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} Criar, trocar e revogar pedem permissão para administrar a API. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/9RvQi0hhzqFzXG_WHS9bQ_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} Pelo proxy de leitura só funcionam contas somente leitura. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/HVWNzOP4QoSdgiYZYe3CK_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} O endereço do webhook precisa ser https público; endereços privados são recusados. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/z6S_fPVE0kSaT3Aubk0Ie_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} Não há OAuth para contas de integração. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/Dvxg0WA_tHyotCA9bdNjp_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} ### Relacionados Popule seu CMDB em 3 passos ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/H0P4D7S5SG7NdTHlMMwuO_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} Integrar com o GRCS ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/okWjP_3Qtu3FNBRzxlRpb_image.png" size="10" isUploading="false" width="16" height="12" showCaption="false"} Grafana e Power BI ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/v2BGfCrhi9H_AhLvtgUsK_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} Chamados de ITSM, CMDB e mudanças aprovadas ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/81qubNzyAzNu-yVOhPTRR_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} ### Popule seu CMDB em 3 passos Qualquer plataforma pode manter seu CMDB igual ao Hive sem conector dedicado: uma carga inicial, depois só o que mudou, depois avisos de mudança. Tudo usa uma **conta de integração** criada em **Integrações › Central de integrações › API e contas de integração**, com o escopo **Ativos e detalhes** (e **Software e uso** para incluir o software instalado). ### O que você pode fazer aqui Exportar todos os itens de configuração (ICs) de uma vez, no modelo do Hive, ServiceNow CSDM ou DMTF CIM. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/b7uyCXhcVPmsVKgnfVXIW_image.png" size="10" isUploading="false" width="16" height="16" darkWidth="16" darkHeight="16" showCaption="false"} ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/84E47Y-V9KDbf7TgJH0ND_image.png" size="35" isUploading="false" width="352" height="48" darkWidth="352" darkHeight="48" showCaption="false"} ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/Wiyu73GAgZAKW8h-HWcpu_image.png" size="118" isUploading="false" width="1184" height="52" darkWidth="1184" darkHeight="52" showCaption="false"} Ler só o que mudou desde a última leitura, incluindo os itens removidos. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/mdK3eViT9QutGEHEk95On_image.png" size="10" isUploading="false" width="16" height="16" darkWidth="16" darkHeight="16" showCaption="false"} Receber um POST assinado para cada IC criado, alterado ou removido. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/v8c0qit54n1fX2uebOLpP_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} 1. **Carga inicial** GET /api/v1/cis/export?model=hive|csdm|cim\&include=software devolve todos os ICs ativos em NDJSON (um IC por linha), no arquivo hive-cis.ndjson . Ou leia em páginas: GET /api/v1/cis?limit=500 e depois GET /api/v1/cis?cursor=\ até hasMore ser false. limit vai até 2000. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/-HLPe6UwXgyUY0-mw24Gu_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} Cada item tem id , class , removed , updatedAt , attributes e, quando pedido, relationships . O modelo vem da conta (**Modelo de CMDB das respostas**) ou de model= . ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/KM9TSq3zQ0_jTcaXhPhDr_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} 2. **Só o que mudou** A última página de uma leitura traz o syncToken . Guarde. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/AMyLhQBmAt0B6GHff6Jw5_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} Na próxima vez chame GET /api/v1/cis?changed\_since=\ : vêm só os ICs novos e alterados, e os aposentados com removed: true . Pagine com cursor como antes e guarde o novo syncToken . ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/WVd48blNUnhtDXZqhqpk7_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} changed\_since=0 (ou sem o parâmetro) é uma leitura completa. 3. **Avisos de mudança** Em vez de consultar, ligue o **Webhook de CI** da conta (coluna **Webhook de CI** › **Configurar**, ou **Webhook para avisos de mudança** no assistente). O Hive faz POST de ci.created , ci.updated e ci.removed com o corpo \{type, occurredAt, ci} e os cabeçalhos X-Hive-Event , X-Hive-Delivery , X-Hive-Timestamp e X-Hive-Signature: sha256=\ . Falhas são tentadas de novo de 30 s até 12 h. As mudanças também podem ir para um barramento de eventos (Kafka, RabbitMQ, Service Bus, SNS, Pub/Sub). ### Ferramentas Baixe o contrato com **Baixar openapi.json** (ou abra **Documentação da API (Swagger)**) e importe no Postman ou no Bruno para ter a coleção completa. Toda chamada usa Authorization: Bearer \ . ### Exemplo prático: carga no ServiceNow CSDM e delta toda noite 1. Crie a conta de integração cmdb-servicenow : **Domínios de dados** Ativos e detalhes e Software e uso, **Modo** Somente leitura, **Modelo de CMDB das respostas** ServiceNow CSDM. Copie o token. 2. Carga inicial: \`\` curl -H "Authorization: Bearer hive\_tk\_…" "https\://hive.centralit.com.br/api/v1/cis/export?include=software" -o hive-cis.ndjson \` Chegam 4.180 linhas, com classes como cmdb\_ci\_server , cmdb\_ci\_vm\_instance , cmdb\_ci\_computer e cmdb\_ci\_netgear , e relações "Installed on\::Installs" com cmdb\_ci\_spkg\`. 3. Leia uma vez com GET /api/v1/cis?limit=2000 até hasMore ser false e guarde o syncToken da última página. 4. Na noite seguinte: GET /api/v1/cis?changed\_since=\\&limit=2000 devolve 23 itens: 20 alterados, 2 novos e o NB-OLD-17 com removed: true (foi aposentado). A rotina o marca como aposentado no CMDB e guarda o novo token. 5. Depois, a equipe liga o webhook de CI para https\://centralit.service-now\.com/api/x\_hive/ci : cada mudança chega em segundos, assinada; o receptor confere X-Hive-Signature com o segredo mostrado uma vez. ### Cuidados e limites Um sync token inválido devolve 422 ( invalid-sync-token ); recomece com uma leitura completa. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/IAcbt2HLIYeqVIkETGk_c_image.png" size="10" isUploading="false" width="16" height="16" darkWidth="16" darkHeight="16" showCaption="false"} A exportação não é retomável; para bases muito grandes, leia em páginas com cursor . ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/CuoxUEl6KXq-6qIvw8A4G_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} Os eventos do webhook vão só para contas com o escopo de ativos, a partir do momento em que ele é ligado (sem histórico anterior), e só para os ativos assinados quando a conta tem uma lista. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/R47LiNvU0FLySKUEsbcOB_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} O endereço do webhook precisa ser https público. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/QeZqUSoDUUdbpbp9KPMs4_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} O contrato ( /api/openapi.json ) pede login, a não ser que o administrador tenha deixado a documentação da API pública. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/QefPQ3Dhtte0J06kipcvZ_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} ### Relacionados API e contas de integração ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/f2jUFFmTyCrW_PJVo3-Lg_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} Integrar com o GRCS ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/X51NSJVQWLUHJ7bvuFUC6_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} Chamados de ITSM, CMDB e mudanças aprovadas ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/C_vhAJHybgoHq04UnUUqx_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} ### Integrar com o GRCS O GRCS traz do Hive só os ativos que têm um risco ativo ou uma não conformidade aberta: o cadastro do ativo, as vulnerabilidades abertas, os alertas abertos, os serviços de negócio e a avaliação dos controles com evidência. Ele usa uma conta de integração e a API REST; o cartão **GRCS** em **Integrações › Central de integrações › Catálogo** (categoria GRC e risco) abre o assistente da conta com os escopos certos. ### O que você pode fazer aqui Criar a conta de integração do GRCS com webhook e limite de chamadas. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/sS4hdI8kmrZyhmpsawUxS_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} Vincular cada alvo do GRCS a um ativo do Hive pelos identificadores. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/1pz4TychOXsYAfINarYFH_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} Assinar a conta nos ativos que importam, por id ou tag. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/AdEmWbILuEBZydjXTqtPY_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} Ler ativos, achados, alertas, serviços de negócio e conformidade em lotes, e receber eventos. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/e7dwVMN67wnryPE4nndqZ_image.png" size="10" isUploading="false" width="16" height="16" darkWidth="16" darkHeight="16" showCaption="false"} 1. **Conta de integração** Em **Central de integrações › API e contas de integração**, clique em **Nova conta de integração** (ou **Conectar** no cartão do GRCS). Escolha os **Domínios de dados** Ativos e detalhes, Vulnerabilidades e insights, Alertas e eventos e Relatórios; **Modo** Somente leitura (escolha Leitura e envio só se o GRCS gravar a referência dele de volta). Preencha **Webhook para avisos de mudança (opcional)** e o **Limite de chamadas por minuto**. O token aparece uma vez. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/x9sLdOSQOdu3cStONVedO_image.png" size="71" isUploading="false" width="712" height="52" darkWidth="712" darkHeight="52" showCaption="false"} ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/3orDIsqGhkd1PpWFCAh14_image.png" size="80" isUploading="false" width="804" height="52" darkWidth="804" darkHeight="52" showCaption="false"} ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/YUdLNpv2W-MBhqcJaoVib_image.png" size="161" isUploading="false" width="1612" height="48" darkWidth="1612" darkHeight="48" showCaption="false"} ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/XB2cBg3mvA1vQ1xg4mncL_image.png" size="60" isUploading="false" width="596" height="52" darkWidth="596" darkHeight="52" showCaption="false"} ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/gBXy7svsP1sqRkSb1gzav_image.png" size="56" isUploading="false" width="560" height="52" darkWidth="560" darkHeight="52" showCaption="false"} 2. **Vincular cada alvo do GRCS ao ativo** POST /api/v1/assets/lookup com até 500 identificadores ( id , externalRef , hwUuid , serial , fqdn , hostname , ip , ou sem tipo para tentar nesta ordem). Cada resposta diz found , none ou ambiguous (com candidatos) e qual identificador casou. O IP é o último recurso: um casamento ambíguo nunca vincula. Opcional: grave a referência do GRCS com PUT /api/v1/assets/import (fonte grcs , externalId = id do alvo; precisa de Leitura e envio). Depois, GET /api/v1/assets?externalRef=grcs:\ o encontra. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/QwVpIX9MoARl6DxLzklMk_image.png" size="10" isUploading="false" width="16" height="12" darkWidth="16" darkHeight="12" showCaption="false"} 3. **Assinar os ativos que importam** PUT , PATCH ou DELETE /api/v1/api-accounts//assets com ids de ativos ou tags (por exemplo a tag grcs ). A própria conta pode manter sua lista com o próprio token. Com uma lista, o webhook e os eventos cobrem só os ativos assinados; sem lista, tudo o que os escopos permitem. Até 5.000 ativos e 100 tags por chamada, 50.000 entradas por conta. 4. **Ler em lotes** GET /api/v1/assets//full — o ativo com hardware, software, serviços, bancos de dados e relacionamentos. GET /api/v1/vulnerabilities/findings?asset=a,b,c e GET /api/v1/alerts?asset=a,b,c — até 200 ativos por chamada; com changedSince (24h, 7d ou uma data ISO) a lista vem em ordem de mudança e a próxima página está no cabeçalho Hive-Next-Cursor . GET /api/v1/business-services?asset=a,b — os serviços de que cada ativo faz parte, o papel (componente ou dependência) e se é ponto único de falha. GET /api/v1/assets//compliance ou POST /api/v1/compliance/assets (até 200 ativos) — cada controle da ISO 27001, PCI DSS, LGPD/GDPR, HIPAA e CIS v8 que se aplica ao ativo: atendido , parcial , nao\_atendido ou na , percentual e a evidência medida com a data. 5. **Eventos** O webhook recebe vulnerability.opened , vulnerability.closed , vulnerability.risk\_changed (mudou a severidade, o KEV ou a faixa do EPSS) e compliance.changed , com subject = id do ativo e a assinatura HMAC em X-Hive-Signature , além dos eventos ci.\* . Os mesmos eventos podem ir para um barramento de eventos filtrado por uma tag de ativo. ### Exemplo prático: o GRCS acompanha 40 servidores críticos 1. **Catálogo › GRCS › Conectar**: o assistente abre com os escopos escolhidos. Nome grcs , webhook https\://grcs.centralit.com.br/hooks/hive , limite de 600 por minuto. Copie o token e o segredo do webhook. 2. O GRCS envia seus 40 alvos: POST /api/v1/assets/lookup com \{"identifiers":\[\{"value":"SRV-ERP-01"},\{"type":"serial","value":"CZ1234ABC"},…]} . 38 voltam found , 1 none e 1 ambiguous com dois candidatos (o analista escolhe o id certo). 3. Marque os 39 ativos com a tag grcs no Hive e assine: PUT /api/v1/api-accounts/\/assets com \{"tags":\["grcs"]} . 4. Toda noite: GET /api/v1/vulnerabilities/findings?asset=\<39 ids>\&changedSince=24h , seguindo o Hive- Next-Cursor até ele sumir; depois POST /api/v1/compliance/assets com \{"assets": | \[…],"framework":"iso27001"} . | | ------------------------------ | 5. Durante o dia, uma vulnerabilidade KEV nova no SRV-ERP-01 manda vulnerability.opened ao webhook; o GRCS abre o risco com a evidência. ### Cuidados e limites Acima do limite da conta a API responde 429 com Retry-After ; toda resposta traz RateLimit-Limit , RateLimit-Remaining e RateLimit-Reset . O limite vale por nó do núcleo. Aqui o parâmetro é changedSince ; a rota de ICs usa changed\_since . ### Relacionados API e contas de integração ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/6SZbOQ6nz4cMc-0BtsLVY_image.png" size="10" isUploading="false" width="16" height="16" darkWidth="16" darkHeight="16" showCaption="false"} Popule seu CMDB em 3 passos ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/FW3inGDupqiF2f9rAWhf9_image.png" size="10" isUploading="false" width="16" height="16" darkWidth="16" darkHeight="16" showCaption="false"} Conformidade e hardening ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/lPZLe0MCyxG631jmuV-Vs_image.png" size="10" isUploading="false" width="16" height="16" darkWidth="16" darkHeight="16" showCaption="false"} Vulnerabilidades ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/5Nz4fHeXDO0p4hSIffliT_image.png" size="10" isUploading="false" width="16" height="16" darkWidth="16" darkHeight="16" showCaption="false"} ### Grafana e Power BI ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/Snjha0WUVnEJGCvW86Mbm_image.png" size="137" isUploading="false" width="1366" height="860" darkWidth="1366" darkHeight="860" showCaption="false"} Tela: Grafana e Power BI O Hive serve conjuntos de dados prontos para ferramentas de BI em /api/v1/bi , só leitura: JSON simples para o **Grafana** e um feed **OData v4** para o **Power BI**. Os dois usam o token de uma conta de integração ( Authorization: Bearer \ ), e cada conjunto confere a permissão de leitura do seu domínio, então uma conta vê só o que os escopos dela permitem. Os cartões **Grafana** e **Power BI** em **Integrações › Central de integrações › Catálogo** (categoria **BI**) criam essa conta para você. ### O que você pode fazer aqui Criar com um clique, pelo catálogo, uma conta somente leitura para o Grafana ou o Power BI. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/10j1slicLn3rHIrckFDrD_image.png" size="10" isUploading="false" width="16" height="12" darkWidth="16" darkHeight="12" showCaption="false"} Listar os conjuntos disponíveis para a conta e lê-los em JSON ou OData. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/1jTSKdCtbs1s7WOUVRzuf_image.png" size="10" isUploading="false" width="16" height="16" darkWidth="16" darkHeight="16" showCaption="false"} Montar painéis do Grafana com séries no tempo ( from / to do painel) e relatórios do Power BI que se atualizam pelo feed. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/op6vq0fdjPviXC35aT-gF_image.png" size="10" isUploading="false" width="16" height="16" darkWidth="16" darkHeight="16" showCaption="false"} ### Conjuntos de dados | **Conjunto (JSON)** | **Entity set OData** | **O que tem** | **Pede o escopo** | | --------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------ | | assets | Assets | id, name, hostname, type, osFamily, os, osVersion, vendor, model, serial, site, user, status, firstSeen, lastSeen | Ativos | | assets-by-type | AssetsByType | type, assets (ativos) | Ativos | | alerts-by-severity | AlertsBySeverity | severity, alerts (abertos), sempre 4 linhas | Alertas | | alerts-open-over-
time | OpenAlertsOverTime | time, critical, major, warning, info, total | Alertas | | vulnerabilities-by-
severity | VulnerabilitiesBySeverity | severity, findings, cves, assets | Vulnerabilidades | | patch-compliance | PatchCompliance | status (compliant, missing-security, missing-other, not-scanned), assets, percent | Ativos | | license-usage | LicenseUsage | product, edition, metric, acquired, consumed, inUse, balance, status | Ativos ou
Contratos | Todo conjunto respeita o escopo de ativos do perfil (sites, tags, grupos) de quem chama. ### JSON para o Grafana GET /api/v1/bi lista os conjuntos com título, colunas, a permissão, se está **disponível** para quem chama e os caminhos. GET /api/v1/bi/\ devolve uma lista JSON de linhas. from e to : milissegundos do Grafana ( $ , $ ) ou ISO 8601; padrão os últimos 7 dias. interval : 5m, 15m, 1h, 6h ou 1d; sem ele, até 2 dias → 15m, até 31 dias → 1h, mais → 1d (no máximo 5000 pontos). limit (padrão 1000, até 10000) e offset ; a próxima página está no cabeçalho Link: \<…>; rel="next" . ### OData para o Power BI Documento de serviço: GET /api/v1/bi/odata ; metadados: GET /api/v1/bi/odata/$metadata ; dados: GET /api/v1/bi/odata/\ . ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/A5IUZiRn7J1b0GZuR868m_image.png" size="10" isUploading="false" width="16" height="16" darkWidth="16" darkHeight="16" showCaption="false"} Opções de consulta: $select , $top , $skip , $count e $format . O servidor pagina de 1000 linhas por vez com @odata.nextLink . $filter e $orderby são recusados ("Filtre e ordene no Power Query depois de carregar os dados"). ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/q0hBakB89ElOMpwEPph_7_image.png" size="10" isUploading="false" width="16" height="16" darkWidth="16" darkHeight="16" showCaption="false"} Conjuntos que a conta não pode ler ficam fora do documento de serviço e do $metadata . ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/mawidVOtTbY4y2FNbArpN_image.png" size="10" isUploading="false" width="16" height="16" darkWidth="16" darkHeight="16" showCaption="false"} ### Exemplo prático: painel do Grafana com ativos por site 1. **Catálogo › BI › Grafana › Conectar**. O assistente **Nova conta de integração** abre com grafana , somente leitura e os escopos Alertas, Ativos e Vulnerabilidades. Crie e copie o token. 2. No Grafana, instale o plugin de fonte de dados **Infinity** e adicione uma fonte: URL https\://hive.centralit.com.br , cabeçalho Authorization = Bearer hive\_tk\_… (como cabeçalho seguro). 3. Painel novo, consulta do tipo JSON, URL /api/v1/bi/assets?limit=10000 . Aparecem as colunas: name, type, site, status… 4\. Adicione a transformação **Group by**: agrupe por site e calcule id → Count. Escolha um gráfico de barras: São Paulo 1.240, Rio de Janeiro 610, Recife 180. 4. Segundo painel: URL /api/v1/bi/alerts-open-over-time?from=$\&to=$ , uma série no tempo com critical, major, warning e info. Mudar o período do painel para 30 dias passa os pontos para 1 hora. ### Exemplo prático: feed OData do Power BI com uma conta de API 1. **Catálogo › BI › Power BI › Conectar**, crie a conta powerbi e copie o token. Se o financeiro também precisa de licenças, elas já vêm pelo escopo de Ativos. 2. No Power BI Desktop: **Obter dados › Consulta nula** e, no editor avançado: \`\` = | OData.Feed("https\://hive.centralit.com.br/api/v1/bi/odata", \[Authorization="Bearer hive\_tk\_…"], | | --------------------------------------------------------------------------------------------------- | \[Implementation="2.0"]) \`\` 3\. O navegador lista Assets, AssetsByType, AlertsBySeverity, OpenAlertsOverTime, VulnerabilitiesBySeverity, PatchCompliance e LicenseUsage. Carregue **LicenseUsage** e **PatchCompliance**. 4. Filtre no Power Query (por exemplo status \<> "compliant" ); um $filter no endereço seria recusado. 5. Monte o relatório "Licenças: adquiridas × em uso" com product , acquired e inUse . Cada atualização lê o feed de novo, página por página. ### Cuidados e limites Só o token Bearer é aceito: sem usuário e senha (Basic) e sem token no endereço. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/2vAq7JR2B6MNMkSThHxg0_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} Um conjunto sem a permissão responde 403 ("This account cannot read this dataset."); sem token, 401. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/TyA6-Qs-4SoWvrxQSOjfY_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} O limite de chamadas da conta vale (padrão 600 por minuto); painéis grandes do Grafana contam cada painel. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/CaoZpFbFBYa9AcZDnfftH_image.png" size="10" isUploading="false" width="16" height="16" showCaption="false"} As rotas de BI também podem ser servidas pelo proxy de leitura na DMZ, com uma conta somente leitura. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/71bvOma7gfncFXN_k1eU9_image.png" size="10" isUploading="false" width="16" height="12" darkWidth="16" darkHeight="12" showCaption="false"} As telas do Power BI e do Grafana não fazem parte do Hive; os nomes dos menus delas podem mudar entre versões. ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/5aeUbm5tYUSvokcd_Wcva_image.png" size="10" isUploading="false" width="16" height="16" darkWidth="16" darkHeight="16" showCaption="false"} ### Relacionados API e contas de integração ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/zNujt22EsUzWYYUrFtCAV_image.png" size="10" isUploading="false" width="16" height="16" darkWidth="16" darkHeight="16" showCaption="false"} Relatórios e painéis ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/1rFPgQ0tUPH6Bm27WArFu_image.png" size="10" isUploading="false" width="16" height="16" darkWidth="16" darkHeight="16" showCaption="false"} Central de integrações ::Image[]{src="https://api.archbee.com/api/optimize/pu5VMc-2TW3GQX4ly5Xp7/TmAKNSV1kZ_KgWDy0yP3n_image.png" size="10" isUploading="false" width="16" height="12" darkWidth="16" darkHeight="12" showCaption="false"}