# 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. Endereço: https://docs.nextags.com.br/comecar/visao-geral/ Tipo: Conceito Atualizado em: 26/10/2026 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](https://docs.nextags.com.br/comecar/autenticacao/) e [Sua primeira requisição](https://docs.nextags.com.br/comecar/primeira-requisicao/). ## 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](https://docs.nextags.com.br/referencia/conta/) | | Contatos | Criar um contato, consultar pelo ID e buscar pelo telefone, pelo e-mail ou por um campo personalizado. | [Contatos](https://docs.nextags.com.br/referencia/contatos/) | | Mensagens | Enviar ao contato um fluxo, um texto, um arquivo ou um conteúdo com várias mensagens e ações. | [Mensagens](https://docs.nextags.com.br/referencia/mensagens/) | | Etiquetas | Listar, criar, buscar pelo nome e apagar etiquetas; pôr e tirar etiquetas do contato. | [Etiquetas](https://docs.nextags.com.br/referencia/etiquetas/) | | Campos personalizados | Listar, criar e buscar campos pelo nome; ler, preencher e limpar o valor de cada contato. | [Campos personalizados](https://docs.nextags.com.br/referencia/campos-personalizados/) | | Campos do bot | Ler, preencher e limpar um campo do bot, o valor único da conta. | [Campos do bot](https://docs.nextags.com.br/referencia/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](https://docs.nextags.com.br/referencia/fluxos/) | | Pipelines | Listar pipelines, etapas e campos; criar, consultar, atualizar, transferir e apagar oportunidades; comentar. | [Pipelines e oportunidades](https://docs.nextags.com.br/referencia/pipelines/) | | 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](https://docs.nextags.com.br/referencia/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](https://docs.nextags.com.br/referencia/ecommerce/) | | Disparos | Listar, consultar, reenviar e cancelar Broadcasts. | [Disparos](https://docs.nextags.com.br/referencia/disparos/) | | Agenda | Listar e consultar os calendários do **Gestor de Agendamentos**. | [Agenda](https://docs.nextags.com.br/referencia/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](https://docs.nextags.com.br/referencia/ferramentas/) | ### O endereço e os métodos A URL base é `https://app.nextagsai.com.br/api`. Junte a ela o caminho do endpoint: ```http GET https://app.nextagsai.com.br/api/accounts/me X-ACCESS-TOKEN: ``` - `GET` lê, `POST` cria e altera (inclusive para atualizar oportunidades, produtos e pedidos) e `DELETE` apaga ou limpa. A API não usa `PUT` nem `PATCH`. - As respostas vêm em JSON. No erro de chave, o corpo é JSON, mas o cabeçalho `Content-Type` vem `text/html`: leia o corpo como JSON sem olhar o cabeçalho. Veja [Limites, erros e boas práticas](https://docs.nextags.com.br/comecar/limites-e-erros/). ### 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](https://docs.nextags.com.br/referencia/etiquetas/criar-etiqueta/), `POST /accounts/tags` | `name` | | [Preencher campo do contato](https://docs.nextags.com.br/referencia/campos-personalizados/preencher-campo-do-contato/), `POST /contacts/{contact_id}/custom_fields/{custom_field_id}` | `value` | | [Preencher campo do bot](https://docs.nextags.com.br/referencia/campos-do-bot/preencher-campo-do-bot/), `POST /accounts/bot_fields/{bot_field_id}` | `value` | | [Adicionar produto ao carrinho](https://docs.nextags.com.br/referencia/ecommerce/adicionar-produto-ao-carrinho/), `POST /contacts/{contact_id}/cart/{product_id}` | `quantity` | | [Marcar pedido como pago](https://docs.nextags.com.br/referencia/ecommerce/marcar-pedido-como-pago/), `POST /contacts/{contact_id}/pay/{order_id}` | `amount_received` | | As [ferramentas](https://docs.nextags.com.br/referencia/ferramentas/), `POST /tools/...`, menos `/tools/echo` | os campos de cada ferramenta | Quatro chamadas não levam corpo: [Enviar fluxo](https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo/), [Reenviar disparo](https://docs.nextags.com.br/referencia/disparos/reenviar-disparo/), [Cancelar disparo](https://docs.nextags.com.br/referencia/disparos/cancelar-disparo/) e [Gerar link de uso único do modelo](https://docs.nextags.com.br/referencia/fluxos/gerar-link-de-uso-unico-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_id` aceita o ID de um campo e também `phone` e `email`. Onde achar cada um: [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/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](https://docs.nextags.com.br/referencia/ecommerce/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](https://docs.nextags.com.br/guias/buscar-contato-por-campo/)) ou exporte na tela ([Exportar contatos](https://help.nextags.com.br/tutoriais/contatos/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](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/). Veja [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/). | | Apagar um contato | Na tela, nas [ações em massa de Contatos](https://help.nextags.com.br/tutoriais/contatos/acoes-em-massa/), ou num fluxo, com a ação **Excluir Contato** ([Todas as ações do fluxo](https://help.nextags.com.br/tutoriais/fluxos/acoes-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](https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo/) ou os [webhooks de saída](https://help.nextags.com.br/tutoriais/ferramentas/webhooks-de-saida/). | | Criar um Broadcast | Na tela: [Criar um Broadcast](https://help.nextags.com.br/tutoriais/disparos/criar-disparo/). A API lista, consulta, reenvia e cancela ([guia](https://docs.nextags.com.br/guias/disparos-pela-api/)). | | Enviar um Modelo de Mensagem do WhatsApp | Monte um fluxo que comece com o modelo ([Modelo de mensagem do WhatsApp no fluxo](https://help.nextags.com.br/tutoriais/fluxos/modelos-no-fluxo/)) e envie o fluxo ([guia](https://docs.nextags.com.br/guias/enviar-fluxo/)). | | 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](https://help.nextags.com.br/tutoriais/fluxos/iniciar-sequencia/)). 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](https://docs.nextags.com.br/referencia/#arquivos-para-baixar), em dois formatos: o [OpenAPI em JSON](https://docs.nextags.com.br/openapi.json), para gerar clientes e dar contexto a uma IA, e a [coleção do Postman](https://docs.nextags.com.br/nextags.postman_collection.json), 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](https://docs.nextags.com.br/webhooks/visao-geral/). - Você quer ligar ferramentas sem programar: use a API pelo [Make, n8n e Zapier](https://docs.nextags.com.br/guias/make-n8n-zapier/). - Uma IA vai escrever a integração: entregue a ela [a documentação pronta para IA](https://docs.nextags.com.br/ia/documentacao-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](https://docs.nextags.com.br/comecar/autenticacao/). > **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](https://docs.nextags.com.br/guias/criar-ou-atualizar-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.