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

# API de Vendas: Gerenciar Negociações e Fechamentos

> Endpoints REST para criar, atualizar e consultar vendas e negociações no pipeline do Vault ERP, com exemplos de request e response.

A API de Vendas permite criar negociações, mover oportunidades pelo pipeline comercial e registrar fechamentos de forma programática — ideal para integrar CRMs externos, plataformas de e-commerce ou fluxos de automação com o Vault ERP. Cada negociação (*deal*) representa a jornada de um relógio específico desde o primeiro contato com um cliente até o fechamento da venda.

> [!NOTE]
>
> Valores monetários são sempre representados em **centavos de real (BRL)**. Por exemplo, `8100000` = R\$81.000,00. Consulte a [Visão Geral da API](https://docs.vaulterp.com.br/api/overview.md) para mais detalhes sobre formatos.

***

## GET /sales

Lista todas as negociações do pipeline, com suporte a filtros por status e paginação.

### Parâmetros de Query

**status** `string`

Filtra pelo estágio atual da negociação no pipeline. Valores aceitos: `prospecto`, `em_negociacao`, `proposta_enviada`, `reservado`, `fechado_ganho`, `fechado_perdido`.

**page** `integer` (default: 1)

Número da página de resultados.

**per\_page** `integer` (default: 20)

Itens por página. Máximo: `100`.

### Exemplo de Requisição

```bash theme={null}
curl "https://api.vault-erp.com/v1/sales?status=em_negociacao" \
  -H "Authorization: Bearer seu_api_key"
```

### Exemplo de Resposta

```json theme={null}
{
  "data": [
    {
      "id": "sale_xyz456",
      "watch_id": "watch_abc123",
      "customer_id": "cust_def789",
      "status": "em_negociacao",
      "asking_price": 8500000,
      "final_price": null,
      "salesperson_id": "user_sp001",
      "notes": "Customer interested, requesting service history.",
      "created_at": "2024-03-10T09:00:00Z",
      "closed_at": null
    },
    {
      "id": "sale_uvw789",
      "watch_id": "watch_pq9r2s",
      "customer_id": "cust_ghi012",
      "status": "fechado_ganho",
      "asking_price": 22000000,
      "final_price": 21500000,
      "salesperson_id": "user_sp002",
      "notes": null,
      "created_at": "2024-02-28T11:30:00Z",
      "closed_at": "2024-03-05T15:45:00Z"
    }
  ],
  "meta": {
    "total": 27,
    "page": 1,
    "per_page": 20,
    "last_page": 2
  }
}
```

**Campos do objeto Sale**

**id** `string`

Identificador único da negociação.

**watch\_id** `string`

ID do relógio associado a esta negociação.

**customer\_id** `string`

ID do cliente comprador.

**status** `string`

Estágio atual no pipeline: `prospecto`, `em_negociacao`, `proposta_enviada`, `reservado`, `fechado_ganho` ou `fechado_perdido`.

**asking\_price** `integer`

Preço de tabela no momento da abertura da negociação, em centavos.

**final\_price** `integer | null`

Preço final acordado no fechamento, em centavos. `null` enquanto a negociação estiver em aberto.

**salesperson\_id** `string | null`

ID do vendedor responsável pela negociação.

**created\_at** `string`

Data e hora de criação da negociação (ISO 8601 UTC).

**closed\_at** `string | null`

Data e hora do fechamento (ISO 8601 UTC). `null` enquanto em aberto.

***

## POST /sales

Abre uma nova negociação para um relógio e um cliente específicos. O status inicial é sempre `prospecto`.

### Campos do Body

**watch\_id** `string` *required*

ID do relógio que está sendo negociado. O relógio deve ter status `disponivel` no catálogo.

**customer\_id** `string` *required*

ID do cliente interessado na compra.

**asking\_price** `integer` *required*

Preço de tabela no início da negociação, em centavos de real. Geralmente corresponde ao `asking_price` do relógio.

**salesperson\_id** `string`

ID do vendedor responsável. Se omitido, a negociação fica sem vendedor atribuído.

### Exemplo de Requisição

```bash theme={null}
curl -X POST https://api.vault-erp.com/v1/sales \
  -H "Authorization: Bearer seu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "watch_id": "watch_abc123",
    "customer_id": "cust_def789",
    "asking_price": 8500000,
    "salesperson_id": "user_sp001"
  }'
```

### Exemplo de Resposta

```json theme={null}
{
  "data": {
    "id": "sale_new001",
    "watch_id": "watch_abc123",
    "customer_id": "cust_def789",
    "status": "prospecto",
    "asking_price": 8500000,
    "final_price": null,
    "salesperson_id": "user_sp001",
    "notes": null,
    "created_at": "2024-03-20T14:00:00Z",
    "closed_at": null
  }
}
```

***

## PATCH /sales/{id}

Atualiza uma negociação existente — avança o estágio no pipeline, registra o preço final ou adiciona observações. Envie apenas os campos que deseja alterar.

### Parâmetros de Path

**id** `string` *required*

Identificador único da negociação.

### Campos do Body

**status** `string`

Novo estágio no pipeline. Valores aceitos: `prospecto`, `em_negociacao`, `proposta_enviada`, `reservado`, `fechado_ganho`, `fechado_perdido`.

Ao mover para `fechado_ganho`, o status do relógio associado é automaticamente atualizado para `vendido`. Ao mover para `reservado`, o relógio é marcado como `reservado`.

**final\_price** `integer`

Preço final acordado, em centavos. Obrigatório ao fechar com `fechado_ganho`.

**notes** `string`

Observações sobre a negociação (histórico de conversa, condições especiais, motivo de perda, etc.).

### Exemplo de Requisição — Fechando uma Venda

```bash theme={null}
curl -X PATCH https://api.vault-erp.com/v1/sales/sale_xyz456 \
  -H "Authorization: Bearer seu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "fechado_ganho", "final_price": 8100000}'
```

### Exemplo de Resposta

```json theme={null}
{
  "data": {
    "id": "sale_xyz456",
    "watch_id": "watch_abc123",
    "customer_id": "cust_def789",
    "status": "fechado_ganho",
    "asking_price": 8500000,
    "final_price": 8100000,
    "salesperson_id": "user_sp001",
    "notes": null,
    "created_at": "2024-03-10T09:00:00Z",
    "closed_at": "2024-03-20T14:30:00Z"
  }
}
```

### Exemplo de Requisição — Avançando no Pipeline

```bash theme={null}
curl -X PATCH https://api.vault-erp.com/v1/sales/sale_xyz456 \
  -H "Authorization: Bearer seu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "proposta_enviada",
    "notes": "Sent formal proposal via email. Customer will respond by Friday."
  }'
```

### Exemplo de Requisição — Registrando Perda

```bash theme={null}
curl -X PATCH https://api.vault-erp.com/v1/sales/sale_xyz456 \
  -H "Authorization: Bearer seu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "fechado_perdido",
    "notes": "Customer bought from a competitor. Price was the main objection."
  }'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.