OneTrace.pro Central de ajuda

Chaves de API

Uma chave de API permite que o site, o aplicativo ou o seu servidor trabalhe com o projeto sem entrar na interface: enviar eventos, ler perfis e gerenciar segmentos, jornadas e campanhas. As chaves são criadas e revogadas em “Configurações” → “Chaves de API”.

A seção fica visível para “Proprietário”, “Administrador” e “Gerente”. Criar e revogar chaves é permitido para “Proprietário” e “Administrador”.

Lista de chaves de API

Tipos de chave

Write Secret
Começa com cdp_wk_ cdp_sk_
O que permite apenas enviar eventos enviar eventos e executar ações no projeto, conforme as permissões escolhidas
Onde usar código do site, aplicativo móvel, servidor somente no seu servidor
Pode ser exposta a terceiros sim, ela aparece no código das páginas do site não, mantenha-a em segredo
Limite de requisições 6000 por minuto 1200 por minuto (padrão)

A chave de gravação (Write) é pública por natureza: ela fica no código de cada página do site. Com ela só é possível enviar eventos, então um vazamento não dá acesso aos dados. Para impedir que outro site envie eventos em seu nome, você pode informar na seção Site → Conexão os domínios dos quais a chave é aceita; veja Conexão do site.

A chave secreta (Secret) dá acesso aos dados do projeto pelo servidor. Nunca a coloque no código das páginas, em aplicativos móveis ou em repositórios públicos.

Como criar uma chave

  1. Abra “Chaves de API”.
  2. No cartão “Nova chave”, informe o “Nome”: por ele você vai saber depois onde a chave é usada, por exemplo “Site” ou “Servidor da loja virtual”.
  3. Escolha o “Tipo”: “Gravação” (Write) ou “Secreta” (Secret).
  4. Para a chave secreta, marque as “Permissões da chave”: apenas o que a integração realmente precisa.
  5. Clique em “Criar chave”.

Criação de uma chave secreta com permissões

Logo após a criação, a chave completa aparece no topo da página. Clique em “Copiar” e guarde-a, por exemplo em um gerenciador de senhas ou nas variáveis de ambiente do servidor. A chave secreta é exibida apenas uma vez: guardamos somente a impressão digital dela, e não é possível recuperá-la. Se você a perder, crie uma nova e revogue a antiga.

É mais prático criar a chave de gravação do site diretamente na seção Site → Conexão: lá ela já entra no código de instalação e fica disponível a qualquer momento; veja Conexão do site.

Na tabela de chaves aparecem o nome, quem criou e quando, o tipo, o início da chave (por exemplo, cdp_sk_a1b2…), o número de permissões e a data do último uso.

Permissões da chave secreta

Você só pode conceder à chave as permissões que você mesmo possui. As permissões valem para o projeto inteiro: não é possível limitar a chave a jornadas ou segmentos específicos.

Permissão O que libera
Ler perfis perfil por identificador e os eventos dele
Dados pessoais sem máscara e-mail, telefone e outros dados pessoais sem máscara; sem essa permissão, eles são mascarados
Alterar perfis e consentimentos consentimentos para mensagens, vínculo com o Telegram
Excluir perfis (GDPR) exclusão do perfil a pedido do cliente
Catálogo de eventos e atributos lista de eventos e de propriedades dos perfis
Alterar o esquema de eventos substituição do esquema de eventos do projeto, veja Esquema de eventos
Ler / alterar segmentos visualizar, criar, alterar, excluir e recalcular segmentos
Ler jornadas e relatórios; editar rascunhos e inscrever participantes; publicar, pausar e arquivar jornadas trabalho com jornadas
Ler campanhas e relatórios; criar e editar campanhas; lançar, pausar e cancelar campanhas trabalho com campanhas
Ler o catálogo de produtos e as recomendações; enviar e excluir produtos produtos e recomendações
Envio de mensagens avulsas mensagens transacionais e cascatas a partir do seu servidor; veja Mensagens transacionais e cascatas
Análises cálculo de relatórios, leitura de relatórios salvos e painéis, relatório da jornada
Relatórios salvos e painéis criação, alteração e exclusão de relatórios salvos e painéis; veja Painéis e envio de relatórios
Conversas do chat; respostas no chat e encerramento de conversas leitura de conversas e respostas aos clientes em nome da chave, para bots e helpdesk; veja Chat online

Exemplo: para uma chave que sincroniza clientes VIP a partir do CRM, bastam as permissões “Ler segmentos” e “Alterar segmentos”.

Todas as ações realizadas com uma chave secreta ficam registradas no log de auditoria do projeto em nome da chave; veja Configurações do projeto, plano e auditoria.

Como revogar uma chave

  1. Encontre a chave na tabela e clique em “Revogar”.
  2. Confirme a ação.

As requisições com essa chave param de funcionar na hora (resposta 401). A chave revogada continua na lista com a marca “Revogada”, para que o histórico dela fique visível. Não é possível reativá-la; se precisar, crie uma nova.

Revogue a chave imediatamente se ela puder ter chegado a terceiros, se um funcionário com acesso a ela tiver saído da empresa ou se a integração não for mais usada.

O que é importante saber

  • Limites. Ao exceder o limite de requisições ou a cota mensal de eventos do plano, a API responde 429. Distribua os envios de forma uniforme e repita a requisição após uma pausa.
  • Troca segura da chave. Crie uma nova chave, atualize-a no servidor, verifique se as requisições estão chegando (campo “Último uso”) e só então revogue a antiga.
  • Uma chave para cada integração. Assim o log de auditoria mostra quem fez o quê e, em caso de vazamento, basta revogar uma chave.
  • Para saber como enviar eventos e chamar a API pelo servidor, veja o artigo Integração pelo servidor.
  • A chave secreta também serve para conectar um assistente de IA, como o Claude Code; veja Assistentes de IA (MCP).