# Listar negócios

`GET /api/v1/deals`

Página de negócios visíveis ao membro da chave, ordenada pela criação mais recente. Sem status, inclui abertos, ganhos e perdidos. Mantenha os mesmos filtros ao reutilizar o cursor.

## Autenticação

Envie a chave em `Authorization: Bearer pf_live_…`.

## Parâmetros

| Nome | Local | Obrigatório | Tipo | Descrição |
| --- | --- | --- | --- | --- |
| `pipeline` | query | Não | `integer` | Número sequencial do funil dentro do workspace. |
| `stageId` | query | Não | `string` | — |
| `returning` | query | Não | `boolean` | — |
| `createdFrom` | query | Não | `string` | yyyy-MM-dd |
| `createdTo` | query | Não | `string` | yyyy-MM-dd |
| `source` | query | Não | `string` | Slug da origem do negócio, por exemplo, manual ou whatsapp. |
| `responsibleUserIds` | query | Não | `array` | Pode ser repetido ou informado como lista separada por vírgulas. |
| `tagIds` | query | Não | `array` | Pode ser repetido ou informado como lista separada por vírgulas. |
| `search` | query | Não | `string` | Busca por negócio, contato ou telefone. |
| `limit` | query | Não | `integer` | — |
| `cursor` | query | Não | `string` | Cursor opaco retornado pela página anterior. |
| `customFields[slug]` | query | Não | `string` | Filtra pelo valor de um campo personalizado, usando o slug: `customFields[budget]=high`. O valor reservado `__empty__` inclui negócios sem preenchimento (campo ausente, nulo, texto vazio ou lista vazia). Pode ser combinado com outros valores, usando a regra OU. |
| `status` | query | Não | `array` | Situações do negócio. Repita o parâmetro ou separe os valores por vírgula. Omitido: todas as situações. |
| `customFieldRanges[slug][from]` | query | Não | `string` | Limite inicial do intervalo de um campo de data. Substitua slug pela chave do campo. |
| `customFieldRanges[slug][to]` | query | Não | `string` | Limite final do intervalo de um campo de data. Combine com o limite inicial ou envie apenas um limite. |

## Respostas

### 200

Sucesso

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `data` | `object` | Não |  |
| `data.items` | `array` | Não |  |
| `data.items[].id` | `string` | Não |  |
| `data.items[].seq` | `integer` | Não |  |
| `data.items[].name` | `string` | Não |  |
| `data.items[].value` | `number` | Não |  |
| `data.items[].currency` | `string` | Não |  |
| `data.items[].closeProbability` | `integer` | Não |  |
| `data.items[].source` | `string` | Não |  |
| `data.items[].status` | `string` | Não |  |
| `data.items[].isReturning` | `boolean` | Não |  |
| `data.items[].pipelineId` | `string` | Não |  |
| `data.items[].stageId` | `string` | Não |  |
| `data.items[].responsibleUserId` | `string` | Não |  |
| `data.items[].coOwnerUserId` | `string` | Não | Aceita null. |
| `data.items[].lostReason` | `string` | Não | Aceita null. |
| `data.items[].notes` | `string` | Não | Aceita null. |
| `data.items[].daysInStage` | `integer` | Não |  |
| `data.items[].tags` | `array` | Não |  |
| `data.items[].tags[].id` | `string` | Não |  |
| `data.items[].tags[].name` | `string` | Não |  |
| `data.items[].tags[].color` | `string` | Não |  |
| `data.items[].responsible` | `DealMember` | Não |  |
| `data.items[].responsible.userId` | `string` | Não |  |
| `data.items[].responsible.name` | `string` | Não | Aceita null. |
| `data.items[].coOwner` | `object` | Não | Aceita null. |
| `data.items[].coOwner.userId` | `string` | Não |  |
| `data.items[].coOwner.name` | `string` | Não | Aceita null. |
| `data.items[].activeChannels` | `array` | Não |  |
| `data.items[].lastMessageAt` | `string` | Não | Formato: date-time. Aceita null. |
| `data.items[].lastMessageText` | `string` | Não |  |
| `data.items[].replyPending` | `boolean` | Não |  |
| `data.items[].properties` | `object` | Não | Valores resolvidos dos campos personalizados. |
| `data.items[].channel` | `object` | Não | Aceita null. |
| `data.items[].channelOverride` | `object` | Não | Aceita null. |
| `data.items[].expectedCloseAt` | `string` | Não | Formato: date-time. Aceita null. |
| `data.items[].stageChangedAt` | `string` | Não | Formato: date-time. |
| `data.items[].closedAt` | `string` | Não | Formato: date-time. Aceita null. |
| `data.items[].returnSignaledAt` | `string` | Não | Formato: date-time. Aceita null. |
| `data.items[].contact` | `object` | Não | Aceita null. |
| `data.items[].stage` | `object` | Não | Aceita null. |
| `data.items[].company` | `object` | Não | Aceita null. |
| `data.items[].createdAt` | `string` | Não | Formato: date-time. |
| `data.items[].updatedAt` | `string` | Não | Formato: date-time. |
| `data.items[].tracking` | `object` | Não | Aceita null. |
| `data.items[].tracking.utmContent` | `string` | Não | Aceita null. |
| `data.items[].tracking.utmMedium` | `string` | Não | Aceita null. |
| `data.items[].tracking.utmCampaign` | `string` | Não | Aceita null. |
| `data.items[].tracking.utmSource` | `string` | Não | Aceita null. |
| `data.items[].tracking.utmTerm` | `string` | Não | Aceita null. |
| `data.items[].tracking.utmReferrer` | `string` | Não | Aceita null. |
| `data.items[].tracking.referrer` | `string` | Não | Aceita null. |
| `data.items[].tracking.gclientid` | `string` | Não | Aceita null. |
| `data.items[].tracking.gclid` | `string` | Não | Aceita null. |
| `data.items[].tracking.fbclid` | `string` | Não | Aceita null. |
| `data.items[].tracking.metaLeadId` | `string` | Não | Aceita null. |
| `data.items[].tracking.fbp` | `string` | Não | Aceita null. |
| `data.items[].tracking.fbc` | `string` | Não | Aceita null. |
| `data.items[].tracking.clientIpAddress` | `string` | Não | Aceita null. |
| `data.items[].tracking.clientUserAgent` | `string` | Não | Aceita null. |
| `data.items[].tracking.ctwaClid` | `string` | Não | Aceita null. |
| `data.items[].lostFromStage` | `object` | Não | Aceita null. |
| `data.items[].lostFromStage.id` | `string` | Não |  |
| `data.items[].lostFromStage.name` | `string` | Não |  |
| `data.items[].lostFromStage.pipelineId` | `string` | Não |  |
| `data.items[].taskSummary` | `object` | Não | Resumo de tarefas quando habilitado na configuração do card. Aceita null. |
| `data.items[].taskSummary.pendingCount` | `integer` | Não |  |
| `data.items[].taskSummary.overdueCount` | `integer` | Não |  |
| `data.items[].taskSummary.nextTask` | `object` | Não | Aceita null. |
| `data.items[].taskSummary.nextTask.id` | `string` | Não |  |
| `data.items[].taskSummary.nextTask.title` | `string` | Não |  |
| `data.items[].taskSummary.nextTask.dueAt` | `string` | Não | Formato: date-time. Aceita null. |
| `data.items[].taskSummary.nextTask.categoryName` | `string` | Não | Aceita null. |
| `data.items[].taskSummary.nextTask.categoryColor` | `string` | Não | Aceita null. |
| `data.items[].lastActivity` | `object` | Não | Última atividade quando habilitada na configuração do card. Aceita null. |
| `data.items[].lastActivity.id` | `string` | Não |  |
| `data.items[].lastActivity.type` | `string` | Não |  |
| `data.items[].lastActivity.occurredAt` | `string` | Não | Formato: date-time. |
| `data.items[].lastActivity.title` | `string` | Não |  |
| `data.items[].lastActivity.body` | `string` | Não | Aceita null. |
| `data.items[].lastActivity.meta` | `object` | Não |  |
| `data.items[].lastActivity.actor` | `object` | Não | Aceita null. |
| `data.items[].lastActivity.actor.actorType` | `string` | Não |  |
| `data.items[].lastActivity.actor.userId` | `string` | Não | Aceita null. |
| `data.items[].lastActivity.actor.userName` | `string` | Não | Aceita null. |
| `data.items[].lastActivity.actor.userAvatarUrl` | `string` | Não | Aceita null. |
| `data.items[].lastActivity.actor.automationId` | `string` | Não | Aceita null. |
| `data.items[].lastActivity.actor.automationName` | `string` | Não | Aceita null. |
| `data.items[].lastActivity.actor.copilotActionId` | `string` | Não | Aceita null. |
| `data.items[].lastActivity.actor.apiKeyId` | `string` | Não | Aceita null. |
| `data.nextCursor` | `string` | Não | Aceita null. |
| `data.hasMore` | `boolean` | Não |  |
| `message` | `string` | Não | Aceita null. |

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/DealListItem"
          }
        },
        "nextCursor": {
          "type": "string",
          "nullable": true
        },
        "hasMore": {
          "type": "boolean"
        }
      }
    },
    "message": {
      "type": "string",
      "nullable": true
    }
  }
}
```

### 401

Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo.

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `error` | `string` | Sim |  |
| `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. |
| `requestId` | `string` | Sim |  |
| `details` | `string` | Não | Aceita null. |
| `fieldErrors` | `array` | Não | Aceita null. |
| `fieldErrors[].field` | `string` | Não |  |
| `fieldErrors[].message` | `string` | Não |  |

```json
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
```

### 429

Limite de requisições excedido por workspace ou IP.

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `error` | `string` | Sim |  |
| `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. |
| `requestId` | `string` | Sim |  |
| `details` | `string` | Não | Aceita null. |
| `fieldErrors` | `array` | Não | Aceita null. |
| `fieldErrors[].field` | `string` | Não |  |
| `fieldErrors[].message` | `string` | Não |  |

```json
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
```