> For the complete documentation index, see [llms.txt](https://docs.sprinthub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sprinthub.com/topicos/api/api-listar-oportunidades-do-funil-com-filtros-e-paginacao.md).

# API - Listar Oportunidades do Funil com Filtros e Paginação

Complementa a página [API - Chamada API para Listar Oportunidades de um Lead](https://docs.sprinthub.com/topicos/api/api-chamada-api-para-listar-oportunidades-de-um-lead.md). Enquanto aquele endpoint retorna todas as oportunidades de **um lead específico**, este retorna as oportunidades de **um funil inteiro**, com filtros, ordenação implícita do Kanban, paginação e, principalmente, a possibilidade de paginar **coluna por coluna (etapa por etapa)** através do parâmetro `columnId`.

É o mesmo endpoint que a interface do CRM usa para montar o Kanban: cada coluna carrega sua própria página de cards, de forma independente das demais.

### Listar oportunidades de um funil

**`POST`** `/crm/opportunities/{funnelId}?i=suainstancia&apitoken=xxxxxx`

`{funnelId}` = ID do funil (CRM). No exemplo abaixo, `8`.

Endpoint completo: `https://sprinthub-api-master.sprinthub.app/crm/opportunities/8?i=suainstancia&apitoken=xxxxxx`

> **Base da API.** `https://sprinthub-api-master.sprinthub.app` é a URL base. Substitua `suainstancia` pelo nome da sua instância, o mesmo que aparece na URL do painel, e `xxxxxx` pela sua chave de API.

#### Parâmetros de URL

| Parâmetro  | Obrigatório | Descrição                                      |
| ---------- | ----------- | ---------------------------------------------- |
| `i`        | Sim         | Nome da instância. Exemplo: `?i=suainstancia`. |
| `apitoken` | Sim         | Chave de API da instância.                     |

#### Headers

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |

As oportunidades retornadas respeitam as permissões vinculadas à chave de API (Departamentos, Grupos de Permissões e permissões do funil).

***

### Antes de começar: descobrindo o `funnelId` e o `columnId`

O `funnelId` da URL é o ID do CRM (funil). Para listar todos os funis da instância em uma única chamada GET:

```bash
curl --location 'https://sprinthub-api-master.sprinthub.app/crm?i=suainstancia&apitoken=xxxxxx'
```

Cada funil retornado traz seu ID, que é o valor usado em `/crm/opportunities/{funnelId}`, e as etapas do funil, cujos IDs alimentam o parâmetro `columnId` do corpo da requisição.

Os IDs de etapa também aparecem no campo `crm_column` de cada oportunidade retornada por este endpoint, o que serve como conferência rápida.

### Corpo da requisição

```json
{
    "filterByUsers": [],
    "filterByStatus": ["open"],
    "filterByCreateDate": null,
    "filterByExpectedCloseDate": null,
    "filters": [],
    "search": "",
    "searchBy": "lead",
    "page": 5,
    "limit": 25,
    "columnId": 58,
    "onlyArchived": false
}
```

#### Referência dos parâmetros

| Parâmetro                   | Tipo              | Padrão   | Descrição                                                                                                            |
| --------------------------- | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `filterByUsers`             | array de inteiros | `[]`     | IDs dos usuários responsáveis pelas oportunidades. Vazio retorna todos os responsáveis visíveis para a sessão.       |
| `filterByStatus`            | array de strings  | `[]`     | Status das oportunidades: `open`, `gain`, `lost`. Aceita mais de um. Vazio retorna todos.                            |
| `filterByCreateDate`        | objeto ou `null`  | `null`   | Período de criação da oportunidade. `null` desliga o filtro.                                                         |
| `filterByExpectedCloseDate` | objeto ou `null`  | `null`   | Período de fechamento previsto. `null` desliga o filtro.                                                             |
| `filters`                   | array de objetos  | `[]`     | Filtros avançados (condições combinadas sobre campos da oportunidade, do lead e da empresa). Vazio desliga o filtro. |
| `search`                    | string            | `""`     | Termo de busca textual. Vazio desliga a busca.                                                                       |
| `searchBy`                  | string            | `"lead"` | Define onde o termo de `search` é aplicado. `lead` busca pelos dados do contato vinculado à oportunidade.            |
| `page`                      | inteiro           | `1`      | Página desejada. A primeira página é `1`.                                                                            |
| `limit`                     | inteiro           | `25`     | Quantidade de oportunidades por página.                                                                              |
| `columnId`                  | inteiro           | -        | ID da coluna (etapa) do funil. Restringe o resultado a uma única etapa e pagina apenas dentro dela.                  |
| `onlyArchived`              | booleano          | `false`  | `true` retorna somente oportunidades arquivadas. `false` retorna somente as não arquivadas.                          |

#### Detalhamento dos filtros

**`filterByUsers`**

Filtra pelo responsável da oportunidade. Corresponde ao filtro **Responsável** da interface.

```json
"filterByUsers": [12, 47]
```

Retorna oportunidades cujo responsável seja o usuário 12 ou o 47. O array vazio não significa "nenhum responsável": significa "sem filtro por responsável".

**`filterByStatus`**

Corresponde ao filtro **Status**.

| Valor  | Significado            |
| ------ | ---------------------- |
| `open` | Oportunidade em aberto |
| `gain` | Oportunidade ganha     |
| `lost` | Oportunidade perdida   |

```json
"filterByStatus": ["gain", "lost"]
```

> **Atenção.** A visualização de oportunidades ganhas e perdidas depende da permissão **CRM - Oportunidades Ganhas e Perdidas** do grupo do usuário. Se a chave de API não tiver essa permissão, o filtro não trará esses registros.

**`filterByCreateDate` e `filterByExpectedCloseDate`**

Filtram por período: data de criação da oportunidade e data de fechamento previsto, respectivamente. Correspondem aos filtros **Data de criação** e **Data de fechamento esperada** da interface.

```json
"filterByCreateDate": {
    "start": "2026-08-01",
    "end": "2026-08-31"
}
```

Enviar `null` (ou omitir) desliga o filtro. Os dois filtros são independentes e podem ser combinados na mesma requisição.

**`filters`**

Recebe os **Filtros Avançados** do CRM: condições montadas sobre campos da oportunidade, do lead ou da empresa, inclusive campos personalizados. Cada item do array representa uma condição, e as condições são combinadas entre si.

```json
"filters": [
    {
        "field": "custom_field_id_ou_nome",
        "operator": "equals",
        "value": "Plano Premium"
    }
]
```

A forma mais segura de descobrir a estrutura exata de uma condição é montá-la na interface do CRM e inspecionar o corpo da requisição enviada pelo navegador. O array vazio equivale a "sem filtros avançados".

**`search` e `searchBy`**

`search` é o termo digitado. `searchBy` define o alvo da busca. Com `searchBy: "lead"`, o termo é comparado com os dados do contato vinculado à oportunidade (nome, telefone, e-mail), e não com o título do card.

```json
"search": "maria",
"searchBy": "lead"
```

`search` vazio ignora `searchBy`.

**`onlyArchived`**

Alterna entre as duas visões da base. Não existe visão combinada: ou a requisição traz arquivadas, ou traz não arquivadas.

```json
"onlyArchived": true
```

***

### Paginação por coluna do funil

Este é o ponto central deste endpoint. O CRM não pagina o funil como uma lista única: cada coluna do Kanban é uma sequência de páginas própria.

* Com `columnId` preenchido, `page` e `limit` navegam **apenas dentro daquela etapa**. `page: 5` com `limit: 25` retorna as oportunidades da 101ª à 125ª posição **daquela coluna**, na ordem em que aparecem no Kanban.
* Sem `columnId`, `page` e `limit` navegam pelo funil inteiro, misturando as etapas.
* Os filtros são aplicados **antes** da paginação. Mudar qualquer filtro reinicia a contagem: volte para `page: 1`.
* O fim da coluna é detectado quando a resposta traz menos itens do que o `limit` solicitado, ou quando traz um array vazio.

#### Exemplo: quinta página da coluna 58

```bash
curl --location 'https://sprinthub-api-master.sprinthub.app/crm/opportunities/8?i=suainstancia&apitoken=xxxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "filterByUsers": [],
    "filterByStatus": ["open"],
    "filterByCreateDate": null,
    "filterByExpectedCloseDate": null,
    "filters": [],
    "search": "",
    "searchBy": "lead",
    "page": 5,
    "limit": 25,
    "columnId": 58,
    "onlyArchived": false
}'
```

#### Exemplo: funil inteiro, sem separar por etapa

Basta omitir `columnId`.

```bash
curl --location 'https://sprinthub-api-master.sprinthub.app/crm/opportunities/8?i=suainstancia&apitoken=xxxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "filterByUsers": [],
    "filterByStatus": ["open"],
    "filterByCreateDate": null,
    "filterByExpectedCloseDate": null,
    "filters": [],
    "search": "",
    "searchBy": "lead",
    "page": 1,
    "limit": 50,
    "onlyArchived": false
}'
```

#### Exemplo: ganhas no mês, de dois vendedores, em uma etapa

```bash
curl --location 'https://sprinthub-api-master.sprinthub.app/crm/opportunities/8?i=suainstancia&apitoken=xxxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "filterByUsers": [12, 47],
    "filterByStatus": ["gain"],
    "filterByCreateDate": {
        "start": "2026-08-01",
        "end": "2026-08-31"
    },
    "filterByExpectedCloseDate": null,
    "filters": [],
    "search": "",
    "searchBy": "lead",
    "page": 1,
    "limit": 25,
    "columnId": 58,
    "onlyArchived": false
}'
```

#### Exemplo: varrer uma coluna inteira

```javascript
async function listarColunaCompleta(funnelId, columnId, apitoken, instancia) {
  const base = `https://sprinthub-api-master.sprinthub.app/crm/opportunities/${funnelId}?i=${instancia}&apitoken=${apitoken}`;
  const limit = 50;
  let page = 1;
  const todas = [];

  while (true) {
    const res = await fetch(base, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        filterByUsers: [],
        filterByStatus: ["open"],
        filterByCreateDate: null,
        filterByExpectedCloseDate: null,
        filters: [],
        search: "",
        searchBy: "lead",
        page,
        limit,
        columnId,
        onlyArchived: false,
      }),
    });

    const pagina = await res.json();
    const itens = Array.isArray(pagina) ? pagina : pagina.opportunities || [];

    todas.push(...itens);
    if (itens.length < limit) break;
    page++;
  }

  return todas;
}
```

Para varrer o funil inteiro etapa por etapa, execute a função acima em laço sobre os IDs das colunas do funil. Essa é a forma recomendada de exportar grandes volumes: cada coluna é uma sequência menor e mais estável do que uma paginação única sobre o funil todo, que sofre deslocamento sempre que um card muda de etapa durante a varredura.

***

### Respostas

#### 200 OK

```json
[
    {
        "id": 4533,
        "title": "Test Oportunidade",
        "value": "1.00",
        "crm_column": 58,
        "lead_id": 8473,
        "sequence": 2
        ...
    }
]
```

Cada item traz `crm_column` igual ao `columnId` solicitado, quando o filtro por coluna é usado.

#### 400 Bad Request

```json
{
    "error": "Invalid request"
}
```

Corpo malformado ou `funnelId` inexistente.

#### 401 Unauthorized

```json
{
    "error": "Unauthorized"
}
```

`apitoken` ausente, inválido ou sem permissão sobre o funil solicitado.

***

### Boas práticas

* Use `limit` entre 25 e 50 para alimentar interfaces. Valores altos aumentam o tempo de resposta e o risco de timeout.
* Ao reaplicar filtros, sempre reinicie `page` em `1`.
* Prefira paginar por `columnId` quando o objetivo é reproduzir o Kanban ou exportar o funil de forma previsível.
* Envie todos os campos do corpo, mesmo os desligados (`[]` ou `null`). Isso mantém o payload compatível com a interface e facilita a depuração comparando com as requisições do navegador.
* Os resultados sempre respeitam as permissões da chave de API. Duas chaves diferentes podem receber contagens diferentes para os mesmos filtros.
