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

# Criar negócio

> Cria um novo negócio em um funil de venda.

## Endpoint

```
POST /v1/deals
```

**Escopo necessário:** `write:deals`

## Corpo da requisição

| Campo                 | Tipo      | Obrigatório | Descrição                                                       |
| --------------------- | --------- | ----------- | --------------------------------------------------------------- |
| `title`               | string    | Sim         | Título do negócio                                               |
| `pipeline_id`         | string    | Sim         | ID do pipeline                                                  |
| `stage_id`            | string    | Não         | ID da etapa. Se omitido, usa a primeira etapa do funil de venda |
| `value`               | number    | Não         | Valor em reais. Padrão: `0`                                     |
| `contact_ids`         | string\[] | Não         | IDs dos contatos vinculados                                     |
| `company_id`          | string    | Não         | ID da empresa                                                   |
| `assigned_to`         | string    | Não         | ID do membro responsável                                        |
| `expected_close_date` | string    | Não         | Data prevista de fechamento (ISO 8601)                          |
| `tags`                | string\[] | Não         | Tags                                                            |
| `custom_fields`       | object    | Não         | Campos personalizados                                           |

## Obtendo o pipeline\_id

Use `GET /v1/pipelines` para listar os pipelines disponíveis e seus IDs de etapas.

## Exemplo de requisição

```bash theme={null}
curl -X POST https://api.socialsell.ai/v1/deals \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Contrato Anual - TechCorp",
    "pipeline_id": "664a1b2c3d4e5f6789012345",
    "value": 36000,
    "contact_ids": ["664f1a2b3c4d5e6f78901234"],
    "company_id": "664b1c2d3e4f5a6789012346",
    "expected_close_date": "2026-08-31T00:00:00.000Z",
    "tags": ["contrato-anual"]
  }'
```

## Resposta

Retorna `HTTP 201` com o objeto negócio criado.

A criação dispara o evento `deal.created` em webhooks configurados.

## Erros

| Código                   | Status | Descrição                              |
| ------------------------ | ------ | -------------------------------------- |
| `MISSING_REQUIRED_FIELD` | `400`  | `title` ou `pipeline_id` ausente       |
| `PIPELINE_NOT_FOUND`     | `404`  | Funil de venda não encontrado          |
| `STAGE_NOT_FOUND`        | `404`  | Etapa não encontrada no funil de venda |
| `NO_STAGES`              | `422`  | Funil de venda não tem etapas          |