Vault ERP API REST: Visão Geral e Referência Completa

A API REST do Vault ERP oferece acesso programático completo ao seu negócio de relógios de luxo seminovos. Com ela, você pode integrar seu catálogo de estoque, pipeline de vendas e base de clientes com lojas virtuais, marketplaces, sistemas de CRM externos e fluxos de trabalho personalizados — tudo via requisições HTTP padrão.

Base URL

Todas as requisições devem ser feitas para:

https://api.vault-erp.com/v1

Formato

Todas as requisições e respostas utilizam JSON. Inclua os headers abaixo em todas as chamadas:

Content-Type: application/json
Accept: application/json

Respostas com corpo vazio (por exemplo, 204 No Content) não retornam payload JSON.

Versionamento

A versão atual da API é v1, presente no prefixo da Base URL. Mudanças que quebram compatibilidade retroativa (breaking changes) serão lançadas sob um novo prefixo de versão (por exemplo, /v2). A versão anterior continuará recebendo suporte por 12 meses após o lançamento de uma nova versão — tempo suficiente para você migrar suas integrações sem pressa. Melhorias não-destrutivas (novos campos opcionais, novos endpoints, novos valores de enum) podem ser adicionadas à versão atual sem aviso prévio.

Paginação

Todos os endpoints de listagem retornam resultados paginados. Controle a paginação com os parâmetros de query:

Parâmetro	Padrão	Máximo	Descrição
`page`	`1`	—	Número da página desejada
`per_page`	`20`	`100`	Quantidade de itens por página

Toda resposta paginada inclui um objeto meta com informações de navegação:

{
  "data": [...],
  "meta": {
    "total": 142,
    "page": 1,
    "per_page": 20,
    "last_page": 8
  }
}

array

Array com os itens da página atual.

integer

Número total de itens em todas as páginas.

integer

Número da página atual.

integer

Quantidade de itens retornados nesta página.

integer

Número da última página disponível.

Erros

A API utiliza os códigos de status HTTP padrão para indicar o resultado de cada requisição:

Código	Status	Descrição
`200`	OK	Requisição bem-sucedida.
`201`	Created	Recurso criado com sucesso.
`400`	Bad Request	Erro de validação — verifique os campos enviados.
`401`	Unauthorized	API key ausente ou inválida.
`403`	Forbidden	API key válida, mas sem permissão para esta operação.
`404`	Not Found	Recurso não encontrado.
`422`	Unprocessable Entity	Erro de regra de negócio — a requisição é válida, mas não pode ser executada.
`429`	Too Many Requests	Limite de requisições atingido. Aguarde antes de tentar novamente.
`500`	Internal Server Error	Erro interno no servidor do Vault ERP.

Todas as respostas de erro seguem a mesma estrutura:

{
  "error": {
    "code": "WATCH_NOT_FOUND",
    "message": "Watch with ID 'watch_abc123' was not found in your catalog.",
    "request_id": "req_xyz789"
  }
}

string

Código de erro legível por máquina para tratamento programático (ex.: WATCH_NOT_FOUND, UNAUTHORIZED).

string

Mensagem descritiva explicando o problema.

string

Identificador único da requisição. Inclua este valor ao contatar o suporte para diagnóstico.

Rate Limiting

Cada API key pode realizar até 1.000 requisições por minuto. O status do seu limite atual é informado nos headers de toda resposta:

Header	Descrição
`X-RateLimit-Limit`	Número total de requisições permitidas por minuto.
`X-RateLimit-Remaining`	Requisições restantes na janela atual.
`X-RateLimit-Reset`	Timestamp Unix indicando quando a janela de limite será reiniciada.

Ao atingir o limite, a API retorna 429 Too Many Requests. Aguarde até o timestamp indicado em X-RateLimit-Reset antes de retomar as chamadas.

Relatórios via API

O Vault ERP disponibiliza dois endpoints de relatório para você exportar e processar dados consolidados de estoque e vendas em sistemas externos — painéis de BI, planilhas automatizadas ou pipelines de dados.

GET /reports/inventory

Retorna um relatório consolidado do estoque atual, com contagens por status, marca e tipo de estoque (próprio ou consignado).

curl https://api.vault-erp.com/v1/reports/inventory \
  -H "Authorization: Bearer seu_api_key" \
  -H "Accept: application/json"

Resposta de exemplo:

{
  "data": {
    "generated_at": "2024-03-20T18:00:00Z",
    "totals": {
      "disponivel": 28,
      "reservado": 4,
      "consignado": 12,
      "vendido": 198
    },
    "by_brand": [
      { "brand": "Rolex", "count": 15, "total_asking_price": 127500000 },
      { "brand": "Patek Philippe", "count": 6, "total_asking_price": 132000000 },
      { "brand": "Audemars Piguet", "count": 5, "total_asking_price": 96000000 }
    ],
    "by_stock_type": {
      "proprio": 32,
      "consignado": 12
    }
  }
}

GET /reports/sales

Retorna um relatório consolidado de vendas fechadas, incluindo volume de negócios, ticket médio e comparativos por período.

curl "https://api.vault-erp.com/v1/reports/sales?start_date=2024-01-01&end_date=2024-03-31" \
  -H "Authorization: Bearer seu_api_key" \
  -H "Accept: application/json"

Os parâmetros de query start_date e end_date (formato YYYY-MM-DD) são opcionais. Quando omitidos, o relatório abrange os últimos 30 dias. Resposta de exemplo:

{
  "data": {
    "generated_at": "2024-03-20T18:00:00Z",
    "period": {
      "start_date": "2024-01-01",
      "end_date": "2024-03-31"
    },
    "totals": {
      "sales_count": 42,
      "gross_revenue": 358200000,
      "average_ticket": 8528571,
      "closed_lost": 11
    },
    "by_month": [
      { "month": "2024-01", "sales_count": 12, "gross_revenue": 98400000 },
      { "month": "2024-02", "sales_count": 15, "gross_revenue": 123600000 },
      { "month": "2024-03", "sales_count": 15, "gross_revenue": 136200000 }
    ]
  }
}

Os endpoints de relatório retornam dados agregados calculados em tempo real. Para conjuntos de dados muito grandes, a resposta pode levar alguns segundos a mais do que os endpoints de listagem padrão. Consulte a documentação de Relatórios Financeiros para mais detalhes sobre os campos disponíveis e interpretação dos dados.

Próximos Passos

Autenticação

Aprenda a gerar e usar API keys para autenticar suas requisições.

Relógios

Gerencie seu catálogo: liste, cadastre e atualize peças em estoque.

Vendas

Crie negociações, mova pelo pipeline e registre fechamentos.

Clientes

Sincronize perfis de compradores e consignantes com sistemas externos.

Webhooks

Receba notificações em tempo real sobre eventos críticos do negócio.

​Base URL

​Formato

​Versionamento

​Paginação

​Erros

​Rate Limiting

​Relatórios via API

​GET /reports/inventory

​GET /reports/sales

​Próximos Passos

Autenticação

Relógios

Vendas

Clientes

Webhooks

Base URL

Formato

Versionamento

Paginação

Erros

Rate Limiting

Relatórios via API

GET /reports/inventory

GET /reports/sales

Próximos Passos