Visão geral da API
O que a API REST da NexTags faz em cada recurso, a URL base e o formato das respostas, dos IDs, das datas e do dinheiro. E o que fica fora dela.
A API da NexTags deixa o seu sistema trabalhar com a conta sem abrir o painel: criar e achar contatos, enviar fluxos e mensagens, pôr etiquetas, preencher campos, mover oportunidades, cuidar do carrinho e dos pedidos e acompanhar os Broadcasts. É uma API REST: cada recurso tem um endereço, e as respostas vêm em JSON.
Toda chamada leva a chave de API da conta no cabeçalho X-ACCESS-TOKEN e sai do seu servidor. Comece por Autenticação com a chave de API e Sua primeira requisição.
Como funciona
O que a API faz
| Recurso | O que dá para fazer | Referência |
|---|---|---|
| Conta | Consultar os dados da conta e listar os administradores, as equipes e as integrações ligadas. | Conta |
| Contatos | Criar um contato, consultar pelo ID e buscar pelo telefone, pelo e-mail ou por um campo personalizado. | Contatos |
| Mensagens | Enviar ao contato um fluxo, um texto, um arquivo ou um conteúdo com várias mensagens e ações. | Mensagens |
| Etiquetas | Listar, criar, buscar pelo nome e apagar etiquetas; pôr e tirar etiquetas do contato. | Etiquetas |
| Campos personalizados | Listar, criar e buscar campos pelo nome; ler, preencher e limpar o valor de cada contato. | Campos personalizados |
| Campos do bot | Ler, preencher e limpar um campo do bot, o valor único da conta. | Campos do bot |
| Fluxos e modelos | Listar os fluxos; instalar na conta um modelo da ferramenta Templates e gerar um link de uso único dele. | Fluxos e modelos |
| Pipelines | Listar pipelines, etapas e campos; criar, consultar, atualizar, transferir e apagar oportunidades; comentar. | Pipelines e oportunidades |
| Agentes de IA | Listar e consultar os agentes do AI Hub; atualizar o prompt, o modelo e o limite de tokens; listar funções, servidores MCP e arquivos; salvar mensagens no histórico da IA do contato. | Agentes de IA |
| E-commerce | Consultar e atualizar produtos (preço, estoque e se está ativo); enviar produtos; mexer no carrinho; consultar e alterar pedidos e marcar como pagos. | E-commerce |
| Disparos | Listar, consultar, reenviar e cancelar Broadcasts. | Disparos |
| Agenda | Listar e consultar os calendários do Gestor de Agendamentos. | Agenda |
| Ferramentas | Formatar números, trocar e recortar textos, codificar URLs, gerar QR Code e hash e calcular distâncias, para usar nas requisições externas dos fluxos. | Ferramentas |
O endereço e os métodos
A URL base é https://app.nextagsai.com.br/api. Junte a ela o caminho do endpoint:
GET https://app.nextagsai.com.br/api/accounts/me
X-ACCESS-TOKEN: <a chave da conta>GETlê,POSTcria e altera (inclusive para atualizar oportunidades, produtos e pedidos) eDELETEapaga ou limpa. A API não usaPUTnemPATCH.- As respostas vêm em JSON. No erro de chave, o corpo é JSON, mas o cabeçalho
Content-Typevemtext/html: leia o corpo como JSON sem olhar o cabeçalho. Veja Limites, erros e boas práticas.
Corpo em JSON ou em formulário
O corpo vai em JSON (Content-Type: application/json), menos nestas chamadas, que recebem formulário (application/x-www-form-urlencoded):
| Chamada | Campo |
|---|---|
Criar etiqueta, POST /accounts/tags | name |
Preencher campo do contato, POST /contacts/{contact_id}/custom_fields/{custom_field_id} | value |
Preencher campo do bot, POST /accounts/bot_fields/{bot_field_id} | value |
Adicionar produto ao carrinho, POST /contacts/{contact_id}/cart/{product_id} | quantity |
Marcar pedido como pago, POST /contacts/{contact_id}/pay/{order_id} | amount_received |
As ferramentas, POST /tools/..., menos /tools/echo | os campos de cada ferramenta |
Quatro chamadas não levam corpo: Enviar fluxo, Reenviar disparo, Cancelar disparo e Gerar link de uso único do modelo.
Listas
Umas listas vêm direto, como [...]; outras vêm dentro de data, como {"data": [...]}:
| Formato | Chamadas |
|---|---|
[...] | Etiquetas, campos personalizados, fluxos, administradores e equipes da conta; etiquetas e campos de um contato. |
{"data": [...]} | Busca de contatos, pipelines, etapas, oportunidades, comentários, agentes de IA, funções, servidores MCP, arquivos dos agentes, calendários e disparos. |
IDs
- Os IDs são números inteiros: contato, fluxo, etiqueta, campo, pipeline, etapa, oportunidade, agente, produto, disparo, calendário. Guarde em inteiro de 64 bits ou como texto.
- O ID do pedido (
order_id) é texto. - Na busca de contatos, o
field_idaceita o ID de um campo e tambémphoneeemail.
Onde achar cada um: Contatos, fluxos e outros identificadores.
Datas e horas
| Onde | Formato | Exemplo |
|---|---|---|
Datas dos objetos, como created_at, updated_at e subscribed_date | Texto em UTC, AAAA-MM-DD HH:MM:SS | 2026-10-26 12:00:00 (9h em Brasília) |
last_sent, last_delivered, last_seen e last_interaction do contato | Unix timestamp em milissegundos | 1793016000000 |
| Valor de um campo personalizado do tipo Data ou Data e hora | Unix timestamp em segundos | 1794279600 (10/11/2026, 0h em Brasília) |
Converta para o fuso da sua conta antes de mostrar a data a alguém.
Dinheiro
| Valor | Unidade | Exemplo |
|---|---|---|
total, subtotal e coupon_discount do carrinho e do pedido | Centavos | 17980 = R$ 179,80 |
amount_received de Marcar pedido como pago | Centavos | 17980 = R$ 179,80 |
price de cada item do carrinho (line_items) | Reais, não centavos | 89.9 = R$ 89,90 |
price e sale_price do produto | Reais, não centavos | 89.9 = R$ 89,90 |
value da oportunidade | O contrato não diz | Confira no seu teste como o valor aparece no cartão. |
O que a API não faz
| Você quer | Como fazer |
|---|---|
| Listar todos os contatos | Não há lista de contatos. Busque pelo telefone, pelo e-mail ou por um campo (guia) ou exporte na tela (Exportar contatos). |
| Mudar o nome, o telefone ou o e-mail de um contato | Não há chamada de atualizar contato. Use a ação set_field_value com first_name, last_name, full_name, phone ou email em Enviar conteúdo. Veja Mensagens e ações em JSON. |
| Apagar um contato | Na tela, nas ações em massa de Contatos, ou num fluxo, com a ação Excluir Contato (Todas as ações do fluxo). |
| Ler as conversas e as mensagens da Caixa de Entrada | Não há. Para levar dados da conversa ao seu sistema, use a requisição externa no fluxo ou os webhooks de saída. |
| Criar um Broadcast | Na tela: Criar um Broadcast. A API lista, consulta, reenvia e cancela (guia). |
| Enviar um Modelo de Mensagem do WhatsApp | Monte um fluxo que comece com o modelo (Modelo de mensagem do WhatsApp no fluxo) e envie o fluxo (guia). |
| Inscrever um contato numa sequência | Num fluxo, com a ação Inscrever-se em uma sequência (Inscrever e cancelar inscrição em sequência). Pela API, envie esse fluxo. |
| Criar fluxos, pipelines, etapas, agentes de IA ou produtos | Na tela. |
| Listar pedidos ou criar agendamentos | Na tela. A API consulta um pedido pelo ID e lista os calendários. |
Arquivos para baixar
O contrato da API está na Referência, em dois formatos: o OpenAPI em JSON, para gerar clientes e dar contexto a uma IA, e a coleção do Postman, para testar as chamadas.
Quando usar
- O seu sistema precisa agir na NexTags quando algo acontece nele, como uma venda, um cadastro ou um pagamento: chame a API.
- A NexTags precisa avisar o seu sistema, ou um fluxo precisa de dados dele: use os webhooks.
- Você quer ligar ferramentas sem programar: use a API pelo Make, n8n e Zapier.
- Uma IA vai escrever a integração: entregue a ela a documentação pronta para IA.
Boas práticas
Chame a API do seu servidor
A chave dá acesso à conta inteira. Nunca a coloque no código do navegador nem no app do celular: qualquer pessoa veria a chave. Veja Autenticação com a chave de API.
Procure antes de criar
Antes de criar um contato, uma etiqueta ou uma oportunidade, procure se já existe. Assim uma nova tentativa não duplica dados. Veja Criar ou atualizar um contato.
Guarde os IDs
Depois de achar o ID de uma etiqueta, de um campo ou de um fluxo, guarde no seu sistema. Os IDs não mudam quando o nome muda, e você economiza chamadas.
Relacionados
Este conteúdo ajudou?
Obrigado! Sua resposta ajuda a melhorar a central.