Negócios (Deals)

Gerencie o pipeline de vendas da sua loja ou shopping automotivo. Negócios representam potenciais compradores ou negociações de veículos em andamento.

GET /v1/deals

Lista todos os negócios do time.

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
`page`	number	1	Página atual
`limit`	number	20	Itens por página (máx: 100)
`status`	string	-	Filtrar por status: `ativo`, `ganho`, `perdido`, `arquivado`
`phase`	string	-	Filtrar por fase do pipeline
`client_id`	string	-	Filtrar por cliente
`responsible_id`	string	-	Filtrar por responsável
`source`	string	-	Filtrar por origem
`min_value`	number	-	Valor mínimo
`max_value`	number	-	Valor máximo
`from`	string	-	Data de criação inicial (YYYY-MM-DD)
`to`	string	-	Data de criação final (YYYY-MM-DD)
`sort`	string	`-created_at`	Ordenação

Request

curl -X GET "https://api.shopcar.com.br/v1/deals?status=ativo&phase=proposta" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": [
    {
      "id": "deal_abc123def456",
      "title": "Venda Honda Civic 2024 - Cliente João",
      "value": 142900.00,
      "currency": "BRL",
      "phase": "proposta",
      "probability": 60,
      "status": "ativo",
      "expected_close_date": "2026-03-15",
      "client": {
        "id": "cli_xyz789",
        "name": "João da Silva",
        "type": "PF"
      },
      "responsible": {
        "id": "user_123",
        "name": "Carlos Mendes"
      },
      "source": "showroom",
      "created_at": "2026-01-20T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 25,
    "pages": 2
  }
}

POST /v1/deals

Cria um novo negócio.

Request Body

Campo	Tipo	Obrigatório	Descrição
`title`	string	Sim	Título do negócio
`value`	number	Não	Valor estimado
`currency`	string	Não	Moeda (padrão: `BRL`)
`phase`	string	Não	Fase inicial (padrão: primeira fase)
`probability`	number	Não	Probabilidade de ganho (0-100)
`expected_close_date`	string	Não	Data prevista de fechamento (YYYY-MM-DD)
`client_id`	string	Não	ID do cliente
`responsible_id`	string	Não	ID do responsável
`source`	string	Não	Origem do negócio
`description`	string	Não	Descrição detalhada
`labels`	array	Não	Labels/tags
`metadata`	object	Não	Dados customizados

Request

curl -X POST https://api.shopcar.com.br/v1/deals \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Venda Toyota Corolla 2025 - Empresa ABC",
    "value": 165000.00,
    "phase": "lead",
    "probability": 30,
    "expected_close_date": "2026-04-01",
    "client_id": "cli_abc123def456",
    "source": "portal",
    "description": "Cliente interessado no Corolla 2025 após ver anúncio no portal",
    "labels": ["corolla", "alta-margem"]
  }'

Response

{
  "success": true,
  "data": {
    "id": "deal_new123abc456",
    "title": "Venda Toyota Corolla 2025 - Empresa ABC",
    "value": 165000.00,
    "currency": "BRL",
    "phase": "lead",
    "probability": 30,
    "status": "ativo",
    "expected_close_date": "2026-04-01",
    "client_id": "cli_abc123def456",
    "source": "portal",
    "description": "Cliente interessado no Corolla 2025 após ver anúncio no portal",
    "labels": ["corolla", "alta-margem"],
    "created_at": "2026-02-04T10:30:00Z",
    "updated_at": "2026-02-04T10:30:00Z"
  }
}

GET /v1/deals/:id

Busca um negócio específico.

Request

curl -X GET https://api.shopcar.com.br/v1/deals/deal_abc123def456 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": {
    "id": "deal_abc123def456",
    "title": "Venda Honda Civic 2024 - Cliente João",
    "value": 142900.00,
    "currency": "BRL",
    "phase": "proposta",
    "probability": 60,
    "status": "ativo",
    "expected_close_date": "2026-03-15",
    "description": "Cliente interessado no Honda Civic EXL 2024 preto",
    "client": {
      "id": "cli_xyz789",
      "name": "João da Silva",
      "type": "PF",
      "email": "joao@email.com"
    },
    "responsible": {
      "id": "user_123",
      "name": "Carlos Mendes",
      "email": "carlos@loja.com"
    },
    "source": "showroom",
    "labels": ["civic"],
    "activities_count": 3,
    "ai_insights": {
      "win_probability": 65,
      "health": "good",
      "risk_factors": []
    },
    "metadata": {},
    "created_at": "2026-01-20T10:00:00Z",
    "updated_at": "2026-02-04T14:00:00Z"
  }
}

PUT /v1/deals/:id

Atualiza um negócio.

Request

curl -X PUT https://api.shopcar.com.br/v1/deals/deal_abc123def456 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 139900.00,
    "probability": 75,
    "phase": "negociacao"
  }'

Response

{
  "success": true,
  "data": {
    "id": "deal_abc123def456",
    "value": 139900.00,
    "probability": 75,
    "phase": "negociacao",
    "updated_at": "2026-02-04T15:00:00Z"
  }
}

PUT /v1/deals/:id/phase

Move um negócio para outra fase do pipeline.

Request

curl -X PUT https://api.shopcar.com.br/v1/deals/deal_abc123def456/phase \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "phase": "negociacao",
    "notes": "Cliente solicitou desconto para pagamento à vista"
  }'

Response

{
  "success": true,
  "data": {
    "id": "deal_abc123def456",
    "phase": "negociacao",
    "previous_phase": "proposta",
    "phase_changed_at": "2026-02-04T15:30:00Z",
    "updated_at": "2026-02-04T15:30:00Z"
  }
}

PUT /v1/deals/:id/won

Marca um negócio como ganho (venda concretizada).

Request

curl -X PUT https://api.shopcar.com.br/v1/deals/deal_abc123def456/won \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "final_value": 139900.00,
    "notes": "Contrato assinado em 04/02/2026, pagamento via financiamento",
    "create_contract": true,
    "contract_data": {
      "title": "Venda Honda Civic EXL 2024 - João da Silva",
      "vehicle_id": "veh_xyz789ghi012"
    }
  }'

Response

{
  "success": true,
  "data": {
    "id": "deal_abc123def456",
    "status": "ganho",
    "final_value": 139900.00,
    "won_at": "2026-02-04T16:00:00Z",
    "contract_created": {
      "id": "ctr_new123",
      "title": "Venda Honda Civic EXL 2024 - João da Silva"
    }
  }
}

PUT /v1/deals/:id/lost

Marca um negócio como perdido.

Request

curl -X PUT https://api.shopcar.com.br/v1/deals/deal_abc123def456/lost \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "loss_reason": "Preço acima do orçamento",
    "competitor": "Concessionária XYZ",
    "notes": "Cliente optou por proposta mais econômica na concorrência"
  }'

Response

{
  "success": true,
  "data": {
    "id": "deal_abc123def456",
    "status": "perdido",
    "loss_reason": "Preço acima do orçamento",
    "competitor": "Concessionária XYZ",
    "lost_at": "2026-02-04T16:30:00Z"
  }
}

DELETE /v1/deals/:id

Arquiva um negócio.

Request

curl -X DELETE https://api.shopcar.com.br/v1/deals/deal_abc123def456 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": {
    "id": "deal_abc123def456",
    "status": "arquivado",
    "archived_at": "2026-02-04T17:00:00Z"
  }
}

GET /v1/deals/summary

Retorna um resumo do pipeline.

Request

curl -X GET https://api.shopcar.com.br/v1/deals/summary \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": {
    "total_deals": 25,
    "total_value": 3250000.00,
    "weighted_value": 1625000.00,
    "by_phase": {
      "lead": { "count": 8, "value": 1120000.00 },
      "qualificado": { "count": 6, "value": 780000.00 },
      "proposta": { "count": 5, "value": 750000.00 },
      "negociacao": { "count": 4, "value": 500000.00 },
      "fechamento": { "count": 2, "value": 300000.00 }
    },
    "by_status": {
      "ativo": { "count": 25, "value": 3250000.00 },
      "ganho": { "count": 12, "value": 1680000.00 },
      "perdido": { "count": 5, "value": 650000.00 }
    },
    "conversion_rate": 70.6,
    "average_deal_size": 130000.00,
    "average_sales_cycle_days": 21
  }
}

Fases do Pipeline

Fases padrão (configuráveis por time):

Fase	Descrição	Probabilidade Sugerida
`lead`	Lead recém-chegado	10%
`qualificado`	Lead qualificado	25%
`proposta`	Proposta enviada	50%
`negociacao`	Em negociação	75%
`fechamento`	Fechamento iminente	90%

Origens Comuns

Origem	Descrição
`showroom`	Visita ao showroom/loja
`portal`	Portal de anúncios (OLX, Webmotors, etc.)
`indicacao`	Indicação de cliente
`site`	Site da loja
`instagram`	Instagram
`whatsapp`	WhatsApp direto
`parceiro`	Parceiro comercial

Erros Comuns

Código	Erro	Solução
`400`	`Invalid phase`	Use uma fase válida
`400`	`Invalid probability`	Use valor entre 0 e 100
`404`	`Deal not found`	Verifique o ID
`422`	`Deal already closed`	Negócio já ganho/perdido

Negócios (Deals)

On this page