Criar e mover oportunidades no pipeline
Liste pipelines e etapas, crie a oportunidade do contato, mova de etapa, marque como ganha ou perdida, transfira para outro pipeline e comente, pela API.
Os pipelines da NexTags acompanham negócios e atendimentos em etapas, como um quadro kanban. Pela API, o seu sistema cria a oportunidade quando o lead chega, move de etapa quando a proposta sai, marca como ganha quando o pagamento entra e deixa um comentário com o que aconteceu. Neste guia, você faz esse caminho inteiro.
Antes de começar
- A chave de API na variável de ambiente
NEXTAGS_API_KEY. Veja Autenticação com a chave de API. - Um pipeline criado na NexTags. Veja Criar um pipeline a partir de um modelo.
- O ID do contato e, se for atribuir a oportunidade, o ID do administrador. Veja Contatos, fluxos e outros identificadores.
Passo a passo
Passo 1: Liste os pipelines
Use Listar pipelines para achar o ID do pipeline:
curl "https://app.nextagsai.com.br/api/pipelines" \
-H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines', {
headers: {
'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
},
});
const dados = await resposta.json();
console.log(resposta.status, dados);
import os
import requests
resposta = requests.get(
"https://app.nextagsai.com.br/api/pipelines",
headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
timeout=30,
)
print(resposta.status_code, resposta.json())
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/pipelines');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
{"data": [{"id": 4001, "name": "Vendas"}, {"id": 4002, "name": "Pós-venda"}]}A lista aceita offset e limit (padrão 0 e 100). Veja Limites, erros e boas práticas.
Passo 2: Liste as etapas
Use Listar etapas do pipeline. As etapas vêm na lista data:
curl "https://app.nextagsai.com.br/api/pipelines/4001/stages" \
-H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/stages', {
headers: {
'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
},
});
const dados = await resposta.json();
console.log(resposta.status, dados);
import os
import requests
resposta = requests.get(
"https://app.nextagsai.com.br/api/pipelines/4001/stages",
headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
timeout=30,
)
print(resposta.status_code, resposta.json())
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/pipelines/4001/stages');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
{
"data": [
{"id": 4101, "name": "Lead"},
{"id": 4102, "name": "Proposta enviada"},
{"id": 4103, "name": "Fechado"}
]
}Guarde os IDs das etapas no seu sistema: eles não aparecem na tela.
Passo 3: Veja os campos do pipeline
Cada pipeline pode ter campos próprios, criados nas Definições dele. Use Listar campos do pipeline para ver o id, o name, o type e a description de cada um:
curl "https://app.nextagsai.com.br/api/pipelines/4001/custom_fields" \
-H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/custom_fields', {
headers: {
'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
},
});
const dados = await resposta.json();
console.log(resposta.status, dados);
import os
import requests
resposta = requests.get(
"https://app.nextagsai.com.br/api/pipelines/4001/custom_fields",
headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
timeout=30,
)
print(resposta.status_code, resposta.json())
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/pipelines/4001/custom_fields');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
Esses campos são da oportunidade, não do contato. Veja Comentários, anexos e campos do pipeline.
Passo 4: Procure antes de criar
Use Listar oportunidades com o contact_id para ver se o contato já tem uma oportunidade neste pipeline:
curl "https://app.nextagsai.com.br/api/pipelines/4001/opportunities?contact_id=123456789" \
-H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
const resposta = await fetch(`https://app.nextagsai.com.br/api/pipelines/4001/opportunities?${new URLSearchParams({
contact_id: '123456789',
})}`, {
headers: {
'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
},
});
const dados = await resposta.json();
console.log(resposta.status, dados);
import os
import requests
resposta = requests.get(
"https://app.nextagsai.com.br/api/pipelines/4001/opportunities",
headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
params={
"contact_id": "123456789",
},
timeout=30,
)
print(resposta.status_code, resposta.json())
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/pipelines/4001/opportunities?' . http_build_query([
'contact_id' => '123456789',
]));
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
Se a lista data vier com uma oportunidade aberta, atualize essa (passo 7) em vez de criar outra.
Passo 5: Crie a oportunidade
Use Criar oportunidade. O contact_id e o title são obrigatórios; o resto é opcional:
curl -X POST "https://app.nextagsai.com.br/api/pipelines/4001/opportunities" \
-H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact_id": 123456789,
"title": "Bolo de casamento - Ana Souza",
"description": "Bolo de 3 andares para 120 pessoas",
"value": 1200,
"stage_id": 4101,
"status": "open",
"priority": "high",
"assigned_admins": [
10001
],
"custom_fields": [
{
"name": "Origem",
"value": "Site"
}
]
}'
const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/opportunities', {
method: 'POST',
headers: {
'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
contact_id: 123456789,
title: 'Bolo de casamento - Ana Souza',
description: 'Bolo de 3 andares para 120 pessoas',
value: 1200,
stage_id: 4101,
status: 'open',
priority: 'high',
assigned_admins: [10001],
custom_fields: [
{
name: 'Origem',
value: 'Site',
},
],
}),
});
const dados = await resposta.json();
console.log(resposta.status, dados);
import os
import requests
resposta = requests.post(
"https://app.nextagsai.com.br/api/pipelines/4001/opportunities",
headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
json={
"contact_id": 123456789,
"title": "Bolo de casamento - Ana Souza",
"description": "Bolo de 3 andares para 120 pessoas",
"value": 1200,
"stage_id": 4101,
"status": "open",
"priority": "high",
"assigned_admins": [10001],
"custom_fields": [
{
"name": "Origem",
"value": "Site",
},
],
},
timeout=30,
)
print(resposta.status_code, resposta.json())
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/pipelines/4001/opportunities');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'contact_id' => 123456789,
'title' => 'Bolo de casamento - Ana Souza',
'description' => 'Bolo de 3 andares para 120 pessoas',
'value' => 1200,
'stage_id' => 4101,
'status' => 'open',
'priority' => 'high',
'assigned_admins' => [10001],
'custom_fields' => [
[
'name' => 'Origem',
'value' => 'Site',
],
],
]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
| Campo | O que é |
|---|---|
stage_id | A etapa. Sem ele, a oportunidade entra na primeira etapa. |
value | O valor. O contrato não diz a unidade: confira no primeiro teste como ele aparece no cartão. |
status | open (Aberto, o padrão), won (Ganho) ou lost (Perdido). |
priority | low (Baixa), medium (Média, o padrão) ou high (Alta). |
assigned_admins | Os IDs dos administradores responsáveis. |
custom_fields | Os campos do pipeline, como {"id": …, "value": …} ou {"name": …, "value": …}. |
A resposta traz a oportunidade criada dentro de data:
{
"data": [
{
"id": 4201,
"contact_id": 123456789,
"title": "Bolo de casamento - Ana Souza",
"description": "Bolo de 3 andares para 120 pessoas",
"value": 1200,
"status": "open",
"priority": "high",
"stage": {"id": 4101, "name": "Lead"},
"assigned_admins": [10001],
"created_at": "2026-10-26 12:00:00",
"created_by": 10001,
"updated_at": "2026-10-26 12:00:00",
"updated_by": 10001
}
]
}Passo 6: Consulte a oportunidade antes de mudar
Use Consultar oportunidade para ter os valores atuais:
curl "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201" \
-H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201', {
headers: {
'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
},
});
const dados = await resposta.json();
console.log(resposta.status, dados);
import os
import requests
resposta = requests.get(
"https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201",
headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
timeout=30,
)
print(resposta.status_code, resposta.json())
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
],
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
A atualização pede o title e mostra valores padrão para value, status, priority e assigned_admins, e o contrato não diz se os campos que faltam ficam como estão. Por isso, mande de volta os valores atuais junto com o que muda.
Passo 7: Mova de etapa
Use Atualizar oportunidade com o stage_id novo e os valores atuais do passo 6 (a etapa atual vem em stage.id):
curl -X POST "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201" \
-H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Bolo de casamento - Ana Souza",
"description": "Bolo de 3 andares para 120 pessoas",
"stage_id": 4102,
"value": 1200,
"status": "open",
"priority": "high",
"assigned_admins": [
10001
]
}'
const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201', {
method: 'POST',
headers: {
'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
title: 'Bolo de casamento - Ana Souza',
description: 'Bolo de 3 andares para 120 pessoas',
stage_id: 4102,
value: 1200,
status: 'open',
priority: 'high',
assigned_admins: [10001],
}),
});
const dados = await resposta.json();
console.log(resposta.status, dados);
import os
import requests
resposta = requests.post(
"https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201",
headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
json={
"title": "Bolo de casamento - Ana Souza",
"description": "Bolo de 3 andares para 120 pessoas",
"stage_id": 4102,
"value": 1200,
"status": "open",
"priority": "high",
"assigned_admins": [10001],
},
timeout=30,
)
print(resposta.status_code, resposta.json())
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'title' => 'Bolo de casamento - Ana Souza',
'description' => 'Bolo de 3 andares para 120 pessoas',
'stage_id' => 4102,
'value' => 1200,
'status' => 'open',
'priority' => 'high',
'assigned_admins' => [10001],
]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
A resposta é {"success": true}.
Passo 8: Marque como ganha ou perdida
Na mesma chamada, mude o status para won (ganha) ou lost (perdida). Dá para mover para a última etapa ao mesmo tempo:
curl -X POST "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201" \
-H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Bolo de casamento - Ana Souza",
"description": "Bolo de 3 andares para 120 pessoas",
"stage_id": 4103,
"value": 1200,
"status": "won",
"priority": "high",
"assigned_admins": [
10001
]
}'
const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201', {
method: 'POST',
headers: {
'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
title: 'Bolo de casamento - Ana Souza',
description: 'Bolo de 3 andares para 120 pessoas',
stage_id: 4103,
value: 1200,
status: 'won',
priority: 'high',
assigned_admins: [10001],
}),
});
const dados = await resposta.json();
console.log(resposta.status, dados);
import os
import requests
resposta = requests.post(
"https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201",
headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
json={
"title": "Bolo de casamento - Ana Souza",
"description": "Bolo de 3 andares para 120 pessoas",
"stage_id": 4103,
"value": 1200,
"status": "won",
"priority": "high",
"assigned_admins": [10001],
},
timeout=30,
)
print(resposta.status_code, resposta.json())
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'title' => 'Bolo de casamento - Ana Souza',
'description' => 'Bolo de 3 andares para 120 pessoas',
'stage_id' => 4103,
'value' => 1200,
'status' => 'won',
'priority' => 'high',
'assigned_admins' => [10001],
]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
Para reabrir, mande status como open. Para apagar a oportunidade, use Apagar oportunidade (DELETE no mesmo endereço).
Passo 9: Transfira para outro pipeline
Use Transferir oportunidade de pipeline, com o pipeline e a etapa de destino. Os dois são obrigatórios:
curl -X POST "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/transfer-to-pipeline" \
-H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"target_pipeline_id": 4002,
"target_stage_id": 4111
}'
const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/transfer-to-pipeline', {
method: 'POST',
headers: {
'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
target_pipeline_id: 4002,
target_stage_id: 4111,
}),
});
const dados = await resposta.json();
console.log(resposta.status, dados);
import os
import requests
resposta = requests.post(
"https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/transfer-to-pipeline",
headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
json={
"target_pipeline_id": 4002,
"target_stage_id": 4111,
},
timeout=30,
)
print(resposta.status_code, resposta.json())
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201/transfer-to-pipeline');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'target_pipeline_id' => 4002,
'target_stage_id' => 4111,
]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
A resposta é {"success": true}. Depois disso, use o pipeline de destino (4002) no caminho das próximas chamadas. Os IDs das etapas do outro pipeline vêm de Listar etapas do pipeline.
Passo 10: Comente na oportunidade
Use Comentar na oportunidade, com o texto em content:
curl -X POST "https://app.nextagsai.com.br/api/pipelines/4002/opportunities/4201/comments" \
-H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "Pagamento confirmado. Entrega no sábado, às 10h."
}'
const resposta = await fetch('https://app.nextagsai.com.br/api/pipelines/4002/opportunities/4201/comments', {
method: 'POST',
headers: {
'X-ACCESS-TOKEN': process.env.NEXTAGS_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
content: 'Pagamento confirmado. Entrega no sábado, às 10h.',
}),
});
const dados = await resposta.json();
console.log(resposta.status, dados);
import os
import requests
resposta = requests.post(
"https://app.nextagsai.com.br/api/pipelines/4002/opportunities/4201/comments",
headers={"X-ACCESS-TOKEN": os.environ["NEXTAGS_API_KEY"]},
json={
"content": "Pagamento confirmado. Entrega no sábado, às 10h.",
},
timeout=30,
)
print(resposta.status_code, resposta.json())
<?php
$ch = curl_init('https://app.nextagsai.com.br/api/pipelines/4002/opportunities/4201/comments');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'X-ACCESS-TOKEN: ' . getenv('NEXTAGS_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'content' => 'Pagamento confirmado. Entrega no sábado, às 10h.',
]),
]);
$dados = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($dados);
A resposta traz o comentário, com o texto em data:
{
"id": 4301,
"data": "Pagamento confirmado. Entrega no sábado, às 10h.",
"created_at": "2026-10-26 12:05:00",
"created_by": 10001
}Para ler os comentários, use Listar comentários da oportunidade; para apagar, Apagar comentário.
Pronto: como conferir
- Consultar oportunidade mostra a etapa em
stage, ostatuse os responsáveis. - Na NexTags, o cartão aparece na coluna da etapa, com o valor, a prioridade e o comentário. Veja Oportunidades e tickets: criar, mover, ganhar e perder.
Se não funcionou
401 com "No valid API key provided."
A chave não chegou ou não vale. Veja Autenticação com a chave de API.
A oportunidade foi criada duas vezes
A criação rodou sem a busca antes. Liste as oportunidades do contato (passo 4) antes de criar. Para apagar a repetida, use Apagar oportunidade.
Depois de mover, o valor, a prioridade ou os responsáveis mudaram
Se a atualização foi sem os valores atuais, os campos que faltaram podem ter voltado ao padrão. Consulte a oportunidade antes (passo 6) e mande de volta tudo o que deve ficar igual.
A oportunidade entrou na primeira etapa
O stage_id não veio ou não é deste pipeline. Liste as etapas do pipeline (passo 2) e use um ID da lista.
O campo do pipeline ficou vazio
O nome ou o ID do campo não bate com os do pipeline. Liste os campos (passo 3) e use o id ou o name exatos.
O pipeline de suporte mostra outros estados
Nos pipelines de suporte, a tela mostra Resolvido e Não Resolvido no lugar de Ganho e Perdido. Confira no primeiro teste como won e lost aparecem no seu pipeline.
Faça com a IA
Copie o pedido e cole no ChatGPT ou no Claude.
Leia https://docs.nextags.com.br/guias/oportunidades-no-pipeline.md.
Quero ligar o [seu sistema, por exemplo: o CRM ou o checkout] ao pipeline [nome] da NexTags: criar a oportunidade quando [evento], mover para a etapa [nome] quando [evento] e marcar como ganha quando [evento], com um comentário em cada mudança. Escreva, em [linguagem], o código com os IDs numa configuração, que procura a oportunidade do contato antes de criar e sempre manda os valores atuais na atualização. A chave vem da variável de ambiente NEXTAGS_API_KEY.
Relacionados
Este conteúdo ajudou?
Obrigado! Sua resposta ajuda a melhorar a central.