Uma chave de API é a credencial que outro sistema usa para cadastrar contatos e disparar e-mail na sua conta, sem passar pela tela. É assim que a loja virtual da Casa Moura Cafés manda o e-mail transacional pedido-confirmado a cada compra, ou cadastra o cliente novo na lista Clientes da loja.
As chaves ficam em Configurações › Integrações, no cartão Chaves de API, e só o Dono as cria e revoga. O motivo: uma chave alcança a base de contatos sem tela, sem login e sem prazo de validade. Se a aba não aparece para você, fale com o suporte.
Criar uma chave
Clique em Nova chave e preencha:
- Nome — o sistema que vai usá-la, como Loja virtual. É por ele que você vai saber qual revogar.
- O que esta chave pode fazer — as permissões. Marque só as que o sistema usa. Uma permissão não inclui a outra: Cadastrar e corrigir contatos não dá direito a Ler contatos.
- Onde ela pode agir — aparece quando a conta tem espaços de envio. Veja abaixo.
- Tipo padrão das mensagens — Transacional ou Marketing, usado quando o envio não diz o tipo. Ele decide o consentimento exigido e onde o envio aparece nos relatórios: marketing respeita o descadastro, transacional não. Os dois consomem a mesma cota. A loja da Casa Moura usa Transacional, porque confirmação de pedido precisa chegar mesmo para quem saiu da lista de novidades.
A chave aparece uma vez só
Ao criar, a janela Chave criada mostra o valor completo. Copie e guarde agora: ele não aparece de novo, nem para o suporte. A janela não fecha ao clicar fora, de propósito — a saída é Concluir. O sistema manda a chave no cabeçalho Authorization: Bearer de cada chamada.
Perdeu a chave? Não há como recuperá-la: crie outra e revogue a perdida.
Onde a chave pode agir
Com espaços de envio na conta, o campo Onde ela pode agir decide o alcance:
- Nenhum marcado — a chave age só na conta principal, e não alcança espaço nenhum.
- Espaços marcados — age só neles, sem a conta principal. Quem precisa dos dois usa duas chaves.
- Todos os espaços atuais — atalho que marca os espaços que existem hoje. Um espaço criado depois não entra sozinho: é preciso editar a chave e marcá-lo.
Para a chamada acontecer num espaço, o sistema manda o identificador dele no cabeçalho X-WiseData-Space — o valor aparece em Configurações › Espaços de envio.
Chave de homologação
Marque Chave de homologação para o ambiente de testes do sistema. Com ela, o disparo é aceito por inteiro, mas nenhum e-mail sai e nada consome cota: a mensagem vai para a Caixa de teste, onde você lê o conteúdo e simula o que aconteceria.
Ela só pode ter as permissões de envio e de leitura de campos e listas. Não mexe em contatos: os contatos seriam os reais da conta, e um teste alteraria a base de verdade. Na lista, a chave aparece com o selo Homologação — confira o selo antes de copiar uma chave para a configuração do sistema, porque trocar uma pela outra faz a produção parar de enviar sem erro aparente.
Chave de plataforma
Aparece para contas com espaços de envio. É para um sistema que atende vários clientes, cada um no seu espaço: ela cria espaços pela API e alcança todos eles, inclusive os criados depois. É a única chave com as permissões de espaços, e não pode ser de homologação.
É a credencial de maior alcance da conta: se vazar, alcança a base de todos os espaços. Use só se o seu sistema realmente cria e opera espaços.
A lista de chaves
Cada chave mostra os quatro últimos caracteres, a situação (Ativa ou Revogada), os selos, as permissões, onde age, o último uso e quem a criou. O último uso é o que diz se uma chave ainda está em pé — uma chave que nunca foi usada provavelmente foi esquecida.
Editar
Editar muda nome, permissões, alcance e tipo sem trocar o valor da chave: o sistema continua funcionando, e o que mudou vale na chamada seguinte. Ligar ou desligar a homologação na edição muda o comportamento na hora — a tela avisa antes de salvar.
Revogar e trocar
Revogar faz o sistema que usa a chave parar imediatamente. A chave continua na lista, marcada como revogada, para registrar quando isso aconteceu.
Não existe trocar o valor de uma chave. Para substituir sem derrubar o sistema: crie a nova, instale no sistema, confira o último uso dela e só então revogue a antiga. Se a chave vazou, a ordem se inverte: revogue primeiro.
Boas práticas
- Uma chave por sistema, com só as permissões daquele sistema. Revogar uma não derruba as outras.
- A chave é de servidor. Nunca em página, aplicativo, navegador ou repositório público.
Para onde ir depois
- Webhooks — o caminho de volta: o WiseData Mail avisando o seu sistema do que aconteceu com cada e-mail.
- Caixa de teste — onde chegam os envios da chave de homologação.
- Métricas da API — o que a integração enviou.
- Espaços de envio — o identificador de cada espaço para a API.
Resumindo: crie uma chave por sistema com só as permissões necessárias, copie o valor na hora porque ele não aparece de novo, marque os espaços quando a chave precisar agir neles, use a chave de homologação nos testes e, para trocar, crie a nova antes de revogar a antiga.