# Requisição externa: o fluxo chama o seu sistema

> Prepare o seu servidor para a requisição externa do fluxo: o que chega, o cabeçalho X-USER-ID, o que responder para guardar dados ou mandar mensagens e ações.

Endereço: https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo/
Tipo: Guia

Atualizado em: 26/10/2026

Na ação **External API Request**, o fluxo chama um endereço seu quando o contato chega à etapa. O seu servidor recebe a chamada e responde de um destes jeitos: com um JSON comum, que a NexTags guarda em campos do contato pelo **Mapeamento de resposta**, ou com conteúdo dinâmico, que a NexTags transforma em mensagens para o contato e em ações, como aplicar uma etiqueta. Este guia mostra o lado do seu servidor, com um exemplo que consulta um pedido e responde ao contato. A configuração da ação na tela, passo a passo, está em [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/).

**Antes de começar**

- Um endereço `https://` do seu servidor que aceite a chamada. Para só ver o que chega, comece com um endereço de teste, como o Test URL do n8n: veja [Segurança, testes e novas tentativas](https://docs.nextags.com.br/webhooks/seguranca-e-testes/).
- Uma etapa **Ações** no fluxo, com a ação **External API Request**. Veja [Requisição externa](https://help.nextags.com.br/tutoriais/fluxos/requisicao-externa/).
- Para responder com mensagens e ações, o formato de [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/).

## Passo a passo

### Passo 1: Configure a chamada no fluxo

Na janela **External Request**, escolha o método em **Request Type** (**GET**, **POST**, **PUT**, **PATCH** ou **DELETE**) e o endereço em **Request URL**. O endereço aceita variáveis do contato: digite `{` para escolher o campo. Na aba **Cabeçalhos**, um cabeçalho por linha, com **Adicionar** para mais um. Na aba **Corpo**, o formato:

| Na aba **Corpo** | O que o seu servidor recebe |
|---|---|
| **Todos os dados do contato** | Os dados do contato num formato pronto. Marque **Incluir tags do contato** e **Incluir campos personalizados do contato** para juntar as etiquetas e os campos. A tela remete à documentação da API; o formato exato, confira em **Corpo da solicitação**, no **Testar Agora**. |
| **JSON** | O JSON que você escrever, com as variáveis `{{campo}}` trocadas pelos valores do contato. Um JSON inválido faz a tela avisar "O JSON no corpo da solicitação não é válido". |
| **Form-encoded** | Pares de nome e valor, como um formulário. |

Com **GET**, a aba **Corpo** fica desligada. O corpo em **JSON** deste guia manda o código do pedido guardado num campo do contato. Os campos de texto vão entre aspas:

```json
{
  "contato_id": "{{user_id}}",
  "nome": "{{full_name}}",
  "telefone": "{{phone}}",
  "pedido": "{{ID do pedido}}"
}
```

No seu servidor chegam o método, os cabeçalhos que você montou e o corpo. A NexTags manda também o cabeçalho `X-USER-ID`, com o ID do contato, em toda requisição. Use esse ID para saber de que contato é a chamada ou para consultar o contato pela API, em [Consultar contato](https://docs.nextags.com.br/referencia/contatos/consultar-contato/).

Para o seu servidor saber que a chamada veio do seu fluxo, crie um cabeçalho com um segredo seu, como `X-Segredo`, e confira no servidor. Para não repetir o segredo em cada fluxo, guarde num campo do bot: veja [Campos do bot](https://help.nextags.com.br/tutoriais/fluxos/campos-do-bot/).

### Passo 2: Decida o que responder

O seu servidor responde de um destes jeitos.

**JSON comum, para guardar em campos.** Na aba **Mapeamento de resposta**, cada linha liga um caminho (**JSONPath**) a um campo, em **Salvar em um campo personalizado**. Para esta resposta:

```json
{
  "pedido": {
    "id": "PED-1001",
    "status": "enviado",
    "rastreio": "https://seusistema.exemplo.com.br/rastreio/PED-1001"
  }
}
```

| Valor | JSONPath | Campo |
|---|---|---|
| A situação do pedido | `$.pedido.status` | Status do pedido (texto) |
| O link de acompanhamento | `$.pedido.rastreio` | Link de rastreio (texto) |

Três nomes especiais, escritos no lugar do JSONPath, guardam a resposta inteira:

| No lugar do JSONPath | O que guarda |
|---|---|
| `http_status_code` | O código HTTP da resposta, como `200` ou `404`. Guarde num campo de número e use numa condição. |
| `http_response_body` | O corpo inteiro da resposta, como texto. Depois, dá para tirar valores dele com **Obter dados de JSON**. |
| `http_download_<extensão>` | Baixa a resposta como um arquivo com essa extensão, como `http_download_mp3` para um áudio. |

**Conteúdo dinâmico, para mandar mensagens e executar ações.** Responda com `messages` (as mensagens que o contato recebe, na ordem) e `actions` (as ações, na ordem). A NexTags converte as mensagens para o canal do contato. O formato completo, com botões, imagens, cartões e as ações, está em [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/).

```json
{
  "messages": [
    { "message": { "text": "Seu pedido PED-1001 está a caminho." } },
    { "message": { "text": "Acompanhe aqui: https://seusistema.exemplo.com.br/rastreio/PED-1001" } }
  ],
  "actions": [
    { "action": "add_tag", "tag_name": "pedido-consultado" },
    { "action": "set_field_value", "field_name": "Status do pedido", "value": "enviado" }
  ]
}
```

O conteúdo dinâmico só funciona quando o endereço é seu: é o seu servidor que monta a resposta nesse formato. Para a API de outra empresa, use o **Mapeamento de resposta** e mostre os campos numa mensagem do fluxo.

### Passo 3: Escreva o servidor

Um servidor mínimo para o exemplo: confere o segredo do cabeçalho `X-Segredo`, lê o corpo em JSON e o `X-USER-ID`, e responde com conteúdo dinâmico. O segredo fica na variável de ambiente `NEXTAGS_SEGREDO`, com o mesmo valor do cabeçalho configurado na requisição. Num sistema de verdade, a situação do pedido viria do seu banco de dados.

**Servidor que responde com mensagens e ações**

```javascript
// servidor.mjs (Node 18 ou mais novo): node servidor.mjs
import http from 'node:http';
import { timingSafeEqual } from 'node:crypto';

const SEGREDO = process.env.NEXTAGS_SEGREDO;

function igual(a, b) {
  const x = Buffer.from(String(a ?? ''));
  const y = Buffer.from(String(b ?? ''));
  return x.length === y.length && timingSafeEqual(x, y);
}

http.createServer(async (req, res) => {
  if (req.method !== 'POST' || req.url !== '/nextags/pedido') {
    res.writeHead(404).end();
    return;
  }
  if (!SEGREDO || !igual(req.headers['x-segredo'], SEGREDO)) {
    res.writeHead(401).end();
    return;
  }
  let corpo = '';
  for await (const parte of req) corpo += parte;
  let dados;
  try {
    dados = JSON.parse(corpo || '{}');
  } catch {
    res.writeHead(400).end();
    return;
  }
  const contato = req.headers['x-user-id']; // o ID do contato na NexTags
  console.log(`Contato ${contato} consultou o pedido ${dados.pedido}`);

  const resposta = {
    messages: [
      { message: { text: `Seu pedido ${dados.pedido} está a caminho.` } },
    ],
    actions: [
      { action: 'add_tag', tag_name: 'pedido-consultado' },
      { action: 'set_field_value', field_name: 'Status do pedido', value: 'enviado' },
    ],
  };
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify(resposta));
}).listen(3000);
```
```python
# servidor.py (Flask): flask --app servidor run --port 3000
import hmac
import os

from flask import Flask, jsonify, request

app = Flask(__name__)
SEGREDO = os.environ.get("NEXTAGS_SEGREDO", "")

@app.post("/nextags/pedido")
def pedido():
    recebido = request.headers.get("X-Segredo", "")
    if not SEGREDO or not hmac.compare_digest(recebido.encode(), SEGREDO.encode()):
        return "", 401
    dados = request.get_json(silent=True) or {}
    contato = request.headers.get("X-USER-ID")  # o ID do contato na NexTags
    app.logger.info("Contato %s consultou o pedido %s", contato, dados.get("pedido"))

    return jsonify({
        "messages": [
            {"message": {"text": f"Seu pedido {dados.get('pedido')} está a caminho."}},
        ],
        "actions": [
            {"action": "add_tag", "tag_name": "pedido-consultado"},
            {"action": "set_field_value", "field_name": "Status do pedido", "value": "enviado"},
        ],
    })
```
```php
<?php
// pedido.php: a Request URL da requisição aponta para este arquivo
$segredo = (string) getenv('NEXTAGS_SEGREDO');
$recebido = $_SERVER['HTTP_X_SEGREDO'] ?? '';
if ($segredo === '' || !hash_equals($segredo, $recebido)) {
    http_response_code(401);
    exit;
}

$dados = json_decode(file_get_contents('php://input'), true) ?: [];
$contato = $_SERVER['HTTP_X_USER_ID'] ?? ''; // o ID do contato na NexTags
$pedido = $dados['pedido'] ?? '';
error_log("Contato $contato consultou o pedido $pedido");

header('Content-Type: application/json');
echo json_encode([
    'messages' => [
        ['message' => ['text' => "Seu pedido $pedido está a caminho."]],
    ],
    'actions' => [
        ['action' => 'add_tag', 'tag_name' => 'pedido-consultado'],
        ['action' => 'set_field_value', 'field_name' => 'Status do pedido', 'value' => 'enviado'],
    ],
], JSON_UNESCAPED_UNICODE);
```

Publique o servidor num endereço `https://`, como `https://seusistema.exemplo.com.br/nextags/pedido`, e use esse endereço em **Request URL**.

### Passo 4: Teste o servidor antes de ligar o fluxo

Simule a chamada da NexTags com o cURL, no próprio servidor. A resposta deve ser o conteúdo dinâmico do passo anterior.

```bash
curl -X POST "http://127.0.0.1:3000/nextags/pedido" \
  -H "Content-Type: application/json" \
  -H "X-Segredo: $NEXTAGS_SEGREDO" \
  -H "X-USER-ID: 123456789" \
  -d '{"contato_id": "123456789", "nome": "Ana Souza", "telefone": "5511988776655", "pedido": "PED-1001"}'
```

Sem o cabeçalho `X-Segredo`, ou com outro valor, o servidor responde `401`.

### Passo 5: Teste no fluxo e ligue as saídas

Na janela da requisição, abra a aba **Testar Agora** e clique no botão **Testar Agora**. Escolha o canal em **Selecionar canal** e clique em **Continuar**. O resultado mostra:

```text
Código do estado          200
Corpo da resposta         o JSON que o seu servidor devolveu
Cabeçalhos da resposta    os cabeçalhos que o seu servidor devolveu
Cabeçalhos da solicitação os cabeçalhos que a NexTags mandou, com os que você montou
Corpo da solicitação      o corpo que a NexTags mandou, já com os valores do contato
```

Confira em **Cabeçalhos da solicitação** e **Corpo da solicitação** o que o seu servidor recebe de verdade, principalmente com **Todos os dados do contato**. Clique no nome de cada parte para abrir. Clique em **Salvar**. No quadro, ligue a saída **Sucesso** à próxima etapa e a saída **Falhado** a um caminho de reserva, como uma mensagem de "tente mais tarde" ou a passagem para a equipe. Depois, publique o fluxo.

## Pronto: como conferir

- O **Testar Agora** mostra o **Código do estado** `200` e o seu JSON em **Corpo da resposta**.
- Clique em **Testar**, no topo do editor, e passe pela etapa no seu celular: as mensagens do conteúdo dinâmico chegam, e a etiqueta e o campo aparecem no seu contato. Veja [Testar o fluxo](https://help.nextags.com.br/tutoriais/fluxos/testar-fluxo/).
- O log do seu servidor mostra o `X-USER-ID`: é o ID do seu contato na NexTags.

## Se não funcionou

### O teste mostra o código 401

O segredo não bateu. Confira o nome do cabeçalho na aba **Cabeçalhos** (`X-Segredo`, no exemplo) e o valor, sem espaços, e a variável `NEXTAGS_SEGREDO` no servidor.

### O teste mostra "Não foi possível concluir esta operação."

O teste não chegou ao fim. Confira se o endereço em **Request URL** está certo, começa com `https://` e responde fora da sua rede. Veja [Erros de requisição externa, webhook e planilha](https://help.nextags.com.br/tutoriais/erros/erros-de-requisicao-externa/).

### O código é 200, mas as mensagens não chegaram

Confira em **Corpo da resposta** se o JSON tem a lista `messages` e se cada item tem um objeto `message`, como em [Mensagens e ações em JSON](https://docs.nextags.com.br/comecar/mensagens-e-acoes/). O servidor também deve responder com o cabeçalho `Content-Type: application/json`.

### O campo do Mapeamento de resposta ficou vazio

O JSONPath não bate com a resposta. Abra o **Testar Agora**, copie o **Corpo da resposta** e confira o caminho. Para ver tudo o que voltou, guarde `http_response_body` num campo de texto. Veja [Mapear o corpo recebido para campos do contato](https://docs.nextags.com.br/webhooks/mapear-campos/).

### O contato foi pela saída Falhado

Veja o código e a resposta no **Testar Agora** e confira o log do seu servidor: a chamada chegou? O servidor respondeu rápido e com um código de 200 a 299? As falhas dos fluxos ficam no **Registro de Erros**: veja [Registro de Erros: ler e resolver](https://help.nextags.com.br/tutoriais/fluxos/registro-de-erros/).

### Faça com a IA

Cole este pedido no ChatGPT ou no Claude:

```text
Vou receber a requisição externa de um fluxo da NexTags no meu servidor. Leia este guia: https://docs.nextags.com.br/webhooks/requisicao-externa-no-fluxo.md e o formato das mensagens: https://docs.nextags.com.br/comecar/mensagens-e-acoes.md

Minha linguagem e framework: [ex.: Node com Express, Python com FastAPI, PHP com Laravel]. O que o servidor deve fazer: [descreva, por exemplo: consultar o pedido no meu banco e responder com a situação e um botão]. Escreva o servidor completo, que confere o segredo do cabeçalho X-Segredo (guardado numa variável de ambiente), lê o X-USER-ID e responde em JSON com messages e actions. Diga também o que configurar na External API Request: Request Type, Request URL, Cabeçalhos e Corpo.
```