# 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.

Endereço: https://docs.nextags.com.br/guias/oportunidades-no-pipeline/
Tipo: Guia

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**

- A chave de API na variável de ambiente `NEXTAGS_API_KEY`. Veja [Autenticação com a chave de API](https://docs.nextags.com.br/comecar/autenticacao/).
- Um pipeline criado na NexTags. Veja [Criar um pipeline a partir de um modelo](https://help.nextags.com.br/tutoriais/pipelines/criar-pipeline/).
- O ID do contato e, se for atribuir a oportunidade, o ID do administrador. Veja [Contatos, fluxos e outros identificadores](https://docs.nextags.com.br/comecar/identificadores/).

## Passo a passo

### Passo 1: Liste os pipelines

Use [Listar pipelines](https://docs.nextags.com.br/referencia/pipelines/listar-pipelines/) para achar o ID do pipeline:

**Listar pipelines**

```bash
curl "https://app.nextagsai.com.br/api/pipelines" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
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);
```
```python
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
<?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);
```

```json
{"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](https://docs.nextags.com.br/comecar/limites-e-erros/).

### Passo 2: Liste as etapas

Use [Listar etapas do pipeline](https://docs.nextags.com.br/referencia/pipelines/listar-etapas-do-pipeline/). As etapas vêm na lista `data`:

**Listar etapas do pipeline**

```bash
curl "https://app.nextagsai.com.br/api/pipelines/4001/stages" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
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);
```
```python
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
<?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);
```

```json
{
  "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](https://docs.nextags.com.br/referencia/pipelines/listar-campos-do-pipeline/) para ver o `id`, o `name`, o `type` e a `description` de cada um:

**Listar campos do pipeline**

```bash
curl "https://app.nextagsai.com.br/api/pipelines/4001/custom_fields" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
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);
```
```python
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
<?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](https://help.nextags.com.br/tutoriais/pipelines/comentarios-e-anexos/).

### Passo 4: Procure antes de criar

Use [Listar oportunidades](https://docs.nextags.com.br/referencia/pipelines/listar-oportunidades/) com o `contact_id` para ver se o contato já tem uma oportunidade neste pipeline:

**Oportunidades do contato**

```bash
curl "https://app.nextagsai.com.br/api/pipelines/4001/opportunities?contact_id=123456789" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
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);
```
```python
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
<?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](https://docs.nextags.com.br/referencia/pipelines/criar-oportunidade/). O `contact_id` e o `title` são obrigatórios; o resto é opcional:

**Criar oportunidade**

```bash
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"
      }
    ]
  }'
```
```javascript
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);
```
```python
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
<?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`:

```json
{
  "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](https://docs.nextags.com.br/referencia/pipelines/consultar-oportunidade/) para ter os valores atuais:

**Consultar oportunidade**

```bash
curl "https://app.nextagsai.com.br/api/pipelines/4001/opportunities/4201" \
  -H "X-ACCESS-TOKEN: $NEXTAGS_API_KEY"
```
```javascript
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);
```
```python
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
<?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](https://docs.nextags.com.br/referencia/pipelines/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**

```bash
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
    ]
  }'
```
```javascript
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);
```
```python
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
<?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:

**Marcar como ganha**

```bash
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
    ]
  }'
```
```javascript
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);
```
```python
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
<?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](https://docs.nextags.com.br/referencia/pipelines/apagar-oportunidade/) (`DELETE` no mesmo endereço).

### Passo 9: Transfira para outro pipeline

Use [Transferir oportunidade de pipeline](https://docs.nextags.com.br/referencia/pipelines/transferir-oportunidade-de-pipeline/), com o pipeline e a etapa de destino. Os dois são obrigatórios:

**Transferir para o Pós-venda**

```bash
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
  }'
```
```javascript
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);
```
```python
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
<?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](https://docs.nextags.com.br/referencia/pipelines/listar-etapas-do-pipeline/).

### Passo 10: Comente na oportunidade

Use [Comentar na oportunidade](https://docs.nextags.com.br/referencia/pipelines/comentar-na-oportunidade/), com o texto em `content`:

**Comentar na oportunidade**

```bash
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."
  }'
```
```javascript
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);
```
```python
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
<?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`:

```json
{
  "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](https://docs.nextags.com.br/referencia/pipelines/listar-comentarios-da-oportunidade/); para apagar, [Apagar comentário](https://docs.nextags.com.br/referencia/pipelines/apagar-comentario/).

## Pronto: como conferir

- [Consultar oportunidade](https://docs.nextags.com.br/referencia/pipelines/consultar-oportunidade/) mostra a etapa em `stage`, o `status` e 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](https://help.nextags.com.br/tutoriais/pipelines/oportunidades/).

## 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](https://docs.nextags.com.br/comecar/autenticacao/).

### 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](https://docs.nextags.com.br/referencia/pipelines/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

Cole este pedido no ChatGPT ou no Claude:

```text
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.
```