Gerando chaves de API

Chaves de API permitem que você acesse os recursos da Docana de forma programática e os integre às suas aplicações. Este tutorial vai guiar você pelo processo de criação de uma chave de API.

Pré-requisitos

Você precisa ter uma conta Docana com permissões adequadas para gerar chaves de API. Fale com o administrador da sua organização caso não tenha acesso à área de Desenvolvedor.

Etapa 1: Acesse a Docana

Acesse platform.docana.com e informe o domínio da sua empresa para começar.

Etapa 2: Autentique-se

Informe suas credenciais (e-mail e senha) ou utilize uma das opções de login federado disponíveis (Google ou Microsoft) para entrar.

Etapa 3: Navegue até API Keys

Depois de entrar, localize a seção Desenvolvedor na barra lateral esquerda. Expanda a seção e clique em API Keys. Você também pode acessar diretamente em API Keys.

Etapa 4: Veja suas chaves de API

Você verá a página de gerenciamento de chaves de API. Nela é possível visualizar todas as chaves existentes, seus status, data de criação, último uso e data de expiração.

Para criar uma nova chave, clique no botão + Criar API key no canto superior direito.

Etapa 5: Configure a sua chave de API

Na modal que será exibida:

1. Nome: Defina um nome descritivo para a sua chave de API. Isso ajuda a identificar o propósito da chave depois (por exemplo, "Backend de produção", "Ambiente de desenvolvimento", "Pipeline de CI/CD").

2. Expira em: Escolha quando a chave de API deve expirar. As opções normalmente incluem:

   • 1 mês
   • 3 meses
   • 6 meses
   • 1 ano
   • Data personalizada

Clique em + Criar para gerar sua chave de API.

Etapa 6: Copie a sua chave de API

Importante

Esta é a única vez que você verá a chave de API completa. Certifique-se de copiá-la agora e armazená-la com segurança. Você não poderá visualizá-la novamente após fechar esta janela.

Sua chave de API será exibida na tela. Clique em Copiar Key ou selecione o valor da chave e copie manualmente.

Armazene a chave com segurança em variáveis de ambiente ou em um gerenciador de segredos. Nunca faça commit de chaves de API no controle de versão.

Usando a sua chave de API

Depois de obter a sua chave de API, você pode utilizá-la para autenticar chamadas à API. Por exemplo, é possível arquivar uma conversa utilizando o endpoint de Archive thread.

As chaves de API da Docana são enviadas no cabeçalho Authorization usando o esquema ApiKey, não como Bearer:

Authorization: ApiKey SUA_API_KEY

Exemplo em cURL

THREAD_ID="seu-thread-id"
DOCANA_API_KEY="sua-api-key"

curl -X POST "https://platform.docana.com/api/threads/${THREAD_ID}/archive" \
  -H "Authorization: ApiKey ${DOCANA_API_KEY}"

Exemplo em TypeScript/JavaScript

const threadId = 'seu-thread-id';

const response = await fetch(
  `https://platform.docana.com/api/threads/${threadId}/archive`,
  {
    method: 'POST',
    headers: {
      Authorization: `ApiKey ${process.env.DOCANA_API_KEY}`,
    },
  }
);

if (!response.ok) {
  throw new Error('Falha ao arquivar a thread');
}

const result = await response.json();
console.log('Thread arquivada:', result.thread);

Gerenciando chaves de API

Visualizando detalhes da chave

Na lista de chaves de API, você consegue ver:

• ID: Identificador único da chave
• Nome: O nome descritivo que você definiu
• Status: Se a chave está ativa ou revogada
• Criada em: Quando a chave foi criada
• Último uso: A última vez em que a chave foi utilizada (útil para identificar chaves não utilizadas)
• Expira em: Quando a chave irá expirar

Revogando uma chave

Se você suspeitar que uma chave foi comprometida ou se ela não for mais necessária:

1. Vá até a página de API Keys
2. Localize a chave que deseja revogar
3. Clique no ícone de exclusão/revogação
4. Confirme a ação

perigo

Revogar uma chave é imediato e não pode ser desfeito. Qualquer aplicação que estiver utilizando essa chave perderá acesso na mesma hora.

Boas práticas

1. Use nomes descritivos: Nomeie suas chaves de acordo com o propósito (por exemplo, "Aplicação de produção", "Ambiente de staging", "CI/CD").
2. Defina expiração adequada: Escolha uma data de expiração que equilibre segurança e operação. Prazos menores tendem a ser mais seguros.
3. Faça rotação periódica: Mesmo que as chaves não tenham expirado, considere rotacioná-las periodicamente como boa prática de segurança.
4. Use variáveis de ambiente: Nunca deixe chaves de API diretamente no código-fonte. Utilize variáveis de ambiente ou um gerenciador de segredos.
5. Separe por escopo: Sempre que possível, crie chaves diferentes para aplicações ou ambientes distintos.
6. Monitore o uso: Verifique regularmente a coluna "Último uso" para identificar chaves que podem ser desativadas.

Próximos passos

• Referência de API - Explore os endpoints disponíveis (em breve)
• Servidores MCP - Configure integrações usando Model Context Protocol (em breve)
• Webhooks - Configure webhooks para receber atualizações em tempo real (em breve)