{ "openapi": "3.1.0", "info": { "title": "API da NexTags", "version": "1.1", "summary": "Contatos, mensagens, etiquetas, campos, fluxos, pipelines, agentes de IA, e-commerce, disparos e ferramentas.", "description": "A API REST da NexTags: crie e encontre contatos, envie mensagens e fluxos, organize etiquetas, campos e oportunidades, e consulte agentes de IA, pedidos e disparos. Toda chamada leva a chave de API da conta no cabeçalho `X-ACCESS-TOKEN`. Comece por [Sua primeira requisição](https://docs.nextags.com.br/comecar/primeira-requisicao/).", "contact": { "name": "Suporte NexTags", "email": "suporte@nextags.com.br", "url": "https://help.nextags.com.br/comecar/falar-com-o-suporte/" } }, "externalDocs": { "description": "Documentação para desenvolvedores", "url": "https://docs.nextags.com.br/" }, "servers": [ { "url": "https://app.nextagsai.com.br/api", "description": "Produção" } ], "security": [ { "ChaveDeApi": [] } ], "tags": [ { "name": "Conta", "description": "Dados da conta, administradores, equipes e integrações ligadas.\n\nOs dados da conta dona da chave de API: o nome, quantos contatos ela tem, os administradores, as equipes e as integrações ligadas. Use estas chamadas para conferir a chave e para achar os IDs de administradores e equipes que outras chamadas pedem.", "externalDocs": { "url": "https://docs.nextags.com.br/referencia/conta/" } }, { "name": "Contatos", "description": "Crie, encontre e consulte contatos.\n\nOs contatos são as pessoas que falam com a conta, em qualquer canal. Crie um contato a partir do seu sistema, encontre um contato pelo telefone, pelo e-mail ou por um campo personalizado e consulte os dados, as etiquetas e os campos de cada um. O `id` do contato é o `contact_id` que as outras chamadas pedem: veja [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/).", "externalDocs": { "url": "https://docs.nextags.com.br/referencia/contatos/" } }, { "name": "Mensagens", "description": "Envie fluxos, textos, arquivos e conteúdos para um contato.\n\nEnvie conteúdo a um contato a partir do seu sistema: um fluxo pronto, um texto, um arquivo ou várias mensagens com ações numa chamada só. As regras de cada canal valem para a API como para a Caixa de Entrada: no WhatsApp, fora da janela de 24 horas, só sai Modelo de Mensagem aprovado. O formato das mensagens e das ações está em [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/).", "externalDocs": { "url": "https://docs.nextags.com.br/referencia/mensagens/" } }, { "name": "Etiquetas", "description": "Etiquetas da conta e dos contatos.\n\nAs etiquetas marcam contatos para separar, filtrar e disparar automações, como `cliente-vip` ou `lead-quente`. Crie e consulte as etiquetas da conta e ponha ou tire cada uma de um contato. Na conta, elas ficam em **Fluxos** › **Etiquetas**, e o ID de cada uma sai do menu **⋮** › **Obter ID**: veja [Criar e usar etiquetas](https://help.nextags.com.br/tutoriais/fluxos/etiquetas/).", "externalDocs": { "url": "https://docs.nextags.com.br/referencia/etiquetas/" } }, { "name": "Campos personalizados", "description": "Campos da conta e os valores de cada contato.\n\nOs campos personalizados guardam uma informação de cada contato, como a cidade ou o plano de interesse. Crie e consulte os campos da conta e leia, preencha ou limpe o valor de um contato. Na conta, eles ficam em **Fluxos** › **Campo Personalizados**, e o ID de cada um sai do menu **⋮** › **Obter ID**: veja [Criar campos personalizados](https://help.nextags.com.br/tutoriais/fluxos/campos-personalizados/) e [Campos personalizados, campos do bot e variáveis](https://docs.nextags.com.br/comecar/campos-e-variaveis/).", "externalDocs": { "url": "https://docs.nextags.com.br/referencia/campos-personalizados/" } }, { "name": "Campos do bot", "description": "Valores globais da conta, iguais para todos os contatos.\n\nO campo do bot guarda um valor só para a conta toda, igual para todos os contatos, como o horário de atendimento ou a chave PIX. Leia, troque ou apague esse valor pelo ID do campo. O campo se cria em **Fluxos** › **Campo Personalizados**, na seção **Campo Personalizados do Bot** (ou pela API, em [Criar campo personalizado](https://docs.nextags.com.br/referencia/campos-personalizados/criar-campo-personalizado/) com `isBotField: true`), e o ID sai do menu **⋮** › **Obter ID**. Veja [Campos do bot](https://help.nextags.com.br/tutoriais/fluxos/campos-do-bot/).", "externalDocs": { "url": "https://docs.nextags.com.br/referencia/campos-do-bot/" } }, { "name": "Fluxos e modelos", "description": "Liste os fluxos e instale modelos prontos.\n\nListe os fluxos da conta para pegar o ID que [Enviar fluxo](https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo/) e a ação `send_flow` pedem, e instale modelos prontos: os pacotes de **Templates**, montados em **Ferramentas** › **Templates**, com fluxos, pipelines, agentes de IA e outros itens de uma conta. Os Templates não têm relação com o Modelo de Mensagem do WhatsApp. Veja [Templates: copiar conteúdo entre contas](https://help.nextags.com.br/tutoriais/ferramentas/templates/).", "externalDocs": { "url": "https://docs.nextags.com.br/referencia/fluxos/" } }, { "name": "Pipelines e oportunidades", "description": "Pipelines, etapas, oportunidades e comentários do CRM.\n\nO CRM em quadro da NexTags: cada pipeline tem etapas (as colunas) e oportunidades (os cartões), com o contato, o valor, o estado, a prioridade e os responsáveis. Use estas chamadas para levar ao pipeline as vendas e os atendimentos do seu sistema, mudar os cartões de etapa, fechar como ganho ou perdido e registrar comentários. O passo a passo está no guia [Criar e mover oportunidades no pipeline](https://docs.nextags.com.br/guias/oportunidades-no-pipeline/); a tela, em [O que é um pipeline](https://help.nextags.com.br/tutoriais/pipelines/o-que-e-um-pipeline/).", "externalDocs": { "url": "https://docs.nextags.com.br/referencia/pipelines/" } }, { "name": "Agentes de IA", "description": "Agentes, funções, servidores MCP, arquivos e histórico da IA.\n\nOs agentes de IA do **AI Hub**: as instruções e os modelos com que a IA responde os contatos, usando o provedor conectado na conta (OpenAI, Gemini, Claude, xAI ou DeepSeek). Pela API, você lista e consulta os agentes, troca a mensagem do sistema, o limite de tokens e os modelos, lista as funções, os servidores MCP e os arquivos, e põe mensagens no histórico da IA de um contato. Veja o guia [Agentes de IA pela API](https://docs.nextags.com.br/guias/agentes-de-ia-pela-api/) e [Criar um agente de IA](https://help.nextags.com.br/tutoriais/ia/criar-agente/).", "externalDocs": { "url": "https://docs.nextags.com.br/referencia/agentes-de-ia/" } }, { "name": "E-commerce", "description": "Produtos, carrinho e pedidos de cada contato.\n\nA loja dentro da conversa: os produtos do E-commerce (**Ferramentas** › **Ecommerce**), o carrinho de cada contato e os pedidos. Cuidado com os centavos: os valores do carrinho e do pedido (`total`, `subtotal`, `coupon_discount`) e o `amount_received` vão em centavos (`8082` = R$ 80,82), mas o `price` do produto e o de cada item do carrinho não (`49.9` = R$ 49,90). Veja o guia [Carrinho, pedidos e produtos](https://docs.nextags.com.br/guias/carrinho-e-pedidos/) e [Carrinho e pedidos na conversa](https://help.nextags.com.br/tutoriais/ecommerce/carrinho-e-pedidos/).", "externalDocs": { "url": "https://docs.nextags.com.br/referencia/ecommerce/" } }, { "name": "Disparos", "description": "Consulte, reenvie e cancele disparos (broadcasts).\n\nOs Broadcasts da conta (menu **Broadcasts**): os envios em massa, cada um com o seu estado. Pela API, você acompanha, reenvia e cancela Broadcasts; criar um Broadcast é só na tela, em **Broadcasts** › **Enviar** ([Criar um Broadcast](https://help.nextags.com.br/tutoriais/disparos/criar-disparo/)). Veja o guia [Acompanhar, reenviar e cancelar disparos](https://docs.nextags.com.br/guias/disparos-pela-api/).", "externalDocs": { "url": "https://docs.nextags.com.br/referencia/disparos/" } }, { "name": "Agenda", "description": "Calendários usados nos agendamentos.\n\nOs calendários do **Gestor de Agendamentos** (**Ferramentas** › **Gestor de Agendamentos**): o que o contato reserva pelo link do calendário, pelo fluxo ou pela IA. A API só lê os calendários; criar e editar um calendário e ver os agendamentos é na tela. Veja [Criar um calendário](https://help.nextags.com.br/tutoriais/agenda/criar-calendario/).", "externalDocs": { "url": "https://docs.nextags.com.br/referencia/agenda/" } }, { "name": "Ferramentas", "description": "Utilitários para usar nas requisições externas dos fluxos: texto, números, URLs, QR Code, hash e distância.\n\nUtilitários para transformar um valor no meio de um fluxo: formatar números, trocar, recortar e contar textos, codificar URLs, gerar QR Code e hash e medir a distância entre dois pontos. Chame pela [requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/) do fluxo: **Request Type** POST, o endereço da ferramenta em **Request URL** (como `https://app.nextagsai.com.br/api/tools/text_to_upper`), o cabeçalho `X-ACCESS-TOKEN` com a chave de API (guarde a chave num [campo do bot](https://help.nextags.com.br/tutoriais/fluxos/campos-do-bot/)), o **Corpo** em **Form-encoded** e, no **Mapeamento de resposta**, o JSONPath do resultado (`$.data`, na maioria) ligado ao campo que vai guardar o valor. Todas pedem a chave e recebem o corpo em formulário (`application/x-www-form-urlencoded`), menos o eco, que recebe JSON.", "externalDocs": { "url": "https://docs.nextags.com.br/referencia/ferramentas/" } } ], "paths": { "/accounts/me": { "get": { "operationId": "getAccountInformation", "summary": "Consultar a conta", "description": "Devolve os dados da conta dona da chave de API: o ID, o nome, se o acesso ao painel está liberado, quando a conta foi criada e quantos contatos ela tem. É a chamada mais simples da API: use para conferir se a chave funciona. Veja [Sua primeira requisição](https://docs.nextags.com.br/comecar/primeira-requisicao/).", "tags": [ "Conta" ], "responses": { "200": { "description": "Os dados da conta.", "content": { "application/json": { "schema": { "type": "object", "properties": { "page_id": { "type": "integer", "format": "int64", "description": "O ID da conta." }, "name": { "type": "string", "description": "O nome da conta." }, "active": { "type": "boolean", "description": "Se os administradores conseguem entrar no painel da conta." }, "created": { "type": "integer", "format": "int64", "description": "Quando a conta foi criada, em Unix timestamp." }, "total_users": { "type": "integer", "format": "int64", "description": "Quantos contatos a conta tem." } } }, "example": { "page_id": 123456, "name": "Loja Exemplo", "active": true, "created": 1735700000, "total_users": 5230 } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/accounts/me\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/me', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/accounts/me\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/conta/consultar-a-conta/" } } }, "/accounts/admins": { "get": { "operationId": "getAccountAdmins", "summary": "Listar administradores", "description": "Lista os administradores da conta, as pessoas da equipe que entram no painel, com o ID de cada um. Outras chamadas pedem esse ID: por exemplo, os responsáveis de uma oportunidade (`assigned_admins`) e a ação `assign_conversation`, que atribui a conversa a alguém. Veja [Administradores e permissões](https://help.nextags.com.br/tutoriais/configuracoes/administradores-e-permissoes/).", "tags": [ "Conta" ], "responses": { "200": { "description": "A lista de administradores.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Admin" } }, "example": [ { "id": 10001, "email": "ana@exemplo.com.br", "first_name": "Ana", "last_name": "Souza", "full_name": "Ana Souza", "profile_pic": "https://exemplo.com.br/fotos/ana.jpg", "available": true } ] } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/accounts/admins\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/admins', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/accounts/admins\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/conta/listar-administradores/" } } }, "/accounts/teams": { "get": { "operationId": "getAccountTeams", "summary": "Listar equipes", "description": "Lista as equipes de atendimento da conta (as equipes da Caixa de Entrada), com o ID e o nome de cada uma. Veja [Equipes de caixa de entrada](https://help.nextags.com.br/tutoriais/caixa-de-entrada/equipes-de-atendimento/).", "tags": [ "Conta" ], "responses": { "200": { "description": "A lista de equipes.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } }, "example": [ { "id": 501, "name": "Vendas" }, { "id": 502, "name": "Suporte" } ] } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/accounts/teams\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/teams', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/accounts/teams\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/conta/listar-equipes/" } } }, "/accounts/tags": { "get": { "operationId": "getAccountTags", "summary": "Listar etiquetas", "description": "Lista as etiquetas da conta, com o ID e o nome de cada uma. Use o ID para pôr ou tirar a etiqueta de um contato.", "tags": [ "Etiquetas" ], "responses": { "200": { "description": "As etiquetas da conta.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "example": [ { "id": 2001, "name": "cliente-vip" }, { "id": 2002, "name": "lead-quente" } ] } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/accounts/tags\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/tags', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/accounts/tags\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/etiquetas/listar-etiquetas/" } }, "post": { "operationId": "createTag", "summary": "Criar etiqueta", "description": "Cria uma etiqueta na conta e devolve o ID dela. O nome vai em formulário (`application/x-www-form-urlencoded`), não em JSON.", "tags": [ "Etiquetas" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "O nome da etiqueta.", "examples": [ "cliente-vip" ] } }, "required": [ "name" ] }, "example": { "name": "cliente-vip" } } } }, "responses": { "200": { "description": "A etiqueta criada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID da etiqueta nova." } } }, "example": { "id": 2001 } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/accounts/tags\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'name=cliente-vip'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/tags', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n name: 'cliente-vip',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/accounts/tags\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"name\": \"cliente-vip\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'name' => 'cliente-vip',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/etiquetas/criar-etiqueta/" } } }, "/accounts/tags/{tag_id}": { "get": { "operationId": "getTagById", "summary": "Consultar etiqueta", "description": "Devolve o nome de uma etiqueta a partir do ID.", "tags": [ "Etiquetas" ], "parameters": [ { "name": "tag_id", "in": "path", "required": true, "description": "O ID da etiqueta.", "schema": { "type": "integer" }, "example": 2001 } ], "responses": { "200": { "description": "A etiqueta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" }, "example": { "id": 2001, "name": "cliente-vip" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/accounts/tags/2001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/tags/2001', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/accounts/tags/2001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/etiquetas/consultar-etiqueta/" } }, "delete": { "operationId": "deleteTag", "summary": "Apagar etiqueta", "description": "Apaga a etiqueta da conta, sem volta. Antes, confira os fluxos e os acionadores que usam a etiqueta. Para só tirar a etiqueta de um contato, use [Remover etiqueta do contato](https://docs.nextags.com.br/referencia/etiquetas/remover-etiqueta-do-contato/).", "tags": [ "Etiquetas" ], "parameters": [ { "name": "tag_id", "in": "path", "required": true, "description": "O ID da etiqueta.", "schema": { "type": "integer" }, "example": 2001 } ], "responses": { "200": { "description": "A etiqueta foi apagada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando a etiqueta foi apagada." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X DELETE \"https://app.nextagsai.com.br/api/accounts/tags/2001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/tags/2001', {\n method: 'DELETE',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.delete(\n \"https://app.nextagsai.com.br/api/accounts/tags/2001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'DELETE',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/etiquetas/apagar-etiqueta/" } } }, "/accounts/tags/name/{tag_name}": { "get": { "operationId": "getTagByName", "summary": "Buscar etiqueta pelo nome", "description": "Encontra uma etiqueta pelo nome e devolve o ID dela. O nome vai no caminho, codificado para URL: `lead quente` vira `lead%20quente`.", "tags": [ "Etiquetas" ], "parameters": [ { "name": "tag_name", "in": "path", "required": true, "description": "O nome da etiqueta, codificado para URL.", "schema": { "type": "string" }, "example": "cliente-vip" } ], "responses": { "200": { "description": "A etiqueta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" }, "example": { "id": 2001, "name": "cliente-vip" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/accounts/tags/name/cliente-vip\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/tags/name/cliente-vip', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/accounts/tags/name/cliente-vip\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/etiquetas/buscar-etiqueta-pelo-nome/" } } }, "/accounts/flows": { "get": { "operationId": "getAccountFlows", "summary": "Listar fluxos", "description": "Lista os fluxos da conta, com o ID e o nome de cada um. Use o ID em [Enviar fluxo](https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo/) e na ação `send_flow`.", "tags": [ "Fluxos e modelos" ], "responses": { "200": { "description": "Os fluxos da conta.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID do fluxo." }, "name": { "type": "string", "description": "O nome do fluxo." } } } }, "example": [ { "id": 1000001, "name": "Boas-vindas" }, { "id": 1000002, "name": "Recuperar carrinho" } ] } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/accounts/flows\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/flows', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/accounts/flows\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/fluxos/listar-fluxos/" } } }, "/accounts/custom_fields": { "get": { "operationId": "getAccountCustomFields", "summary": "Listar campos personalizados", "description": "Lista os campos personalizados da conta. Cada campo traz o ID (`id`), o nome (`name`), o tipo (`type`: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla) e a descrição (`description`). Use o ID para ler ou preencher o valor de um contato.", "tags": [ "Campos personalizados" ], "responses": { "200": { "description": "Os campos da conta.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID do campo." }, "name": { "type": "string", "description": "O nome do campo." }, "type": { "type": "integer", "description": "O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla." }, "description": { "type": "string", "description": "A descrição do campo." } } } }, "example": [ { "id": 3001, "name": "cidade", "type": 0, "description": "Cidade de entrega" }, { "id": 3002, "name": "data_nascimento", "type": 2, "description": "" } ] } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/accounts/custom_fields\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/custom_fields', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/accounts/custom_fields\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/campos-personalizados/listar-campos-personalizados/" } }, "post": { "operationId": "createCustomField", "summary": "Criar campo personalizado", "description": "Cria um campo personalizado na conta e devolve o ID dele. Pela API, o tipo vai de 0 a 4 (texto, número, data, data e hora e sim/não); texto longo e seleções se criam no app. Com `isBotField: true`, o campo nasce como [campo do bot](https://help.nextags.com.br/tutoriais/fluxos/campos-do-bot/), com um valor só para a conta toda, que vai em `value`. Use um nome novo: no app, um nome repetido ou reservado é recusado.", "tags": [ "Campos personalizados" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "O nome do campo, como ele aparece nas listas e nas variáveis das mensagens (`{{cidade}}`).", "examples": [ "cidade" ] }, "type": { "type": "integer", "description": "O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não. Depois de criado, o campo não muda de tipo.", "enum": [ 0, 1, 2, 3, 4 ] }, "isBotField": { "type": "boolean", "default": false, "description": "`true` cria um campo do bot (um valor para a conta toda) no lugar de um campo do contato." }, "value": { "type": "string", "description": "O valor do campo do bot, no formato do tipo. Num campo do contato, é ignorado." }, "description": { "type": "string", "description": "Uma descrição, que aparece embaixo do nome na lista de campos.", "examples": [ "Cidade de entrega" ] } }, "required": [ "name", "type" ] }, "example": { "name": "cidade", "type": 0, "description": "Cidade de entrega" } } } }, "responses": { "200": { "description": "O campo criado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID do campo novo." }, "name": { "type": "string", "description": "O nome do campo." } } }, "example": { "id": 3001, "name": "cidade" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/accounts/custom_fields\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"cidade\",\n \"type\": 0,\n \"description\": \"Cidade de entrega\"\n }'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/custom_fields', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n name: 'cidade',\n type: 0,\n description: 'Cidade de entrega',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/accounts/custom_fields\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n json={\n \"name\": \"cidade\",\n \"type\": 0,\n \"description\": \"Cidade de entrega\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'name' => 'cidade',\n 'type' => 0,\n 'description' => 'Cidade de entrega',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/campos-personalizados/criar-campo-personalizado/" } } }, "/accounts/custom_fields/{custom_field_id}": { "get": { "operationId": "getCustomFieldById", "summary": "Consultar campo personalizado", "description": "Devolve o nome, o tipo e a descrição de um campo personalizado a partir do ID.", "tags": [ "Campos personalizados" ], "parameters": [ { "name": "custom_field_id", "in": "path", "required": true, "description": "O ID do campo personalizado.", "schema": { "type": "integer" }, "example": 3001 } ], "responses": { "200": { "description": "O campo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID do campo." }, "name": { "type": "string", "description": "O nome do campo." }, "type": { "type": "integer", "description": "O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla." }, "description": { "type": "string", "description": "A descrição do campo." } } }, "example": { "id": 3001, "name": "cidade", "type": 0, "description": "Cidade de entrega" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/accounts/custom_fields/3001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/custom_fields/3001', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/accounts/custom_fields/3001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/campos-personalizados/consultar-campo-personalizado/" } } }, "/accounts/custom_fields/name/{custom_field_name}": { "get": { "operationId": "getCustomFieldByName", "summary": "Buscar campo pelo nome", "description": "Encontra um campo personalizado pelo nome e devolve o ID, o tipo e a descrição. O nome vai no caminho, codificado para URL: `data de nascimento` vira `data%20de%20nascimento`.", "tags": [ "Campos personalizados" ], "parameters": [ { "name": "custom_field_name", "in": "path", "required": true, "description": "O nome do campo, codificado para URL.", "schema": { "type": "string" }, "example": "cidade" } ], "responses": { "200": { "description": "O campo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID do campo." }, "name": { "type": "string", "description": "O nome do campo." }, "type": { "type": "integer", "description": "O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla." }, "description": { "type": "string", "description": "A descrição do campo." } } }, "example": { "id": 3001, "name": "cidade", "type": 0, "description": "Cidade de entrega" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/accounts/custom_fields/name/cidade\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/custom_fields/name/cidade', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/accounts/custom_fields/name/cidade\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/campos-personalizados/buscar-campo-pelo-nome/" } } }, "/accounts/bot_fields/{bot_field_id}": { "get": { "operationId": "getBFieldValue", "summary": "Consultar campo do bot", "description": "Devolve o nome, o tipo e o valor de um campo do bot.", "tags": [ "Campos do bot" ], "parameters": [ { "name": "bot_field_id", "in": "path", "required": true, "description": "O ID do campo do bot.", "schema": { "type": "integer" }, "example": 3101 } ], "responses": { "200": { "description": "O campo do bot, com o valor.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "O ID do campo do bot." }, "type": { "type": "integer", "description": "O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo." }, "name": { "type": "string", "description": "O nome do campo." }, "value": { "type": [ "string", "number" ], "description": "O valor, no formato do tipo: texto nos campos de texto e de texto longo; número nos de número, de data e de data e hora (Unix timestamp, em segundos) e de sim/não (1 ou 0)." } } }, "example": { "id": 3101, "name": "Horário de atendimento", "type": 0, "value": "Seg a sex, das 9h às 18h" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/accounts/bot_fields/3101\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/bot_fields/3101', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/accounts/bot_fields/3101\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/campos-do-bot/consultar-campo-do-bot/" } }, "post": { "operationId": "setBField", "summary": "Preencher campo do bot", "description": "Troca o valor de um campo do bot: todos os fluxos que usam o campo passam a mostrar o valor novo. Use quando o valor vem de outro sistema, como o preço do dia ou o cupom da semana. O valor vai em formulário, no formato do tipo do campo: data e data e hora em Unix timestamp (segundos) e sim/não como `1` ou `0`.", "tags": [ "Campos do bot" ], "parameters": [ { "name": "bot_field_id", "in": "path", "required": true, "description": "O ID do campo do bot.", "schema": { "type": "integer" }, "example": 3101 } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "O valor novo, no formato do tipo do campo.", "examples": [ "Seg a sex, das 9h às 18h" ] } }, "required": [ "value" ] }, "example": { "value": "Seg a sex, das 9h às 18h" } } } }, "responses": { "200": { "description": "O valor foi gravado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando o valor foi gravado." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/accounts/bot_fields/3101\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'value=Seg a sex, das 9h às 18h'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/bot_fields/3101', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n value: 'Seg a sex, das 9h às 18h',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/accounts/bot_fields/3101\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"value\": \"Seg a sex, das 9h às 18h\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'value' => 'Seg a sex, das 9h às 18h',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/campos-do-bot/preencher-campo-do-bot/" } }, "delete": { "operationId": "removeBField", "summary": "Limpar campo do bot", "description": "Apaga o valor de um campo do bot. O campo continua na conta, sem valor.", "tags": [ "Campos do bot" ], "parameters": [ { "name": "bot_field_id", "in": "path", "required": true, "description": "O ID do campo do bot.", "schema": { "type": "integer" }, "example": 3101 } ], "responses": { "200": { "description": "O valor foi apagado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando o valor foi apagado." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X DELETE \"https://app.nextagsai.com.br/api/accounts/bot_fields/3101\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/bot_fields/3101', {\n method: 'DELETE',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.delete(\n \"https://app.nextagsai.com.br/api/accounts/bot_fields/3101\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'DELETE',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/campos-do-bot/limpar-campo-do-bot/" } } }, "/accounts/integrations": { "get": { "operationId": "getAccountIntegrations", "summary": "Listar integrações da conta", "description": "Mostra quais integrações estão ligadas na conta: os provedores de IA (OpenAI, Gemini, Claude, xAI e DeepSeek), o Google Sheets e o e-mail. Cada uma vem com `active`: `true` quando está conectada. Veja [A aba Integrações](https://help.nextags.com.br/tutoriais/configuracoes/integracoes/).", "tags": [ "Conta" ], "responses": { "200": { "description": "Cada integração com o seu estado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "openai": { "type": "object", "properties": { "active": { "type": "boolean" } }, "description": "A OpenAI (ChatGPT)." }, "gemini": { "type": "object", "properties": { "active": { "type": "boolean" } }, "description": "O Google Gemini." }, "claude": { "type": "object", "properties": { "active": { "type": "boolean" } }, "description": "O Claude." }, "xai": { "type": "object", "properties": { "active": { "type": "boolean" } }, "description": "O xAI." }, "deepseek": { "type": "object", "properties": { "active": { "type": "boolean" } }, "description": "O DeepSeek." }, "google_sheets": { "type": "object", "properties": { "active": { "type": "boolean" } }, "description": "O Google Sheets." }, "email": { "type": "object", "properties": { "active": { "type": "boolean" } }, "description": "O envio de e-mail." } } }, "example": { "openai": { "active": true }, "gemini": { "active": false }, "claude": { "active": false }, "xai": { "active": false }, "deepseek": { "active": false }, "google_sheets": { "active": true }, "email": { "active": false } } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/accounts/integrations\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/integrations', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/accounts/integrations\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/conta/listar-integracoes-da-conta/" } } }, "/contacts/{contact_id}": { "get": { "operationId": "getContactById", "summary": "Consultar contato", "description": "Devolve um contato, com os dados do perfil, as etiquetas e os campos personalizados. Vêm o nome, o canal atual, o gênero, o idioma, o fuso, as datas da última mensagem e da última interação e a inscrição. Para achar o ID a partir do telefone ou do e-mail, use [Buscar contato por campo personalizado](https://docs.nextags.com.br/referencia/contatos/buscar-contato-por-campo-personalizado/).", "tags": [ "Contatos" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato.", "schema": { "type": "integer" }, "example": 123456789 } ], "responses": { "200": { "description": "O contato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" }, "example": { "id": 123456789, "page_id": 123456, "first_name": "Ana", "last_name": "Souza", "channel": 5, "profile_pic": "https://exemplo.com.br/fotos/ana.jpg", "locale": "pt_BR", "gender": 0, "timezone": -3, "last_sent": 1792936930000, "last_delivered": 1792936932000, "last_seen": 1792937020000, "last_interaction": 1792936680000, "subscribed_date": "2026-10-12 14:40:00", "subscribed": 1, "tags": [ { "id": 2001, "name": "cliente-vip" } ], "custom_fields": [ { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" } ] } } } }, "400": { "description": "O `contact_id` não é um ID válido." }, "401": { "$ref": "#/components/responses/ChaveInvalida" }, "404": { "description": "Não existe contato com esse ID nesta conta." } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/contacts/123456789\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/contacts/123456789\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/contatos/consultar-contato/" } } }, "/contacts/find_by_custom_field": { "get": { "operationId": "findByCustomField", "summary": "Buscar contato por campo personalizado", "description": "Encontra contatos pelo valor de um campo: o telefone, o e-mail ou um campo personalizado. Devolve no máximo 100 contatos, os mais recentes primeiro, pela última mudança do campo. É o jeito de achar o `contact_id` de quem você conhece pelo telefone ou pelo e-mail: veja [Encontrar um contato pelo e-mail ou telefone](https://docs.nextags.com.br/guias/buscar-contato-por-campo/).", "tags": [ "Contatos" ], "parameters": [ { "name": "field_id", "in": "query", "required": true, "description": "Onde procurar: `phone` (telefone), `email` (e-mail) ou o ID de um campo personalizado.", "schema": { "type": "string" }, "example": "phone" }, { "name": "value", "in": "query", "required": true, "description": "O valor procurado. O telefone vai completo e só com números, como `5511988776655`.", "schema": { "type": "string" }, "example": "5511988776655" } ], "responses": { "200": { "description": "Os contatos encontrados, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" }, "maxItems": 100, "description": "Os contatos, no máximo 100, os mais recentes primeiro." } } }, "example": { "data": [ { "id": 123456789, "page_id": 123456, "first_name": "Ana", "last_name": "Souza", "channel": 5, "profile_pic": "https://exemplo.com.br/fotos/ana.jpg", "locale": "pt_BR", "gender": 0, "timezone": -3, "last_sent": 1792936930000, "last_delivered": 1792936932000, "last_seen": 1792937020000, "last_interaction": 1792936680000, "subscribed_date": "2026-10-12 14:40:00", "subscribed": 1, "tags": [ { "id": 2001, "name": "cliente-vip" } ], "custom_fields": [ { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" } ] } ] } } } }, "400": { "description": "Faltou `field_id` ou `value`, ou um deles não vale." }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/contacts/find_by_custom_field?field_id=phone&value=5511988776655\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch(`https://app.nextagsai.com.br/api/contacts/find_by_custom_field?${new URLSearchParams({\n field_id: 'phone',\n value: '5511988776655',\n})}`, {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/contacts/find_by_custom_field\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n params={\n \"field_id\": \"phone\",\n \"value\": \"5511988776655\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " 'phone',\n 'value' => '5511988776655',\n]));\ncurl_setopt_array($ch, [\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/contatos/buscar-contato-por-campo-personalizado/" } } }, "/contacts/{contact_id}/tags": { "get": { "operationId": "getUserTags", "summary": "Listar etiquetas do contato", "description": "Lista as etiquetas que o contato tem. O contato inteiro, com os campos personalizados, sai de [Consultar contato](https://docs.nextags.com.br/referencia/contatos/consultar-contato/).", "tags": [ "Etiquetas" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato.", "schema": { "type": "integer" }, "example": 123456789 } ], "responses": { "200": { "description": "As etiquetas do contato.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "example": [ { "id": 2001, "name": "cliente-vip" } ] } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/contacts/123456789/tags\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/tags', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/contacts/123456789/tags\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/etiquetas/listar-etiquetas-do-contato/" } } }, "/contacts/{contact_id}/tags/{tag_id}": { "post": { "operationId": "addTagToUser", "summary": "Adicionar etiqueta ao contato", "description": "Põe a etiqueta no contato, como a ação **Adicionar Etiqueta** de um fluxo. Para usar o nome da etiqueta no lugar do ID, mande a ação `add_tag` em [Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/). Veja [Etiquetar contatos e preencher campos](https://docs.nextags.com.br/guias/etiquetas-e-campos/).", "tags": [ "Etiquetas" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato.", "schema": { "type": "integer" }, "example": 123456789 }, { "name": "tag_id", "in": "path", "required": true, "description": "O ID da etiqueta.", "schema": { "type": "integer" }, "example": 2001 } ], "responses": { "200": { "description": "A etiqueta foi aplicada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando a etiqueta foi aplicada." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/contacts/123456789/tags/2001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/tags/2001', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/contacts/123456789/tags/2001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/etiquetas/adicionar-etiqueta-ao-contato/" } }, "delete": { "operationId": "removeTagFromUser", "summary": "Remover etiqueta do contato", "description": "Tira a etiqueta do contato, como a ação **Remover Etiqueta** de um fluxo. A etiqueta continua na conta.", "tags": [ "Etiquetas" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato.", "schema": { "type": "integer" }, "example": 123456789 }, { "name": "tag_id", "in": "path", "required": true, "description": "O ID da etiqueta.", "schema": { "type": "integer" }, "example": 2001 } ], "responses": { "200": { "description": "A etiqueta foi tirada do contato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando a etiqueta foi tirada." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X DELETE \"https://app.nextagsai.com.br/api/contacts/123456789/tags/2001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/tags/2001', {\n method: 'DELETE',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.delete(\n \"https://app.nextagsai.com.br/api/contacts/123456789/tags/2001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'DELETE',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/etiquetas/remover-etiqueta-do-contato/" } } }, "/contacts": { "post": { "operationId": "createNewContact", "summary": "Criar contato", "description": "Cria um contato e, na mesma chamada, roda ações nele: etiquetar, preencher campos e enviar um fluxo. O telefone vai completo, com o código do país e o DDD, só com números, como `5511988776655`: veja [O formato certo do telefone](https://help.nextags.com.br/tutoriais/contatos/formato-do-telefone/). Para não criar o mesmo contato duas vezes, procure antes pelo telefone ou pelo e-mail em [Buscar contato por campo personalizado](https://docs.nextags.com.br/referencia/contatos/buscar-contato-por-campo-personalizado/). Veja [Criar ou atualizar um contato](https://docs.nextags.com.br/guias/criar-ou-atualizar-contato/).\n\nSe o contato nunca mandou mensagem para a conta, a janela de 24 horas do WhatsApp está fechada: o fluxo da ação `send_flow` precisa começar com um Modelo de Mensagem aprovado. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/).", "tags": [ "Contatos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "O telefone com o código do país (DDI) e o DDD, só com números.", "examples": [ "5511988776655" ] }, "email": { "type": "string", "description": "O e-mail do contato.", "examples": [ "ana@exemplo.com.br" ] }, "first_name": { "type": "string", "description": "O nome.", "examples": [ "Ana" ] }, "last_name": { "type": "string", "description": "O sobrenome.", "examples": [ "Souza" ] }, "gender": { "type": "string", "enum": [ "male", "female", "unknown" ], "description": "O gênero: `male` (masculino), `female` (feminino) ou `unknown` (desconhecido)." }, "actions": { "type": "array", "description": "Ações para rodar no contato, na ordem da lista: `add_tag`, `set_field_value`, `send_flow` e as outras de [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/).", "items": { "$ref": "#/components/schemas/Acao" } } }, "required": [ "phone" ] }, "example": { "phone": "5511988776655", "email": "ana@exemplo.com.br", "first_name": "Ana", "last_name": "Souza", "gender": "female", "actions": [ { "action": "add_tag", "tag_name": "cliente-vip" }, { "action": "set_field_value", "field_name": "cidade", "value": "São Paulo" }, { "action": "send_flow", "flow_id": 1000001 } ] } } } }, "responses": { "200": { "description": "Deu certo: o contato foi criado." }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/contacts\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"phone\": \"5511988776655\",\n \"email\": \"ana@exemplo.com.br\",\n \"first_name\": \"Ana\",\n \"last_name\": \"Souza\",\n \"gender\": \"female\",\n \"actions\": [\n {\n \"action\": \"add_tag\",\n \"tag_name\": \"cliente-vip\"\n },\n {\n \"action\": \"set_field_value\",\n \"field_name\": \"cidade\",\n \"value\": \"São Paulo\"\n },\n {\n \"action\": \"send_flow\",\n \"flow_id\": 1000001\n }\n ]\n }'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n phone: '5511988776655',\n email: 'ana@exemplo.com.br',\n first_name: 'Ana',\n last_name: 'Souza',\n gender: 'female',\n actions: [\n {\n action: 'add_tag',\n tag_name: 'cliente-vip',\n },\n {\n action: 'set_field_value',\n field_name: 'cidade',\n value: 'São Paulo',\n },\n {\n action: 'send_flow',\n flow_id: 1000001,\n },\n ],\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/contacts\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n json={\n \"phone\": \"5511988776655\",\n \"email\": \"ana@exemplo.com.br\",\n \"first_name\": \"Ana\",\n \"last_name\": \"Souza\",\n \"gender\": \"female\",\n \"actions\": [\n {\n \"action\": \"add_tag\",\n \"tag_name\": \"cliente-vip\",\n },\n {\n \"action\": \"set_field_value\",\n \"field_name\": \"cidade\",\n \"value\": \"São Paulo\",\n },\n {\n \"action\": \"send_flow\",\n \"flow_id\": 1000001,\n },\n ],\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'phone' => '5511988776655',\n 'email' => 'ana@exemplo.com.br',\n 'first_name' => 'Ana',\n 'last_name' => 'Souza',\n 'gender' => 'female',\n 'actions' => [\n [\n 'action' => 'add_tag',\n 'tag_name' => 'cliente-vip',\n ],\n [\n 'action' => 'set_field_value',\n 'field_name' => 'cidade',\n 'value' => 'São Paulo',\n ],\n [\n 'action' => 'send_flow',\n 'flow_id' => 1000001,\n ],\n ],\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/contatos/criar-contato/" } } }, "/contacts/{contact_id}/custom_fields": { "get": { "operationId": "getUserFields", "summary": "Listar campos do contato", "description": "Lista os campos personalizados do contato, com o valor de cada um. O contato inteiro, com as etiquetas, sai de [Consultar contato](https://docs.nextags.com.br/referencia/contatos/consultar-contato/).", "tags": [ "Campos personalizados" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato.", "schema": { "type": "integer" }, "example": 123456789 } ], "responses": { "200": { "description": "Os campos do contato, com o valor.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Custom_field" } }, "example": [ { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" }, { "id": 3002, "name": "data_nascimento", "type": 2, "value": 642643200 } ] } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/contacts/123456789/custom_fields\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/contacts/123456789/custom_fields\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/campos-personalizados/listar-campos-do-contato/" } } }, "/contacts/{contact_id}/custom_fields/{custom_field_id}": { "get": { "operationId": "getFieldValue", "summary": "Consultar campo do contato", "description": "Devolve o valor de um campo personalizado do contato. Data e data e hora vêm em Unix timestamp, em segundos; sim/não vem como 1 ou 0.", "tags": [ "Campos personalizados" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato.", "schema": { "type": "integer" }, "example": 123456789 }, { "name": "custom_field_id", "in": "path", "required": true, "description": "O ID do campo personalizado.", "schema": { "type": "integer" }, "example": 3001 } ], "responses": { "200": { "description": "O campo, com o valor do contato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "O ID do campo." }, "type": { "type": "integer", "description": "O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla." }, "name": { "type": "string", "description": "O nome do campo." }, "value": { "type": [ "string", "number" ], "description": "O valor do contato, no formato do tipo: texto nos campos de texto e de texto longo; número nos de número, de data e de data e hora (Unix timestamp, em segundos) e de sim/não (1 ou 0)." } } }, "example": { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/campos-personalizados/consultar-campo-do-contato/" } }, "post": { "operationId": "addFieldToUser", "summary": "Preencher campo do contato", "description": "Grava um valor num campo personalizado do contato, como a ação **Definir Campo Personalizado** de um fluxo. O valor vai em formulário, no formato do tipo do campo: data e data e hora em Unix timestamp (segundos) e sim/não como `1` ou `0`. Para preencher pelo nome do campo no lugar do ID, mande a ação `set_field_value` em [Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/). Veja [Etiquetar contatos e preencher campos](https://docs.nextags.com.br/guias/etiquetas-e-campos/).", "tags": [ "Campos personalizados" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato.", "schema": { "type": "integer" }, "example": 123456789 }, { "name": "custom_field_id", "in": "path", "required": true, "description": "O ID do campo personalizado.", "schema": { "type": "string" }, "example": "3001" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "value": { "type": "string", "description": "O valor, no formato do tipo do campo.", "examples": [ "São Paulo" ] } }, "required": [ "value" ] }, "example": { "value": "São Paulo" } } } }, "responses": { "200": { "description": "O valor foi gravado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando o valor foi gravado." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'value=São Paulo'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n value: 'São Paulo',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"value\": \"São Paulo\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'value' => 'São Paulo',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/campos-personalizados/preencher-campo-do-contato/" } }, "delete": { "operationId": "removeFieldFromUser", "summary": "Limpar campo do contato", "description": "Apaga o valor de um campo personalizado do contato, como a ação **Limpar Campo Personalizado** de um fluxo. O campo continua na conta.", "tags": [ "Campos personalizados" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato.", "schema": { "type": "integer" }, "example": 123456789 }, { "name": "custom_field_id", "in": "path", "required": true, "description": "O ID do campo personalizado.", "schema": { "type": "integer" }, "example": 3001 } ], "responses": { "200": { "description": "O valor foi apagado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando o valor foi apagado." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X DELETE \"https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001', {\n method: 'DELETE',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.delete(\n \"https://app.nextagsai.com.br/api/contacts/123456789/custom_fields/3001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'DELETE',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/campos-personalizados/limpar-campo-do-contato/" } } }, "/contacts/{contact_id}/send/{flow_id}": { "post": { "operationId": "sendFlowToUser", "summary": "Enviar fluxo", "description": "Envia um fluxo ao contato, como o **Enviar Fluxo** da Caixa de Entrada: o contato recebe as mensagens e passa pelas ações do fluxo, na versão publicada. É o jeito mais completo de mandar conteúdo pela API, porque o fluxo pode ter botões, perguntas e o Modelo de Mensagem do WhatsApp. O ID do fluxo sai de [Listar fluxos](https://docs.nextags.com.br/referencia/fluxos/listar-fluxos/). Veja [Enviar um fluxo para um contato](https://docs.nextags.com.br/guias/enviar-fluxo/).\n\nNo WhatsApp, a mensagem livre só sai até 24 horas depois da última mensagem do contato. Fora dessa janela, o fluxo precisa começar com um Modelo de Mensagem aprovado: veja [Modelo de mensagem do WhatsApp no fluxo](https://help.nextags.com.br/tutoriais/fluxos/modelos-no-fluxo/) e [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/). Para o Instagram e o Messenger, veja [Mensagens fora da janela](https://help.nextags.com.br/tutoriais/instagram-e-facebook/mensagens-fora-da-janela/).", "tags": [ "Mensagens" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato que recebe.", "schema": { "type": "integer" }, "example": 123456789 }, { "name": "flow_id", "in": "path", "required": true, "description": "O ID do fluxo.", "schema": { "type": "integer" }, "example": 1000001 } ], "responses": { "200": { "description": "O envio do fluxo foi aceito." }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/contacts/123456789/send/1000001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send/1000001', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/contacts/123456789/send/1000001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo/" } } }, "/contacts/{contact_id}/send/text": { "post": { "operationId": "sendTextMessage", "summary": "Enviar texto", "description": "Envia uma mensagem de texto ao contato. Para mandar mais de uma mensagem, botões ou ações na mesma chamada, use [Enviar conteúdo](https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/). Veja [Enviar texto, imagem e arquivo](https://docs.nextags.com.br/guias/enviar-texto-e-arquivos/).\n\nNo WhatsApp, a mensagem livre só sai até 24 horas depois da última mensagem do contato. Fora dessa janela, use [Enviar fluxo](https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo/) com um fluxo que comece com um Modelo de Mensagem aprovado. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/) e, para o Instagram e o Messenger, [Mensagens fora da janela](https://help.nextags.com.br/tutoriais/instagram-e-facebook/mensagens-fora-da-janela/).", "tags": [ "Mensagens" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato que recebe.", "schema": { "type": "integer" }, "example": 123456789 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "O texto da mensagem.", "examples": [ "Oi, Ana! Seu pedido PED-1001 saiu para entrega." ] }, "channel": { "type": "string", "enum": [ "messenger", "whatsapp", "webchat", "telegram", "instagram" ], "description": "Por qual canal a mensagem sai." } }, "required": [ "text" ] }, "example": { "text": "Oi, Ana! Seu pedido PED-1001 saiu para entrega.", "channel": "whatsapp" } } } }, "responses": { "200": { "description": "O envio foi aceito.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando a NexTags aceitou o envio." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/contacts/123456789/send/text\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"text\": \"Oi, Ana! Seu pedido PED-1001 saiu para entrega.\",\n \"channel\": \"whatsapp\"\n }'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send/text', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n text: 'Oi, Ana! Seu pedido PED-1001 saiu para entrega.',\n channel: 'whatsapp',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/contacts/123456789/send/text\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n json={\n \"text\": \"Oi, Ana! Seu pedido PED-1001 saiu para entrega.\",\n \"channel\": \"whatsapp\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'text' => 'Oi, Ana! Seu pedido PED-1001 saiu para entrega.',\n 'channel' => 'whatsapp',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/mensagens/enviar-texto/" } } }, "/contacts/{contact_id}/send/file": { "post": { "operationId": "sendFile", "summary": "Enviar arquivo", "description": "Envia ao contato uma imagem, um vídeo, um áudio ou um documento, a partir do endereço do arquivo. Os formatos e os tamanhos aceitos mudam de canal para canal: veja [Tipos de arquivo e limites por canal](https://help.nextags.com.br/tutoriais/canais/tipos-de-arquivo-e-limites/) e [Enviar texto, imagem e arquivo](https://docs.nextags.com.br/guias/enviar-texto-e-arquivos/).\n\nNo WhatsApp, a mensagem livre só sai até 24 horas depois da última mensagem do contato. Fora dessa janela, use [Enviar fluxo](https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo/) com um fluxo que comece com um Modelo de Mensagem aprovado. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/) e, para o Instagram e o Messenger, [Mensagens fora da janela](https://help.nextags.com.br/tutoriais/instagram-e-facebook/mensagens-fora-da-janela/).", "tags": [ "Mensagens" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato que recebe.", "schema": { "type": "integer" }, "example": 123456789 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "O endereço público do arquivo, que abra sem login.", "examples": [ "https://exemplo.com.br/arquivos/catalogo.pdf" ] }, "type": { "type": "string", "enum": [ "file", "image", "audio", "video" ], "description": "O tipo do arquivo: `image` (imagem), `video` (vídeo), `audio` (áudio) ou `file` (documento)." }, "channel": { "type": "string", "enum": [ "messenger", "whatsapp", "telegram", "instagram" ], "description": "Por qual canal o arquivo sai." } }, "required": [ "url", "type" ] }, "example": { "url": "https://exemplo.com.br/arquivos/catalogo.pdf", "type": "file", "channel": "whatsapp" } } } }, "responses": { "200": { "description": "O envio foi aceito.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando a NexTags aceitou o envio." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/contacts/123456789/send/file\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"https://exemplo.com.br/arquivos/catalogo.pdf\",\n \"type\": \"file\",\n \"channel\": \"whatsapp\"\n }'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send/file', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n url: 'https://exemplo.com.br/arquivos/catalogo.pdf',\n type: 'file',\n channel: 'whatsapp',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/contacts/123456789/send/file\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n json={\n \"url\": \"https://exemplo.com.br/arquivos/catalogo.pdf\",\n \"type\": \"file\",\n \"channel\": \"whatsapp\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'url' => 'https://exemplo.com.br/arquivos/catalogo.pdf',\n 'type' => 'file',\n 'channel' => 'whatsapp',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/mensagens/enviar-arquivo/" } } }, "/contacts/{contact_id}/send_content": { "post": { "operationId": "sendContent", "summary": "Enviar conteúdo", "description": "Envia várias mensagens e roda ações no contato, numa chamada só. As mensagens (texto, botões, respostas rápidas, mídia e cartões) e as ações (`add_tag`, `set_field_value`, `send_flow` e as outras) seguem o formato de [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/), e a NexTags converte cada mensagem para o canal do contato. No WhatsApp, `messages` aceita também mensagens no formato da API do WhatsApp (lista, localização, contatos), com `\"to\": null`: a NexTags preenche o número.\n\nNo WhatsApp, a mensagem livre só sai até 24 horas depois da última mensagem do contato. Fora dessa janela, use [Enviar fluxo](https://docs.nextags.com.br/referencia/mensagens/enviar-fluxo/) com um fluxo que comece com um Modelo de Mensagem aprovado. Veja [A janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/) e, para o Instagram e o Messenger, [Mensagens fora da janela](https://help.nextags.com.br/tutoriais/instagram-e-facebook/mensagens-fora-da-janela/).", "tags": [ "Mensagens" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato que recebe.", "schema": { "type": "integer" }, "example": 123456789 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Mensagem" }, "description": "As mensagens, na ordem de envio." }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/Acao" }, "description": "As ações para rodar no contato, na ordem da lista." }, "channel": { "type": "string", "enum": [ "messenger", "whatsapp", "telegram", "instagram" ], "description": "Por qual canal as mensagens saem." } } }, "example": { "messages": [ { "message": { "text": "Oi, Ana! Seu pedido PED-1001 saiu para entrega." } }, { "message": { "attachment": { "type": "template", "payload": { "template_type": "button", "text": "Quer falar com a equipe?", "buttons": [ { "type": "postback", "title": "Falar com a equipe", "payload": "1000001" } ] } } } } ], "actions": [ { "action": "add_tag", "tag_name": "cliente-vip" }, { "action": "set_field_value", "field_name": "cidade", "value": "São Paulo" } ], "channel": "whatsapp" } } } }, "responses": { "200": { "description": "O envio foi aceito." }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/contacts/123456789/send_content\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"messages\": [\n {\n \"message\": {\n \"text\": \"Oi, Ana! Seu pedido PED-1001 saiu para entrega.\"\n }\n },\n {\n \"message\": {\n \"attachment\": {\n \"type\": \"template\",\n \"payload\": {\n \"template_type\": \"button\",\n \"text\": \"Quer falar com a equipe?\",\n \"buttons\": [\n {\n \"type\": \"postback\",\n \"title\": \"Falar com a equipe\",\n \"payload\": \"1000001\"\n }\n ]\n }\n }\n }\n }\n ],\n \"actions\": [\n {\n \"action\": \"add_tag\",\n \"tag_name\": \"cliente-vip\"\n },\n {\n \"action\": \"set_field_value\",\n \"field_name\": \"cidade\",\n \"value\": \"São Paulo\"\n }\n ],\n \"channel\": \"whatsapp\"\n }'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send_content', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n messages: [\n {\n message: {\n text: 'Oi, Ana! Seu pedido PED-1001 saiu para entrega.',\n },\n },\n {\n message: {\n attachment: {\n type: 'template',\n payload: {\n template_type: 'button',\n text: 'Quer falar com a equipe?',\n buttons: [\n {\n type: 'postback',\n title: 'Falar com a equipe',\n payload: '1000001',\n },\n ],\n },\n },\n },\n },\n ],\n actions: [\n {\n action: 'add_tag',\n tag_name: 'cliente-vip',\n },\n {\n action: 'set_field_value',\n field_name: 'cidade',\n value: 'São Paulo',\n },\n ],\n channel: 'whatsapp',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/contacts/123456789/send_content\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n json={\n \"messages\": [\n {\n \"message\": {\n \"text\": \"Oi, Ana! Seu pedido PED-1001 saiu para entrega.\",\n },\n },\n {\n \"message\": {\n \"attachment\": {\n \"type\": \"template\",\n \"payload\": {\n \"template_type\": \"button\",\n \"text\": \"Quer falar com a equipe?\",\n \"buttons\": [\n {\n \"type\": \"postback\",\n \"title\": \"Falar com a equipe\",\n \"payload\": \"1000001\",\n },\n ],\n },\n },\n },\n },\n ],\n \"actions\": [\n {\n \"action\": \"add_tag\",\n \"tag_name\": \"cliente-vip\",\n },\n {\n \"action\": \"set_field_value\",\n \"field_name\": \"cidade\",\n \"value\": \"São Paulo\",\n },\n ],\n \"channel\": \"whatsapp\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'messages' => [\n [\n 'message' => [\n 'text' => 'Oi, Ana! Seu pedido PED-1001 saiu para entrega.',\n ],\n ],\n [\n 'message' => [\n 'attachment' => [\n 'type' => 'template',\n 'payload' => [\n 'template_type' => 'button',\n 'text' => 'Quer falar com a equipe?',\n 'buttons' => [\n [\n 'type' => 'postback',\n 'title' => 'Falar com a equipe',\n 'payload' => '1000001',\n ],\n ],\n ],\n ],\n ],\n ],\n ],\n 'actions' => [\n [\n 'action' => 'add_tag',\n 'tag_name' => 'cliente-vip',\n ],\n [\n 'action' => 'set_field_value',\n 'field_name' => 'cidade',\n 'value' => 'São Paulo',\n ],\n ],\n 'channel' => 'whatsapp',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/mensagens/enviar-conteudo/" } } }, "/pipelines": { "get": { "operationId": "getPipelines", "summary": "Listar pipelines", "description": "Lista os pipelines da conta, com o ID e o nome de cada um. É daqui que sai o `pipeline_id` das outras chamadas. A lista vem em páginas: ande por ela com `offset` e `limit`.", "tags": [ "Pipelines e oportunidades" ], "parameters": [ { "name": "offset", "in": "query", "required": false, "description": "Quantos registros pular antes do primeiro da página. Comece em 0 e some o `limit` a cada página.", "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Quantos registros trazer por página.", "schema": { "type": "integer", "default": 100 } } ], "responses": { "200": { "description": "Os pipelines, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Pipeline" }, "description": "A lista de pipelines." } } }, "example": { "data": [ { "id": 4001, "name": "Funil de vendas" }, { "id": 4002, "name": "Onboarding de clientes" } ] } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/pipelines\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/pipelines\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/" } } }, "/contacts/{contact_id}/ai/save_messages": { "post": { "operationId": "aiSaveMessages", "summary": "Salvar mensagens no histórico da IA", "description": "Põe mensagens no histórico de conversa que a IA guarda do contato, sem enviar nada a ele. Use para dar contexto à IA sobre uma conversa que aconteceu fora da NexTags, como um atendimento por telefone, por e-mail ou na loja: nas próximas respostas, ela já sabe o que foi dito. Nos fluxos, a ação **Excluir histórico de mensagens** apaga o histórico da IA do contato; veja [Chamar a IA no fluxo](https://help.nextags.com.br/tutoriais/fluxos/ia-no-fluxo/).", "tags": [ "Agentes de IA" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato.", "schema": { "type": "integer" }, "example": 123456789 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "examples": [ "Liguei ontem para trocar o tamanho do tênis do pedido PED-1001." ], "description": "O texto da mensagem." }, "type": { "type": "string", "enum": [ "text", "image", "file", "audio" ], "examples": [ "text" ], "description": "O tipo: `text` (texto), `image` (imagem), `file` (arquivo) ou `audio` (áudio)." }, "role": { "type": "string", "enum": [ "assistant", "user", "developer" ], "examples": [ "user" ], "description": "Quem falou: `user` (o contato), `assistant` (a IA ou a sua equipe, respondendo) ou `developer` (uma instrução para a IA, que não é fala de ninguém)." } }, "required": [ "text", "role" ] }, "description": "As mensagens, na ordem em que aconteceram." } } }, "example": { "messages": [ { "role": "user", "type": "text", "text": "Liguei ontem para trocar o tamanho do tênis do pedido PED-1001." }, { "role": "assistant", "type": "text", "text": "Combinado, Ana! A troca para o 38 foi aberta e o novo par sai amanhã." } ] } } } }, "responses": { "200": { "description": "As mensagens entraram no histórico da IA do contato." }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/contacts/123456789/ai/save_messages\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"messages\": [\n {\n \"role\": \"user\",\n \"type\": \"text\",\n \"text\": \"Liguei ontem para trocar o tamanho do tênis do pedido PED-1001.\"\n },\n {\n \"role\": \"assistant\",\n \"type\": \"text\",\n \"text\": \"Combinado, Ana! A troca para o 38 foi aberta e o novo par sai amanhã.\"\n }\n ]\n }'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/ai/save_messages', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n messages: [\n {\n role: 'user',\n type: 'text',\n text: 'Liguei ontem para trocar o tamanho do tênis do pedido PED-1001.',\n },\n {\n role: 'assistant',\n type: 'text',\n text: 'Combinado, Ana! A troca para o 38 foi aberta e o novo par sai amanhã.',\n },\n ],\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/contacts/123456789/ai/save_messages\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n json={\n \"messages\": [\n {\n \"role\": \"user\",\n \"type\": \"text\",\n \"text\": \"Liguei ontem para trocar o tamanho do tênis do pedido PED-1001.\",\n },\n {\n \"role\": \"assistant\",\n \"type\": \"text\",\n \"text\": \"Combinado, Ana! A troca para o 38 foi aberta e o novo par sai amanhã.\",\n },\n ],\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'messages' => [\n [\n 'role' => 'user',\n 'type' => 'text',\n 'text' => 'Liguei ontem para trocar o tamanho do tênis do pedido PED-1001.',\n ],\n [\n 'role' => 'assistant',\n 'type' => 'text',\n 'text' => 'Combinado, Ana! A troca para o 38 foi aberta e o novo par sai amanhã.',\n ],\n ],\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/agentes-de-ia/salvar-mensagens-no-historico-da-ia/" } } }, "/pipelines/{pipeline_id}": { "get": { "operationId": "getPipeline", "summary": "Consultar pipeline", "description": "Devolve um pipeline pelo ID: o ID e o nome. As colunas do quadro vêm em [Listar etapas do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-etapas-do-pipeline/).", "tags": [ "Pipelines e oportunidades" ], "parameters": [ { "name": "pipeline_id", "in": "path", "required": true, "description": "O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)).", "schema": { "type": "integer" }, "example": 4001 } ], "responses": { "200": { "description": "O pipeline.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pipeline" }, "example": { "id": 4001, "name": "Funil de vendas" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/pipelines/4001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/pipelines/4001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/pipelines/consultar-pipeline/" } } }, "/pipelines/{pipeline_id}/stages": { "get": { "operationId": "getPipelineStages", "summary": "Listar etapas do pipeline", "description": "Lista as etapas do pipeline (as colunas do quadro), com o ID e o nome de cada uma. O ID da etapa vai em `stage_id`, para criar a oportunidade numa etapa ou mudá-la de etapa, e em `target_stage_id`, para transferir. Veja [Etapas: criar, ordenar e configurar](https://help.nextags.com.br/tutoriais/pipelines/etapas/).", "tags": [ "Pipelines e oportunidades" ], "parameters": [ { "name": "pipeline_id", "in": "path", "required": true, "description": "O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)).", "schema": { "type": "integer" }, "example": 4001 } ], "responses": { "200": { "description": "As etapas, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineStage" }, "description": "A lista de etapas." } } }, "example": { "data": [ { "id": 4101, "name": "Novo lead" }, { "id": 4102, "name": "Proposta enviada" }, { "id": 4103, "name": "Fechamento" } ] } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/pipelines/4001/stages\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/stages', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/pipelines/4001/stages\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/pipelines/listar-etapas-do-pipeline/" } } }, "/pipelines/{pipeline_id}/custom_fields": { "get": { "operationId": "getPipelineCustomFields", "summary": "Listar campos do pipeline", "description": "Lista os campos do pipeline: os campos próprios das oportunidades, criados nas definições do pipeline em **Campo Personalizados**. Não são os campos personalizados do contato. Use o `id` ou o `name` deles em `custom_fields`, ao criar ou atualizar uma oportunidade. Veja [Comentários, anexos e campos do pipeline](https://help.nextags.com.br/tutoriais/pipelines/comentarios-e-anexos/).", "tags": [ "Pipelines e oportunidades" ], "parameters": [ { "name": "pipeline_id", "in": "path", "required": true, "description": "O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)).", "schema": { "type": "integer" }, "example": 4001 } ], "responses": { "200": { "description": "A lista de campos, sem `data` em volta.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID do campo." }, "name": { "type": "string", "description": "O **Nome** do campo, como aparece na oportunidade." }, "type": { "type": [ "integer", "string" ], "description": "O código do tipo, como na tela: 0 Texto, 1 Número, 2 Data, 3 Data e hora, 4 Verdadeiro/Falso, 6 Seleção única e 7 Seleção múltipla." }, "description": { "type": "string", "description": "A descrição do campo. A tela não pede descrição ao criar o campo." } } } }, "example": [ { "id": 3201, "name": "Origem do lead", "type": 0, "description": "" }, { "id": 3202, "name": "Previsão de fechamento", "type": 2, "description": "" } ] } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/pipelines/4001/custom_fields\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/custom_fields', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/pipelines/4001/custom_fields\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/pipelines/listar-campos-do-pipeline/" } } }, "/pipelines/{pipeline_id}/opportunities": { "get": { "operationId": "pipelinesGetCards", "summary": "Listar oportunidades", "description": "Lista as oportunidades de um pipeline, em páginas (`offset` e `limit`). Com `contact_id`, traz só as de um contato: o jeito de saber se o cliente já tem uma oportunidade aberta antes de criar outra.", "tags": [ "Pipelines e oportunidades" ], "parameters": [ { "name": "pipeline_id", "in": "path", "required": true, "description": "O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)).", "schema": { "type": "integer" }, "example": 4001 }, { "name": "contact_id", "in": "query", "required": false, "description": "O ID de um contato: traz só as oportunidades dele.", "schema": { "type": "number" }, "example": 123456789 }, { "name": "offset", "in": "query", "required": false, "description": "Quantos registros pular antes do primeiro da página. Comece em 0 e some o `limit` a cada página.", "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Quantos registros trazer por página.", "schema": { "type": "integer", "default": 100 } } ], "responses": { "200": { "description": "As oportunidades, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Opportunity" }, "description": "A lista de oportunidades." } } }, "example": { "data": [ { "id": 4201, "contact_id": 123456789, "title": "Plano Pro anual", "description": "Quer começar em novembro, com 3 atendentes.", "value": 1500, "status": "open", "priority": "high", "stage": { "id": 4101, "name": "Novo lead" }, "assigned_admins": [ 10001 ], "created_at": "2026-10-20 14:30:00", "created_by": 10001, "updated_at": "2026-10-22 18:05:00", "updated_by": 10001 } ] } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/pipelines/4001/opportunities?contact_id=123456789\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch(`https://app.nextagsai.com.br/api/pipelines/4001/opportunities?${new URLSearchParams({\n contact_id: 123456789,\n})}`, {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/pipelines/4001/opportunities\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n params={\n \"contact_id\": 123456789,\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " 123456789,\n]));\ncurl_setopt_array($ch, [\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/" } }, "post": { "operationId": "pipelinesAddCard", "summary": "Criar oportunidade", "description": "Cria uma oportunidade (ou um ticket, nos pipelines de suporte) para um contato. Sem `stage_id`, ela entra na primeira etapa do pipeline. Os IDs vêm de [Listar etapas do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-etapas-do-pipeline/), [Listar administradores](https://docs.nextags.com.br/referencia/conta/listar-administradores/) e [Listar campos do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-campos-do-pipeline/). Veja o guia [Criar e mover oportunidades no pipeline](https://docs.nextags.com.br/guias/oportunidades-no-pipeline/).", "tags": [ "Pipelines e oportunidades" ], "parameters": [ { "name": "pipeline_id", "in": "path", "required": true, "description": "O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)).", "schema": { "type": "integer" }, "example": 4001 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "integer", "description": "O ID do contato dono da oportunidade." }, "title": { "type": "string", "description": "O nome da oportunidade (o **Nome da Oportunidade** da tela), como \"Plano Pro anual\"." }, "description": { "type": "string", "description": "A descrição (a **Descrição da Oportunidade**)." }, "stage_id": { "type": "integer", "description": "O ID da etapa onde a oportunidade entra. Sem ele, a primeira etapa do pipeline." }, "value": { "type": "number", "default": 0, "description": "O **Valor da Oportunidade**, na moeda da conta. Não é em centavos: `1500` = R$ 1.500,00." }, "status": { "type": "string", "description": "O **Estado**: `open` (Aberto), `won` (Ganho) ou `lost` (Perdido). Nos pipelines de suporte e nos personalizados, `won` aparece como **Resolvido** e `lost` como **Não Resolvido**.", "enum": [ "open", "won", "lost" ], "default": "open" }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium", "description": "A **Prioridade**: `low` (Baixa), `medium` (Média) ou `high` (Alta)." }, "assigned_admins": { "type": "array", "default": [], "items": { "type": "integer" }, "description": "Os **Administradores atribuídos**: uma lista de IDs de administradores (veja [Listar administradores](https://docs.nextags.com.br/referencia/conta/listar-administradores/))." }, "custom_fields": { "type": "array", "description": "Os valores dos campos do pipeline (veja [Listar campos do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-campos-do-pipeline/)). Cada item leva o `id` ou o `name` do campo e o `value`.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "O ID do campo do pipeline." }, "name": { "type": "string", "description": "O nome do campo do pipeline, no lugar do `id`." }, "value": { "type": [ "string", "number" ], "description": "O valor do campo: texto ou número, conforme o tipo." } } } } }, "required": [ "contact_id", "title" ] }, "example": { "contact_id": 123456789, "title": "Plano Pro anual", "description": "Quer começar em novembro, com 3 atendentes.", "stage_id": 4101, "value": 1500, "status": "open", "priority": "high", "assigned_admins": [ 10001 ], "custom_fields": [ { "id": 3201, "value": "Anúncio no Instagram" } ] } } } }, "responses": { "200": { "description": "A oportunidade criada, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Opportunity" }, "description": "Uma lista com a oportunidade criada." } } }, "example": { "data": [ { "id": 4201, "contact_id": 123456789, "title": "Plano Pro anual", "description": "Quer começar em novembro, com 3 atendentes.", "value": 1500, "status": "open", "priority": "high", "stage": { "id": 4101, "name": "Novo lead" }, "assigned_admins": [ 10001 ], "created_at": "2026-10-20 14:30:00", "created_by": 10001, "updated_at": "2026-10-22 18:05:00", "updated_by": 10001 } ] } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/pipelines/4001/opportunities\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"contact_id\": 123456789,\n \"title\": \"Plano Pro anual\",\n \"description\": \"Quer começar em novembro, com 3 atendentes.\",\n \"stage_id\": 4101,\n \"value\": 1500,\n \"status\": \"open\",\n \"priority\": \"high\",\n \"assigned_admins\": [\n 10001\n ],\n \"custom_fields\": [\n {\n \"id\": 3201,\n \"value\": \"Anúncio no Instagram\"\n }\n ]\n }'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/opportunities', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n contact_id: 123456789,\n title: 'Plano Pro anual',\n description: 'Quer começar em novembro, com 3 atendentes.',\n stage_id: 4101,\n value: 1500,\n status: 'open',\n priority: 'high',\n assigned_admins: [10001],\n custom_fields: [\n {\n id: 3201,\n value: 'Anúncio no Instagram',\n },\n ],\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/pipelines/4001/opportunities\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n json={\n \"contact_id\": 123456789,\n \"title\": \"Plano Pro anual\",\n \"description\": \"Quer começar em novembro, com 3 atendentes.\",\n \"stage_id\": 4101,\n \"value\": 1500,\n \"status\": \"open\",\n \"priority\": \"high\",\n \"assigned_admins\": [10001],\n \"custom_fields\": [\n {\n \"id\": 3201,\n \"value\": \"Anúncio no Instagram\",\n },\n ],\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'contact_id' => 123456789,\n 'title' => 'Plano Pro anual',\n 'description' => 'Quer começar em novembro, com 3 atendentes.',\n 'stage_id' => 4101,\n 'value' => 1500,\n 'status' => 'open',\n 'priority' => 'high',\n 'assigned_admins' => [10001],\n 'custom_fields' => [\n [\n 'id' => 3201,\n 'value' => 'Anúncio no Instagram',\n ],\n ],\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/pipelines/criar-oportunidade/" } } }, "/pipelines/{pipeline_id}/opportunities/{opportunity_id}": { "get": { "operationId": "pipelinesGetCard", "summary": "Consultar oportunidade", "description": "Devolve uma oportunidade: o contato, o título, o valor, o estado, a prioridade, a etapa, os responsáveis e as datas.", "tags": [ "Pipelines e oportunidades" ], "parameters": [ { "name": "pipeline_id", "in": "path", "required": true, "description": "O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)).", "schema": { "type": "integer" }, "example": 4001 }, { "name": "opportunity_id", "in": "path", "required": true, "description": "O ID da oportunidade (veja [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/)).", "schema": { "type": "integer" }, "example": 4201 } ], "responses": { "200": { "description": "A oportunidade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Opportunity" }, "example": { "id": 4201, "contact_id": 123456789, "title": "Plano Pro anual", "description": "Quer começar em novembro, com 3 atendentes.", "value": 1500, "status": "open", "priority": "high", "stage": { "id": 4101, "name": "Novo lead" }, "assigned_admins": [ 10001 ], "created_at": "2026-10-20 14:30:00", "created_by": 10001, "updated_at": "2026-10-22 18:05:00", "updated_by": 10001 } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/pipelines/consultar-oportunidade/" } }, "post": { "operationId": "pipelinesUpdateCard", "summary": "Atualizar oportunidade", "description": "Muda uma oportunidade: o título, a descrição, a etapa, o valor, o estado, a prioridade, os responsáveis e os campos do pipeline. Para mudar de etapa, mande o `stage_id` novo; para fechar, o `status` com `won` (ganha) ou `lost` (perdida); para reabrir, `open`. O `title` vai sempre, mesmo quando não muda. Veja [Valor, prioridade, vencimento e responsáveis](https://help.nextags.com.br/tutoriais/pipelines/campos-do-card/).", "tags": [ "Pipelines e oportunidades" ], "parameters": [ { "name": "pipeline_id", "in": "path", "required": true, "description": "O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)).", "schema": { "type": "integer" }, "example": 4001 }, { "name": "opportunity_id", "in": "path", "required": true, "description": "O ID da oportunidade (veja [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/)).", "schema": { "type": "integer" }, "example": 4201 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "O nome da oportunidade. Vai sempre: mande o atual quando não for mudar." }, "description": { "type": "string", "description": "A descrição (a **Descrição da Oportunidade**)." }, "stage_id": { "type": "integer", "description": "O ID da etapa para onde a oportunidade vai." }, "value": { "type": "number", "default": 0, "description": "O **Valor da Oportunidade**, na moeda da conta. Não é em centavos: `1500` = R$ 1.500,00." }, "status": { "type": "string", "description": "O **Estado**: `open` (Aberto), `won` (Ganho) ou `lost` (Perdido). Nos pipelines de suporte e nos personalizados, `won` aparece como **Resolvido** e `lost` como **Não Resolvido**.", "enum": [ "open", "won", "lost" ], "default": "open" }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium", "description": "A **Prioridade**: `low` (Baixa), `medium` (Média) ou `high` (Alta)." }, "assigned_admins": { "type": "array", "default": [], "items": { "type": "integer" }, "description": "Os **Administradores atribuídos**: uma lista de IDs de administradores (veja [Listar administradores](https://docs.nextags.com.br/referencia/conta/listar-administradores/))." }, "custom_fields": { "type": "array", "description": "Os valores dos campos do pipeline (veja [Listar campos do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-campos-do-pipeline/)). Cada item leva o `id` ou o `name` do campo e o `value`.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "O ID do campo do pipeline." }, "name": { "type": "string", "description": "O nome do campo do pipeline, no lugar do `id`." }, "value": { "type": [ "string", "number" ], "description": "O valor do campo: texto ou número, conforme o tipo." } } } } }, "required": [ "title" ] }, "example": { "title": "Plano Pro anual", "stage_id": 4103, "status": "won", "value": 1800, "custom_fields": [ { "name": "Origem do lead", "value": "Indicação" } ] } } } }, "responses": { "200": { "description": "A oportunidade foi atualizada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando deu certo." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"title\": \"Plano Pro anual\",\n \"stage_id\": 4103,\n \"status\": \"won\",\n \"value\": 1800,\n \"custom_fields\": [\n {\n \"name\": \"Origem do lead\",\n \"value\": \"Indicação\"\n }\n ]\n }'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n title: 'Plano Pro anual',\n stage_id: 4103,\n status: 'won',\n value: 1800,\n custom_fields: [\n {\n name: 'Origem do lead',\n value: 'Indicação',\n },\n ],\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n json={\n \"title\": \"Plano Pro anual\",\n \"stage_id\": 4103,\n \"status\": \"won\",\n \"value\": 1800,\n \"custom_fields\": [\n {\n \"name\": \"Origem do lead\",\n \"value\": \"Indicação\",\n },\n ],\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'title' => 'Plano Pro anual',\n 'stage_id' => 4103,\n 'status' => 'won',\n 'value' => 1800,\n 'custom_fields' => [\n [\n 'name' => 'Origem do lead',\n 'value' => 'Indicação',\n ],\n ],\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/pipelines/atualizar-oportunidade/" } }, "delete": { "operationId": "pipelinesDeleteCard", "summary": "Apagar oportunidade", "description": "Apaga a oportunidade do pipeline, como o **Excluir** do menu do cartão.", "tags": [ "Pipelines e oportunidades" ], "parameters": [ { "name": "pipeline_id", "in": "path", "required": true, "description": "O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)).", "schema": { "type": "integer" }, "example": 4001 }, { "name": "opportunity_id", "in": "path", "required": true, "description": "O ID da oportunidade (veja [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/)).", "schema": { "type": "integer" }, "example": 4201 } ], "responses": { "200": { "description": "A oportunidade foi apagada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando deu certo." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X DELETE \"https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201', {\n method: 'DELETE',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.delete(\n \"https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'DELETE',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/pipelines/apagar-oportunidade/" } } }, "/pipelines/{pipeline_id}/opportunities/{opportunity_id}/transfer-to-pipeline": { "post": { "operationId": "pipelinesTransferCard", "summary": "Transferir oportunidade de pipeline", "description": "Leva a oportunidade para outro pipeline, numa etapa escolhida, como o **Transferir para o Pipeline** do cartão. A etapa é do pipeline de destino: pegue o ID dela em [Listar etapas do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-etapas-do-pipeline/), com o ID do pipeline novo. Veja [Oportunidades e tickets](https://help.nextags.com.br/tutoriais/pipelines/oportunidades/).", "tags": [ "Pipelines e oportunidades" ], "parameters": [ { "name": "pipeline_id", "in": "path", "required": true, "description": "O ID do pipeline onde a oportunidade está agora.", "schema": { "type": "integer" }, "example": 4001 }, { "name": "opportunity_id", "in": "path", "required": true, "description": "O ID da oportunidade (veja [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/)).", "schema": { "type": "integer" }, "example": 4201 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target_pipeline_id": { "type": "integer", "description": "O ID do pipeline de destino." }, "target_stage_id": { "type": "integer", "description": "O ID da etapa do pipeline de destino onde a oportunidade entra." } }, "required": [ "target_pipeline_id", "target_stage_id" ] }, "example": { "target_pipeline_id": 4002, "target_stage_id": 4111 } } } }, "responses": { "200": { "description": "A oportunidade mudou de pipeline.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando deu certo." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/transfer-to-pipeline\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"target_pipeline_id\": 4002,\n \"target_stage_id\": 4111\n }'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/transfer-to-pipeline', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n target_pipeline_id: 4002,\n target_stage_id: 4111,\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/transfer-to-pipeline\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n json={\n \"target_pipeline_id\": 4002,\n \"target_stage_id\": 4111,\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'target_pipeline_id' => 4002,\n 'target_stage_id' => 4111,\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/pipelines/transferir-oportunidade-de-pipeline/" } } }, "/pipelines/{pipeline_id}/opportunities/{opportunity_id}/comments": { "get": { "operationId": "pipelinesGetComments", "summary": "Listar comentários da oportunidade", "description": "Lista os comentários de uma oportunidade (a seção **Comentários** do cartão), em páginas (`offset` e `limit`). Veja [Comentários, anexos e campos do pipeline](https://help.nextags.com.br/tutoriais/pipelines/comentarios-e-anexos/).", "tags": [ "Pipelines e oportunidades" ], "parameters": [ { "name": "pipeline_id", "in": "path", "required": true, "description": "O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)).", "schema": { "type": "integer" }, "example": 4001 }, { "name": "opportunity_id", "in": "path", "required": true, "description": "O ID da oportunidade (veja [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/)).", "schema": { "type": "integer" }, "example": 4201 }, { "name": "offset", "in": "query", "required": false, "description": "Quantos registros pular antes do primeiro da página. Comece em 0 e some o `limit` a cada página.", "schema": { "type": "integer", "default": 0 } }, { "name": "limit", "in": "query", "required": false, "description": "Quantos registros trazer por página.", "schema": { "type": "integer", "default": 100 } } ], "responses": { "200": { "description": "Os comentários, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OpportunityComment" }, "description": "A lista de comentários." } } }, "example": { "data": [ { "id": 4301, "data": "Proposta enviada por e-mail: Plano Pro anual com 10% de desconto.", "created_at": "2026-10-21 13:15:00", "created_by": 10001 } ] } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/comments\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/comments', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/comments\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/pipelines/listar-comentarios-da-oportunidade/" } }, "post": { "operationId": "pipelinesAddComment", "summary": "Comentar na oportunidade", "description": "Escreve um comentário na oportunidade, como o **Adicionar Comentário** do cartão. Serve para registrar no pipeline o que aconteceu no seu sistema, como uma proposta enviada ou um pagamento.", "tags": [ "Pipelines e oportunidades" ], "parameters": [ { "name": "pipeline_id", "in": "path", "required": true, "description": "O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)).", "schema": { "type": "integer" }, "example": 4001 }, { "name": "opportunity_id", "in": "path", "required": true, "description": "O ID da oportunidade (veja [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/)).", "schema": { "type": "integer" }, "example": 4201 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "O texto do comentário." } }, "required": [ "content" ] }, "example": { "content": "Proposta enviada por e-mail: Plano Pro anual com 10% de desconto." } } } }, "responses": { "200": { "description": "O comentário criado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityComment" }, "example": { "id": 4301, "data": "Proposta enviada por e-mail: Plano Pro anual com 10% de desconto.", "created_at": "2026-10-21 13:15:00", "created_by": 10001 } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/comments\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"content\": \"Proposta enviada por e-mail: Plano Pro anual com 10% de desconto.\"\n }'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/comments', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n content: 'Proposta enviada por e-mail: Plano Pro anual com 10% de desconto.',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/comments\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n json={\n \"content\": \"Proposta enviada por e-mail: Plano Pro anual com 10% de desconto.\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'content' => 'Proposta enviada por e-mail: Plano Pro anual com 10% de desconto.',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/pipelines/comentar-na-oportunidade/" } } }, "/pipelines/{pipeline_id}/opportunities/{opportunity_id}/comments/{comment_id}": { "delete": { "operationId": "pipelinesDeleteComment", "summary": "Apagar comentário", "description": "Apaga um comentário da oportunidade, como o **Excluir** do menu do comentário.", "tags": [ "Pipelines e oportunidades" ], "parameters": [ { "name": "pipeline_id", "in": "path", "required": true, "description": "O ID do pipeline (veja [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/)).", "schema": { "type": "integer" }, "example": 4001 }, { "name": "opportunity_id", "in": "path", "required": true, "description": "O ID da oportunidade (veja [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/)).", "schema": { "type": "integer" }, "example": 4201 }, { "name": "comment_id", "in": "path", "required": true, "description": "O ID do comentário (veja [Listar comentários da oportunidade](https://docs.nextags.com.br/referencia/pipelines/listar-comentarios-da-oportunidade/)).", "schema": { "type": "integer" }, "example": 4301 } ], "responses": { "200": { "description": "O comentário foi apagado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando deu certo." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X DELETE \"https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/comments/4301\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/comments/4301', {\n method: 'DELETE',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.delete(\n \"https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/comments/4301\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'DELETE',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/pipelines/apagar-comentario/" } } }, "/agents/": { "get": { "operationId": "getAIAgents", "summary": "Listar agentes de IA", "description": "Lista os agentes de IA da conta (a aba **Agentes de IA** do AI Hub), com o ID e o nome de cada um. O endereço termina com barra: `/agents/`. Veja [Conheça o AI Hub](https://help.nextags.com.br/tutoriais/ia/ia-hub/).", "tags": [ "Agentes de IA" ], "responses": { "200": { "description": "Os agentes, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" }, "maxItems": 100, "description": "A lista de agentes (até 100)." } } }, "example": { "data": [ { "id": 5001, "name": "Bia - Loja Exemplo", "created_by": 10001, "created_at": "2026-09-15 13:20:00" }, { "id": 5002, "name": "Suporte pós-venda", "created_by": 10001, "created_at": "2026-10-02 17:45:00" } ] } } } }, "400": { "description": "Parâmetros inválidos." }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/agents/\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/agents/', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/agents/\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/agentes-de-ia/listar-agentes-de-ia/" } } }, "/agents/{agent_id}": { "get": { "operationId": "getAIById", "summary": "Consultar agente de IA", "description": "Devolve um agente de IA pelo ID: o nome, quem criou e quando. Veja [Criar um agente de IA](https://help.nextags.com.br/tutoriais/ia/criar-agente/).", "tags": [ "Agentes de IA" ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "O ID do agente (veja [Listar agentes de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-agentes-de-ia/)).", "schema": { "type": "integer" }, "example": 5001 } ], "responses": { "200": { "description": "O agente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" }, "example": { "id": 5001, "name": "Bia - Loja Exemplo", "created_by": 10001, "created_at": "2026-09-15 13:20:00" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/agents/5001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/agents/5001', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/agents/5001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/agentes-de-ia/consultar-agente-de-ia/" } }, "post": { "operationId": "updateAIById", "summary": "Atualizar agente de IA", "description": "Muda a configuração de um agente: a **Mensagem do sistema (Prompt)**, o **Max tokens** e o modelo de cada provedor. Os três campos são opcionais. Veja [Escrever a mensagem do sistema](https://help.nextags.com.br/tutoriais/ia/escrever-o-prompt/) e [Modelo, temperatura e limite de tokens](https://help.nextags.com.br/tutoriais/ia/modelo-e-parametros/).", "tags": [ "Agentes de IA" ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "description": "O ID do agente (veja [Listar agentes de IA](https://docs.nextags.com.br/referencia/agentes-de-ia/listar-agentes-de-ia/)).", "schema": { "type": "integer" }, "example": 5001 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "description": "A **Mensagem do sistema (Prompt)**: as instruções que o agente segue em todas as respostas. O texto novo substitui o atual." }, "max_output_tokens": { "type": "integer", "description": "O **Max tokens**: o tamanho máximo de cada resposta, em tokens. Na tela, de 1 a 32768; o agente novo vem com 2048." }, "model": { "type": "object", "properties": { "openAI": { "type": "string", "description": "O modelo da OpenAI, como `gpt-6-luna`." }, "gemini": { "type": "string", "description": "O modelo do Google Gemini, com o prefixo `models/`, como `models/gemini-3.5-flash-lite`." }, "claude": { "type": "string", "description": "O modelo do Claude, como `claude-haiku-4-5-20251001`." }, "xAI": { "type": "string", "description": "O modelo do xAI, como `grok-4.3`." }, "deepseek": { "type": "string", "description": "O modelo do DeepSeek, como `deepseek-v4-flash`." } }, "required": [ "openAI", "gemini", "claude", "xAI", "deepseek" ], "description": "O modelo de cada provedor, os campos **Modelo (OpenAI)**, **Modelo (Gemini)**, **Modelo (Claude)**, **Modelo (xAI)** e **Modelo (DeepSeek)** dos ajustes do agente. Use o nome do modelo como o provedor chama; os exemplos são os modelos com que um agente novo começa. Mande os cinco, mesmo os de provedores que a conta não usa." } } }, "example": { "prompt": "Você é a Bia, atendente da Loja Exemplo. Responda em português, em até 3 frases. Quando o cliente pedir troca, passe para a equipe.", "max_output_tokens": 2048, "model": { "openAI": "gpt-6-luna", "gemini": "models/gemini-3.5-flash-lite", "claude": "claude-haiku-4-5-20251001", "xAI": "grok-4.3", "deepseek": "deepseek-v4-flash" } } } } }, "responses": { "200": { "description": "O agente, depois da mudança.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" }, "example": { "id": 5001, "name": "Bia - Loja Exemplo", "created_by": 10001, "created_at": "2026-09-15 13:20:00" } } } }, "400": { "description": "A mudança não foi aceita: confira os campos do corpo." }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/agents/5001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"prompt\": \"Você é a Bia, atendente da Loja Exemplo. Responda em português, em até 3 frases. Quando o cliente pedir troca, passe para a equipe.\",\n \"max_output_tokens\": 2048,\n \"model\": {\n \"openAI\": \"gpt-6-luna\",\n \"gemini\": \"models/gemini-3.5-flash-lite\",\n \"claude\": \"claude-haiku-4-5-20251001\",\n \"xAI\": \"grok-4.3\",\n \"deepseek\": \"deepseek-v4-flash\"\n }\n }'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/agents/5001', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n prompt: 'Você é a Bia, atendente da Loja Exemplo. Responda em português, em até 3 frases. Quando o cliente pedir troca, passe para a equipe.',\n max_output_tokens: 2048,\n model: {\n openAI: 'gpt-6-luna',\n gemini: 'models/gemini-3.5-flash-lite',\n claude: 'claude-haiku-4-5-20251001',\n xAI: 'grok-4.3',\n deepseek: 'deepseek-v4-flash',\n },\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/agents/5001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n json={\n \"prompt\": \"Você é a Bia, atendente da Loja Exemplo. Responda em português, em até 3 frases. Quando o cliente pedir troca, passe para a equipe.\",\n \"max_output_tokens\": 2048,\n \"model\": {\n \"openAI\": \"gpt-6-luna\",\n \"gemini\": \"models/gemini-3.5-flash-lite\",\n \"claude\": \"claude-haiku-4-5-20251001\",\n \"xAI\": \"grok-4.3\",\n \"deepseek\": \"deepseek-v4-flash\",\n },\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'prompt' => 'Você é a Bia, atendente da Loja Exemplo. Responda em português, em até 3 frases. Quando o cliente pedir troca, passe para a equipe.',\n 'max_output_tokens' => 2048,\n 'model' => [\n 'openAI' => 'gpt-6-luna',\n 'gemini' => 'models/gemini-3.5-flash-lite',\n 'claude' => 'claude-haiku-4-5-20251001',\n 'xAI' => 'grok-4.3',\n 'deepseek' => 'deepseek-v4-flash',\n ],\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/agentes-de-ia/atualizar-agente-de-ia/" } } }, "/agents/functions": { "get": { "operationId": "getAIFunctions", "summary": "Listar funções dos agentes", "description": "Lista as **Funções de IA** da conta (AI Hub › **Ferramentas de IA**): as tarefas que o agente executa durante a conversa, como coletar dados e acionar um fluxo. Cada função é ligada ao agente na lista **Ferramentas de IA** do editor dele. Veja [Funções de IA: coletar dados e acionar fluxos](https://help.nextags.com.br/tutoriais/ia/funcoes-do-agente/).", "tags": [ "Agentes de IA" ], "responses": { "200": { "description": "As funções, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "O ID da função." }, "name": { "type": "string", "description": "O **Nome** da função, como `agendar_horario`." }, "created_by": { "type": "integer", "description": "O ID do administrador que criou." }, "created_at": { "type": "string", "format": "date-time", "description": "A data de criação, em UTC." } } }, "description": "A lista de funções." } } }, "example": { "data": [ { "id": 5101, "name": "agendar_horario", "created_by": 10001, "created_at": "2026-09-15 13:40:00" } ] } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/agents/functions\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/agents/functions', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/agents/functions\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/agentes-de-ia/listar-funcoes-dos-agentes/" } } }, "/agents/mcp": { "get": { "operationId": "getAIMCPs", "summary": "Listar servidores MCP", "description": "Lista os **Servidores MCP** da conta (AI Hub › **Ferramentas de IA**): os sistemas externos que o agente consulta pelo protocolo MCP, como o estoque de uma loja. A aba aparece com a OpenAI, o xAI, o Claude ou o Gemini conectados. Veja [Servidores MCP no agente](https://help.nextags.com.br/tutoriais/ia/mcp-no-agente/).", "tags": [ "Agentes de IA" ], "responses": { "200": { "description": "Os servidores, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "O ID do servidor." }, "name": { "type": "string", "description": "O **Nome** do servidor, como `estoque_loja`." }, "created_by": { "type": "integer", "description": "O ID do administrador que criou." }, "created_at": { "type": "string", "format": "date-time", "description": "A data de criação, em UTC." } } }, "description": "A lista de servidores MCP." } } }, "example": { "data": [ { "id": 5201, "name": "estoque_loja", "created_by": 10001, "created_at": "2026-09-20 11:00:00" } ] } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/agents/mcp\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/agents/mcp', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/agents/mcp\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/agentes-de-ia/listar-servidores-mcp/" } } }, "/agents/files": { "get": { "operationId": "getAIFiles", "summary": "Listar arquivos dos agentes", "description": "Lista os **Arquivos** da conta (AI Hub › **Ferramentas de IA**): a base de conhecimento que o agente consulta para responder. A aba **Arquivos** só aparece com a OpenAI conectada. Veja [Arquivos: a base de conhecimento do agente](https://help.nextags.com.br/tutoriais/ia/base-de-conhecimento/).", "tags": [ "Agentes de IA" ], "responses": { "200": { "description": "Os arquivos, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "O ID do arquivo." }, "name": { "type": "string", "description": "O nome do arquivo." }, "size": { "type": "number", "description": "O tamanho do arquivo." }, "url": { "type": "string", "description": "O endereço do arquivo." }, "created_by": { "type": "integer", "description": "O ID do administrador que criou." }, "created_at": { "type": "string", "format": "date-time", "description": "A data de criação, em UTC." } } }, "description": "A lista de arquivos." } } }, "example": { "data": [ { "id": 5301, "name": "politica-de-trocas.pdf", "size": 248000, "url": "https://exemplo.com.br/arquivos/politica-de-trocas.pdf", "created_by": 10001, "created_at": "2026-09-16 10:00:00" } ] } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/agents/files\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/agents/files', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/agents/files\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/agentes-de-ia/listar-arquivos-dos-agentes/" } } }, "/accounts/templates/{template_id}/install": { "post": { "operationId": "installTemplate", "summary": "Instalar modelo na conta", "description": "Instala um modelo de **Templates** na conta dona da chave de API, sem abrir o link de instalação. O ID e a chave saem do link que o **Obter Link** copia, em **Ferramentas** › **Templates** › **⋮**: ele termina em `store/template?id=9001&key=b7Xk29QpLm4R`, e o `id` vai no caminho e o `key` vai em `template_key`. No app, a conta que criou o modelo não pode instalá-lo.", "tags": [ "Fluxos e modelos" ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "description": "O ID do modelo: o `id` do link de instalação.", "schema": { "type": "integer" }, "example": 9001 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "template_key": { "type": "string", "description": "A chave do modelo: o `key` do link de instalação.", "examples": [ "b7Xk29QpLm4R" ] } }, "required": [ "template_key" ] }, "example": { "template_key": "b7Xk29QpLm4R" } } } }, "responses": { "200": { "description": "O modelo foi instalado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando o modelo foi instalado." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/accounts/templates/9001/install\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"template_key\": \"b7Xk29QpLm4R\"\n }'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/templates/9001/install', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n template_key: 'b7Xk29QpLm4R',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/accounts/templates/9001/install\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n json={\n \"template_key\": \"b7Xk29QpLm4R\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'template_key' => 'b7Xk29QpLm4R',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/fluxos/instalar-modelo-na-conta/" } } }, "/accounts/templates/{template_id}/generateSingleUseLink": { "post": { "operationId": "generateTemplateLink", "summary": "Gerar link de uso único do modelo", "description": "Gera um link de instalação do modelo que vale para um uso só. Use para entregar o modelo a uma pessoa sem passar o link fixo do **Obter Link**. O `template_id` é o `id` do link de instalação: veja [Instalar modelo na conta](https://docs.nextags.com.br/referencia/fluxos/instalar-modelo-na-conta/).", "tags": [ "Fluxos e modelos" ], "parameters": [ { "name": "template_id", "in": "path", "required": true, "description": "O ID do modelo: o `id` do link de instalação.", "schema": { "type": "integer" }, "example": 9001 } ], "responses": { "200": { "description": "O link gerado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "link": { "type": "string", "description": "O link de instalação, de uso único." } } }, "example": { "link": "https://app.nextagsai.com.br/store/template?id=9001&key=Q4mZ81xTr6Wd" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/accounts/templates/9001/generateSingleUseLink\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/accounts/templates/9001/generateSingleUseLink', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/accounts/templates/9001/generateSingleUseLink\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/fluxos/gerar-link-de-uso-unico-do-modelo/" } } }, "/calendars": { "get": { "operationId": "getCalendars", "summary": "Listar calendários", "description": "Lista os calendários da conta, com o ID, o nome e a duração de cada um. A API não lista os agendamentos: eles ficam na aba **Agendamentos** ([Ver e cancelar agendamentos](https://help.nextags.com.br/tutoriais/agenda/ver-agendamentos/)).", "tags": [ "Agenda" ], "responses": { "200": { "description": "Os calendários, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Calendar" }, "maxItems": 100, "description": "A lista de calendários (até 100)." } } }, "example": { "data": [ { "id": 8001, "name": "Avaliação gratuita", "duration": 30, "created_by": 10001, "created_at": "2026-08-01 12:00:00" }, { "id": 8002, "name": "Reunião de implantação", "duration": 60, "created_by": 10001, "created_at": "2026-08-12 15:30:00" } ] } } } }, "400": { "description": "Parâmetros inválidos." }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/calendars\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/calendars', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/calendars\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/agenda/listar-calendarios/" } } }, "/calendars/{calendar_id}": { "get": { "operationId": "getCalendarById", "summary": "Consultar calendário", "description": "Devolve um calendário pelo ID: o nome, a duração de cada agendamento, quem criou e quando. Para usar o calendário numa conversa, veja [Agendar pela conversa](https://help.nextags.com.br/tutoriais/agenda/agendar-pelo-fluxo/).", "tags": [ "Agenda" ], "parameters": [ { "name": "calendar_id", "in": "path", "required": true, "description": "O ID do calendário (veja [Listar calendários](https://docs.nextags.com.br/referencia/agenda/listar-calendarios/)).", "schema": { "type": "integer" }, "example": 8001 } ], "responses": { "200": { "description": "O calendário.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Calendar" }, "example": { "id": 8001, "name": "Avaliação gratuita", "duration": 30, "created_by": 10001, "created_at": "2026-08-01 12:00:00" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/calendars/8001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/calendars/8001', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/calendars/8001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/agenda/consultar-calendario/" } } }, "/contacts/{contact_id}/send/products": { "post": { "operationId": "sendProduct", "summary": "Enviar produtos ao contato", "description": "Manda ao contato uma mensagem com um ou mais produtos do E-commerce, como o **Enviar Produtos** da Caixa de Entrada. Veja [Enviar produtos na conversa](https://help.nextags.com.br/tutoriais/ecommerce/enviar-produtos-na-conversa/).\n\nNo WhatsApp, no Instagram e no Messenger, a mensagem só chega dentro da [janela de 24 horas](https://help.nextags.com.br/tutoriais/canais/janela-de-24-horas/).", "tags": [ "E-commerce" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato.", "schema": { "type": "integer" }, "example": 123456789 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": [ "integer", "string", "array" ], "description": "O produto ou os produtos: um ID (`6001`), uma lista de IDs (`[6001, 6002]`) ou IDs separados por vírgula (`\"6001,6002\"`).", "items": {} } }, "required": [ "product_id" ] }, "example": { "product_id": [ 6001, 6002 ] } } } }, "responses": { "200": { "description": "O envio foi aceito." }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/contacts/123456789/send/products\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"product_id\": [\n 6001,\n 6002\n ]\n }'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/send/products', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n product_id: [6001, 6002],\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/contacts/123456789/send/products\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n json={\n \"product_id\": [6001, 6002],\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'product_id' => [6001, 6002],\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ecommerce/enviar-produtos-ao-contato/" } } }, "/contacts/{contact_id}/cart": { "get": { "operationId": "getUserCart", "summary": "Consultar carrinho", "description": "Devolve o carrinho do contato: os itens, a quantidade de cada um, o cupom e os totais. Os totais vêm em centavos; o `price` de cada item, não.", "tags": [ "E-commerce" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato.", "schema": { "type": "integer" }, "example": 123456789 } ], "responses": { "200": { "description": "O carrinho.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" }, "example": { "order_id": "PED-1001", "page_id": 123456, "user_id": 123456789, "currency": "BRL", "total": 8082, "subtotal": 8980, "total_items": 2, "coupon_discount": 898, "coupon": "BEMVINDO10", "line_items": [ { "id": 6001, "name": "Camiseta Básica Preta", "img": "https://exemplo.com.br/produtos/camiseta-preta.jpg", "price": 49.9, "amount": 1, "descr_min": "Camiseta 100% algodão, gola redonda.", "manufacturer": 0, "variant": "M", "user_msg": "" }, { "id": 6002, "name": "Boné Aba Curva", "img": "https://exemplo.com.br/produtos/bone.jpg", "price": 39.9, "amount": 1, "descr_min": "Boné ajustável de algodão.", "manufacturer": 0, "variant": "", "user_msg": "Embrulhar para presente." } ], "contact": { "id": 123456789, "page_id": 123456, "first_name": "Ana", "last_name": "Souza", "channel": 5, "profile_pic": "https://exemplo.com.br/fotos/ana.jpg", "locale": "pt_BR", "gender": 0, "timezone": -3, "last_sent": 1792933200000, "last_delivered": 1792933202000, "last_seen": 1792933500000, "last_interaction": 1792933560000, "subscribed_date": "2026-03-10 14:22:00", "subscribed": 1, "tags": [ { "id": 2001, "name": "cliente-vip" } ], "custom_fields": [ { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" } ] } } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/contacts/123456789/cart\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/cart', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/contacts/123456789/cart\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ecommerce/consultar-carrinho/" } }, "delete": { "operationId": "clearUserCart", "summary": "Esvaziar carrinho", "description": "Tira todos os itens do carrinho do contato, como a operação **Limpar Carrinho de Compras** da ação **Ecommerce** dos fluxos.", "tags": [ "E-commerce" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato.", "schema": { "type": "integer" }, "example": 123456789 } ], "responses": { "200": { "description": "O carrinho ficou vazio.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando deu certo." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X DELETE \"https://app.nextagsai.com.br/api/contacts/123456789/cart\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/cart', {\n method: 'DELETE',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.delete(\n \"https://app.nextagsai.com.br/api/contacts/123456789/cart\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'DELETE',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ecommerce/esvaziar-carrinho/" } } }, "/contacts/{contact_id}/pay/{order_id}": { "post": { "operationId": "payOrder", "summary": "Marcar pedido como pago", "description": "Marca um pedido como pago, quando o contato pagou fora da NexTags (Pix, link de pagamento, na loja). O valor recebido precisa cobrir o total do pedido. O corpo vai em formulário (`application/x-www-form-urlencoded`). Veja [Receber pagamentos no e-commerce](https://help.nextags.com.br/tutoriais/ecommerce/pagamentos/).\n\nO `amount_received` vai em centavos: R$ 80,82 = `8082`.", "tags": [ "E-commerce" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato.", "schema": { "type": "integer" }, "example": 123456789 }, { "name": "order_id", "in": "path", "required": true, "description": "O ID do pedido (texto). Ele vem em `order_id`, no carrinho e no pedido.", "schema": { "type": "string" }, "example": "PED-1001" } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "amount_received": { "type": "integer", "description": "O valor que o contato pagou, em centavos (`8082` = R$ 80,82)." } }, "required": [ "amount_received" ] }, "example": { "amount_received": 8082 } } } }, "responses": { "200": { "description": "O pedido foi marcado como pago.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando deu certo." } } }, "example": { "success": true } } } }, "400": { "description": "O `amount_received` é menor que o total do pedido." }, "401": { "$ref": "#/components/responses/ChaveInvalida" }, "402": { "description": "O checkout falhou, e o contato recebeu uma mensagem explicando por quê." }, "404": { "description": "O pedido não existe para este contato." } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/contacts/123456789/pay/PED-1001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'amount_received=8082'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/pay/PED-1001', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n amount_received: 8082,\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/contacts/123456789/pay/PED-1001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"amount_received\": 8082,\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'amount_received' => 8082,\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ecommerce/marcar-pedido-como-pago/" } } }, "/contacts/{contact_id}/order/{order_id}": { "get": { "operationId": "getUserOrder", "summary": "Consultar pedido", "description": "Devolve um pedido do contato, no mesmo formato do carrinho: os itens, o cupom e os totais em centavos (menos o `price` de cada item). Veja [Pedidos, cupons e vendedores](https://help.nextags.com.br/tutoriais/ecommerce/pedidos-cupons-e-vendedores/).", "tags": [ "E-commerce" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato.", "schema": { "type": "integer" }, "example": 123456789 }, { "name": "order_id", "in": "path", "required": true, "description": "O ID do pedido (texto). Ele vem em `order_id`, no carrinho e no pedido.", "schema": { "type": "string" }, "example": "PED-1001" } ], "responses": { "200": { "description": "O pedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" }, "example": { "order_id": "PED-1001", "page_id": 123456, "user_id": 123456789, "currency": "BRL", "total": 8082, "subtotal": 8980, "total_items": 2, "coupon_discount": 898, "coupon": "BEMVINDO10", "line_items": [ { "id": 6001, "name": "Camiseta Básica Preta", "img": "https://exemplo.com.br/produtos/camiseta-preta.jpg", "price": 49.9, "amount": 1, "descr_min": "Camiseta 100% algodão, gola redonda.", "manufacturer": 0, "variant": "M", "user_msg": "" }, { "id": 6002, "name": "Boné Aba Curva", "img": "https://exemplo.com.br/produtos/bone.jpg", "price": 39.9, "amount": 1, "descr_min": "Boné ajustável de algodão.", "manufacturer": 0, "variant": "", "user_msg": "Embrulhar para presente." } ], "contact": { "id": 123456789, "page_id": 123456, "first_name": "Ana", "last_name": "Souza", "channel": 5, "profile_pic": "https://exemplo.com.br/fotos/ana.jpg", "locale": "pt_BR", "gender": 0, "timezone": -3, "last_sent": 1792933200000, "last_delivered": 1792933202000, "last_seen": 1792933500000, "last_interaction": 1792933560000, "subscribed_date": "2026-03-10 14:22:00", "subscribed": 1, "tags": [ { "id": 2001, "name": "cliente-vip" } ], "custom_fields": [ { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" } ] } } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ecommerce/consultar-pedido/" } }, "post": { "operationId": "changeOrder", "summary": "Alterar pedido", "description": "Muda a situação de um pedido e os dados de entrega. A situação vai em `status`, pelo código: `6` **Aceito** (em processamento), `7` **Entregando** (enviado), `10` **Concluído** e `13` **Cancelado**. O **Não processado** (código 4) não pode ser escolhido aqui. Veja [Pedidos, cupons e vendedores](https://help.nextags.com.br/tutoriais/ecommerce/pedidos-cupons-e-vendedores/).", "tags": [ "E-commerce" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato.", "schema": { "type": "integer" }, "example": 123456789 }, { "name": "order_id", "in": "path", "required": true, "description": "O ID do pedido (texto). Ele vem em `order_id`, no carrinho e no pedido.", "schema": { "type": "string" }, "example": "PED-1001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "A situação nova: `6` Aceito, `7` Entregando, `10` Concluído ou `13` Cancelado.", "enum": [ 6, 7, 10, 13 ] }, "name": { "type": "string", "description": "O nome de quem recebe a entrega." }, "phone": { "type": "string", "description": "O telefone para a entrega." }, "email": { "type": "string", "description": "O e-mail para a entrega." }, "country": { "type": "string", "description": "O país da entrega." }, "state": { "type": "string", "description": "O estado." }, "city": { "type": "string", "description": "A cidade." }, "zip_code": { "type": "string", "description": "O CEP." }, "address": { "type": "string", "description": "O endereço de entrega." }, "street_1": { "type": "string", "description": "A primeira linha do endereço: rua e número." }, "street_2": { "type": "string", "description": "A segunda linha do endereço, como o complemento." }, "note": { "type": "string", "description": "Uma observação sobre o pedido." } } }, "example": { "status": 7, "name": "Ana Souza", "phone": "5511988776655", "city": "São Paulo", "state": "SP", "zip_code": "01310-100", "street_1": "Av. Paulista, 1578", "street_2": "Apto 45", "note": "Entregar na portaria." } } } }, "responses": { "200": { "description": "O pedido foi alterado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando deu certo." } } }, "example": { "success": true } } } }, "400": { "description": "O `status` não é 6, 7, 10 nem 13." }, "401": { "$ref": "#/components/responses/ChaveInvalida" }, "402": { "description": "O pedido já está nessa situação." }, "404": { "description": "O pedido não existe para este contato." } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"status\": 7,\n \"name\": \"Ana Souza\",\n \"phone\": \"5511988776655\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"zip_code\": \"01310-100\",\n \"street_1\": \"Av. Paulista, 1578\",\n \"street_2\": \"Apto 45\",\n \"note\": \"Entregar na portaria.\"\n }'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n status: 7,\n name: 'Ana Souza',\n phone: '5511988776655',\n city: 'São Paulo',\n state: 'SP',\n zip_code: '01310-100',\n street_1: 'Av. Paulista, 1578',\n street_2: 'Apto 45',\n note: 'Entregar na portaria.',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/contacts/123456789/order/PED-1001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n json={\n \"status\": 7,\n \"name\": \"Ana Souza\",\n \"phone\": \"5511988776655\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"zip_code\": \"01310-100\",\n \"street_1\": \"Av. Paulista, 1578\",\n \"street_2\": \"Apto 45\",\n \"note\": \"Entregar na portaria.\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'status' => 7,\n 'name' => 'Ana Souza',\n 'phone' => '5511988776655',\n 'city' => 'São Paulo',\n 'state' => 'SP',\n 'zip_code' => '01310-100',\n 'street_1' => 'Av. Paulista, 1578',\n 'street_2' => 'Apto 45',\n 'note' => 'Entregar na portaria.',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ecommerce/alterar-pedido/" } } }, "/contacts/{contact_id}/cart/{product_id}": { "post": { "operationId": "addProductCart", "summary": "Adicionar produto ao carrinho", "description": "Põe um produto no carrinho do contato, com a quantidade. O corpo vai em formulário (`application/x-www-form-urlencoded`), não em JSON.", "tags": [ "E-commerce" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato.", "schema": { "type": "integer" }, "example": 123456789 }, { "name": "product_id", "in": "path", "required": true, "description": "O ID do produto.", "schema": { "type": "integer" }, "example": 6001 } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "quantity": { "type": "integer", "description": "Quantas unidades do produto." } }, "required": [ "quantity" ] }, "example": { "quantity": 2 } } } }, "responses": { "200": { "description": "O produto entrou no carrinho.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando deu certo." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/contacts/123456789/cart/6001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'quantity=2'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/cart/6001', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n quantity: 2,\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/contacts/123456789/cart/6001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"quantity\": 2,\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'quantity' => 2,\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ecommerce/adicionar-produto-ao-carrinho/" } }, "delete": { "operationId": "removeProductCart", "summary": "Remover produto do carrinho", "description": "Tira um produto do carrinho do contato.", "tags": [ "E-commerce" ], "parameters": [ { "name": "contact_id", "in": "path", "required": true, "description": "O ID do contato.", "schema": { "type": "integer" }, "example": 123456789 }, { "name": "product_id", "in": "path", "required": true, "description": "O ID do produto.", "schema": { "type": "integer" }, "example": 6001 } ], "responses": { "200": { "description": "O produto saiu do carrinho.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando deu certo." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X DELETE \"https://app.nextagsai.com.br/api/contacts/123456789/cart/6001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/contacts/123456789/cart/6001', {\n method: 'DELETE',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.delete(\n \"https://app.nextagsai.com.br/api/contacts/123456789/cart/6001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'DELETE',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ecommerce/remover-produto-do-carrinho/" } } }, "/products/{product_id}": { "get": { "operationId": "getProductById", "summary": "Consultar produto", "description": "Devolve um produto do E-commerce: o nome, os preços, o estoque, a categoria, a descrição curta e a imagem. Os preços vêm na moeda da loja, não em centavos. Veja [Cadastrar produtos](https://help.nextags.com.br/tutoriais/ecommerce/cadastrar-produtos/).", "tags": [ "E-commerce" ], "parameters": [ { "name": "product_id", "in": "path", "required": true, "description": "O ID do produto.", "schema": { "type": "integer" }, "example": 6001 } ], "responses": { "200": { "description": "O produto.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "id": 6001, "name": "Camiseta Básica Preta", "price": 49.9, "sale_price": 39.9, "category_id": 6101, "category_name": "Camisetas", "stock": 120, "short_description": "Camiseta 100% algodão, gola redonda.", "image": "https://exemplo.com.br/produtos/camiseta-preta.jpg", "created_at": "2026-07-10 18:00:00" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/products/6001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/products/6001', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/products/6001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ecommerce/consultar-produto/" } }, "post": { "operationId": "updateProduct", "summary": "Atualizar produto", "description": "Muda o preço, o estoque e o **Ativo** de um produto, para a loja acompanhar o seu sistema de estoque. Os três campos são opcionais. Veja [Cadastrar produtos](https://help.nextags.com.br/tutoriais/ecommerce/cadastrar-produtos/).", "tags": [ "E-commerce" ], "parameters": [ { "name": "product_id", "in": "path", "required": true, "description": "O ID do produto.", "schema": { "type": "integer" }, "example": 6001 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "price": { "type": "number", "description": "O preço novo, na moeda da loja. Não é em centavos: `44.9` = R$ 44,90." }, "active": { "type": "boolean", "description": "O **Ativo** da lista de produtos: `true` deixa o produto à venda; `false` tira da venda." }, "stock": { "type": "integer", "description": "O estoque novo (a coluna **Inventário** da lista de produtos)." } } }, "example": { "price": 44.9, "stock": 85, "active": true } } } }, "responses": { "200": { "description": "O produto foi atualizado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando deu certo." }, "updated": { "type": "boolean", "description": "Se algum dado do produto mudou." } } }, "example": { "success": true, "updated": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/products/6001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"price\": 44.9,\n \"stock\": 85,\n \"active\": true\n }'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/products/6001', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n price: 44.9,\n stock: 85,\n active: true,\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/products/6001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n json={\n \"price\": 44.9,\n \"stock\": 85,\n \"active\": True,\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'price' => 44.9,\n 'stock' => 85,\n 'active' => true,\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ecommerce/atualizar-produto/" } } }, "/broadcasts": { "get": { "operationId": "getBroadcasts", "summary": "Listar disparos", "description": "Lista os Broadcasts da conta, com o nome, o estado e as datas de cada um. Não há chamada para criar um Broadcast: ele é criado na tela, em **Broadcasts** › **Enviar** ([Criar um Broadcast](https://help.nextags.com.br/tutoriais/disparos/criar-disparo/)).", "tags": [ "Disparos" ], "responses": { "200": { "description": "Os Broadcasts, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Broadcast" }, "maxItems": 100, "description": "A lista de Broadcasts (até 100)." } } }, "example": { "data": [ { "id": 7001, "name": "Black Friday - clientes VIP", "status": "SENT", "sent_at": "2026-10-20 15:00:00", "created_by": 10001, "created_at": "2026-10-20 14:45:00" }, { "id": 7002, "name": "Lançamento da coleção de verão", "status": "SENT", "sent_at": "2026-10-05 13:00:00", "created_by": 10001, "created_at": "2026-10-05 12:40:00" } ] } } } }, "400": { "description": "Parâmetros inválidos." }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/broadcasts\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/broadcasts', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/broadcasts\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/disparos/listar-disparos/" } } }, "/broadcasts/{broadcast_id}": { "get": { "operationId": "getBroadcastById", "summary": "Consultar disparo", "description": "Devolve um Broadcast pelo ID, com o estado: use para acompanhar um envio até `SENT`. Os números de entregues, vistos, cliques e falhas não vêm aqui: ficam na lista **Broadcasts** ([Resultados: entregues, abertos, clicados e falhas](https://help.nextags.com.br/tutoriais/disparos/resultados-e-custos/)).", "tags": [ "Disparos" ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "description": "O ID do Broadcast (veja [Listar disparos](https://docs.nextags.com.br/referencia/disparos/listar-disparos/)).", "schema": { "type": "integer" }, "example": 7001 } ], "responses": { "200": { "description": "O Broadcast.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Broadcast" }, "example": { "id": 7001, "name": "Black Friday - clientes VIP", "status": "SENT", "sent_at": "2026-10-20 15:00:00", "created_by": 10001, "created_at": "2026-10-20 14:45:00" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" }, "404": { "description": "O Broadcast não existe nesta conta." } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \"https://app.nextagsai.com.br/api/broadcasts/7001\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/broadcasts/7001', {\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.get(\n \"https://app.nextagsai.com.br/api/broadcasts/7001\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/disparos/consultar-disparo/" } } }, "/broadcasts/{broadcast_id}/resend": { "post": { "operationId": "resendBroadcastById", "summary": "Reenviar disparo", "description": "Manda o Broadcast de novo, como o **Reenviar** do menu da lista, que aparece em qualquer estado. Antes de reenviar, pense em quem já recebeu: mensagem repetida aumenta os bloqueios e as denúncias. Veja [Reenviar, cancelar e exportar um Broadcast](https://help.nextags.com.br/tutoriais/disparos/reenviar-e-cancelar/).", "tags": [ "Disparos" ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "description": "O ID do Broadcast (veja [Listar disparos](https://docs.nextags.com.br/referencia/disparos/listar-disparos/)).", "schema": { "type": "integer" }, "example": 7001 } ], "responses": { "200": { "description": "O reenvio foi aceito.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando deu certo." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/broadcasts/7001/resend\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/broadcasts/7001/resend', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/broadcasts/7001/resend\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/disparos/reenviar-disparo/" } } }, "/broadcasts/{broadcast_id}/cancel": { "post": { "operationId": "cancelBroadcastById", "summary": "Cancelar disparo", "description": "Para um Broadcast que ainda não saiu, como o **Cancelar** do menu da lista. Na tela, o **Cancelar** só aparece enquanto o Broadcast está **Agendado**, **Pendente** ou no começo do envio; depois disso, não dá mais para parar. Cancelado, o estado vira `CANCELLED`. Veja [Reenviar, cancelar e exportar um Broadcast](https://help.nextags.com.br/tutoriais/disparos/reenviar-e-cancelar/).", "tags": [ "Disparos" ], "parameters": [ { "name": "broadcast_id", "in": "path", "required": true, "description": "O ID do Broadcast (veja [Listar disparos](https://docs.nextags.com.br/referencia/disparos/listar-disparos/)).", "schema": { "type": "integer" }, "example": 7001 } ], "responses": { "200": { "description": "O Broadcast foi cancelado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "`true` quando deu certo." } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/broadcasts/7001/cancel\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\"" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/broadcasts/7001/cancel', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/broadcasts/7001/cancel\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/disparos/cancelar-disparo/" } } }, "/tools/format_number": { "post": { "operationId": "format_number", "summary": "Formatar número", "description": "Formata um número com as casas decimais e os separadores que você escolher: `1995.5` vira `1.995,50`. Use para mostrar um valor em reais numa mensagem.", "tags": [ "Ferramentas" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "number": { "type": "number", "description": "O número, com ponto decimal (`1995.5`)." }, "decimals": { "type": "integer", "description": "Quantas casas decimais, como `2`." }, "decimal_separator": { "type": "string", "description": "O separador decimal, como `,`." }, "thousands_separator": { "type": "string", "description": "O separador de milhar, como `.`." } }, "required": [ "number" ] }, "example": { "number": 1995.5, "decimals": 2, "decimal_separator": ",", "thousands_separator": "." } } } }, "responses": { "200": { "description": "O número formatado, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": [ "string", "number" ], "description": "O número formatado. Com separadores, vem como texto." } } }, "example": { "data": "1.995,50" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/tools/format_number\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'number=1995.5' \\\n --data-urlencode 'decimals=2' \\\n --data-urlencode 'decimal_separator=,' \\\n --data-urlencode 'thousands_separator=.'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/tools/format_number', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n number: 1995.5,\n decimals: 2,\n decimal_separator: ',',\n thousands_separator: '.',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/tools/format_number\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"number\": 1995.5,\n \"decimals\": 2,\n \"decimal_separator\": \",\",\n \"thousands_separator\": \".\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'number' => 1995.5,\n 'decimals' => 2,\n 'decimal_separator' => ',',\n 'thousands_separator' => '.',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ferramentas/formatar-numero/" } } }, "/tools/split": { "post": { "operationId": "split", "summary": "Dividir um texto em partes", "description": "Divide um texto em partes a cada separador e devolve a lista e o total: `Camiseta,Boné,Meia` com o separador `,` vira três partes. No **Mapeamento de resposta**, `$.data[0]` é a primeira parte.", "tags": [ "Ferramentas" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "O texto." }, "delimiter": { "type": "string", "description": "O separador, como `,` ou `;`." } }, "required": [ "text", "delimiter" ] }, "example": { "text": "Camiseta,Boné,Meia", "delimiter": "," } } } }, "responses": { "200": { "description": "As partes, em `data`, e o total.", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Quantas partes." }, "data": { "type": "array", "items": { "type": "string" }, "description": "As partes, na ordem do texto." } } }, "example": { "total": 3, "data": [ "Camiseta", "Boné", "Meia" ] } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/tools/split\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'text=Camiseta,Boné,Meia' \\\n --data-urlencode 'delimiter=,'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/tools/split', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n text: 'Camiseta,Boné,Meia',\n delimiter: ',',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/tools/split\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"text\": \"Camiseta,Boné,Meia\",\n \"delimiter\": \",\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'text' => 'Camiseta,Boné,Meia',\n 'delimiter' => ',',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ferramentas/dividir-um-texto-em-partes/" } } }, "/tools/urlencode": { "post": { "operationId": "urlencode", "summary": "Codificar texto para URL", "description": "Codifica um texto para usar numa URL, no formato de formulário: o espaço vira `+`, e os acentos e os outros caracteres especiais viram `%XX`. Use no valor de um parâmetro, depois do `?`. Para `%20` no lugar do `+`, use [Codificar para URL (RFC 3986)](https://docs.nextags.com.br/referencia/ferramentas/codificar-para-url-rfc-3986/).", "tags": [ "Ferramentas" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "O texto." } }, "required": [ "text" ] }, "example": { "text": "Olá, quero o pedido PED-1001" } } } }, "responses": { "200": { "description": "O texto codificado, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "O texto codificado." } } }, "example": { "data": "Ol%C3%A1%2C+quero+o+pedido+PED-1001" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/tools/urlencode\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'text=Olá, quero o pedido PED-1001'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/tools/urlencode', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n text: 'Olá, quero o pedido PED-1001',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/tools/urlencode\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"text\": \"Olá, quero o pedido PED-1001\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'text' => 'Olá, quero o pedido PED-1001',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ferramentas/codificar-texto-para-url/" } } }, "/tools/urldecode": { "post": { "operationId": "urldecode", "summary": "Decodificar texto de URL", "description": "Desfaz a codificação de URL: troca as sequências `%XX` pelos caracteres e o `+` por espaço. Use para ler um valor que chegou codificado, como um parâmetro de link.", "tags": [ "Ferramentas" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "O texto codificado." } }, "required": [ "text" ] }, "example": { "text": "Ol%C3%A1%2C+quero+o+pedido+PED-1001" } } } }, "responses": { "200": { "description": "O texto decodificado, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "O texto decodificado." } } }, "example": { "data": "Olá, quero o pedido PED-1001" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/tools/urldecode\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'text=Ol%C3%A1%2C+quero+o+pedido+PED-1001'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/tools/urldecode', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n text: 'Ol%C3%A1%2C+quero+o+pedido+PED-1001',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/tools/urldecode\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"text\": \"Ol%C3%A1%2C+quero+o+pedido+PED-1001\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'text' => 'Ol%C3%A1%2C+quero+o+pedido+PED-1001',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ferramentas/decodificar-texto-de-url/" } } }, "/tools/rawurlencode": { "post": { "operationId": "rawurlencode", "summary": "Codificar para URL (RFC 3986)", "description": "Codifica um texto para URL pela RFC 3986: o espaço vira `%20`, e não `+`. Use quando o outro sistema não aceita o `+`, como num trecho do caminho da URL.", "tags": [ "Ferramentas" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "O texto." } }, "required": [ "text" ] }, "example": { "text": "Olá, quero o pedido PED-1001" } } } }, "responses": { "200": { "description": "O texto codificado, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "O texto codificado." } } }, "example": { "data": "Ol%C3%A1%2C%20quero%20o%20pedido%20PED-1001" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/tools/rawurlencode\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'text=Olá, quero o pedido PED-1001'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/tools/rawurlencode', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n text: 'Olá, quero o pedido PED-1001',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/tools/rawurlencode\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"text\": \"Olá, quero o pedido PED-1001\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'text' => 'Olá, quero o pedido PED-1001',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ferramentas/codificar-para-url-rfc-3986/" } } }, "/tools/rawurldecode": { "post": { "operationId": "rawurldecode", "summary": "Decodificar de URL (RFC 3986)", "description": "Desfaz a codificação da RFC 3986: troca as sequências `%XX` pelos caracteres. O `+` continua `+`; para virar espaço, use [Decodificar texto de URL](https://docs.nextags.com.br/referencia/ferramentas/decodificar-texto-de-url/).", "tags": [ "Ferramentas" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "O texto codificado." } }, "required": [ "text" ] }, "example": { "text": "S%C3%A3o%20Paulo%20-%20SP" } } } }, "responses": { "200": { "description": "O texto decodificado, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "O texto decodificado." } } }, "example": { "data": "São Paulo - SP" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/tools/rawurldecode\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'text=S%C3%A3o%20Paulo%20-%20SP'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/tools/rawurldecode', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n text: 'S%C3%A3o%20Paulo%20-%20SP',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/tools/rawurldecode\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"text\": \"S%C3%A3o%20Paulo%20-%20SP\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'text' => 'S%C3%A3o%20Paulo%20-%20SP',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ferramentas/decodificar-de-url-rfc-3986/" } } }, "/tools/qrcode": { "post": { "operationId": "qrcode", "summary": "Gerar QR Code", "description": "Gera um QR Code com o texto ou o link que você mandar e devolve o endereço da imagem, para enviar como imagem numa mensagem. Para o QR Code de um fluxo, a tela tem o [Gerador de Código QR](https://help.nextags.com.br/tutoriais/ferramentas/qr-code/).", "tags": [ "Ferramentas" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "O texto ou o link que vai no QR Code." } }, "required": [ "text" ] }, "example": { "text": "https://wa.me/5511988776655" } } } }, "responses": { "200": { "description": "O endereço da imagem, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "O endereço da imagem do QR Code." } } }, "example": { "data": "https://exemplo.com.br/qrcode.png" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/tools/qrcode\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'text=https://wa.me/5511988776655'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/tools/qrcode', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n text: 'https://wa.me/5511988776655',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/tools/qrcode\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"text\": \"https://wa.me/5511988776655\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'text' => 'https://wa.me/5511988776655',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ferramentas/gerar-qr-code/" } } }, "/tools/text_to_lower": { "post": { "operationId": "text_to_lower", "summary": "Converter texto para minúsculas", "description": "Passa o texto para letras minúsculas. Use para padronizar um e-mail antes de comparar, salvar ou gerar um hash.", "tags": [ "Ferramentas" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "O texto." } }, "required": [ "text" ] }, "example": { "text": "ANA@EXEMPLO.COM.BR" } } } }, "responses": { "200": { "description": "O texto em minúsculas, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "O texto em minúsculas." } } }, "example": { "data": "ana@exemplo.com.br" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/tools/text_to_lower\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'text=ANA@EXEMPLO.COM.BR'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/tools/text_to_lower', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n text: 'ANA@EXEMPLO.COM.BR',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/tools/text_to_lower\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"text\": \"ANA@EXEMPLO.COM.BR\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'text' => 'ANA@EXEMPLO.COM.BR',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ferramentas/converter-texto-para-minusculas/" } } }, "/tools/text_to_upper": { "post": { "operationId": "text_to_upper", "summary": "Converter texto para maiúsculas", "description": "Passa o texto para letras maiúsculas. Use para padronizar códigos, como o de um cupom ou de um pedido.", "tags": [ "Ferramentas" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "O texto." } }, "required": [ "text" ] }, "example": { "text": "bemvindo10" } } } }, "responses": { "200": { "description": "O texto em maiúsculas, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "O texto em maiúsculas." } } }, "example": { "data": "BEMVINDO10" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/tools/text_to_upper\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'text=bemvindo10'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/tools/text_to_upper', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n text: 'bemvindo10',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/tools/text_to_upper\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"text\": \"bemvindo10\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'text' => 'bemvindo10',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ferramentas/converter-texto-para-maiusculas/" } } }, "/tools/text_length": { "post": { "operationId": "text_length", "summary": "Contar os caracteres de um texto", "description": "Conta os caracteres de um texto. Use para conferir um dado antes de seguir, como o celular com DDI e DDD, que tem 13 dígitos no Brasil.", "tags": [ "Ferramentas" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "O texto." } }, "required": [ "text" ] }, "example": { "text": "5511988776655" } } } }, "responses": { "200": { "description": "O tamanho, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "integer", "description": "Quantos caracteres o texto tem." } } }, "example": { "data": 13 } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/tools/text_length\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'text=5511988776655'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/tools/text_length', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n text: '5511988776655',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/tools/text_length\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"text\": \"5511988776655\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'text' => '5511988776655',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ferramentas/contar-os-caracteres-de-um-texto/" } } }, "/tools/substring": { "post": { "operationId": "substring", "summary": "Recortar parte de um texto", "description": "Recorta um pedaço do texto: a partir da posição `offset` (o primeiro caractere é a posição 0), com `length` caracteres; sem `length`, vai até o fim. No celular `5511988776655`, o DDD está na posição 2, com 2 caracteres.", "tags": [ "Ferramentas" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "O texto." }, "offset": { "type": "integer", "description": "A posição onde o recorte começa, contando do 0." }, "length": { "type": "integer", "description": "Quantos caracteres recortar. Sem ele, vai até o fim do texto." } }, "required": [ "text", "offset" ] }, "example": { "text": "5511988776655", "offset": 2, "length": 2 } } } }, "responses": { "200": { "description": "O pedaço recortado, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "O pedaço recortado." } } }, "example": { "data": "11" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/tools/substring\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'text=5511988776655' \\\n --data-urlencode 'offset=2' \\\n --data-urlencode 'length=2'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/tools/substring', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n text: '5511988776655',\n offset: 2,\n length: 2,\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/tools/substring\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"text\": \"5511988776655\",\n \"offset\": 2,\n \"length\": 2,\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'text' => '5511988776655',\n 'offset' => 2,\n 'length' => 2,\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ferramentas/recortar-parte-de-um-texto/" } } }, "/tools/text_replace": { "post": { "operationId": "text_replace", "summary": "Substituir um texto", "description": "Troca, no texto, todas as vezes que um trecho aparece por outro: com `.` trocado por `,`, o preço `49.90` vira `49,90`. Para várias trocas de uma vez, use [Substituir vários textos](https://docs.nextags.com.br/referencia/ferramentas/substituir-varios-textos/).", "tags": [ "Ferramentas" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "O texto." }, "search": { "type": "string", "description": "O trecho a procurar." }, "replace": { "type": "string", "description": "O que entra no lugar." } }, "required": [ "text", "search", "replace" ] }, "example": { "text": "49.90", "search": ".", "replace": "," } } } }, "responses": { "200": { "description": "O texto com as trocas, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "O texto com as trocas." } } }, "example": { "data": "49,90" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/tools/text_replace\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'text=49.90' \\\n --data-urlencode 'search=.' \\\n --data-urlencode 'replace=,'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/tools/text_replace', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n text: '49.90',\n search: '.',\n replace: ',',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/tools/text_replace\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"text\": \"49.90\",\n \"search\": \".\",\n \"replace\": \",\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'text' => '49.90',\n 'search' => '.',\n 'replace' => ',',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ferramentas/substituir-um-texto/" } } }, "/tools/text_replaces": { "post": { "operationId": "text_replaces", "summary": "Substituir vários textos", "description": "Faz várias trocas de uma vez: cada item de `search` é trocado pelo item na mesma posição de `replace`. No formulário, cada item da lista vai num par próprio, com o nome seguido de colchetes: `search[]=...&search[]=...` (veja os exemplos de código).", "tags": [ "Ferramentas" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "O texto." }, "search": { "type": "array", "items": { "type": "string" }, "description": "Os trechos a procurar, na ordem." }, "replace": { "type": "array", "items": { "type": "string" }, "description": "O que entra no lugar de cada trecho, na mesma ordem de `search`." } }, "required": [ "text", "search", "replace" ] }, "example": { "text": "Olá, {nome}! Seu pedido {pedido} saiu para entrega.", "search": [ "{nome}", "{pedido}" ], "replace": [ "Ana", "PED-1001" ] } } } }, "responses": { "200": { "description": "O texto com as trocas, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "O texto com as trocas." } } }, "example": { "data": "Olá, Ana! Seu pedido PED-1001 saiu para entrega." } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/tools/text_replaces\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'text=Olá, {nome}! Seu pedido {pedido} saiu para entrega.' \\\n --data-urlencode 'search[]={nome}' \\\n --data-urlencode 'search[]={pedido}' \\\n --data-urlencode 'replace[]=Ana' \\\n --data-urlencode 'replace[]=PED-1001'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/tools/text_replaces', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams([\n [\n 'text',\n 'Olá, {nome}! Seu pedido {pedido} saiu para entrega.',\n ],\n ['search[]', '{nome}'],\n ['search[]', '{pedido}'],\n ['replace[]', 'Ana'],\n ['replace[]', 'PED-1001'],\n ]),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/tools/text_replaces\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"text\": \"Olá, {nome}! Seu pedido {pedido} saiu para entrega.\",\n \"search[]\": [\"{nome}\", \"{pedido}\"],\n \"replace[]\": [\"Ana\", \"PED-1001\"],\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'text' => 'Olá, {nome}! Seu pedido {pedido} saiu para entrega.',\n 'search' => ['{nome}', '{pedido}'],\n 'replace' => ['Ana', 'PED-1001'],\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ferramentas/substituir-varios-textos/" } } }, "/tools/get_url_parameters": { "post": { "operationId": "get_url_parameters", "summary": "Ler os parâmetros de uma URL", "description": "Lê os parâmetros de uma URL (o que vem depois do `?`) e devolve cada um com o seu valor. Use para pegar a origem de quem chegou por um link com UTM, como `utm_source` e `utm_campaign`.", "tags": [ "Ferramentas" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "A URL completa, com os parâmetros." } }, "required": [ "url" ] }, "example": { "url": "https://loja.exemplo.com.br/?utm_source=instagram&utm_campaign=black-friday&ref=ana" } } } }, "responses": { "200": { "description": "Os parâmetros, em `data`: um campo para cada parâmetro da URL, com o nome e o valor.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Os parâmetros da URL. Cada parâmetro vira um campo deste objeto, com o mesmo nome." } } }, "example": { "data": { "utm_source": "instagram", "utm_campaign": "black-friday", "ref": "ana" } } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/tools/get_url_parameters\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'url=https://loja.exemplo.com.br/?utm_source=instagram&utm_campaign=black-friday&ref=ana'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/tools/get_url_parameters', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n url: 'https://loja.exemplo.com.br/?utm_source=instagram&utm_campaign=black-friday&ref=ana',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/tools/get_url_parameters\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"url\": \"https://loja.exemplo.com.br/?utm_source=instagram&utm_campaign=black-friday&ref=ana\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'url' => 'https://loja.exemplo.com.br/?utm_source=instagram&utm_campaign=black-friday&ref=ana',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ferramentas/ler-os-parametros-de-uma-url/" } } }, "/tools/echo": { "post": { "operationId": "echo", "summary": "Devolver o JSON enviado (eco)", "description": "Devolve, igual, o JSON que você mandar. Serve para gerar mensagens dinâmicas na [requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/) do fluxo sem ter um servidor seu: monte no corpo o JSON de [mensagens e ações](https://docs.nextags.com.br/comecar/mensagens-e-acoes/), com as variáveis do contato, e a resposta traz esse JSON de volta. Veja [Requisição externa: o fluxo chama o seu sistema](https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo/).", "tags": [ "Ferramentas" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Mensagem" }, "description": "Por exemplo, as mensagens do conteúdo dinâmico. O eco aceita qualquer JSON e devolve igual: estes campos são só o uso mais comum." }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/Acao" }, "description": "Por exemplo, as ações do conteúdo dinâmico." } } }, "example": { "messages": [ { "message": { "text": "Oi, Ana! Seu pedido PED-1001 saiu para entrega." } } ], "actions": [ { "action": "add_tag", "tag_name": "cliente-vip" } ] } } } }, "responses": { "200": { "description": "O mesmo JSON que veio no corpo.", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Mensagem" }, "description": "Por exemplo, as mensagens do conteúdo dinâmico. O eco aceita qualquer JSON e devolve igual: estes campos são só o uso mais comum." }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/Acao" }, "description": "Por exemplo, as ações do conteúdo dinâmico." } } }, "example": { "messages": [ { "message": { "text": "Oi, Ana! Seu pedido PED-1001 saiu para entrega." } } ], "actions": [ { "action": "add_tag", "tag_name": "cliente-vip" } ] } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/tools/echo\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"messages\": [\n {\n \"message\": {\n \"text\": \"Oi, Ana! Seu pedido PED-1001 saiu para entrega.\"\n }\n }\n ],\n \"actions\": [\n {\n \"action\": \"add_tag\",\n \"tag_name\": \"cliente-vip\"\n }\n ]\n }'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/tools/echo', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n messages: [\n {\n message: {\n text: 'Oi, Ana! Seu pedido PED-1001 saiu para entrega.',\n },\n },\n ],\n actions: [\n {\n action: 'add_tag',\n tag_name: 'cliente-vip',\n },\n ],\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/tools/echo\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n json={\n \"messages\": [\n {\n \"message\": {\n \"text\": \"Oi, Ana! Seu pedido PED-1001 saiu para entrega.\",\n },\n },\n ],\n \"actions\": [\n {\n \"action\": \"add_tag\",\n \"tag_name\": \"cliente-vip\",\n },\n ],\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'messages' => [\n [\n 'message' => [\n 'text' => 'Oi, Ana! Seu pedido PED-1001 saiu para entrega.',\n ],\n ],\n ],\n 'actions' => [\n [\n 'action' => 'add_tag',\n 'tag_name' => 'cliente-vip',\n ],\n ],\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ferramentas/devolver-o-json-enviado-eco/" } } }, "/tools/hash": { "post": { "operationId": "hash", "summary": "Gerar um hash", "description": "Gera o hash de um texto com o algoritmo escolhido; sem `algo`, usa o SHA-256. Use, por exemplo, para mandar o e-mail do contato com hash SHA-256, como a API de Conversões da Meta pede (antes, passe o e-mail para minúsculas com [Converter texto para minúsculas](https://docs.nextags.com.br/referencia/ferramentas/converter-texto-para-minusculas/)).", "tags": [ "Ferramentas" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "O texto." }, "algo": { "type": "string", "description": "O algoritmo, como `sha256`, `sha1` ou `md5`. Sem ele, `sha256`.", "default": "sha256" } }, "required": [ "data" ] }, "example": { "data": "ana@exemplo.com.br", "algo": "sha256" } } } }, "responses": { "200": { "description": "O hash, em `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "O hash, em hexadecimal." } } }, "example": { "data": "9908ab973926622870fbcc257bf5c75e507d89d24698137563dab84b1e2cb423" } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/tools/hash\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'data=ana@exemplo.com.br' \\\n --data-urlencode 'algo=sha256'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/tools/hash', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n data: 'ana@exemplo.com.br',\n algo: 'sha256',\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/tools/hash\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"data\": \"ana@exemplo.com.br\",\n \"algo\": \"sha256\",\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'data' => 'ana@exemplo.com.br',\n 'algo' => 'sha256',\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ferramentas/gerar-um-hash/" } } }, "/tools/location_distance": { "post": { "operationId": "location_distance", "summary": "Calcular a distância entre duas coordenadas", "description": "Calcula a distância entre dois pontos de latitude e longitude, em metros e em milhas. Use para saber se o contato está na área de entrega ou para calcular o frete a partir da localização que ele mandou ([Pedir e enviar localização](https://help.nextags.com.br/tutoriais/fluxos/localizacao/)). Com uma chave da API do Google Maps em `googleMapsApiKey`, o cálculo é feito pelo Google Maps.", "tags": [ "Ferramentas" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "source_latitude": { "type": "number", "description": "A latitude do ponto de partida, com ponto decimal (`-23.5614`)." }, "source_longitude": { "type": "number", "description": "A longitude do ponto de partida (`-46.6559`)." }, "destination_latitude": { "type": "number", "description": "A latitude do destino." }, "destination_longitude": { "type": "number", "description": "A longitude do destino." }, "googleMapsApiKey": { "type": "string", "description": "Opcional: uma chave da API do Google Maps. Com ela, a distância é calculada pelo Google Maps." } }, "required": [ "source_latitude", "source_longitude", "destination_latitude", "destination_longitude" ] }, "example": { "source_latitude": -23.5614, "source_longitude": -46.6559, "destination_latitude": -23.5505, "destination_longitude": -46.6333 } } } }, "responses": { "200": { "description": "A distância, em metros e em milhas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meters": { "type": "number", "description": "A distância em metros." }, "miles": { "type": "number", "description": "A distância em milhas." } } }, "example": { "meters": 2603, "miles": 1.617424 } } } }, "401": { "$ref": "#/components/responses/ChaveInvalida" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST \"https://app.nextagsai.com.br/api/tools/location_distance\" \\\n -H \"X-ACCESS-TOKEN: $NEXTAGS_API_KEY\" \\\n --data-urlencode 'source_latitude=-23.5614' \\\n --data-urlencode 'source_longitude=-46.6559' \\\n --data-urlencode 'destination_latitude=-23.5505' \\\n --data-urlencode 'destination_longitude=-46.6333'" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const resposta = await fetch('https://app.nextagsai.com.br/api/tools/location_distance', {\n method: 'POST',\n headers: {\n 'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,\n },\n body: new URLSearchParams({\n source_latitude: -23.5614,\n source_longitude: -46.6559,\n destination_latitude: -23.5505,\n destination_longitude: -46.6333,\n }),\n});\nconst dados = await resposta.json();\nconsole.log(resposta.status, dados);" }, { "lang": "Python", "label": "Python", "source": "import os\n\nimport requests\n\nresposta = requests.post(\n \"https://app.nextagsai.com.br/api/tools/location_distance\",\n headers={\"X-ACCESS-TOKEN\": os.environ[\"NEXTAGS_API_KEY\"]},\n data={\n \"source_latitude\": -23.5614,\n \"source_longitude\": -46.6559,\n \"destination_latitude\": -23.5505,\n \"destination_longitude\": -46.6333,\n },\n timeout=30,\n)\nprint(resposta.status_code, resposta.json())" }, { "lang": "PHP", "label": "PHP", "source": " true,\n CURLOPT_CUSTOMREQUEST => 'POST',\n CURLOPT_HTTPHEADER => [\n 'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),\n ],\n CURLOPT_POSTFIELDS => http_build_query([\n 'source_latitude' => -23.5614,\n 'source_longitude' => -46.6559,\n 'destination_latitude' => -23.5505,\n 'destination_longitude' => -46.6333,\n ]),\n]);\n$dados = json_decode(curl_exec($ch), true);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;\nprint_r($dados);" } ], "externalDocs": { "description": "Página deste endpoint", "url": "https://docs.nextags.com.br/referencia/ferramentas/calcular-a-distancia-entre-duas-coordenadas/" } } } }, "components": { "securitySchemes": { "ChaveDeApi": { "type": "apiKey", "in": "header", "name": "X-ACCESS-TOKEN", "description": "A chave de API da conta, em Configurações › Integrações › Chave de API do NexTags." } }, "responses": { "ChaveInvalida": { "description": "A chave de API não veio no cabeçalho ou não vale.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" }, "example": { "error": { "code": 401, "message": "No valid API key provided." } } } } } }, "schemas": { "Admin": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID do administrador." }, "email": { "type": "string", "description": "O e-mail de acesso." }, "first_name": { "type": "string", "description": "O nome." }, "last_name": { "type": "string", "description": "O sobrenome." }, "full_name": { "type": "string", "description": "O nome completo." }, "profile_pic": { "type": "string", "description": "O endereço da foto do perfil." }, "available": { "type": "boolean", "description": "Se a pessoa está como **Disponível** para receber conversas." } }, "title": "Administrador", "description": "Uma pessoa da equipe que entra no painel da conta.", "examples": [ { "id": 10001, "email": "ana@exemplo.com.br", "first_name": "Ana", "last_name": "Souza", "full_name": "Ana Souza", "profile_pic": "https://exemplo.com.br/fotos/ana.jpg", "available": true } ] }, "Team": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID da equipe." }, "name": { "type": "string", "description": "O nome da equipe." } }, "title": "Equipe", "description": "Uma equipe de atendimento da Caixa de Entrada.", "examples": [ { "id": 501, "name": "Vendas" } ] }, "Tag": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID da etiqueta." }, "name": { "type": "string", "description": "O nome da etiqueta." } }, "title": "Etiqueta", "description": "Uma etiqueta da conta, usada para marcar contatos.", "examples": [ { "id": 2001, "name": "cliente-vip" } ] }, "Contact": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID do contato: o `contact_id` das outras chamadas." }, "page_id": { "type": "integer", "format": "int64", "description": "O ID da conta." }, "first_name": { "type": "string", "description": "O nome." }, "last_name": { "type": "string", "description": "O sobrenome." }, "channel": { "type": "integer", "description": "O canal atual do contato: 0 Messenger, 5 WhatsApp, 8 Telegram, 9 Webchat, 10 Instagram, 17 TikTok." }, "profile_pic": { "type": "string", "description": "O endereço da foto de perfil." }, "locale": { "type": "string", "description": "O idioma do contato, como `pt_BR`." }, "gender": { "type": "integer", "description": "O gênero: 0 feminino, 1 masculino, 2 desconhecido." }, "timezone": { "type": "integer", "description": "O fuso horário do contato, em horas em relação ao UTC (-3 em Brasília)." }, "last_sent": { "type": "integer", "format": "int64", "description": "Quando a última mensagem foi enviada ao contato, em Unix timestamp em milissegundos." }, "last_delivered": { "type": "integer", "format": "int64", "description": "Quando a última mensagem foi entregue ao contato, em Unix timestamp em milissegundos." }, "last_seen": { "type": "integer", "format": "int64", "description": "Quando o contato foi visto pela última vez (**Visto pela última vez**, no app), em Unix timestamp em milissegundos." }, "last_interaction": { "type": "integer", "format": "int64", "description": "Quando o contato interagiu com a conta pela última vez, em Unix timestamp em milissegundos." }, "subscribed_date": { "type": "string", "description": "Quando o contato entrou na conta, em UTC, no formato `2026-10-12 14:40:00`." }, "subscribed": { "type": "integer", "description": "1 inscrito; 2 inscrição cancelada (o contato saiu das transmissões e não recebe Broadcasts). Veja [Contatos que pediram para sair das transmissões](https://help.nextags.com.br/tutoriais/contatos/cancelar-inscricao/)." }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" }, "description": "As etiquetas do contato." }, "custom_fields": { "type": "array", "items": { "$ref": "#/components/schemas/Custom_field" }, "description": "Os campos personalizados do contato, com o valor de cada um." } }, "title": "Contato", "description": "Uma pessoa que fala com a conta, com o canal, os dados do perfil, as datas da conversa, as etiquetas e os campos personalizados.", "examples": [ { "id": 123456789, "page_id": 123456, "first_name": "Ana", "last_name": "Souza", "channel": 5, "profile_pic": "https://exemplo.com.br/fotos/ana.jpg", "locale": "pt_BR", "gender": 0, "timezone": -3, "last_sent": 1792936930000, "last_delivered": 1792936932000, "last_seen": 1792937020000, "last_interaction": 1792936680000, "subscribed_date": "2026-10-12 14:40:00", "subscribed": 1, "tags": [ { "id": 2001, "name": "cliente-vip" } ], "custom_fields": [ { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" } ] } ] }, "Acao": { "title": "Ação", "type": "object", "required": [ "action" ], "additionalProperties": true, "description": "Uma ação para rodar no contato. Veja [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/).", "properties": { "action": { "type": "string", "enum": [ "add_tag", "remove_tag", "set_field_value", "unset_field_value", "send_flow", "transfer_conversation_to", "assign_conversation", "unassign_conversation" ] }, "tag_name": { "type": "string", "description": "O nome da etiqueta (add_tag, remove_tag)." }, "field_name": { "type": "string", "description": "O nome do campo (set_field_value, unset_field_value)." }, "value": { "type": "string", "description": "O valor do campo (set_field_value) ou human/bot (transfer_conversation_to)." }, "flow_id": { "type": [ "integer", "string" ], "description": "O ID do fluxo (send_flow)." }, "admin_id": { "type": [ "integer", "string" ], "description": "O ID do administrador (assign_conversation)." } }, "examples": [ { "action": "add_tag", "tag_name": "cliente-vip" } ] }, "Custom_field": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID do campo." }, "name": { "type": "string", "description": "O nome do campo." }, "type": { "type": "integer", "description": "O tipo: 0 texto, 1 número, 2 data, 3 data e hora, 4 sim/não, 5 texto longo, 6 seleção única, 7 seleção múltipla.", "enum": [ 0, 1, 2, 3, 4, 5, 6, 7 ] }, "value": { "type": [ "string", "number" ], "description": "O valor do contato, no formato do tipo: texto nos campos de texto e de texto longo; número nos de número, de data e de data e hora (Unix timestamp, em segundos) e de sim/não (1 ou 0)." } }, "title": "Campo personalizado", "description": "Um campo personalizado de um contato, com o valor dele.", "examples": [ { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" } ] }, "Mensagem": { "title": "Mensagem", "type": "object", "additionalProperties": true, "description": "Uma mensagem no formato da NexTags (texto, botões, respostas rápidas, mídia, cartões). Veja [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/).", "examples": [ { "message": { "text": "Oi! Seu pedido saiu para entrega." } } ] }, "Pipeline": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID do pipeline." }, "name": { "type": "string", "description": "O nome do pipeline." } }, "title": "Pipeline", "description": "Um quadro de oportunidades ou de tickets, com as etapas em colunas.", "examples": [ { "id": 4001, "name": "Funil de vendas" } ] }, "PipelineStage": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID da etapa: o `stage_id` das oportunidades." }, "name": { "type": "string", "description": "O nome da etapa." } }, "title": "Etapa do pipeline", "description": "Uma etapa do pipeline: uma coluna do quadro.", "examples": [ { "id": 4101, "name": "Novo lead" } ] }, "Opportunity": { "type": "object", "properties": { "id": { "type": "integer", "description": "O ID da oportunidade." }, "contact_id": { "type": "integer", "description": "O ID do contato." }, "title": { "type": "string", "description": "O nome da oportunidade." }, "description": { "type": "string", "description": "A descrição." }, "value": { "type": "number", "description": "O valor, na moeda da conta. Não é em centavos: `1500` = R$ 1.500,00." }, "status": { "type": "string", "description": "O estado: `open` (Aberto), `won` (Ganho; Resolvido nos pipelines de suporte e nos personalizados) ou `lost` (Perdido; Não Resolvido).", "enum": [ "open", "won", "lost" ] }, "priority": { "type": "string", "description": "A prioridade: `low` (Baixa), `medium` (Média) ou `high` (Alta).", "enum": [ "low", "medium", "high" ] }, "stage": { "type": "object", "properties": { "id": { "type": "integer", "description": "O ID da etapa." }, "name": { "type": "string", "description": "O nome da etapa." } }, "description": "A etapa onde a oportunidade está." }, "assigned_admins": { "type": "array", "items": { "type": "integer" }, "description": "Os IDs dos administradores atribuídos." }, "created_at": { "type": "string", "description": "Quando a oportunidade foi criada, em UTC.", "examples": [ "2026-10-20 14:30:00" ] }, "created_by": { "type": "integer", "description": "O ID do administrador que criou." }, "updated_at": { "type": "string", "description": "A última mudança, em UTC.", "examples": [ "2026-10-22 18:05:00" ] }, "updated_by": { "type": "integer", "description": "O ID do administrador que fez a última mudança." } }, "title": "Oportunidade", "description": "Um cartão do pipeline: uma oportunidade de venda ou, nos pipelines de suporte, um ticket.", "examples": [ { "id": 4201, "contact_id": 123456789, "title": "Plano Pro anual", "description": "Quer começar em novembro, com 3 atendentes.", "value": 1500, "status": "open", "priority": "high", "stage": { "id": 4101, "name": "Novo lead" }, "assigned_admins": [ 10001 ], "created_at": "2026-10-20 14:30:00", "created_by": 10001, "updated_at": "2026-10-22 18:05:00", "updated_by": 10001 } ] }, "OpportunityComment": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID do comentário." }, "data": { "type": "string", "description": "O texto do comentário." }, "created_at": { "type": "string", "description": "Quando o comentário foi escrito, em UTC.", "examples": [ "2026-10-21 13:15:00" ] }, "created_by": { "type": "integer", "description": "O ID do administrador que escreveu." } }, "title": "Comentário da oportunidade", "description": "Um comentário da seção **Comentários** de uma oportunidade.", "examples": [ { "id": 4301, "data": "Proposta enviada por e-mail: Plano Pro anual com 10% de desconto.", "created_at": "2026-10-21 13:15:00", "created_by": 10001 } ] }, "Agent": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID do agente." }, "name": { "type": "string", "description": "O nome do agente, como aparece na lista do AI Hub." }, "created_by": { "type": "integer", "format": "int64", "description": "O ID do administrador que criou." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando o agente foi criado, em UTC.", "examples": [ "2026-09-15 13:20:00" ] } }, "title": "Agente de IA", "description": "Um agente do AI Hub: as instruções e os modelos com que a IA responde os contatos.", "examples": [ { "id": 5001, "name": "Bia - Loja Exemplo", "created_by": 10001, "created_at": "2026-09-15 13:20:00" } ] }, "Calendar": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID do calendário." }, "name": { "type": "string", "description": "O nome do calendário." }, "duration": { "type": "integer", "format": "int64", "description": "A **Duração do evento**: quanto dura cada agendamento, em minutos (na tela, de 5 minutos a 23 horas)." }, "created_by": { "type": "integer", "format": "int64", "description": "O ID do administrador que criou." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando o calendário foi criado, em UTC.", "examples": [ "2026-08-01 12:00:00" ] } }, "title": "Calendário", "description": "Um calendário do Gestor de Agendamentos.", "examples": [ { "id": 8001, "name": "Avaliação gratuita", "duration": 30, "created_by": 10001, "created_at": "2026-08-01 12:00:00" } ] }, "Cart": { "type": "object", "description": "O carrinho de um contato. A consulta de pedido devolve o mesmo formato. Os valores de dinheiro vão em centavos, menos o `price` de cada item.", "properties": { "order_id": { "type": "string", "description": "O ID do pedido (texto)." }, "page_id": { "type": "integer", "format": "int64", "description": "O ID da conta." }, "user_id": { "type": "integer", "format": "int64", "description": "O ID do contato." }, "currency": { "type": "string", "description": "A moeda da loja, como `BRL`." }, "total": { "type": "integer", "format": "int64", "description": "O total, em centavos." }, "subtotal": { "type": "integer", "format": "int64", "description": "A soma dos itens, em centavos." }, "total_items": { "type": "integer", "description": "Quantos itens o carrinho tem." }, "coupon_discount": { "type": "integer", "format": "int64", "description": "O desconto do cupom, em centavos." }, "coupon": { "type": "string", "description": "O código do cupom aplicado (o **Código de desconto** da aba **Cupons**)." }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCart" }, "description": "Os itens do carrinho." }, "contact": { "$ref": "#/components/schemas/Contact", "description": "O contato dono do carrinho." } }, "title": "Carrinho", "examples": [ { "order_id": "PED-1001", "page_id": 123456, "user_id": 123456789, "currency": "BRL", "total": 8082, "subtotal": 8980, "total_items": 2, "coupon_discount": 898, "coupon": "BEMVINDO10", "line_items": [ { "id": 6001, "name": "Camiseta Básica Preta", "img": "https://exemplo.com.br/produtos/camiseta-preta.jpg", "price": 49.9, "amount": 1, "descr_min": "Camiseta 100% algodão, gola redonda.", "manufacturer": 0, "variant": "M", "user_msg": "" }, { "id": 6002, "name": "Boné Aba Curva", "img": "https://exemplo.com.br/produtos/bone.jpg", "price": 39.9, "amount": 1, "descr_min": "Boné ajustável de algodão.", "manufacturer": 0, "variant": "", "user_msg": "Embrulhar para presente." } ], "contact": { "id": 123456789, "page_id": 123456, "first_name": "Ana", "last_name": "Souza", "channel": 5, "profile_pic": "https://exemplo.com.br/fotos/ana.jpg", "locale": "pt_BR", "gender": 0, "timezone": -3, "last_sent": 1792933200000, "last_delivered": 1792933202000, "last_seen": 1792933500000, "last_interaction": 1792933560000, "subscribed_date": "2026-03-10 14:22:00", "subscribed": 1, "tags": [ { "id": 2001, "name": "cliente-vip" } ], "custom_fields": [ { "id": 3001, "name": "cidade", "type": 0, "value": "São Paulo" } ] } } ] }, "Product": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID do produto." }, "name": { "type": "string", "description": "O nome do produto." }, "price": { "type": "number", "format": "double", "description": "O preço, como na coluna **Preço** da lista (`49.9` = R$ 49,90)." }, "sale_price": { "type": "number", "format": "double", "description": "O preço promocional." }, "category_id": { "type": "integer", "format": "int64", "description": "O ID da categoria (aba **Categorias**)." }, "category_name": { "type": "string", "description": "O nome da categoria." }, "stock": { "type": "integer", "format": "int64", "description": "O estoque, como na coluna **Inventário** da lista." }, "short_description": { "type": "string", "description": "A descrição curta." }, "image": { "type": "string", "description": "O endereço da imagem." }, "created_at": { "type": "string", "description": "Quando o produto foi criado, em UTC.", "examples": [ "2026-07-10 18:00:00" ] } }, "title": "Produto", "description": "Um produto do E-commerce (**Ferramentas** › **Ecommerce** › **Produtos**). Os preços vêm na moeda da loja, não em centavos.", "examples": [ { "id": 6001, "name": "Camiseta Básica Preta", "price": 49.9, "sale_price": 39.9, "category_id": 6101, "category_name": "Camisetas", "stock": 120, "short_description": "Camiseta 100% algodão, gola redonda.", "image": "https://exemplo.com.br/produtos/camiseta-preta.jpg", "created_at": "2026-07-10 18:00:00" } ] }, "Broadcast": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID do Broadcast." }, "name": { "type": "string", "description": "O nome do Broadcast, como na coluna **Nome** da lista." }, "status": { "type": "string", "enum": [ "DRAFT", "NOT_SENT", "SENTING", "SENT", "CANCELLED" ], "description": "O estado: `DRAFT` (rascunho; *Draft* na lista), `NOT_SENT` (ainda não saiu, como um Broadcast **Pendente** ou **Agendado**), `SENTING` (**Enviando**; o nome é escrito assim mesmo), `SENT` (**Enviado**) ou `CANCELLED` (**Cancelado**)." }, "sent_at": { "type": "string", "format": "date-time", "description": "Quando o envio saiu, em UTC.", "examples": [ "2026-10-20 15:00:00" ] }, "created_by": { "type": "integer", "format": "int64", "description": "O ID do administrador que criou." }, "created_at": { "type": "string", "format": "date-time", "description": "Quando o Broadcast foi criado, em UTC.", "examples": [ "2026-10-20 14:45:00" ] } }, "title": "Broadcast", "description": "Um envio em massa da tela **Broadcasts**.", "examples": [ { "id": 7001, "name": "Black Friday - clientes VIP", "status": "SENT", "sent_at": "2026-10-20 15:00:00", "created_by": 10001, "created_at": "2026-10-20 14:45:00" } ] }, "ProductCart": { "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "description": "O ID do produto." }, "name": { "type": "string", "description": "O nome do produto." }, "img": { "type": "string", "description": "O endereço da imagem do produto." }, "price": { "type": "number", "format": "double", "description": "O preço de uma unidade, na moeda da loja. Não é em centavos: `49.9` = R$ 49,90." }, "amount": { "type": "integer", "description": "A quantidade." }, "descr_min": { "type": "string", "description": "A descrição curta do produto." }, "manufacturer": { "type": "integer", "description": "O ID do vendedor do produto (aba **Vendedores**)." }, "variant": { "type": "string", "description": "A variante escolhida, como o tamanho ou a cor." }, "user_msg": { "type": "string", "description": "O pedido especial que o contato anotou no item, quando o produto permite anexar notas." } }, "title": "Item do carrinho", "description": "Um produto dentro do carrinho ou do pedido, com a quantidade. O `price` não é em centavos.", "examples": [ { "id": 6001, "name": "Camiseta Básica Preta", "img": "https://exemplo.com.br/produtos/camiseta-preta.jpg", "price": 49.9, "amount": 1, "descr_min": "Camiseta 100% algodão, gola redonda.", "manufacturer": 0, "variant": "M", "user_msg": "" } ] }, "Erro": { "title": "Erro", "type": "object", "description": "O corpo de uma resposta de erro.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "O código HTTP." }, "message": { "type": "string", "description": "A mensagem, em inglês." } } } }, "examples": [ { "error": { "code": 401, "message": "No valid API key provided." } } ] } } } }