Chaves de API: conectar outro sistema à sua conta

5 min de leitura82
Copiar para a I.A.:

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.

Este artigo foi útil?