Pular para o conteúdo
Acessar conta

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.

Guia12 min
Atualizado em 26/10/2026

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

Passo a passo

Passo 1: Liste os pipelines

Use Listar pipelines para achar o ID do pipeline:

Listar pipelines
curl "https://app.nextagsai.com.br/api/pipelines" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
{"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:

Listar etapas do pipeline
curl "https://app.nextagsai.com.br/api/pipelines/4001/stages" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
{
  "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:

Listar campos do pipeline
curl "https://app.nextagsai.com.br/api/pipelines/4001/custom_fields" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

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:

Oportunidades do contato
curl "https://app.nextagsai.com.br/api/pipelines/4001/opportunities?contact_id=123456789" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

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:

Criar oportunidade
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"
      }
    ]
  }'
CampoO que é
stage_idA etapa. Sem ele, a oportunidade entra na primeira etapa.
valueO valor. O contrato não diz a unidade: confira no primeiro teste como ele aparece no cartão.
statusopen (Aberto, o padrão), won (Ganho) ou lost (Perdido).
prioritylow (Baixa), medium (Média, o padrão) ou high (Alta).
assigned_adminsOs IDs dos administradores responsáveis.
custom_fieldsOs 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:

Consultar oportunidade
curl "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"

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):

Mover para Proposta enviada
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
    ]
  }'

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:

Marcar como ganha
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
    ]
  }'

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:

Transferir para o Pós-venda
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
  }'

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:

Comentar na oportunidade
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."
  }'

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

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.