> ## 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 Relógios: Catálogo, Estoque e Autenticações

> Endpoints REST para listar, criar, atualizar e autenticar relógios no catálogo do Vault ERP. Inclui exemplos completos de request e response.

A API de Relógios oferece controle programático completo sobre o catálogo do Vault ERP. Você pode listar o estoque disponível, cadastrar novas peças (próprias ou em consignação), atualizar informações como preço e condição, e registrar laudos de autenticação — tudo via HTTP, sem precisar acessar o painel.

> [!NOTE]
>
> Todos os valores monetários são representados em **centavos de real (BRL)**. Por exemplo, `8500000` corresponde a R\$85.000,00. Isso evita problemas de arredondamento com ponto flutuante e garante precisão nas operações financeiras.

***

## GET /watches

Lista todos os relógios do catálogo, com suporte a filtros e paginação.

### Parâmetros de Query

**status** `string`

Filtra pelo status atual do relógio no estoque. Valores aceitos: `disponivel`, `reservado`, `vendido`, `consignado`, `devolvido`.

**brand** `string`

Filtra pelo nome da marca (ex.: `Rolex`, `Patek Philippe`, `Audemars Piguet`). A busca é case-insensitive.

**reference** `string`

Filtra pela referência do fabricante (ex.: `126610LN`, `5711/1A-010`).

**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/watches?status=disponivel&brand=Rolex" \
  -H "Authorization: Bearer seu_api_key"
```

### Exemplo de Resposta

```json theme={null}
{
  "data": [
    {
      "id": "watch_abc123",
      "brand": "Rolex",
      "model": "Submariner Date",
      "reference": "126610LN",
      "serial_number": "F123456",
      "year": 2022,
      "condition": "excelente",
      "has_box": true,
      "has_papers": true,
      "status": "disponivel",
      "asking_price": 8500000,
      "stock_type": "proprio",
      "created_at": "2024-01-15T14:30:00Z"
    }
  ],
  "meta": {
    "total": 34,
    "page": 1,
    "per_page": 20,
    "last_page": 2
  }
}
```

***

## POST /watches

Adiciona um novo relógio ao catálogo. Relógios em consignação exigem o campo `consignee_id`.

### Campos do Body

**brand** `string` *required*

Nome da marca do relógio (ex.: `Rolex`, `Omega`, `IWC`).

**model** `string` *required*

Nome do modelo (ex.: `Submariner Date`, `Speedmaster Professional`).

**reference** `string` *required*

Referência oficial do fabricante (ex.: `126610LN`).

**serial\_number** `string`

Número de série do relógio, gravado na caixa pelo fabricante.

**year** `integer`

Ano de fabricação ou compra original.

**condition** `string` *required*

Estado de conservação da peça. Valores aceitos: `novo`, `excelente`, `muito_bom`, `bom`, `regular`.

**has\_box** `boolean` *required*

`true` se a caixa original acompanha o relógio.

**has\_papers** `boolean` *required*

`true` se os papéis/documentos originais acompanham o relógio.

**stock\_type** `string` *required*

Tipo de estoque. `proprio` para peças da loja; `consignado` para peças de terceiros.

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

Preço de venda em centavos de real (BRL). Ex.: `8500000` = R\$85.000,00.

**consignee\_id** `string`

ID do cliente consignante. **Obrigatório** quando `stock_type` é `consignado`.

### Exemplo de Requisição

```bash theme={null}
curl -X POST https://api.vault-erp.com/v1/watches \
  -H "Authorization: Bearer seu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "Patek Philippe",
    "model": "Nautilus",
    "reference": "5711/1A-010",
    "year": 2020,
    "condition": "excelente",
    "has_box": true,
    "has_papers": true,
    "stock_type": "proprio",
    "asking_price": 22000000
  }'
```

### Exemplo de Resposta

```json theme={null}
{
  "data": {
    "id": "watch_pq9r2s",
    "brand": "Patek Philippe",
    "model": "Nautilus",
    "reference": "5711/1A-010",
    "serial_number": null,
    "year": 2020,
    "condition": "excelente",
    "has_box": true,
    "has_papers": true,
    "status": "disponivel",
    "asking_price": 22000000,
    "stock_type": "proprio",
    "consignee_id": null,
    "created_at": "2024-03-20T10:15:00Z"
  }
}
```

***

## GET /watches/{id}

Retorna os detalhes completos de um único relógio, incluindo histórico de autenticações.

### Parâmetros de Path

**id** `string` *required*

Identificador único do relógio (ex.: `watch_abc123`).

### Exemplo de Requisição

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

### Exemplo de Resposta

```json theme={null}
{
  "data": {
    "id": "watch_abc123",
    "brand": "Rolex",
    "model": "Submariner Date",
    "reference": "126610LN",
    "serial_number": "F123456",
    "year": 2022,
    "condition": "excelente",
    "has_box": true,
    "has_papers": true,
    "status": "disponivel",
    "asking_price": 8500000,
    "stock_type": "proprio",
    "consignee_id": null,
    "authentications": [
      {
        "id": "auth_001",
        "authenticator_name": "WatchCSA",
        "authentication_type": "externa",
        "result": "autentico",
        "date": "2024-01-20",
        "notes": "All hallmarks verified. Movement consistent with reference."
      }
    ],
    "created_at": "2024-01-15T14:30:00Z",
    "updated_at": "2024-01-20T09:00:00Z"
  }
}
```

***

## PATCH /watches/{id}

Atualiza campos específicos de um relógio. Envie apenas os campos que deseja alterar — os demais permanecem inalterados.

### Parâmetros de Path

**id** `string` *required*

Identificador único do relógio a ser atualizado.

### Campos do Body

**asking\_price** `integer`

Novo preço de venda em centavos de real.

**condition** `string`

Novo estado de conservação. Valores: `novo`, `excelente`, `muito_bom`, `bom`, `regular`.

**status** `string`

Novo status no estoque. Valores: `disponivel`, `reservado`, `vendido`, `consignado`, `devolvido`.

**has\_box** `boolean`

Atualiza a presença da caixa original.

**has\_papers** `boolean`

Atualiza a presença dos documentos originais.

### Exemplo de Requisição — Ajuste de Preço

```bash theme={null}
curl -X PATCH https://api.vault-erp.com/v1/watches/watch_abc123 \
  -H "Authorization: Bearer seu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"asking_price": 8200000}'
```

### Exemplo de Resposta

```json theme={null}
{
  "data": {
    "id": "watch_abc123",
    "brand": "Rolex",
    "model": "Submariner Date",
    "reference": "126610LN",
    "asking_price": 8200000,
    "status": "disponivel",
    "updated_at": "2024-03-15T16:00:00Z"
  }
}
```

***

## POST /watches/{id}/authenticate

Registra um laudo de autenticação para o relógio. Autenticações são imutáveis após criação — em caso de erro, entre em contato com o suporte.

### Parâmetros de Path

**id** `string` *required*

Identificador único do relógio.

### Campos do Body

**authenticator\_name** `string` *required*

Nome do autenticador ou empresa responsável pelo laudo (ex.: `WatchCSA`, `Equipe Interna`).

**authentication\_type** `string` *required*

Tipo de autenticação. `interna` para avaliação pela equipe da loja; `externa` para laudos de terceiros certificados.

**result** `string` *required*

Resultado da autenticação. Valores aceitos: `autentico`, `inconclusivo`, `nao_autentico`.

**date** `string` *required*

Data em que a autenticação foi realizada, no formato `YYYY-MM-DD`.

**notes** `string`

Observações adicionais do autenticador (ex.: descrição de marcas verificadas, condição do movimento).

### Exemplo de Requisição

```bash theme={null}
curl -X POST https://api.vault-erp.com/v1/watches/watch_abc123/authenticate \
  -H "Authorization: Bearer seu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "authenticator_name": "WatchCSA",
    "authentication_type": "externa",
    "result": "autentico",
    "date": "2024-03-18",
    "notes": "All hallmarks verified. Movement consistent with reference 126610LN."
  }'
```

### Exemplo de Resposta

```json theme={null}
{
  "data": {
    "id": "auth_002",
    "watch_id": "watch_abc123",
    "authenticator_name": "WatchCSA",
    "authentication_type": "externa",
    "result": "autentico",
    "date": "2024-03-18",
    "notes": "All hallmarks verified. Movement consistent with reference 126610LN.",
    "created_at": "2024-03-18T11:30:00Z"
  }
}
```


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