13. Hub de integrações, conectores e De-Para
O hub de integrações é o ponto único onde a Empresa Exemplo S.A. cadastra cada ligação do Bússola/BSC com outro sistema: APIs, web services, bancos de dados, arquivos, SEI, SIAFI, dados abertos e canais de mensagem. Cada integração guarda a credencial cifrada, passa por uma lista de saída aprovada pelo administrador do sistema e é testada antes de ser usada.
Sobre as integrações, os conectores do BSC definem quando agir e o que fazer (avisar pessoas e canais quando um indicador sai da faixa, ou capturar dados por agenda), e o De-Para traduz o dado capturado nos objetos do BSC: realizado e meta de indicador, execução de entregas e atividades e itens de portais.
Este capítulo cobre o cadastro e o teste das integrações, cada tipo disponível, os sistemas corporativos sob demanda, o ambiente de simulação, os conectores e o De-Para com suas tabelas de equivalência. O acompanhamento das execuções está no Monitor de integrações, descrito no capítulo de dados.
13.1 Conceitos: integração, conector e De-Para
ID BSC-ITG-01
Para que serve
O hub de integrações é o lugar único onde a organização cadastra cada ligação do Bússola/BSC com um sistema de fora: SEI, SIAFI, APIs de parceiros, bancos de dados, arquivos, brokers e canais de mensagem (Microsoft Teams, Discord e WhatsApp também são tipos do hub). Ele fica num menu próprio, Integrações; o BSC apenas escolhe entre as integrações cadastradas, e ninguém digita a senha de outro sistema em outra tela.
Três peças trabalham juntas: a integração diz com quem e com que credencial o Bússola/BSC fala; o conector diz quando e para quê usar a integração (por exemplo, "atingimento abaixo de 80%" → enviar mensagem, ou capturar dado por agenda); o De-Para diz o que vira o quê, isto é, qual coluna da origem vai para qual campo de um objeto do BSC.
Quem usa: Analista de Integração de Dados; Gestor de Desempenho; Diretoria de Estratégia; Administrador do sistema.
Passo a passo
- Integrações › Integrações › veja a lista das integrações cadastradas.
- Gestão por indicadores › Configuração de conectores › veja os conectores que usam essas integrações.
- Na ficha de um conector de captura, use Abrir o De-Para para ver a tradução dos campos.
- Na ficha de uma integração, consulte Quem usa para saber quais conectores e canais dependem dela.
Figura 141 — Lista de integrações do hub
Observações
- A senha, a chave ou o token fica cifrado e nunca volta para a tela, o histórico ou uma mensagem de erro; a ficha mostra só "Definido em … por …".
- O endereço de destino precisa estar na lista de saída aprovada pelo administrador do sistema.
- Endereços internos da própria máquina, da nuvem ou dos servidores da plataforma são sempre recusados, mesmo aprovados.
- Homologação e produção do mesmo sistema são duas integrações, cada uma com seu selo de ambiente.
- Uma integração usada por um conector ativo não pode ser desativada: pause ou troque antes o conector.
13.2 Cadastrar uma integração
ID BSC-ITG-02
Para que serve
O cadastro registra o sistema de destino, o objetivo, o ambiente e os responsáveis, além do endereço e da autenticação próprios de cada tipo.
Quem usa: Analista de Integração de Dados.
Passo a passo
- Integrações › Integrações › use os filtros (tipo, direção, ambiente e situação) para conferir se a integração já existe.
- Clique em Nova integração e escolha o tipo num dos cartões, agrupados em Dados, Governo, Mensageria e API aberta.
- Em Identificação, preencha Nome (único; diga sistema, objetivo e ambiente, por exemplo "SEI — abrir processo (homologação)"), Código, Objetivo, Ambiente (homologação ou produção), unidade e pessoa responsáveis.
- Preencha Endereço, Autenticação e Avançado conforme o tipo; consulte o painel Como integrar ao lado do formulário.
- Clique em Salvar; o Bússola/BSC confere o endereço na lista de saída e recusa na hora se não estiver aprovado ou for proibido.
- Na ficha, clique em Testar e, nos tipos que leem dados, em Pré-visualizar.
Figura 142 — Nova integração: escolha do tipo por grupo
Figura 143 — Ficha da integração com Testar, Pré-visualizar e periodicidade
Observações
- A lista mostra nome, tipo, direção (captura, envio ou ambos), ambiente, último teste, quantos conectores a usam e responsável.
- O código aceita maiúsculas, números, hífen e sublinhado e não muda depois; o tipo também não muda: cadastre outra integração.
- É normal ter duas integrações do mesmo sistema (por exemplo, "SEI — abrir processo" e "SEI — consultar andamento"). Nunca troque de ambiente editando o endereço: cadastre a outra.
- "Já existe uma integração com o nome …": acrescente objetivo ou ambiente ao nome.
- "Este tipo de integração ainda não está disponível nesta versão": o tipo é de uma próxima entrega.
- O cadastro e cada alteração entram no histórico da integração.
13.3 Testar uma integração
ID BSC-ITG-03
Para que serve
O botão Testar chama o outro sistema pelo caminho de teste do tipo, passando pela lista de saída e pela guarda de endereços, e grava o resultado com data. A resposta é sempre traduzida para a linguagem do operador.
Quem usa: Analista de Integração de Dados.
Passo a passo
- Integrações › Integrações › abra a integração.
- Clique em Testar.
- Leia o resultado na ficha e na lista, por exemplo "Conectou: o outro sistema respondeu." ou "O outro sistema recusou a credencial…".
- Corrija o que for indicado e teste de novo.
Figura 144 — Resultado do teste na ficha da integração
Observações
- Resultados: funcionando (destino respondeu com sucesso); credencial recusada (confira a autenticação e substitua o segredo); caminho não existe (corrija o caminho de teste); redirecionou (o Bússola/BSC não segue redirecionamento, cadastre o endereço final); endereço não aprovado ou proibido; não respondeu a tempo, recusou a conexão ou certificado não confere (confira o serviço e os tempos em Avançado).
- Editar o endereço ou a credencial apaga o último teste: ele provou outra configuração.
- Se alguém alterar a integração enquanto um teste roda, o resultado aparece para quem testou mas não fica na ficha.
- O tipo Arquivo não tem Testar. O tipo Banco de dados testa também a conta.
- Só quem mantém integrações vê o botão Testar.
- O texto técnico do outro sistema nunca chega à tela.
13.4 Pré-visualizar os dados de uma integração
ID BSC-ITG-04
Para que serve
Os tipos que leem dados (API REST, web service SOAP e arquivo) têm o cartão Pré-visualização: ele lê os primeiros 50 registros como a integração está configurada e mostra os nomes dos campos encontrados, para conferir o caminho dos registros, o elemento que se repete ou o leiaute antes de uma carga ou de um De-Para.
Quem usa: Analista de Integração de Dados.
Passo a passo
- Integrações › Integrações › abra a integração.
- No cartão Pré-visualização, para arquivo enviado pela tela, anexe um arquivo de exemplo.
- Clique em Pré-visualizar.
- Confira a tabela com os nomes dos campos e os fatos medidos (resposta, páginas lidas, versão do SOAP).
- Passe o mouse sobre um valor cortado para vê-lo inteiro.
Figura 145 — Cartão de pré-visualização com os primeiros registros
Observações
- Na API e no SOAP a pré-visualização chama o outro sistema e o resultado fica como último teste da integração.
- No arquivo, o exemplo (até 10 MB) é lido e descartado e não conta como teste.
- Campo aninhado aparece como JSON compacto.
13.5 Periodicidade da atualização
ID BSC-ITG-05
Para que serve
API REST, web service SOAP e banco de dados têm a seção Atualização, que define com que frequência os dados devem ser renovados. Quem executa a atualização são as cargas de dados e os conectores que usam a integração.
Quem usa: Analista de Integração de Dados.
Passo a passo
- Integrações › Integrações › abra a integração e clique em Editar.
- Na seção Atualização, escolha Manual, De hora em hora (no minuto escolhido), Diária, Semanal (dia da semana) ou Mensal (dia 1 a 28).
- Informe o horário no formato HH:mm.
- Salve e confira a próxima atualização prevista na lista e na ficha.
Observações
- Todos os horários são de Brasília, seja qual for o fuso do seu computador.
- O dia do mês vai de 1 a 28 para existir em todos os meses.
- Integração inativa não tem próxima atualização.
- O tipo Arquivo não tem periodicidade própria: o agendamento de arquivo por endereço fica na carga de dados.
13.6 Segredos e troca de credencial
ID BSC-ITG-06
Para que serve
Senhas, chaves, tokens e certificados são guardados cifrados e só podem ser escritos, nunca lidos de volta. A troca de credencial é registrada sem o valor antigo nem o novo.
Quem usa: Analista de Integração de Dados; Administrador do sistema.
Passo a passo
- Integrações › Integrações › abra a integração.
- No cartão Credenciais, clique em Substituir (ou edite a integração e preencha o campo do segredo).
- Informe o novo valor e salve.
- Clique em Testar de novo, pois o último teste foi apagado.
Figura 146 — Cartão Credenciais com a opção Substituir
Observações
- Ao editar, o campo de segredo mostra "Definido em … por …"; deixá-lo intocado mantém o valor guardado.
- O histórico registra "segredo trocado em …" sem os valores.
- Cabeçalho ou parâmetro comum com nome de credencial (Authorization, Cookie, X-Api-Key, ou contendo token, secret, password ou key), chave na URL e usuário e senha embutidos no endereço são recusados: credencial vai na seção Autenticação.
- Os segredos usam a cifragem com versão de chave da plataforma; quando o administrador troca a chave em Início › Chaves de cifragem, os segredos das integrações são recifrados junto.
- "A credencial guardada não pode ser lida": a chave sumiu antes da recifragem; substitua o segredo.
13.7 Lista de saída (destinos aprovados)
ID BSC-ITG-07
Para que serve
A lista de saída diz para onde as integrações do ambiente podem se conectar. É mantida só pelo administrador do sistema e protege a rede interna e a plataforma contra conexões indevidas.
Quem usa: Administrador do sistema.
Passo a passo
- Início › Lista de saída das integrações › clique em Aprovar destino.
- Informe o Servidor exato (por exemplo, api.exemplo.com.br) ou um IP, sem curinga e sem caminho.
- Escolha o Protocolo (HTTPS, HTTP só para rede local, banco de dados, broker AMQP ou Kafka) e a Porta (vazia só para HTTPS público, que vira 443).
- Marque Servidor da rede local quando o destino for um servidor interno da organização.
- Escreva a Justificativa e salve.
- Para consultar mudanças, abra o histórico do destino (ícone de relógio); para retirar a aprovação, use o ícone de energia.
Figura 147 — Lista de saída com os destinos aprovados
Observações
- Retirar a aprovação faz toda integração que usa o destino ser recusada na próxima execução.
- Nunca são liberados, mesmo aprovados: a própria máquina, a rede de enlace local, os metadados de nuvem, IP escrito de forma não padrão, nomes de uma palavra só e os servidores da própria plataforma (banco, mensageria, autenticação, arquivos, portal).
- O endereço é conferido já resolvido no momento da conexão: um nome aprovado que passe a apontar para a rede interna é recusado.
- Servidor interno exige "Servidor da rede local" marcado e o nome completo.
- O histórico de um destino abre para quem tem a leitura da auditoria.
13.8 Perfis de acesso ao hub
ID BSC-ITG-08
Para que serve
O acesso ao hub é controlado por operações atribuídas aos cargos nas regras de autorização. O Analista de Integração de Dados mantém as integrações; Diretoria de Estratégia e Gestor de Desempenho consultam; o administrador do sistema cuida da lista de saída.
Quem usa: Administrador do sistema; Analista de Integração de Dados; Diretoria de Estratégia; Gestor de Desempenho.
Passo a passo
- Início › Alçada (regras de autorização) › localize as operações Ver o hub de integrações, Cadastrar e testar integrações e Configurar conectores do BSC.
- Atribua ou retire cada operação dos cargos conforme a política da organização.
- Confira com um usuário do cargo se o menu Integrações aparece como esperado.
Figura 148 — Regras de autorização por cargo
Observações
- Analista de Integração de Dados: vê o hub; cadastra, testa, troca segredo e desativa.
- Diretoria de Estratégia: vê o hub sem botões de edição e liga canais de Teams e Discord às unidades.
- Gestor de Desempenho: vê o hub sem botões de edição.
- Administrador do sistema: mantém a lista de saída.
- Demais cargos: o menu não aparece e o acesso é recusado.
13.9 Tipo API REST
ID BSC-ITG-09
Para que serve
Lê dados da API de outro sistema por HTTP(S), com consulta GET (ou POST com corpo fixo), página após página. Tem Testar, Pré-visualizar e periodicidade.
Quem usa: Analista de Integração de Dados; Administrador do sistema.
Passo a passo
- Obtenha do outro sistema o endereço base (por exemplo, https://api.exemplo.com.br/v1), o caminho dos dados, um caminho leve para teste, a credencial (de preferência uma conta só de leitura dedicada ao Bússola/BSC), a forma de paginação e onde fica a lista na resposta JSON.
- Peça ao administrador do sistema a aprovação do servidor da API e, se for outro, do servidor do token OAuth2.
- Integrações › Integrações › Nova integração › API REST.
- Em Endereço, preencha URL base, Método, Caminho dos dados, Corpo da requisição (só POST, JSON fixo, nunca credencial) e Caminho de teste.
- Em Autenticação, escolha Nenhuma, chave num cabeçalho, usuário e senha (Basic), token (Bearer) ou OAuth2 com credenciais do cliente.
- Em Avançado, informe cabeçalhos e parâmetros fixos, Caminho dos registros, Paginação (página e tamanho, deslocamento e limite, cursor ou cabeçalho de próxima página), tempos e requisições por minuto.
- Salve, clique em Testar e depois em Pré-visualizar para conferir os registros.
Figura 149 — Integração de API REST com pré-visualização dos registros
Observações
- No OAuth2 o Bússola/BSC pede o token ao servidor de autorização (HTTPS obrigatório), guarda-o só em memória até vencer e o envia como Bearer.
- A pré-visualização lê até 5 páginas e mostra os 50 primeiros registros.
- Erros comuns: caminho dos registros não encontrado; API que não respondeu em JSON; servidor de autorização recusou o cliente; próxima página apontando para outro servidor (nunca seguida); redirecionamento; resposta acima de 10 MB depois de descompactada (use paginação).
13.10 Tipo web service SOAP
ID BSC-ITG-10
Para que serve
Lê uma operação de consulta de um web service SOAP descrito por um WSDL 1.1, o caso de serviços que ainda não têm API REST. Tem Testar (lê o WSDL e confere a operação, sem chamá-la), Pré-visualizar e periodicidade. O tipo só lê; o SOAP do SEI tem tipo próprio.
Quem usa: Analista de Integração de Dados; Administrador do sistema.
Passo a passo
- Obtenha o endereço do WSDL 1.1 (por exemplo, https://ws.exemplo.com.br/servico?wsdl), a operação de consulta, os valores dos parâmetros de entrada, o elemento que se repete na resposta e a credencial, se houver.
- Peça a aprovação na lista de saída do servidor do WSDL e do servidor do serviço, se forem diferentes.
- Integrações › Integrações › Nova integração › Web service SOAP.
- Informe o Endereço do WSDL e clique em Ler o WSDL para listar serviços, portas e operações.
- Escolha a operação; serviço, porta e versão do SOAP são preenchidos automaticamente.
- Informe o Elemento que se repete e, em Avançado, os Parâmetros (o valor vira o dia da execução).
- Escolha a autenticação (Nenhuma, Basic, chave num cabeçalho ou usuário e senha na mensagem), salve, teste e pré-visualize.
Observações
- Só operações com entrada simples (textos, números, datas) são atendidas; para as demais, use um barramento REST ou peça um tipo próprio.
- Importações do WSDL precisam estar no mesmo servidor; WSDL 2.0 é recusado.
- Basic e usuário e senha na mensagem só funcionam sobre https://.
- Uma falha SOAP aparece com o código e a mensagem curta do outro sistema; o detalhe técnico nunca é mostrado.
- XML com declaração DOCTYPE/DTD é recusado por segurança.
- Use Endereço do serviço só quando o endereço dentro do WSDL estiver errado; ele também é conferido na lista de saída.
13.11 Tipo banco de dados
ID BSC-ITG-11
Para que serve
Lê tabelas e visões do banco de outro sistema (PostgreSQL ou SQL Server) para as consultas e cargas do Bússola/BSC. Tem Testar, com diagnóstico da conta, e periodicidade; as consultas são escritas no editor SQL e nas cargas.
Quem usa: Analista de Integração de Dados; Administrador do sistema.
Passo a passo
- Obtenha o servidor, a porta, o nome do banco e uma conta somente leitura dedicada ao Bússola/BSC, sem poder gravar e sem papel de administração.
- Peça ao administrador do sistema a aprovação do servidor na lista de saída com protocolo Banco de dados e a porta exata (servidor interno com "Servidor da rede local").
- Integrações › Integrações › Nova integração › Banco de dados.
- Em Endereço, informe Tipo de banco, Servidor (só nome ou IP, por exemplo db.exemplo.com.br), Porta, Banco e Criptografia.
- Em Autenticação, informe usuário e senha da conta somente leitura.
- Em Avançado, use apenas as propriedades extras do driver aceitas para o tipo de banco.
- Salve e clique em Testar; leia o diagnóstico da conta.
Figura 150 — Teste de banco de dados com o diagnóstico da conta
Observações
- Diagnóstico: conta somente leitura funciona; conta que pode gravar funciona com aviso (consultas e cargas só rodam depois de um teste limpo); conta administradora é recusada com o motivo.
- Não existe campo de linha de conexão: vírgula, barra, arroba, espaço, instância nomeada e parâmetros no servidor são recusados.
- Trocar servidor, porta, banco, criptografia, usuário ou senha apaga o último teste.
- Prefira "Criptografada, com certificado e nome conferidos" sempre que o servidor tiver certificado confiável.
- Conexão em paralelo a vários endereços e banco em nuvem no modo de redirecionamento não são atendidos; cadastre o endereço que responde por um IP.
- A conexão é feita por driver nativo; não há ODBC a instalar. Outros bancos podem ser instalados sob pedido da organização.
13.12 Tipo arquivo
ID BSC-ITG-12
Para que serve
Lê arquivos CSV, TXT, Excel, JSON ou XML, enviados pela tela ou baixados de um endereço, para as cargas do Bússola/BSC. Não tem Testar nem periodicidade própria; tem Pré-visualizar com arquivo de exemplo.
Quem usa: Analista de Integração de Dados.
Passo a passo
- Integrações › Integrações › Nova integração › Arquivo.
- Em Origem do arquivo, escolha enviado pela tela ou baixado de um endereço (informe a URL https:// e peça a aprovação do servidor na lista de saída).
- Em Avançado, defina Formato, Codificação, Separador, Linha do cabeçalho, Aba (Excel), Caminho dos registros (JSON) ou Elemento que se repete (XML).
- Salve e, na ficha, anexe um arquivo de exemplo e clique em Pré-visualizar.
- Use a integração numa carga de dados, onde fica o agendamento.
Observações
- O leiaute fica fixado na integração: um arquivo exportado com outra codificação ou outro separador lê colunas erradas até a integração ser editada. Pré-visualize um arquivo novo antes de usá-lo numa carga.
- Codificação automática: UTF-8 quando o arquivo é UTF-8; senão Windows-1252.
- XML com DOCTYPE ou entidades é recusado por segurança; nada é lido de fora.
- "Este tipo de integração não tem periodicidade própria": agende pela carga.
13.13 Tipos das próximas entregas: HTTP de saída, webhook de entrada, broker e barramento
ID BSC-ITG-13
Para que serve
Alguns tipos já aparecem citados na tela de nova integração para planejamento, mas ainda não executam nesta versão. Conhecê-los ajuda a preparar o que pedir aos outros sistemas.
Quem usa: Analista de Integração de Dados; Administrador do sistema.
Passo a passo
- Integrações › Integrações › Nova integração › veja os tipos citados abaixo dos cartões.
- Para HTTP de saída (envio de dados com fila de reenvio e chave de idempotência), prepare o endereço que recebe (POST, PUT ou PATCH), a credencial e, se houver, o segredo de assinatura.
- Para Webhook de entrada (eventos assinados enviados ao Bússola/BSC), saiba que o endereço e o segredo serão gerados pelo próprio Bússola/BSC e mostrados uma vez.
- Para Broker de mensageria (Kafka ou AMQP), prepare servidores e portas, usuário e senha ou certificado de cliente, tópicos ou filas e a aprovação na lista de saída com o protocolo do broker.
- Para Barramento de integração, prepare o endereço base, a credencial e o catálogo das operações liberadas.
Observações
- Esses tipos aparecem na paleta de conectores com o selo Próxima entrega e não abrem.
- O broker da própria plataforma nunca pode ser usado como destino.
13.14 Tipo SEI
ID BSC-ITG-14
Para que serve
Abre e acompanha processos no SEI pelo módulo REST oficial do SEI, entrando com um usuário de serviço da organização. O Bússola/BSC só faz o que o perfil desse usuário permite, e tudo aparece no SEI como feito por ele.
Uso no BSC: a execução de uma entrega ou atividade pode ser acompanhada por um processo SEI (quando concluído em todas as unidades, a entrega vai a 100% na data do último andamento); abrir processo, incluir relatório em PDF e lançar andamento são disparados pelos conectores.
Quem usa: Analista de Integração de Dados; Administrador do sistema.
Passo a passo
- Peça à área de TI que administra o SEI: a instalação do módulo REST oficial no SEI de homologação, um usuário de serviço não pessoal com perfil básico lotado na unidade de acompanhamento da estratégia, a senha, o endereço https:// e a liberação de rede.
- Peça ao administrador do sistema a aprovação do servidor do SEI (por exemplo, sei.exemplo.com.br) na lista de saída.
- Integrações › Integrações › Nova integração › SEI; informe nome, código, objetivo e ambiente.
- Em Endereço, informe a URL base e, só se a TI instalou o módulo em outra pasta, o caminho da API.
- Em Autenticação, informe a sigla do usuário de serviço e a senha (podem ficar em branco até serem entregues).
- Clique em Testar: a primeira etapa confirma o módulo; a segunda entra com o usuário e lista as unidades.
- Em Avançado, escolha o órgão e a Unidade padrão na lista e marque as Operações habilitadas no Bússola/BSC.
Figura 151 — Integração do SEI com o teste em duas etapas
Observações
- Operações possíveis: listar catálogos, abrir processo, incluir relatório, lançar andamento, consultar processo, ler o histórico e listar documentos. A trava do que o Bússola/BSC faz é o campo de operações habilitadas.
- Sem usuário ou senha, o teste diz "Módulo encontrado; aguardando o usuário de serviço e a senha do SEI" e a integração aparece desabilitada na escolha, com o motivo.
- A sessão devolvida pelo SEI fica só em memória e é descartada ao fim; ao vencer, o Bússola/BSC entra de novo uma vez.
- Processo sigiloso, de unidade sem lotação ou inexistente aparece igual: "Processo não encontrado ou sem acesso no SEI". Nenhuma mensagem do SEI é gravada.
- "Resultado incerto: o SEI não respondeu à criação": o Bússola/BSC não repete a abertura sozinho; confira no SEI.
- O endereço precisa ser https://. Se a política da organização não aceitar usuário de serviço, a alternativa é o cadastro do Bússola/BSC como sistema no SEI, em entrega própria.
13.15 Tipo SIAFI: API Dados SIAFI (STA)
ID BSC-ITG-15
Para que serve
O tipo SIAFI traz a execução do orçamento (empenhado, liquidado, pago) para o Bússola/BSC, com cinco canais num tipo só. O canal padrão é a API Dados SIAFI (STA), fonte primária de empenhos com itens, restos a pagar e saldos contábeis. Em nenhum canal o Bússola/BSC envia dado ao SIAFI.
Quem usa: Analista de Integração de Dados; Administrador do sistema; Gestor de Desempenho.
Passo a passo
- Obtenha com a área de orçamento: usuário e senha de serviço do STA (só consulta), unidade gestora (6 dígitos), gestão (5 dígitos) e órgão (5 dígitos), com zeros à esquerda.
- Peça à contabilidade a confirmação das contas contábeis que formam disponível, empenhado, liquidado e pago, e à área de orçamento a fórmula do indicador de execução do orçamento.
- Peça ao administrador do sistema a aprovação do servidor do STA na lista de saída (HTTPS, porta 443).
- Integrações › Integrações › Nova integração › SIAFI › Canal API Dados SIAFI (STA).
- Preencha UG e gestão em Endereço; usuário e senha em Autenticação; órgão, exercício, tamanho máximo de resposta e tempos em Avançado.
- Clique em Testar: o Bússola/BSC entra no STA, procura a UG e confere a gestão.
Observações
- Sem credencial nada é chamado e o resultado é "Aguardando usuário e senha do STA"; a integração fica fora dos conectores até um teste com sucesso.
- A captura lê itens de empenho do exercício ou alterados nos últimos dias, restos a pagar, saldos contábeis da UG e do órgão, e as visões derivadas de posição orçamentária e execução por nota de empenho.
- Os dados chegam com defasagem, não em tempo real.
- Credor pessoa física chega sem CPF e nome, a menos que a opção de mantê-los seja ligada.
- O STA não pagina: acima do tamanho máximo de resposta a captura fica parcial. Cada captura tem até 10 minutos.
- Erros comuns: credencial recusada; UG não encontrada; resposta acima do tamanho máximo; contas contábeis de cada grupo não informadas no conector.
13.16 Tipo SIAFI: Portal da Transparência, Tesouro Gerencial e web services
ID BSC-ITG-16
Para que serve
Além do STA, o tipo SIAFI oferece canais alternativos: dados abertos do Portal da Transparência (sem credencial do SIAFI), relatório extraído do Tesouro Gerencial (arquivo enviado por um servidor habilitado) e web services do SIAFI (integração oficial que exige adesão formal).
Quem usa: Analista de Integração de Dados; Administrador do sistema.
Passo a passo
- Integrações › Integrações › Nova integração › SIAFI › escolha o Canal.
- Portal da Transparência: obtenha a chave gratuita da API de dados por um e-mail institucional da área responsável, informe UG, gestão, órgão e exercício, peça a aprovação do servidor do Portal na lista de saída e clique em Testar.
- Tesouro Gerencial: peça um relatório CSV (separador ;) ou XLSX, de até 20 MB, sem colunas de favorecido pessoa física; informe formato, codificação, separador, linha do cabeçalho e aba.
- Web services do SIAFI: cadastre endereço, certificado e senha, UG, gestão, órgão e exercício; o teste informa o que falta (adesão, certificado de aplicação e homologação).
Observações
- Portal: sem chave nada é chamado ("Aguardando a chave"); com chave, o teste lê uma página da despesa anual do órgão. A captura lê documentos de despesa por dia (até 31 dias) e por fase, itens dos empenhos e despesa anual do órgão.
- Portal: se o ritmo for excedido, o Bússola/BSC espera dentro do tempo da execução; se o tempo acabar, a captura fica parcial e o histórico diz a última página lida.
- Tesouro Gerencial: o Bússola/BSC não acessa o sistema; o arquivo é enviado numa captura manual do conector. O teste responde "Pronto". Uma coluna chamada só "ND" nunca é ligada pelo nome: quem configura o De-Para escolhe.
- O histórico de cada captura guarda o nome do arquivo e a impressão digital do conteúdo: o reenvio do mesmo arquivo é reconhecível.
- Web services do SIAFI não são oferecidos aos conectores até a adesão estar completa.
13.17 Canais de mensagem como tipos do hub
ID BSC-ITG-17
Para que serve
Microsoft Teams, Discord e WhatsApp também são cadastrados no hub como tipos de integração da família Mensageria. Eles publicam os avisos do Bússola/BSC num canal ou enviam alertas pessoais, e são usados pelos conectores que enviam mensagem.
Quem usa: Analista de Integração de Dados; Diretoria de Estratégia.
Passo a passo
- Integrações › Integrações › Nova integração › grupo Mensageria › escolha Microsoft Teams, Discord ou WhatsApp.
- Cadastre e teste a integração seguindo o capítulo de mensageria.
- Ligue os canais de Teams e Discord às unidades em Integrações › Canais de área (tarefa da Diretoria de Estratégia).
- Use a integração num conector que envia mensagem.
Figura 152 — Canais de área ligados às unidades
Observações
- O endereço de um webhook de Teams ou Discord é um segredo: fica cifrado e nunca volta à tela.
- Enquanto houver um canal ativo usando a integração, ela não pode ser desativada no hub.
- Os detalhes de cada canal, do consentimento do WhatsApp e das mensagens estão no capítulo de mensageria.
13.18 Sistemas corporativos sob demanda
ID BSC-ITG-18
Para que serve
Na tela Nova integração, o grupo Sistemas corporativos — sob demanda apresenta, com o selo Disponível sob demanda, integrações que o produto pode oferecer com outros sistemas corporativos: GRCS (GRC corporativo), Agility (gestão de cards) e ServiceNow SPM (portfólio estratégico). Elas não estão habilitadas na instalação: não há formulário, nada é gravado e o Bússola/BSC nunca chama o outro sistema.
Quem usa: Analista de Integração de Dados; Diretoria de Estratégia; Administrador do sistema.
Passo a passo
- Integrações › Integrações › Nova integração › grupo Sistemas corporativos — sob demanda.
- Abra o cartão do sistema para ver o que a integração faria em cada direção (Enviar e Capturar) e os campos e segredos que pediria.
- Use Testar para confirmar a situação: "Integração disponível sob demanda — não habilitada nesta instalação".
- Para habilitar, solicite ao provedor contratado.
- Na configuração de conectores, monte e salve o conector com o componente sob demanda para deixar a regra pronta.
Figura 153 — Vitrine dos sistemas corporativos sob demanda na tela Nova integração
Observações
- GRCS: enviaria um risco, uma não conformidade ou um achado de auditoria quando uma regra do BSC disparasse, e acompanharia o estado do registro aberto. Pediria URL base, chave de acesso de conta de serviço, segredo de assinatura do webhook, ações habilitadas e os de-para de criticidade → severidade e de natureza do risco → categoria.
- Agility: criaria um card vinculado a cada tarefa do BSC e moveria o card conforme o percentual; ao contrário, atualizaria o percentual da tarefa quando o card mudasse de raia, por um de-para raia → percentual (por exemplo, Backlog 0%, Em andamento 50%, Homologação 90%, Produção 100%). Pediria URL, endereço do token, id e segredo do cliente, workspace, board e raia de entrada.
- ServiceNow SPM: vincularia demandas e projetos do portfólio a ações estratégicas e sincronizaria o progresso nos dois sentidos. Pediria endereço da instância, cliente OAuth, usuário de serviço, tabelas de projetos e demandas e um filtro de portfólio.
- Conectores com componente sob demanda podem ser configurados e salvos; cada execução fica registrada como "Sob demanda — não habilitado aqui".
13.19 Ambiente de simulação para treinamento e homologação
ID BSC-ITG-19
Para que serve
Para treinar usuários e homologar o lado do Bússola/BSC antes de os sistemas reais estarem disponíveis, existe um ambiente de simulação que responde como o SEI, a API Dados SIAFI (STA) e o Portal da Transparência nas operações que o Bússola/BSC usa, com dados fictícios.
Quem usa: Analista de Integração de Dados; Gestor de Desempenho.
Passo a passo
- Integrações › Integrações › localize as integrações marcadas com o selo Simulador.
- Use-as para testar e exercitar os fluxos de ponta a ponta (entrar com usuário de serviço, abrir processo, incluir relatório, lançar andamento; capturar empenhos e saldos; ler documentos de despesa).
- Mantenha ao lado a integração real do mesmo tipo, cadastrada com os campos definitivos; o Testar dela mostra exatamente o que falta.
- Quando os acessos reais forem entregues, preencha a credencial na integração real e teste de novo, sem mudar mais nada.
Observações
- A integração de simulação é do mesmo tipo da integração real e leva o selo Simulador em toda tela onde aparece.
- A simulação prova o lado do Bússola/BSC, não o sistema real: não prova acentuação gravada no sistema real, limites reais de uso, mensagens reais de erro nem o significado das contas contábeis.
- O ambiente de simulação só é alcançável em ambientes de treinamento e homologação; num ambiente de produção a marca de simulação é recusada.
13.20 Conectores do BSC: a paleta de componentes
ID BSC-ITG-20
Para que serve
A Configuração de conectores põe as integrações do hub para trabalhar no BSC. A tela abre com a paleta: um ícone por componente, lido do catálogo do hub, mais os canais próprios do Bússola/BSC. Cada componente mostra se envia, recebe ou os dois, e o que faz em cada direção.
Quem usa: Gestor de Desempenho; Analista de Integração de Dados; Diretoria de Estratégia.
Passo a passo
- Gestão por indicadores › Configuração de conectores › veja a paleta de componentes.
- Identifique o grupo: Canais do Bússola/BSC (Sino, E-mail, Push), Mensageria (WhatsApp, Teams, Discord), Dados e governo disponíveis, Sistemas corporativos sob demanda ou Próximas entregas.
- Passe pelo componente para ler o que ele faz ao enviar e ao receber.
- Clique no componente desejado para montar um conector.
Figura 154 — Configuração de conectores com a paleta de componentes
Observações
- Configuram: Gestor de Desempenho e Analista de Integração de Dados. A Diretoria de Estratégia lê conectores e histórico, sem editar. Quem não lê as integrações não vê o menu.
- Canais do Bússola/BSC e Mensageria criam conectores que enviam mensagem; na mensageria a integração é opcional e liga os disparos ao monitor.
- Componentes de dados e governo exigem uma integração ativa e testada do mesmo tipo.
- Componentes de próximas entregas aparecem com o selo Próxima entrega e não abrem.
13.21 Montar um conector
ID BSC-ITG-21
Para que serve
O conector define quando agir (por condição ou por agenda), o que fazer (enviar mensagem, capturar dado ou enviar dado) e para quem. Antes de salvar, a simulação mostra o efeito sem enviar nada.
Quem usa: Gestor de Desempenho; Analista de Integração de Dados.
Passo a passo
- Gestão por indicadores › Configuração de conectores › clique no componente da paleta.
- Em Envia ou recebe, para tipo de dado escolha a direção e a integração do hub (só aparecem as ativas e testadas; se a lista estiver vazia, a tela explica cada exclusão).
- Em Quando age, escolha Quando uma condição for alcançada (atingimento abaixo de X% ou alcançou X%, faixa vermelho/amarelo/verde, apuração vencida, avanço da ação abaixo de/alcançou X%, entrega em atraso) com o escopo (ciclo, perspectiva, objetivo, unidade ou lista de registros), ou Por agenda (a cada N horas, diária, semanal ou mensal, hora de Brasília).
- Ajuste reavisar a cada N dias, o Teto diário de disparos (padrão 50) e, se quiser, Adicionar outros limiares para criar conectores irmãos.
- Em O que faz, escolha Enviar mensagem (canais, Também enviar push, destinatários, observação e Avisar também quando normalizar), Capturar dado (abre o De-Para) ou Enviar dado.
- Clique em Simular (sem enviar) e confira registros do escopo, quem dispararia, reavisaria ou normalizaria, canais, destinos, a mensagem como ficaria, o aviso de teto e outros conectores sobre os mesmos registros.
- Clique em Salvar conector.
Figura 155 — Conector aberto com componente, gatilho e ações
Observações
- Teams e Discord exigem o destinatário "Canal da área"; o push vai a pessoas.
- O texto da mensagem segue o modelo Alerta de conector do BSC das mensagens institucionais; a observação vai ao final.
- Até um De-Para ser publicado, o conector de captura fica "De-Para a configurar" e cada execução é registrada sem ler o outro sistema.
- Enviar dado fica registrado como não disponível nesta versão ou sob demanda.
- Outros limiares só podem ser adicionados na criação e cada limiar tem estado próprio.
- "A integração ainda não passou no teste do hub": rode Testar na integração. Nomes de conector são únicos.
13.22 Como o conector dispara e sigilo
ID BSC-ITG-22
Para que serve
O conector dispara na passagem de normal para em alerta, não a cada medição, e só leva a cada pessoa o que ela pode ler. Isso evita excesso de avisos e vazamento de registros sigilosos.
Quem usa: Gestor de Desempenho; Analista de Integração de Dados; Diretoria de Estratégia.
Passo a passo
- Lance ou importe um valor no indicador: a avaliação roda logo depois.
- Aguarde a varredura automática (a cada 15 minutos) ou, na ficha, clique em Avaliar agora (conector por agenda: Executar agora).
- Acompanhe os registros em Registros em alerta e no Histórico de disparos.
Observações
- Exemplo com "atingimento abaixo de 80%": 85% não dispara; 70% gera uma mensagem e o registro fica em alerta; 75% não gera nada (sem reaviso); 85% gera "Normalizado" (se marcado) e volta a normal.
- Duas avaliações ao mesmo tempo nunca mandam a mesma mensagem duas vezes.
- O conector vê só os registros que o dono (quem criou ou reativou) pode ler, e cada pessoa só recebe se puder ler o registro.
- Registro sigiloso nunca sai por WhatsApp, e-mail, Teams ou Discord: vai só ao sino de quem pode lê-lo (e push sem o nome). Sem sino nem push, o disparo fica "Retido: registro sigiloso".
- Quem não pode ler um registro vê "Registro reservado" na simulação e no histórico.
13.23 Ficha do conector e acompanhamento no monitor
ID BSC-ITG-23
Para que serve
A ficha reúne a regra, os canais, os destinatários, os registros em alerta e o histórico completo de disparos e alterações. Todo disparo também aparece no Monitor de integrações.
Quem usa: Gestor de Desempenho; Analista de Integração de Dados; Diretoria de Estratégia.
Passo a passo
- Gestão por indicadores › Configuração de conectores › abra o conector.
- Confira componente, integração herdada, regra em uma frase, canais, destinatários, dono e situação.
- Consulte Registros em alerta e o Histórico de disparos (quando, registro, passagem, valor e resultado).
- Use Simular, Avaliar agora / Executar agora, Pausar / Reativar e Editar conforme a necessidade.
- Integrações › Monitor de integrações › filtre pelo conector para ver cada disparo e cada aplicação do De-Para.
Figura 156 — Ficha do conector com histórico de disparos
Observações
- Resultados possíveis de um disparo: Enviado, Pulado pelo teto, Retido por sigilo, Ninguém a avisar, De-Para a configurar, Sob demanda.
- Mudar a condição, o limiar ou o escopo zera os estados: a regra nova começa do normal.
- O conector se pausa sozinho, com o motivo visível, quando a integração é desativada no hub ou o dono perde a permissão; quem reativa passa a ser o dono.
- No monitor há uma linha por disparo, nunca duas; cada aplicação do De-Para gera uma linha do tipo De-Para aplicado, com as contagens.
13.24 De-Para: destinos
ID BSC-ITG-24
Para que serve
O De-Para traduz o que outro sistema manda no que o BSC guarda: qual coluna do dado capturado vai para qual campo de um objeto do BSC. Ele entrega cada linha ao dono do objeto e nunca grava direto em lugar nenhum.
Quem usa: Gestor de Desempenho; Analista de Integração de Dados.
Passo a passo
- Gestão por indicadores › Configuração de conectores › abra um conector que captura dado e clique em Abrir o De-Para.
- Em Novo De-Para para, escolha o destino: Realizado de indicador, Meta de indicador, Execução de entrega, Execução de atividade, Item de portal do governo ou Só guardar as linhas.
- Confira as condições do destino antes de montar as linhas.
Figura 157 — De-Para do conector com amostra e destinos
Observações
- Realizado de indicador: grava como valor enviado por integração (mesmo valor = sem mudança; valor revisto = retificação com a versão anterior preservada). Exige o indicador marcado como alimentado por integração e o período terminado.
- Meta de indicador: a meta nasce rascunho e, com Enviar para aprovação ao importar, segue o fluxo de aprovação. Meta valendo ou em aprovação nunca é alterada.
- Execução de entrega ou atividade: grava pela sincronização da ação, por referência e só o que mudou. Exige a entrega vinculada a este conector na configuração de execução automática.
- Item de portal do governo: grava pela sincronização dos portais; a fonte do portal precisa ler a mesma integração do conector.
- Só guardar as linhas: as linhas ficam na área de preparação.
- Um objeto que o dono do conector não pode ler é recusado como "Destino não encontrado", sem revelar que existe.
13.25 De-Para: montar, validar e publicar
ID BSC-ITG-25
Para que serve
O De-Para é montado sobre uma amostra real do dado capturado, validado numa prévia que não grava nada e publicado como versão imutável.
Quem usa: Gestor de Desempenho; Analista de Integração de Dados.
Passo a passo
- No quadro Amostra (o que chegou), confira as colunas; num conector SIAFI, clique em Executar leitura de teste; nos demais, execute antes a carga de dados da mesma integração.
- Em Novo De-Para para, escolha o destino ou um modelo pronto (SIAFI — Execução do orçamento (%) ou SIAFI — % financeiro da entrega) e clique em Criar rascunho.
- Num conector SIAFI, confira em O que é lido do SIAFI (STA) a operação e as contas contábeis propostas, confirme com a contabilidade e clique em Salvar o que é lido.
- Em cada linha, escolha Vem de, a Conversão (como vem, sem espaços, maiúsculas, número, data, período, multiplicar, dividir, razão em percentual, valor fixo, valor quando vazio, juntar, parte do texto, tabela de equivalência), o parâmetro e o padrão quando vazio.
- Defina o Formato de número e o padrão de data; se quiser, limite com Só as linhas em que (até 5 condições).
- Clique em Validar (prévia) e confira, para até 50 linhas, o que criaria, ficaria sem mudança, retificaria, seria recusado (com motivo) ou ficaria fora.
- Clique em Publicar.
- Para mudar, use Editar (nova versão); para tirar de uso, Aposentar.
Figura 158 — Linhas do De-Para com conversões e prévia da validação
Observações
- Não há fórmula nem script: só a lista fechada de conversões.
- O produto nunca liga uma coluna pelo nome e nunca adivinha formato de número ou de data.
- Publicar exige validação sem pendências sobre a amostra atual e ao menos uma linha aceita. A versão publicada não muda mais; a anterior é aposentada na hora.
- Cada valor gravado cita o conector, a versão do De-Para e a linha de origem; medições antigas continuam citando a versão que as produziu.
- Os modelos SIAFI trazem uma hipótese de contas contábeis que precisa ser confirmada pela contabilidade antes de confiar nos números.
- Aposentar devolve o conector ao estado "De-Para a configurar".
13.26 De-Para: aplicar
ID BSC-ITG-26
Para que serve
A versão publicada do De-Para é aplicada a cada execução do conector de captura ou sob comando, sem duplicar dados e preservando o histórico de retificações.
Quem usa: Gestor de Desempenho; Analista de Integração de Dados.
Passo a passo
- Deixe o conector de captura executar pela agenda ou pela condição: ele lê o outro sistema e aplica a versão publicada.
- Para aplicar às linhas atuais sem ler o outro sistema de novo, clique em Aplicar agora no topo do De-Para.
- Confira as contagens (criadas, sem mudança, retificadas, recusadas, fora) e as linhas recusadas com o motivo.
- Acompanhe a linha do tipo De-Para aplicado em Integrações › Monitor de integrações.
Observações
- Uma linha recusada não impede as outras.
- Recapturar o mesmo dado não cria nada em dobro; um valor revisto pela origem retifica com a versão anterior preservada.
- Na execução de entrega, a entrega vinculada é sincronizada na hora; fato com data de hoje só entra na execução de amanhã.
13.27 Tabelas de equivalência
ID BSC-ITG-27
Para que serve
Uma tabela de equivalência traduz um código de outro sistema (por exemplo, o plano interno do SIAFI ou um PTRES) num objeto do BSC (entrega, atividade, ação, indicador) ou num texto. É usada pela conversão Tabela de equivalência do De-Para.
Quem usa: Gestor de Desempenho; Analista de Integração de Dados.
Passo a passo
- Integrações › Tabelas de equivalência › clique em Nova tabela.
- Informe código e nome e escolha Os códigos apontam para.
- Acrescente os códigos e escolha o objeto de cada um.
- Clique em Salvar tabela.
- No De-Para, use a conversão Tabela de equivalência e escolha a tabela.
Figura 159 — Tabelas de equivalência
Figura 160 — Tabela de equivalência aberta com os códigos e objetos
Observações
- Só aparecem os objetos que você pode ler.
- Maiúsculas e espaços nas pontas não contam na comparação.
- Um código que falta na tabela deixa a linha fora da captura; nunca é adivinhado.
- O histórico mostra quem mudou o quê; um objeto sigiloso aparece no histórico só pelo tipo.
- O modelo "% financeiro da entrega" cria a tabela PI → entrega se ela ainda não existir.