> ## 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.

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

> A API REST do Vault ERP permite integrar seu catálogo, vendas e clientes com sistemas externos. Base URL, versionamento e formatos explicados.

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:

```bash theme={null}
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:

```json theme={null}
{
  "data": [...],
  "meta": {
    "total": 142,
    "page": 1,
    "per_page": 20,
    "last_page": 8
  }
}
```

**data** `array`

Array com os itens da página atual.

**meta.total** `integer`

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

**meta.page** `integer`

Número da página atual.

**meta.per\_page** `integer`

Quantidade de itens retornados nesta página.

**meta.last\_page** `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:

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

**error.code** `string`

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

**error.message** `string`

Mensagem descritiva explicando o problema.

**error.request\_id** `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).

```bash theme={null}
curl https://api.vault-erp.com/v1/reports/inventory \
  -H "Authorization: Bearer seu_api_key" \
  -H "Accept: application/json"
```

Resposta de exemplo:

```json theme={null}
{
  "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.

```bash theme={null}
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:

```json theme={null}
{
  "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 }
    ]
  }
}
```

> [!NOTE]
>
> 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](https://docs.vaulterp.com.br/finance/reports.md) para mais detalhes sobre os campos disponíveis e interpretação dos dados.

## Próximos Passos

> **[Autenticação](https://docs.vaulterp.com.br/api/authentication.md)**
>
> Aprenda a gerar e usar API keys para autenticar suas requisições.

> **[Relógios](https://docs.vaulterp.com.br/api/watches.md)**
>
> Gerencie seu catálogo: liste, cadastre e atualize peças em estoque.

> **[Vendas](https://docs.vaulterp.com.br/api/sales.md)**
>
> Crie negociações, mova pelo pipeline e registre fechamentos.

> **[Clientes](https://docs.vaulterp.com.br/api/customers.md)**
>
> Sincronize perfis de compradores e consignantes com sistemas externos.

> **[Webhooks](https://docs.vaulterp.com.br/api/webhooks.md)**
>
> Receba notificações em tempo real sobre eventos críticos do negócio.


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