API de Vendas: Gerenciar Negociações e Fechamentos

A API de Vendas permite criar negociações, mover oportunidades pelo pipeline comercial e registrar fechamentos de forma programática — ideal para integrar CRMs externos, plataformas de e-commerce ou fluxos de automação com o Vault ERP. Cada negociação (deal) representa a jornada de um relógio específico desde o primeiro contato com um cliente até o fechamento da venda.

Valores monetários são sempre representados em centavos de real (BRL). Por exemplo, 8100000 = R$81.000,00. Consulte a Visão Geral da API para mais detalhes sobre formatos.

GET /sales

Lista todas as negociações do pipeline, com suporte a filtros por status e paginação.

Parâmetros de Query

string

Filtra pelo estágio atual da negociação no pipeline. Valores aceitos: prospecto, em_negociacao, proposta_enviada, reservado, fechado_ganho, fechado_perdido.

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/sales?status=em_negociacao" \
  -H "Authorization: Bearer seu_api_key"

Exemplo de Resposta

{
  "data": [
    {
      "id": "sale_xyz456",
      "watch_id": "watch_abc123",
      "customer_id": "cust_def789",
      "status": "em_negociacao",
      "asking_price": 8500000,
      "final_price": null,
      "salesperson_id": "user_sp001",
      "notes": "Customer interested, requesting service history.",
      "created_at": "2024-03-10T09:00:00Z",
      "closed_at": null
    },
    {
      "id": "sale_uvw789",
      "watch_id": "watch_pq9r2s",
      "customer_id": "cust_ghi012",
      "status": "fechado_ganho",
      "asking_price": 22000000,
      "final_price": 21500000,
      "salesperson_id": "user_sp002",
      "notes": null,
      "created_at": "2024-02-28T11:30:00Z",
      "closed_at": "2024-03-05T15:45:00Z"
    }
  ],
  "meta": {
    "total": 27,
    "page": 1,
    "per_page": 20,
    "last_page": 2
  }
}

Show Campos do objeto Sale

string

Identificador único da negociação.

string

ID do relógio associado a esta negociação.

string

ID do cliente comprador.

string

Estágio atual no pipeline: prospecto, em_negociacao, proposta_enviada, reservado, fechado_ganho ou fechado_perdido.

integer

Preço de tabela no momento da abertura da negociação, em centavos.

integer | null

Preço final acordado no fechamento, em centavos. null enquanto a negociação estiver em aberto.

string | null

ID do vendedor responsável pela negociação.

string

Data e hora de criação da negociação (ISO 8601 UTC).

string | null

Data e hora do fechamento (ISO 8601 UTC). null enquanto em aberto.

POST /sales

Abre uma nova negociação para um relógio e um cliente específicos. O status inicial é sempre prospecto.

Campos do Body

string

required

ID do relógio que está sendo negociado. O relógio deve ter status disponivel no catálogo.

string

required

ID do cliente interessado na compra.

integer

required

Preço de tabela no início da negociação, em centavos de real. Geralmente corresponde ao asking_price do relógio.

string

ID do vendedor responsável. Se omitido, a negociação fica sem vendedor atribuído.

Exemplo de Requisição

curl -X POST https://api.vault-erp.com/v1/sales \
  -H "Authorization: Bearer seu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "watch_id": "watch_abc123",
    "customer_id": "cust_def789",
    "asking_price": 8500000,
    "salesperson_id": "user_sp001"
  }'

Exemplo de Resposta

{
  "data": {
    "id": "sale_new001",
    "watch_id": "watch_abc123",
    "customer_id": "cust_def789",
    "status": "prospecto",
    "asking_price": 8500000,
    "final_price": null,
    "salesperson_id": "user_sp001",
    "notes": null,
    "created_at": "2024-03-20T14:00:00Z",
    "closed_at": null
  }
}

PATCH /sales/

Atualiza uma negociação existente — avança o estágio no pipeline, registra o preço final ou adiciona observações. Envie apenas os campos que deseja alterar.

Parâmetros de Path

string

required

Identificador único da negociação.

Campos do Body

string

Novo estágio no pipeline. Valores aceitos: prospecto, em_negociacao, proposta_enviada, reservado, fechado_ganho, fechado_perdido.Ao mover para fechado_ganho, o status do relógio associado é automaticamente atualizado para vendido. Ao mover para reservado, o relógio é marcado como reservado.

integer

Preço final acordado, em centavos. Obrigatório ao fechar com fechado_ganho.

string

Observações sobre a negociação (histórico de conversa, condições especiais, motivo de perda, etc.).

Exemplo de Requisição — Fechando uma Venda

curl -X PATCH https://api.vault-erp.com/v1/sales/sale_xyz456 \
  -H "Authorization: Bearer seu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "fechado_ganho", "final_price": 8100000}'

Exemplo de Resposta

{
  "data": {
    "id": "sale_xyz456",
    "watch_id": "watch_abc123",
    "customer_id": "cust_def789",
    "status": "fechado_ganho",
    "asking_price": 8500000,
    "final_price": 8100000,
    "salesperson_id": "user_sp001",
    "notes": null,
    "created_at": "2024-03-10T09:00:00Z",
    "closed_at": "2024-03-20T14:30:00Z"
  }
}

Exemplo de Requisição — Avançando no Pipeline

curl -X PATCH https://api.vault-erp.com/v1/sales/sale_xyz456 \
  -H "Authorization: Bearer seu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "proposta_enviada",
    "notes": "Sent formal proposal via email. Customer will respond by Friday."
  }'

Exemplo de Requisição — Registrando Perda

curl -X PATCH https://api.vault-erp.com/v1/sales/sale_xyz456 \
  -H "Authorization: Bearer seu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "fechado_perdido",
    "notes": "Customer bought from a competitor. Price was the main objection."
  }'

​GET /sales

​Parâmetros de Query

​Exemplo de Requisição

​Exemplo de Resposta

​POST /sales

​Campos do Body

​Exemplo de Requisição

​Exemplo de Resposta

​PATCH /sales/

​Parâmetros de Path

​Campos do Body

​Exemplo de Requisição — Fechando uma Venda

​Exemplo de Resposta

​Exemplo de Requisição — Avançando no Pipeline

​Exemplo de Requisição — Registrando Perda

GET /sales

Parâmetros de Query

Exemplo de Requisição

Exemplo de Resposta

POST /sales

Campos do Body

Exemplo de Requisição

Exemplo de Resposta

PATCH /sales/

Parâmetros de Path

Campos do Body

Exemplo de Requisição — Fechando uma Venda

Exemplo de Resposta

Exemplo de Requisição — Avançando no Pipeline

Exemplo de Requisição — Registrando Perda