Negócios

Funil de vendas: criação, atualização de estágio e acompanhamento de negócios.

GET /api/deals Auth

Listar Negócios

Retorna todos os negócios do funil de vendas do usuário, com paginação e filtros.

Query Parameters

page integer

Número da página

limit integer

Itens por página (máx: 100)

status string

Filtrar por status: open, won, lost

stage string

Filtrar por estágio do funil

Status Codes

200 Lista retornada com sucesso

401 Não autenticado

Response

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439033",
      "title": "Implantação ERP - Tech Solutions",
      "value": 45000.00,
      "currency": "BRL",
      "stage": "negociacao",
      "status": "open",
      "probability": 70,
      "companyId": "507f1f77bcf86cd799439022",
      "contactIds": ["507f1f77bcf86cd799439011"],
      "expectedCloseDate": "2026-06-15T00:00:00Z",
      "createdAt": "2026-04-01T10:00:00Z"
    }
  ],
  "total": 24,
  "page": 1,
  "limit": 20
}

POST /api/deals Auth

Criar Negócio

Cria um novo negócio no funil de vendas. O status inicial é sempre "open".

Request Body

title string obrigatório

Título do negócio

value number obrigatório

Valor estimado em BRL

stage string opcional

Estágio inicial do funil

probability integer opcional

Probabilidade de fechamento (0-100)

companyId string opcional

ID da empresa relacionada

contactIds string[] opcional

IDs dos contatos envolvidos

expectedCloseDate string opcional

Data prevista de fechamento (ISO 8601)

Status Codes

201 Criado com sucesso

400 Dados inválidos

401 Não autenticado

Request

{
  "title": "Implantação ERP - Tech Solutions",
  "value": 45000.00,
  "stage": "novo",
  "probability": 30,
  "companyId": "507f1f77bcf86cd799439022",
  "contactIds": ["507f1f77bcf86cd799439011"],
  "expectedCloseDate": "2026-06-15T00:00:00Z"
}

Response

{
  "id": "507f1f77bcf86cd799439033",
  "title": "Implantação ERP - Tech Solutions",
  "value": 45000.00,
  "currency": "BRL",
  "stage": "novo",
  "status": "open",
  "probability": 30,
  "createdAt": "2026-05-07T10:00:00Z"
}

GET /api/deals/:id Auth

Buscar Negócio por ID

Retorna os dados completos de um negócio específico.

Status Codes

200 Registro encontrado

401 Não autenticado

403 Sem permissão (não é o proprietário)

404 Não encontrado

Response

{
  "id": "507f1f77bcf86cd799439033",
  "title": "Implantação ERP - Tech Solutions",
  "value": 45000.00,
  "currency": "BRL",
  "stage": "negociacao",
  "status": "open",
  "probability": 70,
  "companyId": "507f1f77bcf86cd799439022",
  "contactIds": ["507f1f77bcf86cd799439011"],
  "expectedCloseDate": "2026-06-15T00:00:00Z",
  "createdAt": "2026-04-01T10:00:00Z",
  "updatedAt": "2026-05-05T14:00:00Z"
}

PUT /api/deals/:id Auth

Atualizar Negócio

Atualiza dados de um negócio. Use para mover entre estágios do funil ou alterar valores.

Request Body

title string opcional

Título

value number opcional

Valor em BRL

stage string opcional

Estágio do funil

status string opcional

Status: open, won, lost

probability integer opcional

Probabilidade (0-100)

expectedCloseDate string opcional

Data prevista (ISO 8601)

Status Codes

200 Atualizado com sucesso

400 Dados inválidos

401 Não autenticado

403 Sem permissão (não é o proprietário)

404 Não encontrado

Request

{
  "stage": "fechado",
  "status": "won",
  "probability": 100
}

Response

{
  "id": "507f1f77bcf86cd799439033",
  "title": "Implantação ERP - Tech Solutions",
  "value": 45000.00,
  "stage": "fechado",
  "status": "won",
  "probability": 100,
  "updatedAt": "2026-05-07T15:30:00Z"
}

DELETE /api/deals/:id Auth

Remover Negócio

Remove permanentemente um negócio do funil de vendas.

Status Codes

200 Removido com sucesso

401 Não autenticado

403 Sem permissão (não é o proprietário)

404 Não encontrado

Response

{
  "message": "Negócio excluído com sucesso"
}

GET /api/deals/pipeline-stats Auth

Estatísticas do Funil de Vendas

Retorna estatísticas agregadas do funil de vendas: total por estágio, valores e contagens.

Status Codes

200 Lista retornada com sucesso

401 Não autenticado

Response

{
  "totalDeals": 24,
  "totalValue": 380000.00,
  "byStage": {
    "novo": { "count": 8, "value": 120000 },
    "negociacao": { "count": 10, "value": 180000 },
    "fechado": { "count": 6, "value": 80000 }
  },
  "wonDeals": 15,
  "lostDeals": 5,
  "conversionRate": 75.0
}