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
- Clique em Nova API Key.
- Informe um nome que identifique claramente a integração.
- Escolha um dos perfis de acesso disponíveis.
- Se o perfil acessar a agenda, selecione os Serviços permitidos.
- Decida se a integração poderá receber o telefone completo.
- 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
- Na lista de chaves ativas, clique no lápis (Editar chave) da integração.
- No modal Editar API Key, ajuste o nome e o Preset de Escopos, conforme necessário.
- Se o perfil acessar a agenda, revise os Serviços permitidos.
- Ative ou desative Expor telefone completo (sem máscara) conforme a necessidade da integração.
- 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