Configurações de API Key

1) Acesso à tela de Configuração de API Key

Para acessar a tela de Configuração de API Key no BomControle, siga os passos abaixo:

1. No menu superior, clique em Configurações (engrenagem).

2. No menu de Configurações, selecione a opção Configuração de API Key (geralmente localizada na seção de Integrações).

Após essa navegação, a tela de listagem/pesquisa de API Keys será exibida (Figura 1). Nela, você verá todas as API Keys de integração já cadastradas para as empresas às quais você tem acesso.

Figura 1 — Tela de listagem de Configuração de API Key

• Filtros acima do grid: Nesta tela, não há campos de filtro ou busca textual específicos – por padrão, todas as chaves são listadas e a busca rápida está desabilitada. Caso haja muitas chaves, utilize a paginação do grid para navegar entre elas. (Observação: A listagem exibirá apenas as chaves das empresas que você tem permissão de visualizar.)

• Colunas do grid: Cada coluna representa uma informação da API Key:

• Empresa: nome da empresa à qual a chave pertence. Isso é útil em ambientes com múltiplas empresas, indicando para qual empresa aquela integração está configurada.

• Módulo: o módulo do sistema associado à API Key – atualmente pode ser Financeiro ou CRM, selecionado no cadastro (veja seção de cadastro). Indica em que área/módulo a integração atuará (ex.: integração com Financeiro ou com CRM).

• Nome: o nome descritivo da chave de integração, definido pelo usuário no cadastro. Serve para identificar a finalidade da integração (por exemplo, “Integração E-commerce” ou “Leads Website”).

• Data criação: a data em que a API Key foi criada, no formato DD/MM/AAAA. Útil para controle de quando a integração foi gerada.

• Ações: conjunto de botões para ações rápidas (localizado na última coluna, sem título):

Figura 2 — Imagem dos ícones de ação da Configuração de API Key

• Copiar API Key
  (ícone de prancheta): copia a chave de integração (a sequência de caracteres da API Key) para a área de transferência. Use esta opção para obter a chave e colá-la no sistema externo ou configuração que irá usá-la. (Ao clicar, a chave é copiada e uma mensagem “Chave copiada” é exibida.)

Figura 3 - Tela da chave de integração

• Gerar Nova Key
  (ícone de refresh): gera uma nova API Key para aquela integração. A chave antiga é imediatamente invalidada (inutilizada), e uma nova sequência é criada e copiada para sua área de transferência. Use esta opção com cautela – após gerar uma nova chave, atualize a configuração do sistema externo com a nova API Key, pois a antiga não funcionará mais.

• Configurações
  (ícone de engrenagem): abre a tela de editar configuração da API Key selecionada. É semelhante à tela de cadastro, permitindo alterar o Nome ou configurações adicionais (como vendedor/funil para CRM). Campos não editáveis (Empresa e Módulo) permanecem desabilitados na edição.

• Logs
  (ícone de relógio): abre a tela de Logs de Integração referente àquela API Key. Nesta tela, é possível visualizar o histórico de requisições feitas com a chave – útil para monitorar o uso da API, verificar últimas operações ou diagnosticar erros de integração.

Figura 4 - Tela de log da integração

• Bloquear/Desbloquear
  (ícone de cadeado aberto/fechado): permite inativar temporariamente ou reativar a API Key. Quando uma chave está ativa, o ícone exibido é um cadeado aberto (ação “Bloquear”); ao clicar, a chave será bloqueada (desativada) e o ícone mudará para cadeado fechado. Se a chave estiver bloqueada, o ícone fechado (ação “Desbloquear”) reativa o uso da chave. Utilize o bloqueio para impedir temporariamente que a integração acesse o sistema (por exemplo, em caso de suspeita de comprometimento da chave). Ao bloquear ou desbloquear, uma mensagem confirma a ação (“Chave ‘X’ bloqueada com sucesso” ou “...desbloqueada com sucesso”).

• Botões no rodapé: No canto inferior da listagem, há o botão Cadastrar Novo para incluir uma nova API Key. Clicando nele, você acessará o formulário de cadastro de API Key. (Não há botão de excluir na listagem – para “remover” uma chave, utilize o bloqueio. O sistema mantém todas as chaves criadas para preservação de histórico de integração.)

2) Seção – Dados Básicos (Formulário de API Key)

Ao clicar em Cadastrar Novo na listagem de API Keys, abre-se a tela de cadastro de uma nova chave de integração. Da mesma forma, ao editar uma chave existente, essa tela é exibida preenchida com os dados da chave selecionada. A figura abaixo destaca a seção de Dados Básicos do formulário de Configuração de API Key:

Figura 5 — Dados Básicos do formulário de Configuração de API Key. 

2.1 Campos e regras de preenchimento (Dados Básicos)

Legenda: ✅ Campo obrigatório  ·  ⚠️ Campo opcional ou de uso específico

Nome:

- Regras de preenchimento: ✅ Campo obrigatório. Deve-se informar um nome descritivo para a API Key. Pode ter até 250 caracteres, incluindo letras, números e espaços. Escolha um nome que identifique claramente a integração (por exemplo, “Integração Loja Virtual”, “API Leads Site XYZ”).

- Impacto em outros módulos: O nome serve para identificação interna da chave nos módulos de Configuração e em eventuais logs. Em buscas ou telas de seleção de chaves (como na tela de log), este será o rótulo exibido. Não afeta diretamente operações no Financeiro ou CRM além de facilitar a referência. Por exemplo, ao analisar logs de integração, você verá o nome da chave relacionada a cada evento, ajudando a distinguir integrações diferentes.

- Observações: Evite nomes genéricos. Um nome claro e único facilita a manutenção, principalmente se sua empresa utilizar múltiplas integrações. Lembre-se que você poderá editar o nome posteriormente se necessário, para aprimorar a descrição.

Empresa:

- Regras de preenchimento: ✅ Campo obrigatório. Selecione a empresa à qual esta integração pertencerá. Caso você tenha acesso a apenas uma empresa no sistema, ela já virá selecionada por padrão e o campo ficará desabilitado (não editável). Se houver múltiplas empresas, escolha aquela em cujo contexto os dados da integração serão registrados. Atenção: após salvar a API Key pela primeira vez, não é possível alterar a empresa associada.

- Impacto em outros módulos: Define o contexto empresarial da integração. Todos os dados inseridos via esta API Key serão registrados dentro da empresa selecionada, afetando apenas os módulos daquela empresa. Por exemplo, se for uma integração Financeira, as receitas/despesas ou movimentações criadas via API serão lançadas na empresa escolhida; se for uma integração CRM, os leads/oportunidades criados entrarão no CRM dessa empresa. Além disso, a listagem de chaves exibe a empresa para facilitar a identificação em ambientes multi-empresa, e usuários de outras empresas não visualizam nem conseguem usar a chave.

- Observações: Escolha com cuidado a empresa correta antes de salvar. Se sua conta BomControle gerencia várias empresas/filiais, crie uma API Key para cada empresa que precise integrar com sistemas externos, respeitando as segregações de dados. Para alterar a empresa de uma chave, seria necessário cadastrar uma nova chave (não há como editar esse campo após criação).

Módulo:

- Regras de preenchimento: ✅ Campo obrigatório. Indique qual módulo do BomControle será acessado via esta API Key. As opções disponíveis são atualmente Financeiro ou CRM – selecione uma delas de acordo com a finalidade da integração. (Ex.: escolher “Financeiro” para integrar cobranças, pagamentos ou dados financeiros; escolher “CRM” para integrar leads, oportunidades ou contatos.) Importante: assim como a empresa, o módulo não pode ser alterado após a criação da chave (o campo fica bloqueado na edição), então certifique-se de selecionar o módulo correto.

- Impacto em outros módulos: Esta configuração determina que tipos de operações a API Key poderá realizar e em qual área do sistema. Uma chave do tipo Financeiro terá permissões e acesso às funcionalidades do módulo Financeiro (contas a pagar/receber, lançamentos, etc.), mas não poderá interferir no CRM (e vice-versa). Em outras palavras, cada API Key é específica de um módulo. Se sua empresa precisa integrar dois módulos diferentes, será necessário criar chaves separadas. No uso prático, um sistema externo usando uma API Key do Financeiro poderá, por exemplo, criar movimentações financeiras ou consultar faturas, enquanto uma API Key do CRM permitirá criar ou atualizar leads, oportunidades e consultar dados do funil de vendas.

- Observações: Ao escolher o módulo, o formulário exibirá campos adicionais conforme o módulo selecionado (ver seção CRM adiante). Para chaves Financeiras, não há campos extras nesse cadastro básico – a integração financeira poderá exigir configurações em outros locais (como categoria financeira padrão, conta bancária padrão, etc., dependendo da API utilizada), mas não são definidos aqui na tela de API Key. Já para chaves de CRM, serão habilitados campos específicos do CRM no formulário (detalhados na próxima seção). Planeje a criação das chaves conforme a necessidade: por exemplo, utilize uma chave exclusiva para cada sistema externo que acessará seu BomControle, separando por módulo e finalidade (uma chave para ERP financeiro externo, outra chave para captura de leads do site no CRM, etc.).

Criado em:

- Regras de preenchimento: Campo não editável. Ao cadastrar uma nova API Key, este campo não aparece; ao editar uma chave existente, este campo exibirá automaticamente a data em que a chave foi criada. O formato é DD/MM/AAAA. Não é possível alterar esse valor – é apenas informativo.

- Impacto em outros módulos: Nenhum impacto funcional – trata-se de informação para controle do usuário. Pode auxiliar na auditoria interna, por exemplo, para saber desde quando uma integração está ativa.

- Observações: Você pode usar a data de criação para gerir suas integrações (por exemplo, políticas de segurança podem sugerir rotação periódica de chaves API; sabendo a data, você decide quando regenerar a chave usando a função de gerar nova key). Lembre-se que regenerar a chave invalida a data original de criação no sentido de autenticação, mas este campo continuará mostrando quando a integração foi criada inicialmente (não quando foi gerada a última chave).

(Após preencher todos os campos obrigatórios acima, clique em Salvar. Se algum campo obrigatório não for preenchido ou estiver inválido, o botão Salvar permanecerá desabilitado. Ao salvar com sucesso, o sistema criará a API Key e exibirá uma mensagem de confirmação “Chave criada com sucesso”. Em seguida, você será redirecionado de volta à tela de listagem (Configuração de API Key), onde sua nova chave aparecerá na grade. Use o botão Copiar API Key na listagem para obter o valor da chave gerada e configurá-lo no aplicativo externo que fará uso da integração.)

3) Seção – CRM (Configurações adicionais para módulo CRM)

Se no campo Módulo for selecionado CRM, o formulário de API Key exibirá uma seção extra chamada “CRM” com campos específicos. Essa seção permite definir configurações padrão para integrações que vão inserir dados no módulo de CRM do BomControle, garantindo que os leads/oportunidades criados via API sejam categorizados corretamente. A figura abaixo indica os campos da seção CRM:

Figura 6 — Seção de configurações CRM no cadastro de API Key. 

3.1 Campos e regras de preenchimento (Seção CRM)

Vendedor:

- Regras de preenchimento: ⚠️ Campo opcional. Permite selecionar um vendedor/usuário padrão do CRM para atribuir aos leads/oportunidades que entrarem através desta integração. A lista apresenta os usuários do tipo vendedor cadastrados e ativos no sistema. Você pode deixar em branco caso não queira definir um responsável fixo.

- Impacto em outros módulos: Este campo impacta diretamente o módulo CRM. Se preenchido, todo lead, oportunidade ou negócio criado via API com esta chave já será atribuído ao vendedor selecionado, aparecendo nas telas do CRM (oportunidades, funil de vendas) sob responsabilidade desse usuário. Isso garante que as oportunidades sejam encaminhadas automaticamente para o vendedor certo, sem precisar de atribuição manual posterior. Se o campo Vendedor ficar vazio, as oportunidades vindas pela integração podem entrar sem responsável definido – caberá a um usuário do CRM atribuí-las depois, ou o BomControle poderá usar regras internas para atribuir (por exemplo, manter sem vendedor ou atribuir a um usuário genérico da integração). No módulo Financeiro, este campo não tem efeito.

- Observações: Definir um vendedor é recomendável quando todas as entradas dessa integração devem ser tratadas pela mesma pessoa ou equipe (por exemplo, leads de um formulário de site que sempre serão atendidos pelo vendedor X). Se houver rotatividade ou distribuição de leads por rodada, talvez seja melhor deixar sem preenchimento aqui e gerenciar a atribuição no próprio CRM posteriormente. Lembre-se de que este campo não impede de alterar o responsável depois, dentro do CRM – ele apenas define o padrão inicial no momento em que o lead/op ortunidade é criado via integração.

Funil:

- Regras de preenchimento: ⚠️ Campo opcional. Seleciona o funil de vendas padrão onde as oportunidades capturadas por esta integração serão inseridas. O dropdown listará os funis de venda cadastrados para a empresa (se houver mais de um). Escolha o funil adequado à natureza dos leads que serão integrados. Se sua empresa utiliza apenas um funil no CRM, você pode selecionar esse único disponível. Caso não deseje amarrar a integração a um funil específico, pode deixar em branco – nesse caso, o sistema utilizará o funil padrão do CRM (geralmente o primeiro ou principal) por default. (Ao selecionar um funil, o campo Etapa será habilitado, mostrando as etapas correspondentes a esse funil.)

- Impacto em outros módulos: Afeta o CRM unicamente. Garante que as novas oportunidades criadas via API apareçam no funil de vendas correto, facilitando o acompanhamento no pipeline comercial. Por exemplo, leads vindos de uma integração de formulário de contato podem ser direcionados para um funil específico de “Pré-vendas” se assim configurado. No módulo Financeiro, não tem efeito.

- Observações: Só é possível escolher um funil por chave de integração. Caso sua empresa trabalhe com múltiplos funis e precisa direcionar leads para funis diferentes, isso exigiria chaves separadas ou tratar a lógica de distribuição externamente antes de enviar ao BomControle. Certifique-se de que o usuário de integração (chave) tenha permissão de acesso ao funil escolhido (normalmente, sim, se for acesso total ao CRM). Deixar sem funil explicitamente selecionado pode ser útil se você deseja centralizar tudo no funil principal e eventualmente mover manualmente no CRM depois.

Etapa:

- Regras de preenchimento: ⚠️ Campo opcional, dependente do Funil. Indique a etapa do funil de vendas em que as novas oportunidades serão criadas inicialmente. A lista de etapas é carregada com base no funil selecionado no campo anterior. Escolha a etapa que melhor corresponda ao status inicial esperado dos leads integrados (por exemplo, “Novo Lead”, “Contato Pendente” etc.). Se nenhuma etapa for selecionada, o BomControle poderá considerar a etapa inicial padrão do funil. Este campo fica desabilitado enquanto nenhum Funil for escolhido, e é habilitado assim que um funil é definido, exibindo apenas etapas daquele funil.

- Impacto em outros módulos: Novamente, o efeito é no CRM: as oportunidades entrarão já em determinada fase do funil, o que influencia as visões de pipeline, relatórios de estágio de vendas, etc. No módulo Financeiro não há impacto. Definir a etapa ajuda o time a identificar em que ponto do processo os leads externos entram. Por exemplo, você pode cadastrar todos os leads vindos de uma campanha online já na primeira etapa “Contato Recebido” do funil de Vendas. Se não definir a etapa, o sistema provavelmente colocará o lead na etapa inicial do funil escolhido por padrão (ou na etapa inicial do funil padrão do sistema, caso nenhum funil tenha sido explicitamente selecionado).

- Observações: Assim como o funil, a etapa pode ser alterada manualmente pelos usuários do CRM após a criação da oportunidade. O objetivo aqui é apenas definir uma etapa inicial padrão. Se estiver em dúvida, deixe sem especificar a etapa – o sistema cuidará de posicionar na etapa inicial – ou teste com um lead de exemplo para verificar em qual etapa cai automaticamente, ajustando a configuração conforme necessário. Vale reforçar que este campo só aparece e faz sentido se um Funil for selecionado acima; do contrário, não se aplica.

Após configurar os campos da seção CRM conforme necessário, clique em Salvar para concluir o cadastro da API Key. Caso esteja editando uma chave existente, as alterações (como mudança de vendedor padrão ou etapa) serão salvas e passarão a valer para novas integrações a partir de então. Alterações não retroagem em dados já importados; elas apenas afetam os próximos registros criados via API.

Considerações finais: Uma vez criada a API Key, use os botões da listagem para gerir sua utilização: - Copiar a chave e configure-a no sistema externo que fará as requisições à API do BomControle. - Bloquear a chave se precisar interromper o acesso (por exemplo, em caso de mudança de parceiro ou suspeita de vazamento da chave). 

- Gerar nova chave periodicamente ou quando necessário, reforçando a segurança – lembre-se de atualizar todos os lugares onde a chave antiga estava em uso. 

- Acesse os Logs de Integração para monitorar a comunicação: você poderá verificar se as chamadas do sistema externo estão chegando, se houve erros (como algum dado inválido sendo enviado) e assim por diante, facilitando a resolução de problemas.

Conclusão

Por fim, é importante ressaltar que as API Keys são senhas de integração – mantenha-as seguras. Forneça cada chave apenas aos sistemas ou pessoas responsáveis pela integração correspondente. Em caso de dúvidas sobre os endpoints disponíveis ou formato das requisições, consulte a documentação técnica de API do BomControle ou entre em contato com o suporte técnico. Este manual se ateve à configuração dentro do BomControle, garantindo que você tenha configurado corretamente os parâmetros para uma integração bem-sucedida nos módulos Financeiro e CRM. Boa integração!