# Criar e consultar negócios pela API

## Listar negócios

Use `GET /api/v1/deals`. Sem `status`, a consulta inclui `open`, `won` e `lost`. Para consultar apenas abertos, envie `status=open`; para vários estados, repita o parâmetro ou separe por vírgula.

```bash
curl --get 'https://pipefacil-server.matchsales.com.br/api/v1/deals' \
  --header "Authorization: Bearer $PIPEFACIL_API_KEY" \
  --data-urlencode 'status=open' \
  --data-urlencode 'pipeline=1' \
  --data-urlencode 'limit=50'
```

`pipeline` recebe a sequência do funil. `stageId`, `tagIds` e `responsibleUserIds` recebem IDs técnicos. Os negócios vêm pela criação mais recente. Os filtros do aplicativo não são todos parâmetros dessa rota: consulte a [referência](/api/resources/deals/methods/list-deals/).

Para valores exatos, use `customFields[slug]`. O valor `__empty__` seleciona campos não preenchidos. Para intervalos, use `customFieldRanges[slug][from]` e `[to]`. Os slugs nativos incluem `value`, `close_probability`, `expected_close_at`, `stage_changed_at`, `updated_at`, `lost_reason` e `lost_from_stage`; os dois últimos usam valores exatos.

## Criar um negócio

`POST /api/v1/deals` aceita telefone opcional. Sem telefone ou dados de contato, o negócio pode ficar sem contato. Com nome ou e-mail, pode ser criado um contato sem telefone.

```json
{
	"name": "Proposta de consultoria",
	"contactFirstName": "Ana",
	"contactLastName": "Silva",
	"email": "ana@example.com",
	"value": 1500,
	"currency": "BRL"
}
```

Envie primeiro nome e sobrenome separados. Quando usados, eles têm preferência sobre `contactName`. `stageId` escolhe a etapa inicial; quando omitido, o servidor usa a primeira etapa do funil escolhido pelas regras de criação.

O corpo também aceita campos personalizados, empresa, dados de rastreio e metadados. Use `tracking.ctwaClid` para o identificador de clique Click to WhatsApp quando ele estiver disponível na origem.

## Atualizar e consultar o detalhe

Use `GET /api/v1/deals/{seq}` e `PATCH /api/v1/deals/{seq}`. O PATCH aceita alterações parciais; revise as regras de movimento, campos obrigatórios e motivo da perda antes de mudar a etapa.

`properties` contém valores resolvidos dos campos personalizados. Resumo de tarefas e última atividade podem ser nulos quando não estiverem habilitados na configuração do card. `lostFromStage` informa a etapa anterior à perda.

Para extrair valores de campos em vários negócios, use `GET /api/v1/deals/custom-field-values` com os filtros da referência.

## Notas, tarefas e atividade

| Ação                     | Rota                                    |
| ------------------------ | --------------------------------------- |
| Criar nota               | `POST /api/v1/deals/{seq}/notes`        |
| Criar tarefa             | `POST /api/v1/deals/{seq}/tasks`        |
| Consultar atividade      | `GET /api/v1/deals/{seq}/activities`    |
| Adicionar ou remover tag | Operações de `/api/v1/deals/{seq}/tags` |

Confira o retorno de cada escrita. As tarefas têm corpo próprio, com prazo e responsável; os tipos aceitos estão na referência. Não use os exemplos de uma nota como corpo de uma tarefa.

## Receba um lead de um site ou sistema próprio

A interface chama o negócio de **lead**; a API usa **deal**. Para integrar um formulário externo, comece pela [autenticação](/developers/authentication/) e siga esta sequência:

1. Consulte `GET /api/v1/pipelines` e escolha a etapa de destino. Para `stageId`, use o identificador técnico `id` da etapa, não sua sequência.
2. Envie `POST /api/v1/deals` com os dados do formulário e o `stageId` escolhido. Confira os campos exigidos pelo funil.
3. Leia a sequência `seq` retornada para consultar o registro em `GET /api/v1/deals/{seq}` e conferir o resultado.

Criar o registro e enviar uma mensagem são operações distintas. Uma automação ativa com gatilho **Lead criado** pode executar ações após o cadastro. Revise o fluxo de [primeiro atendimento](/automacoes/primeiro-atendimento/) e as regras do canal antes de integrar a origem. O contrato completo do corpo está em [Criar negócio](/api/resources/deals/methods/create-deal/).