Pular para o conteúdo
Voltar para a Central de Ajuda
Configurações

Chaves de API: acesso seguro à API Pública

Como criar, editar e revogar chaves, escolher perfis e serviços e configurar o telefone completo na API Pública do North Clinic CRM.

A tela de API Keys permite criar credenciais para sistemas externos acessarem a API Pública do North Clinic CRM.

A API Pública está disponível no plano Comercial (CRM) e exige que o módulo API Pública esteja ativo na clínica. “Plano Completo” não é o nome atual de um plano; quando essa expressão for usada, confirme se a referência é ao plano Comercial (CRM) com o módulo de API Pública habilitado.

Como acessar

No CRM, acesse Configurações → Integrações → API Keys.

Para visualizar as chaves, é necessária a permissão de acesso às configurações da API. Criar, editar e revogar chaves exige a permissão de gerenciamento da API. A clínica também deve possuir o módulo API Pública ativo.

Se a opção não aparecer, confira Configurações → Meu Plano ou fale com o suporte para validar o plano e o módulo. Ter o plano Comercial sem o módulo ativo não faz a tela aparecer automaticamente.

Chaves ativas

A lista apresenta somente as chaves que ainda não foram revogadas. Para cada uma, são mostrados:

  • Nome.
  • Prefixo de identificação.
  • Escopos concedidos.
  • Serviços permitidos.
  • Data e hora do último uso, quando houver.
  • Data de criação.

O botão Documentação abre a referência técnica da API Pública. Nas ações da chave, o ícone de gráfico Ver uso real por serviço mostra a atividade dos últimos 30 dias, incluindo consultas de horário, agendamentos criados e último uso. Essa atividade é diferente da lista de serviços autorizados.

Criando uma chave

  1. Clique em Nova API Key.
  2. Informe um nome que identifique claramente a integração.
  3. Escolha um dos perfis de acesso disponíveis.
  4. Se o perfil acessar a agenda, selecione os Serviços permitidos.
  5. Decida se a integração poderá receber o telefone completo.
  6. Confirme em Criar Chave.

Os cinco perfis disponíveis em Preset de Escopos são:

Perfil Acesso concedido
Agendamento IA Consultar a agenda e criar/cancelar agendamentos (scheduling:read e scheduling:write).
Integração Agência Consultar leads (leads:read).
Cadastro de leads Consultar e cadastrar leads (leads:read e leads:write).
Leitura de prontuários Ler prontuários (medical-records:read).
Acesso Completo Agenda e consulta/cadastro de leads (scheduling:read, scheduling:write, leads:read e leads:write). Não inclui leitura de prontuários.

A tela usa esses perfis prontos, sem montar uma combinação personalizada de escopos. Para mudar os acessos posteriormente, edite a chave existente.

Serviços permitidos

Nos perfis com acesso à agenda (Agendamento IA e Acesso Completo), selecione explicitamente os serviços que a integração poderá consultar e agendar. É obrigatório selecionar pelo menos um serviço para salvar. Nos demais perfis, a seleção de serviços não se aplica.

Se uma chave antiga aparecer como Pendente de configuração, abra a edição e escolha os serviços permitidos. A coluna Serviços mostra a configuração de acesso; o gráfico de uso mostra a atividade registrada.

Editando uma chave existente

  1. Na lista de chaves ativas, clique no lápis (Editar chave) da integração.
  2. No modal Editar API Key, ajuste o nome e o Preset de Escopos, conforme necessário.
  3. Se o perfil acessar a agenda, revise os Serviços permitidos.
  4. Ative ou desative Expor telefone completo (sem máscara) conforme a necessidade da integração.
  5. Clique em Salvar alterações.

A credencial continua a mesma: a edição não gera outro segredo e não exige substituir a chave no sistema integrado. Os acessos passam a seguir a configuração salva; remover escopos ou serviços pode impedir as chamadas que dependem deles.

Por exemplo, se uma agência já usa uma chave válida e precisa receber o telefone sem máscara, edite essa chave e ative Expor telefone completo (sem máscara). Não é necessário revogar e recriar a credencial para esse ajuste.

Telefone completo e limites

Por padrão, a chave é criada sem autorização para expor o telefone completo. O switch Expor telefone completo (sem máscara) pode ser alterado tanto na criação quanto na edição. Ative essa opção apenas quando a integração realmente precisar do dado e houver uma finalidade legítima para o tratamento.

As rotas de agendamento e o detalhe de lead com timeline possuem limite de 60 requisições por minuto. As listas de integração permitem 300 requisições por minuto. Os contadores são independentes: no perfil de acesso completo, sincronizar listas não reduz a capacidade reservada ao agendamento.

Copie a chave imediatamente

Após a criação, a credencial completa, iniciada por ncrm_live_, é exibida uma única vez. Copie-a antes de fechar a janela. Depois disso, o CRM mostra somente seu prefixo e não consegue recuperar o segredo original.

Para autenticar uma chamada, a integração envia a chave no cabeçalho X-API-Key, conforme a documentação técnica.

Revogando uma chave

Clique na ação de revogação e confirme. A chave deixa de aparecer entre as ativas e não deve mais ser aceita pela API.

Em caso de troca de fornecedor, perda da credencial ou suspeita de vazamento, revogue-a e gere uma nova. Para apenas ajustar acessos, serviços ou telefone completo de uma integração existente, use a edição.

Boas práticas de segurança

  • Conceda somente o perfil necessário para a integração.
  • Nunca coloque a chave em código executado no navegador ou em aplicativo distribuído ao público.
  • Não envie credenciais por e-mail ou mensagens sem proteção adequada.
  • Não registre a chave completa em logs.
  • Armazene-a em um gerenciador de segredos no servidor que fará as chamadas.
  • Revogue chaves que não são mais utilizadas.

Precisa de ajuda?

Nossa equipe de suporte está pronta para te ajudar com qualquer dúvida.

Falar com suporte