> ## 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 Clientes: Perfis, Histórico e Lista de Desejos

> Endpoints REST para criar, atualizar e consultar clientes no CRM do Vault ERP, incluindo histórico de compras e listas de desejos.

A API de Clientes permite sincronizar perfis de compradores e consignantes entre o Vault ERP e sistemas externos — CRMs, plataformas de e-commerce, sistemas de automação de marketing e afins. Você pode criar e atualizar cadastros, consultar o histórico completo de negociações de um cliente e gerenciar sua lista de desejos (*wishlist*), que alimenta alertas automáticos quando uma peça compatível entra no estoque.

***

## GET /customers

Lista todos os clientes cadastrados no CRM, com suporte a filtros e busca textual.

### Parâmetros de Query

**search** `string`

Busca textual por nome, e-mail, CPF ou CNPJ. A busca é case-insensitive e aceita termos parciais.

**tag** `string`

Filtra clientes que possuam a tag especificada (ex.: `vip`, `consignante`, `prospect`).

**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/customers?tag=vip&per_page=50" \
  -H "Authorization: Bearer seu_api_key"
```

### Exemplo de Resposta

```json theme={null}
{
  "data": [
    {
      "id": "cust_def789",
      "name": "Carlos Mendonça",
      "document": "123.456.789-00",
      "email": "carlos@exemplo.com.br",
      "phone": "+55 11 99999-0000",
      "type": "pessoa_fisica",
      "tags": ["vip", "colecionador"],
      "created_at": "2023-08-10T12:00:00Z"
    }
  ],
  "meta": {
    "total": 8,
    "page": 1,
    "per_page": 50,
    "last_page": 1
  }
}
```

***

## POST /customers

Cadastra um novo cliente no CRM. O campo `document` aceita CPF (pessoa física) ou CNPJ (pessoa jurídica), com ou sem formatação.

### Campos do Body

**name** `string` *required*

Nome completo do cliente (pessoa física) ou razão social (pessoa jurídica).

**document** `string` *required*

CPF ou CNPJ do cliente. Aceita com ou sem pontuação (ex.: `123.456.789-00` ou `12345678900`).

**email** `string` *required*

Endereço de e-mail principal do cliente.

**phone** `string`

Telefone principal, incluindo código do país e DDD (ex.: `+55 11 99999-0000`).

**type** `string` *required*

Tipo de pessoa. `pessoa_fisica` para CPF; `pessoa_juridica` para CNPJ.

**tags** `array`

Lista de tags para categorização do cliente (ex.: `["vip", "colecionador", "consignante"]`). Tags são criadas automaticamente se ainda não existirem.

### Exemplo de Requisição

```bash theme={null}
curl -X POST https://api.vault-erp.com/v1/customers \
  -H "Authorization: Bearer seu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ana Beatriz Fontana",
    "document": "987.654.321-00",
    "email": "ana@fontana.com.br",
    "phone": "+55 21 98888-1234",
    "type": "pessoa_fisica",
    "tags": ["vip", "colecionadora"]
  }'
```

### Exemplo de Resposta

```json theme={null}
{
  "data": {
    "id": "cust_jkl321",
    "name": "Ana Beatriz Fontana",
    "document": "987.654.321-00",
    "email": "ana@fontana.com.br",
    "phone": "+55 21 98888-1234",
    "type": "pessoa_fisica",
    "tags": ["vip", "colecionadora"],
    "created_at": "2024-03-20T15:00:00Z",
    "updated_at": "2024-03-20T15:00:00Z"
  }
}
```

***

## GET /customers/{id}

Retorna o perfil completo de um cliente, incluindo um resumo do histórico de compras e negociações.

### Parâmetros de Path

**id** `string` *required*

Identificador único do cliente.

### Exemplo de Requisição

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

### Exemplo de Resposta

```json theme={null}
{
  "data": {
    "id": "cust_def789",
    "name": "Carlos Mendonça",
    "document": "123.456.789-00",
    "email": "carlos@exemplo.com.br",
    "phone": "+55 11 99999-0000",
    "type": "pessoa_fisica",
    "tags": ["vip", "colecionador"],
    "purchase_summary": {
      "total_purchases": 5,
      "total_spent": 42000000,
      "last_purchase_at": "2024-02-10T13:00:00Z"
    },
    "open_deals": 1,
    "wishlist_items": 3,
    "created_at": "2023-08-10T12:00:00Z",
    "updated_at": "2024-03-01T09:30:00Z"
  }
}
```

**Campos do objeto purchase\_summary**

**total\_purchases** `integer`

Número total de compras finalizadas pelo cliente.

**total\_spent** `integer`

Valor total gasto pelo cliente em centavos de real, considerando apenas negociações `fechado_ganho`.

**last\_purchase\_at** `string | null`

Data e hora da compra mais recente (ISO 8601 UTC). `null` se o cliente nunca finalizou uma compra.

***

## PATCH /customers/{id}

Atualiza dados cadastrais de um cliente. Envie apenas os campos que deseja modificar.

### Parâmetros de Path

**id** `string` *required*

Identificador único do cliente.

### Campos do Body

**name** `string`

Nome atualizado do cliente.

**email** `string`

Novo endereço de e-mail.

**phone** `string`

Novo número de telefone.

**tags** `array`

Nova lista completa de tags. Este campo **substitui** todas as tags existentes — inclua as tags que deseja manter.

### Exemplo de Requisição

```bash theme={null}
curl -X PATCH https://api.vault-erp.com/v1/customers/cust_def789 \
  -H "Authorization: Bearer seu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "carlos.mendonca@novoemail.com.br",
    "tags": ["vip", "colecionador", "consignante"]
  }'
```

***

## GET /customers/{id}/wishlist

Lista todos os itens da lista de desejos de um cliente. O Vault ERP monitora automaticamente o estoque e dispara o evento `customer.wishlist_match` via webhook quando um relógio compatível é cadastrado.

### Parâmetros de Path

**id** `string` *required*

Identificador único do cliente.

### Exemplo de Requisição

```bash theme={null}
curl https://api.vault-erp.com/v1/customers/cust_def789/wishlist \
  -H "Authorization: Bearer seu_api_key"
```

### Exemplo de Resposta

```json theme={null}
{
  "data": [
    {
      "id": "wish_001",
      "reference": "5726A-001",
      "brand_hint": "Patek Philippe",
      "max_price": 35000000,
      "min_condition": "muito_bom",
      "requires_box": true,
      "created_at": "2024-01-05T10:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20,
    "last_page": 1
  }
}
```

***

## POST /customers/{id}/wishlist

Adiciona um item à lista de desejos de um cliente. O Vault ERP usa esses critérios para disparar alertas automáticos quando peças compatíveis entram no estoque.

### Parâmetros de Path

**id** `string` *required*

Identificador único do cliente.

### Campos do Body

**reference** `string` *required*

Referência do fabricante do relógio desejado (ex.: `5711/1A-010`, `126610LN`). É o campo de correspondência principal para alertas automáticos.

**max\_price** `integer`

Preço máximo que o cliente está disposto a pagar, em centavos de real. Se informado, apenas peças com `asking_price` menor ou igual a este valor acionarão o alerta.

**min\_condition** `string`

Condição mínima aceitável para o relógio. Valores: `novo`, `excelente`, `muito_bom`, `bom`, `regular`.

**requires\_box** `boolean`

Se `true`, o alerta só é disparado para peças que incluam a caixa original.

### Exemplo de Requisição

```bash theme={null}
curl -X POST https://api.vault-erp.com/v1/customers/cust_def789/wishlist \
  -H "Authorization: Bearer seu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "5726A-001",
    "max_price": 35000000,
    "min_condition": "muito_bom",
    "requires_box": true
  }'
```

### Exemplo de Resposta

```json theme={null}
{
  "data": {
    "id": "wish_002",
    "customer_id": "cust_def789",
    "reference": "5726A-001",
    "max_price": 35000000,
    "min_condition": "muito_bom",
    "requires_box": true,
    "created_at": "2024-03-20T16:00:00Z"
  }
}
```


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