> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vistum.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Buscar negócios

> Lista os negócios (cards do pipeline) do workspace com filtros por pipeline, etapa, status, responsável, produto e datas.

Um **negócio** (internamente `PipelineCard`) é uma oportunidade de venda vinculada a um contato, posicionada em uma etapa de um pipeline. Todos os endpoints são escopados ao workspace da chave e nunca retornam negócios excluídos (soft-delete).

## Autenticação

<ParamField header="Authorization" type="string" required>
  `Bearer vg_live_<sua_chave>` — API Key com escopo `deals:read`
</ParamField>

## Parâmetros de query

| Parâmetro          | Tipo         | Descrição                                                         |
| ------------------ | ------------ | ----------------------------------------------------------------- |
| `q`                | string       | Busca por nome (case-insensitive) ou telefone (contém).           |
| `pipelineId`       | string       | Filtra negócios cujo estágio pertence a este pipeline.            |
| `stageId`          | string       | Filtra por etapa específica.                                      |
| `status`           | string       | `open`, `won` ou `lost`. Valor fora disso é ignorado.             |
| `assignedTo`       | string       | ID do usuário responsável.                                        |
| `productId`        | string       | ID do produto associado.                                          |
| `createdAfter`     | string (ISO) | Criados a partir desta data.                                      |
| `createdBefore`    | string (ISO) | Criados até esta data.                                            |
| `sort`             | string       | `createdAt` (padrão), `updatedAt`, `value`, `name` ou `closedAt`. |
| `order`            | string       | `asc` ou `desc` (padrão).                                         |
| `limit` / `offset` | number       | Paginação (1–100, padrão 25).                                     |

<RequestExample>
  ```bash cURL theme={null}
  curl "https://crm.vistum.com.br/api/v1/deals?status=open&pipelineId=pipe_vendas01&limit=25" \
    -H "Authorization: Bearer vg_live_SUA_CHAVE_AQUI"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 — OK theme={null}
  {
    "data": [
      {
        "id": "card_def456ghi",
        "name": "João Ferreira",
        "phone": "5511999887766",
        "value": "2500.00",
        "status": "open",
        "origin": "landing-page",
        "stage": { "id": "stage_qualif01", "name": "Qualificação" },
        "pipeline": { "id": "pipe_vendas01", "name": "Vendas" },
        "product": { "id": "prod_x1", "name": "Plano PRO" },
        "assignedUser": { "id": "usr_carlos", "name": "Carlos Atendente" },
        "customValues": { "cidade": "São Paulo" },
        "createdAt": "2026-07-01T12:00:00.000Z",
        "updatedAt": "2026-07-02T09:30:00.000Z",
        "closedAt": null,
        "lostReason": null
      }
    ],
    "pagination": { "total": 1, "limit": 25, "offset": 0, "hasMore": false }
  }
  ```
</ResponseExample>

<Note>
  `value` é sempre uma **string decimal** (ex: `"2500.00"`), nunca um número — precisão monetária não sobrevive a float em JSON.
</Note>