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

string

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

string

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

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

Exemplo de Resposta

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

string

required

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

string

required

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

string

required

Endereço de e-mail principal do cliente.

string

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

string

required

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

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

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

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

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

Parâmetros de Path

string

required

Identificador único do cliente.

Exemplo de Requisição

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

Exemplo de Resposta

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

Show Campos do objeto purchase_summary

integer

Número total de compras finalizadas pelo cliente.

integer

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

string | null

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

PATCH /customers/

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

Parâmetros de Path

string

required

Identificador único do cliente.

Campos do Body

string

Nome atualizado do cliente.

string

Novo endereço de e-mail.

string

Novo número de telefone.

array

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

Exemplo de Requisição

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

string

required

Identificador único do cliente.

Exemplo de Requisição

curl https://api.vault-erp.com/v1/customers/cust_def789/wishlist \
  -H "Authorization: Bearer seu_api_key"

Exemplo de Resposta

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

string

required

Identificador único do cliente.

Campos do Body

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.

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.

string

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

boolean

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

Exemplo de Requisição

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

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

​GET /customers

​Parâmetros de Query

​Exemplo de Requisição

​Exemplo de Resposta

​POST /customers

​Campos do Body

​Exemplo de Requisição

​Exemplo de Resposta

​GET /customers/

​Parâmetros de Path

​Exemplo de Requisição

​Exemplo de Resposta

​PATCH /customers/

​Parâmetros de Path

​Campos do Body

​Exemplo de Requisição

​GET /customers//wishlist

​Parâmetros de Path

​Exemplo de Requisição

​Exemplo de Resposta

​POST /customers//wishlist

​Parâmetros de Path

​Campos do Body

​Exemplo de Requisição

​Exemplo de Resposta

GET /customers

Parâmetros de Query

Exemplo de Requisição

Exemplo de Resposta

POST /customers

Campos do Body

Exemplo de Requisição

Exemplo de Resposta

GET /customers/

Parâmetros de Path

Exemplo de Requisição

Exemplo de Resposta

PATCH /customers/

Parâmetros de Path

Campos do Body

Exemplo de Requisição

GET /customers//wishlist

Parâmetros de Path

Exemplo de Requisição

Exemplo de Resposta

POST /customers//wishlist

Parâmetros de Path

Campos do Body

Exemplo de Requisição

Exemplo de Resposta