Chaves de API

A chave de API é a senha que uma ferramenta usa para acessar o seu CRM pela API. Quem tiver a chave consegue mexer nos dados da conta, então trate-a como uma senha. Se ainda não conhece a API, comece pela visão geral.

Criar uma chave

Qualquer membro da conta pode criar e revogar chaves. A conta pode ter até 25 chaves ativas ao mesmo tempo.

1. Abra a tela de chaves. No menu lateral, clique em Integrações e depois na aba API. Se preferir, vá direto para dattacrm.com.br/integracoes/api.

2. Clique em Criar chave. Se ainda não há nenhuma, a tela mostra “Nenhuma chave de API ainda”.

3. Dê um nome à chave. Preencha o campo Nome com algo que diga onde ela será usada, por exemplo n8n. Isso ajuda a saber qual chave revogar depois.

4. Escolha o acesso. No campo Acesso, escolha Leitura e escrita (já vem marcada) ou Somente leitura. Veja a diferença logo abaixo.

5. Escolha a validade. No campo Validade, escolha por quanto tempo a chave vale. Veja as opções logo abaixo.

6. Clique em Criar chave. Abre a janela Chave criada, com a chave no campo “Sua chave de API”.

7. Copie a chave e guarde em um lugar seguro. Clique em Copiar chave. Depois cole em um lugar seguro, como o seu gerenciador de senhas ou direto na ferramenta que vai usá-la.

8. Feche a janela. Clique em Já guardei a chave. É o único botão que fecha a janela. Antes de clicar, confira que a chave foi guardada: depois disso ela não aparece mais.

Acesso

No campo Acesso você escolhe o que a chave pode fazer:

• Leitura e escrita: consulta, cria e altera leads, vendas, listas, campos personalizados, formulários, campanhas e gatilhos (webhooks). É a opção para o n8n, o Zapier e qualquer ferramenta que grava no CRM.
• Somente leitura: só consulta. Pedidos que criam, alteram ou apagam dados, inclusive criar gatilhos, são recusados com o erro insufficient_scope. Use para painéis e relatórios que só leem.

Na lista, a chave somente leitura aparece com a marca Somente leitura. O acesso não muda depois de criada: para trocar, crie uma chave nova e revogue a antiga. As chaves criadas antes desta opção existir são de leitura e escrita.

Validade

No campo Validade você escolhe uma destas cinco opções:

• 24 horas
• 7 dias
• 30 dias
• 90 dias (já vem marcada)
• Sem expiração

Quando a validade termina, a chave para de funcionar e vai para o grupo Inativas, com a situação Vencida.

Os avisos da tela

A tela mostra até três avisos. Leia com atenção, são os que protegem a sua conta.

Aviso fixo, no alto do formulário

Aparece sempre, no topo da janela Criar chave de API. Com Leitura e escrita:

Atenção

Ação arriscada. Uma chave de API dá acesso completo aos dados desta conta: quem tiver a chave pode ler, criar e alterar leads, vendas, formulários e campanhas. Use apenas em ferramentas de confiança.

Com Somente leitura:

Atenção

Ação arriscada. Uma chave somente leitura dá acesso de leitura a todos os dados desta conta: quem tiver a chave pode consultar leads, vendas, formulários e campanhas, mas não criar nem alterar nada. Use apenas em ferramentas de confiança.

Ao escolher “Sem expiração”

Aparece quando você marca a validade Sem expiração.

Atenção

Ação arriscada. Recomendamos o uso de chaves com vencimento, exceto quando você precisa de uma conexão direta com uma ferramenta.

Na janela “Chave criada”

Aparece logo depois de criar a chave, junto com a chave.

Guarde a chave agora

Copie e guarde esta chave agora. Por segurança, ela não será exibida novamente. Se você perder a chave, será preciso criar outra.

Listas e tags de cada envio

A chave não tem lista. Uma única chave serve para mandar leads para qualquer lista da conta: você escolhe a lista e as tags em cada envio.

• No n8n, o nó Datta CRM tem um campo de listas e outro de tags, carregados da sua conta. Veja n8n.
• Em outras ferramentas, mande listId (ou listIds) e tags na chamada. Veja Primeira chamada.

Para criar um lead, a lista é obrigatória: sem listId nem listIds, a API responde 400 list_required e nada é gravado. Um lead que já existe pode ser atualizado sem lista. O campo source é ignorado: a origem do lead é a da lista escolhida. Veja Origens.

Por que a chave aparece uma vez só

O CRM não guarda a chave. Ele guarda só uma “impressão digital” dela: um código que permite reconhecer a chave quando a ferramenta a apresenta, mas que não permite descobrir a chave original. É como um cofre que sabe conferir a sua senha, mas não consegue lê-la.

Por isso, ninguém, nem a Datta, consegue mostrar a chave de novo depois que a janela fecha. Se você perder, crie outra e revogue a antiga.

Aviso de vencimento

Quando uma chave está perto de vencer, o CRM avisa 24 horas antes todas as pessoas da conta, pela central de notificações: no sino do app e também por e-mail, conforme as preferências de cada pessoa. Veja Notificações.

O aviso traz o nome da chave, o horário do vencimento e o link para a tela de chaves.

Chaves de 24 horas não recebem esse aviso. Só as criadas com validade maior que isso.

Chaves Sem expiração também não recebem o e-mail, porque nunca vencem.

Trocar a chave sem parar a integração

Não existe o botão “renovar”. Para trocar, você cria uma chave nova. A antiga e a nova funcionam juntas até a antiga vencer. Assim a integração não para no meio.

Há um cuidado com os gatilhos (webhooks), que são avisos automáticos que o CRM manda para outra ferramenta. Cada gatilho pertence à chave que o criou e não passa para a chave nova. Por isso, se a sua integração usa gatilhos, você precisa criá-los de novo com a chave nova.

1. Crie uma chave nova. Siga o passo a passo acima e copie a chave.

2. Troque a chave na ferramenta. No n8n, por exemplo, abra onde a chave está guardada e cole a chave nova no lugar da antiga. Confirme que a integração continua funcionando.

3. Crie os gatilhos de novo, se houver. Se a integração usa gatilhos (webhooks), crie-os de novo com a chave nova. Faça isso antes de a antiga vencer ou ser revogada.

4. Deixe a antiga vencer, ou revogue. Se a antiga vence em pouco tempo, pode deixá-la vencer. Se quiser encerrar o acesso dela agora, revogue (veja abaixo).

Revogar uma chave

Revogar tira o acesso da chave na hora, sem volta. Use quando a chave vazou, quando a ferramenta não é mais usada ou depois de trocar por uma nova.

1. Abra Integrações › API. Encontre a chave na lista.

2. Clique em Revogar. O CRM pergunta “Revogar a chave” e o nome dela, e avisa que quem estiver usando a chave perde o acesso na hora e que não dá para desfazer.

3. Clique em Revogar chave. A chave vai para o grupo Inativas, como Revogada.

Os gatilhos da chave também param

Os gatilhos (webhooks) criados por uma chave ficam “desativados” na hora quando ela é revogada. Quando a chave vence, eles também param de receber. Os gatilhos não passam para a chave nova: crie-os de novo com ela antes de revogar ou deixar vencer a antiga.

Ver o último uso

Na lista de chaves, cada chave mostra Último uso em seguido da data. Se ninguém usou a chave ainda, aparece Nunca usada.

É um bom jeito de descobrir quais chaves estão paradas e podem ser revogadas. Esse dado é atualizado no máximo uma vez por minuto. Por isso pode demorar um instante para mostrar o uso mais recente.

Problemas comuns

Aparece o limite de chaves ativas

A conta chegou a 25 chaves ativas. Revogue uma que não use mais e tente de novo.

Perdi a chave

Não dá para recuperar. Crie uma nova, troque na ferramenta e revogue a antiga.

Aparece o erro insufficient_scope

A chave é Somente leitura e a ferramenta tentou gravar. Crie uma chave de Leitura e escrita e troque na ferramenta.

A ferramenta parou de funcionar de repente

Veja a situação da chave na lista. Se estiver em Inativas como Vencida ou Revogada, crie uma nova chave e troque na ferramenta. Se havia gatilhos, crie-os de novo também.