API de Relógios: Catálogo, Estoque e Autenticações

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.

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

string

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

string

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

string

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

integer

default:"1"

Número da página de resultados.

integer

default:"20"

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

Exemplo de Requisição

curl "https://api.vault-erp.com/v1/watches?status=disponivel&brand=Rolex" \
  -H "Authorization: Bearer seu_api_key"

Exemplo de Resposta

{
  "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

string

required

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

string

required

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

string

required

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

string

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

integer

Ano de fabricação ou compra original.

string

required

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

boolean

required

true se a caixa original acompanha o relógio.

boolean

required

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

string

required

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

integer

required

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

string

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

Exemplo de Requisição

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

{
  "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/

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

Parâmetros de Path

string

required

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

Exemplo de Requisição

curl https://api.vault-erp.com/v1/watches/watch_abc123 \
  -H "Authorization: Bearer seu_api_key"

Exemplo de Resposta

{
  "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/

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

Parâmetros de Path

string

required

Identificador único do relógio a ser atualizado.

Campos do Body

integer

Novo preço de venda em centavos de real.

string

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

string

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

boolean

Atualiza a presença da caixa original.

boolean

Atualiza a presença dos documentos originais.

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

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

{
  "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//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

string

required

Identificador único do relógio.

Campos do Body

string

required

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

string

required

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

string

required

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

string

required

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

string

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

Exemplo de Requisição

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

{
  "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"
  }
}

​GET /watches

​Parâmetros de Query

​Exemplo de Requisição

​Exemplo de Resposta

​POST /watches

​Campos do Body

​Exemplo de Requisição

​Exemplo de Resposta

​GET /watches/

​Parâmetros de Path

​Exemplo de Requisição

​Exemplo de Resposta

​PATCH /watches/

​Parâmetros de Path

​Campos do Body

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

​Exemplo de Resposta

​POST /watches//authenticate

​Parâmetros de Path

​Campos do Body

​Exemplo de Requisição

​Exemplo de Resposta

GET /watches

Parâmetros de Query

Exemplo de Requisição

Exemplo de Resposta

POST /watches

Campos do Body

Exemplo de Requisição

Exemplo de Resposta

GET /watches/

Parâmetros de Path

Exemplo de Requisição

Exemplo de Resposta

PATCH /watches/

Parâmetros de Path

Campos do Body

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

Exemplo de Resposta

POST /watches//authenticate

Parâmetros de Path

Campos do Body

Exemplo de Requisição

Exemplo de Resposta