Veículos (Vehicles)

Gerencie o inventário de veículos da sua loja ou shopping automotivo. Veículos são o core do Ecosys Auto - representam carros, motos, caminhões e qualquer veículo disponível para venda.

GET /v1/vehicles

Lista todos os veículos 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: `disponivel`, `reservado`, `vendido`
`phase`	string	-	Filtrar por fase do kanban
`priority`	string	-	Filtrar por prioridade: `alta`, `media`, `baixa`
`brand`	string	-	Filtrar por marca do veículo
`client_id`	string	-	Filtrar por cliente (proprietário/consignante)
`responsible_id`	string	-	Filtrar por responsável
`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
`search`	string	-	Buscar por título ou placa

Request

curl -X GET "https://api.shopcar.com.br/v1/vehicles?status=disponivel&brand=Honda" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": [
    {
      "id": "veh_abc123def456",
      "title": "Honda Civic EXL 2.0 2024",
      "brand": "Honda",
      "model": "Civic",
      "version": "EXL 2.0 Flex",
      "year_model": 2024,
      "year_manufacture": 2023,
      "phase": "em-vitrine",
      "priority": "alta",
      "status": "disponivel",
      "price": 142900.00,
      "mileage": 18500,
      "color": "Preto",
      "fuel": "flex",
      "transmission": "automatico",
      "plate": "ABC1D23",
      "client": {
        "id": "cli_xyz789",
        "name": "João da Silva",
        "type": "PF"
      },
      "responsible": {
        "id": "user_123",
        "name": "Carlos Mendes"
      },
      "activities_count": 5,
      "photos_count": 12,
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-02-04T14:20:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "pages": 3
  }
}

POST /v1/vehicles

Cadastra um novo veículo.

Request Body

Campo	Tipo	Obrigatório	Descrição
`title`	string	Sim	Título do anúncio do veículo
`store_id`	string	Sim	ID da loja onde o veículo será cadastrado
`brand`	string	Não	Marca (Honda, Toyota, VW, etc.)
`model`	string	Não	Modelo (Civic, Corolla, Gol, etc.)
`version`	string	Não	Versão/acabamento
`year_model`	number	Não	Ano modelo
`year_manufacture`	number	Não	Ano fabricação
`price`	number	Não	Preço de venda
`mileage`	number	Não	Quilometragem
`color`	string	Não	Cor do veículo
`fuel`	string	Não	Combustível: `flex`, `gasolina`, `etanol`, `diesel`, `eletrico`, `hibrido`
`transmission`	string	Não	Câmbio: `automatico`, `manual`, `cvt`, `automatizado`
`plate`	string	Não	Placa do veículo
`phase`	string	Não	Fase inicial no kanban (padrão: primeira fase)
`priority`	string	Não	Prioridade: `alta`, `media`, `baixa` (padrão: `media`)
`client_id`	string	Não	ID do cliente (proprietário/consignante)
`responsible_id`	string	Não	ID do usuário responsável
`description`	string	Não	Descrição detalhada do veículo
`labels`	array	Não	Array de labels/tags
`metadata`	object	Não	Dados customizados

Request

curl -X POST https://api.shopcar.com.br/v1/vehicles \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Honda Civic EXL 2.0 2024",
    "brand": "Honda",
    "model": "Civic",
    "version": "EXL 2.0 Flex",
    "year_model": 2024,
    "year_manufacture": 2023,
    "price": 142900.00,
    "mileage": 18500,
    "color": "Preto",
    "fuel": "flex",
    "transmission": "automatico",
    "plate": "ABC1D23",
    "phase": "recebido",
    "priority": "alta",
    "client_id": "cli_abc123def456",
    "description": "Veículo em excelente estado, único dono, todas as revisões na concessionária.",
    "labels": ["destaque", "seminovo-premium"]
  }'

Response

{
  "success": true,
  "data": {
    "id": "veh_xyz789ghi012",
    "title": "Honda Civic EXL 2.0 2024",
    "brand": "Honda",
    "model": "Civic",
    "version": "EXL 2.0 Flex",
    "year_model": 2024,
    "year_manufacture": 2023,
    "price": 142900.00,
    "mileage": 18500,
    "color": "Preto",
    "fuel": "flex",
    "transmission": "automatico",
    "plate": "ABC1D23",
    "phase": "recebido",
    "priority": "alta",
    "status": "disponivel",
    "client_id": "cli_abc123def456",
    "description": "Veículo em excelente estado, único dono, todas as revisões na concessionária.",
    "labels": ["destaque", "seminovo-premium"],
    "activities_count": 0,
    "photos_count": 0,
    "created_at": "2026-02-04T10:30:00Z",
    "updated_at": "2026-02-04T10:30:00Z"
  }
}

GET /v1/vehicles/:id

Busca um veículo específico por ID.

Request

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

Response

{
  "success": true,
  "data": {
    "id": "veh_xyz789ghi012",
    "title": "Honda Civic EXL 2.0 2024",
    "brand": "Honda",
    "model": "Civic",
    "version": "EXL 2.0 Flex",
    "year_model": 2024,
    "year_manufacture": 2023,
    "price": 142900.00,
    "mileage": 18500,
    "color": "Preto",
    "fuel": "flex",
    "transmission": "automatico",
    "plate": "ABC1D23",
    "phase": "recebido",
    "priority": "alta",
    "status": "disponivel",
    "description": "Veículo em excelente estado, único dono...",
    "client": {
      "id": "cli_abc123def456",
      "name": "João da Silva",
      "type": "PF",
      "email": "joao@email.com",
      "phone": "+55 11 99999-8888"
    },
    "responsible": {
      "id": "user_123",
      "name": "Carlos Mendes",
      "email": "carlos@loja.com"
    },
    "labels": ["destaque", "seminovo-premium"],
    "activities_count": 5,
    "photos_count": 12,
    "metadata": {},
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-04T14:20:00Z"
  }
}

PUT /v1/vehicles/:id

Atualiza um veículo existente.

Request Body

Todos os campos são opcionais. Envie apenas os campos que deseja atualizar.

Campo	Tipo	Descrição
`title`	string	Título do anúncio
`brand`	string	Marca
`model`	string	Modelo
`version`	string	Versão/acabamento
`year_model`	number	Ano modelo
`year_manufacture`	number	Ano fabricação
`price`	number	Preço de venda
`mileage`	number	Quilometragem
`color`	string	Cor
`fuel`	string	Combustível
`transmission`	string	Câmbio
`plate`	string	Placa
`phase`	string	Fase no kanban
`priority`	string	Prioridade: `alta`, `media`, `baixa`
`status`	string	Status: `disponivel`, `reservado`, `vendido`
`client_id`	string	ID do cliente
`responsible_id`	string	ID do responsável
`description`	string	Descrição
`labels`	array	Labels/tags
`metadata`	object	Dados customizados

Request

curl -X PUT https://api.shopcar.com.br/v1/vehicles/veh_xyz789ghi012 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "phase": "em-vitrine",
    "priority": "media",
    "price": 139900.00,
    "labels": ["destaque", "seminovo-premium", "preco-reduzido"]
  }'

Response

{
  "success": true,
  "data": {
    "id": "veh_xyz789ghi012",
    "title": "Honda Civic EXL 2.0 2024",
    "phase": "em-vitrine",
    "priority": "media",
    "price": 139900.00,
    "labels": ["destaque", "seminovo-premium", "preco-reduzido"],
    "updated_at": "2026-02-04T15:00:00Z"
  }
}

DELETE /v1/vehicles/:id

Remove um veículo do inventário (soft delete).

Esta operação não exclui permanentemente o veículo. Ele pode ser restaurado alterando o status para disponivel.

Request

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

Response

{
  "success": true,
  "data": {
    "id": "veh_xyz789ghi012",
    "status": "removido",
    "removed_at": "2026-02-04T15:30:00Z"
  }
}

GET /v1/vehicles/:id/activities

Lista as atividades de um veículo.

Request

curl -X GET https://api.shopcar.com.br/v1/vehicles/veh_xyz789ghi012/activities \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": [
    {
      "id": "act_123abc",
      "type": "task",
      "title": "Realizar inspeção veicular",
      "status": "completed",
      "priority": "alta",
      "due_date": "2026-02-10",
      "completed_at": "2026-02-08T16:00:00Z",
      "created_at": "2026-02-01T10:00:00Z"
    },
    {
      "id": "act_456def",
      "type": "deadline",
      "title": "Prazo para laudo cautelar",
      "status": "pending",
      "priority": "alta",
      "due_date": "2026-02-20",
      "created_at": "2026-02-05T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "pages": 1
  }
}

GET /v1/vehicles/:id/timeline

Retorna a timeline de eventos do veículo.

Request

curl -X GET https://api.shopcar.com.br/v1/vehicles/veh_xyz789ghi012/timeline \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": [
    {
      "id": "evt_001",
      "type": "phase_change",
      "description": "Veículo movido para 'em-vitrine'",
      "user": {
        "id": "user_123",
        "name": "Carlos Mendes"
      },
      "created_at": "2026-02-04T15:00:00Z"
    },
    {
      "id": "evt_002",
      "type": "photo_added",
      "description": "Foto 'Frente.jpg' adicionada",
      "user": {
        "id": "user_456",
        "name": "Ana Silva"
      },
      "created_at": "2026-02-03T11:30:00Z"
    },
    {
      "id": "evt_003",
      "type": "vehicle_created",
      "description": "Veículo cadastrado",
      "user": {
        "id": "user_123",
        "name": "Carlos Mendes"
      },
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}

Fases do Kanban

As fases são configuráveis por time. Fases padrão:

Fase	Descrição
`recebido`	Veículo recém-recebido
`em-avaliacao`	Em avaliação e inspeção
`em-vitrine`	Disponível para venda
`em-negociacao`	Em negociação com comprador
`vendido`	Venda concluída

Marcas Populares

Valores sugeridos (customizáveis):

Honda
Toyota
Volkswagen
Chevrolet
Fiat
Hyundai
Jeep
Ford
Nissan
BMW

Erros Comuns

Código	Erro	Solução
`400`	`Invalid phase`	Use uma fase válida do time
`400`	`Invalid priority`	Use: `alta`, `media` ou `baixa`
`404`	`Vehicle not found`	Verifique o ID do veículo
`404`	`Client not found`	Verifique o client_id
`422`	`Duplicate plate`	Placa do veículo já existe

Veículos (Vehicles)

On this page