Autenticação com a chave de API
Guarde a chave de API numa variável de ambiente, mande no cabeçalho X-ACCESS-TOKEN, reconheça o erro 401 e troque a chave sem parar as integrações.
A API da NexTags reconhece a conta pela chave de API: cada chamada leva a chave no cabeçalho X-ACCESS-TOKEN. Neste guia, você guarda a chave fora do código, faz uma chamada autenticada, aprende a reconhecer o erro de chave e a trocar a chave quando precisar.
Antes de começar
- A chave de API da conta, gerada em Configurações › Integrações › Chave de API do NexTags › Gerar. O passo a passo com prints está em Gerar a chave de API.
- Acesso de Super Administrador: só ele abre as Configurações. Veja Administradores e permissões.
- Um servidor ou computador para rodar os exemplos, com cURL, Node 18 ou mais novo, Python 3 com
requestsou PHP com a extensão cURL.
Passo a passo
Passo 1: Guarde a chave numa variável de ambiente
Guarde a chave numa variável de ambiente chamada NEXTAGS_API_KEY, na máquina que vai chamar a API. Assim a chave não fica escrita no código nem vai parar no Git.
export NEXTAGS_API_KEY="cole-aqui-a-chave"$env:NEXTAGS_API_KEY = "cole-aqui-a-chave"Em produção, cadastre a variável no painel da hospedagem, do contêiner ou da função, ou no cofre de segredos que você usa. Todos os exemplos desta documentação leem a chave de NEXTAGS_API_KEY.
A chave age como a conta inteira
A chave não tem permissões por área: com ela, dá para ler os contatos, enviar mensagens e mexer em etiquetas, pipelines, pedidos e agentes da conta. A conta tem uma chave só, a mesma no Zapier, no Make, no Pabbly, no n8n e no seu sistema. Por isso, a chamada sai sempre do servidor, nunca do navegador nem do app do celular: lá, qualquer pessoa veria a chave.
Passo 2: Mande a chave no cabeçalho X-ACCESS-TOKEN
Em toda chamada, mande o cabeçalho X-ACCESS-TOKEN com a chave. Para testar, use Consultar a conta, que só lê os dados da conta:
curl "https://app.nextagsai.com.br/api/accounts/me" \
-H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/me', {
headers: {
'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
},
});
const dados = await resposta.json();
console.log(resposta.status, dados);import os
import requests
resposta = requests.get(
"https://app.nextagsai.com.br/api/accounts/me",
headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
timeout=30,
)
print(resposta.status_code, resposta.json())<?php
$ch = curl_init('https://app.nextagsai.com.br/api/accounts/me');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);Com a chave certa, a resposta é 200 com os dados da conta. Os campos estão em Sua primeira requisição.
Passo 3: Reconheça o erro de chave
Sem a chave, com a chave incompleta ou com uma chave que foi excluída, a API responde 401, em qualquer endereço, com este corpo:
{"error": {"code": 401, "message": "No valid API key provided."}}O cabeçalho Content-Type dessa resposta vem text/html; charset=UTF-8, mas o corpo é JSON. Leia o corpo como JSON sem confiar no cabeçalho. Trate o 401 como chave errada: repetir a chamada não resolve.
curl -i "https://app.nextagsai.com.br/api/accounts/me" \
-H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/me', {
headers: {
'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
},
});
// json() lê o corpo como JSON mesmo com o Content-Type text/html do erro de chave
const dados = await resposta.json();
if (resposta.status === 401) {
throw new Error(`Chave de API recusada: ${dados.error.message}`);
}
console.log(dados);import os
import requests
resposta = requests.get(
"https://app.nextagsai.com.br/api/accounts/me",
headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
timeout=30,
)
# json() lê o corpo como JSON mesmo com o Content-Type text/html do erro de chave
dados = resposta.json()
if resposta.status_code == 401:
raise RuntimeError("Chave de API recusada: " + dados["error"]["message"])
print(dados)<?php
$ch = curl_init('https://app.nextagsai.com.br/api/accounts/me');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
],
]);
// json_decode lê o corpo como JSON mesmo com o Content-Type text/html do erro de chave
$dados = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) === 401) {
throw new RuntimeException('Chave de API recusada: ' . $dados['error']['message']);
}
print_r($dados);Passo 4: Troque a chave quando precisar
Troque a chave se ela vazou ou se alguém que a conhecia saiu da equipe. Em Configurações › Integrações › Chave de API do NexTags, clique em Excluir e depois em Gerar. A chave antiga para de valer: atualize a variável de ambiente e todas as ferramentas que usavam a antiga.
export NEXTAGS_API_KEY="cole-aqui-a-chave-nova"$env:NEXTAGS_API_KEY = "cole-aqui-a-chave-nova"O Excluir não pede confirmação
Entre o Excluir e o Gerar, a conta fica sem chave, e toda chamada recebe 401. Deixe abertas as ferramentas que usam a chave (Zapier, Make, Pabbly, n8n, o seu sistema) e troque tudo de uma vez.
Pronto: como conferir
- Consultar a conta responde
200, com onameda sua conta. - O cartão Chave de API do NexTags mostra o selo Ativa.
Se não funcionou
401 com "No valid API key provided."
A chave não veio, veio incompleta ou foi excluída. Confira o nome do cabeçalho (X-ACCESS-TOKEN) e copie a chave inteira, sem espaços no começo ou no fim. Se a chave foi trocada, use a nova.
O cliente HTTP diz que a resposta não é JSON
O erro de chave vem com Content-Type: text/html, mas o corpo é JSON. Leia o texto do corpo e converta para JSON você mesmo, sem depender do cabeçalho.
A chamada funciona no meu computador e falha no servidor
A variável NEXTAGS_API_KEY não chegou ao processo do servidor. Cadastre a variável no painel da hospedagem, do contêiner ou da função e reinicie a aplicação.
Não vejo a aba Integrações
Só Super Administrador abre as Configurações. Peça a um Super Administrador para gerar a chave e entregar por um canal seguro, como o cofre de senhas da equipe.
Faça com a IA
Copie o pedido e cole no ChatGPT ou no Claude.
Vou integrar o meu sistema à API da NexTags. Leia https://docs.nextags.com.br/comecar/autenticacao.md e https://docs.nextags.com.br/comecar/primeira-requisicao.md.
Meu sistema usa [linguagem e framework, por exemplo: Node 20 com Express]. Escreva um módulo cliente da API que lê a chave da variável de ambiente NEXTAGS_API_KEY, manda o cabeçalho X-ACCESS-TOKEN em toda chamada, lê o corpo como JSON mesmo quando o Content-Type vem text/html e lança um erro claro quando a resposta for 401. Não peça a minha chave.
Relacionados
Este conteúdo ajudou?
Obrigado! Sua resposta ajuda a melhorar a central.