API

Clientes

Gerenciar clientes Pessoa Física (PF) e Jurídica (PJ) via API.

Clientes

Gerencie o cadastro de clientes da sua loja ou shopping automotivo. Suporta Pessoa Física (PF) e Pessoa Jurídica (PJ) com campos específicos para cada tipo.

GET /v1/clients

Lista todos os clientes do time.

Query Parameters

ParâmetroTipoPadrãoDescrição
pagenumber1Página atual
limitnumber20Itens por página (máx: 100)
typestring-Filtrar por tipo: PF, PJ
statusstring-Filtrar por status: active, inactive
segmentstring-Filtrar por segmento: vip, premium, regular, occasional
searchstring-Buscar por nome, email ou documento
sortstring-created_atOrdenação

Request

curl -X GET "https://api.shopcar.com.br/v1/clients?type=PF&segment=premium" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": [
    {
      "id": "cli_abc123def456",
      "type": "PF",
      "name": "João da Silva",
      "email": "joao.silva@email.com",
      "phone": "+55 11 99999-8888",
      "cpf": "123.456.789-00",
      "segment": "premium",
      "status": "active",
      "vehicles_count": 3,
      "created_at": "2026-01-15T10:30:00Z"
    },
    {
      "id": "cli_xyz789ghi012",
      "type": "PJ",
      "name": "AutoPeças ABC Ltda",
      "email": "contato@autopecasabc.com.br",
      "phone": "+55 11 3333-4444",
      "cnpj": "12.345.678/0001-90",
      "segment": "vip",
      "status": "active",
      "vehicles_count": 8,
      "created_at": "2026-01-10T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

POST /v1/clients

Cria um novo cliente.

Request Body - Pessoa Física (PF)

CampoTipoObrigatórioDescrição
typestringSimTipo: PF
namestringSimNome completo
emailstringNãoEmail
phonestringNãoTelefone com DDI
whatsappstringNãoWhatsApp
cpfstringNãoCPF
rgstringNãoRG
birth_datestringNãoData de nascimento (YYYY-MM-DD)
genderstringNãoGênero: masculino, feminino, outro
marital_statusstringNãoEstado civil
nationalitystringNãoNacionalidade
professionstringNãoProfissão
segmentstringNãoSegmento: vip, premium, regular, occasional
addressobjectNãoEndereço completo
notesstringNãoObservações
tagsarrayNãoTags/etiquetas
metadataobjectNãoDados customizados

Request Body - Pessoa Jurídica (PJ)

CampoTipoObrigatórioDescrição
typestringSimTipo: PJ
namestringSimRazão social ou nome fantasia
legal_namestringNãoRazão social
trade_namestringNãoNome fantasia
emailstringNãoEmail
phonestringNãoTelefone com DDI
whatsappstringNãoWhatsApp
cnpjstringNãoCNPJ
state_registrationstringNãoInscrição estadual
segmentstringNãoSegmento: vip, premium, regular, occasional
addressobjectNãoEndereço completo
contact_personstringNãoPessoa de contato
notesstringNãoObservações
tagsarrayNãoTags/etiquetas
metadataobjectNãoDados customizados

Objeto Address

{
  "street": "Av. Paulista",
  "number": "1000",
  "complement": "Sala 101",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "zip_code": "01310-100",
  "country": "Brasil"
}

Request - Pessoa Física

curl -X POST https://api.shopcar.com.br/v1/clients \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PF",
    "name": "João da Silva",
    "email": "joao.silva@email.com",
    "phone": "+55 11 99999-8888",
    "cpf": "123.456.789-00",
    "birth_date": "1985-06-15",
    "profession": "Empresário",
    "segment": "premium",
    "address": {
      "street": "Rua das Flores",
      "number": "123",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zip_code": "01234-567"
    }
  }'

Request - Pessoa Jurídica

curl -X POST https://api.shopcar.com.br/v1/clients \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PJ",
    "name": "AutoPeças ABC Ltda",
    "legal_name": "AutoPeças ABC Comércio e Serviços Ltda",
    "trade_name": "AutoPeças ABC",
    "email": "contato@autopecasabc.com.br",
    "phone": "+55 11 3333-4444",
    "cnpj": "12.345.678/0001-90",
    "segment": "vip",
    "contact_person": "Maria Santos"
  }'

Response

{
  "success": true,
  "data": {
    "id": "cli_abc123def456",
    "type": "PF",
    "name": "João da Silva",
    "email": "joao.silva@email.com",
    "phone": "+55 11 99999-8888",
    "cpf": "123.456.789-00",
    "birth_date": "1985-06-15",
    "profession": "Empresário",
    "segment": "premium",
    "status": "active",
    "address": {
      "street": "Rua das Flores",
      "number": "123",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zip_code": "01234-567"
    },
    "vehicles_count": 0,
    "created_at": "2026-02-04T10:30:00Z",
    "updated_at": "2026-02-04T10:30:00Z"
  }
}

GET /v1/clients/:id

Busca um cliente específico.

Request

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

Response

{
  "success": true,
  "data": {
    "id": "cli_abc123def456",
    "type": "PF",
    "name": "João da Silva",
    "email": "joao.silva@email.com",
    "phone": "+55 11 99999-8888",
    "whatsapp": "+55 11 99999-8888",
    "cpf": "123.456.789-00",
    "rg": "12.345.678-9",
    "birth_date": "1985-06-15",
    "gender": "masculino",
    "marital_status": "casado",
    "nationality": "brasileiro",
    "profession": "Empresário",
    "segment": "premium",
    "status": "active",
    "address": {
      "street": "Rua das Flores",
      "number": "123",
      "complement": null,
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zip_code": "01234-567",
      "country": "Brasil"
    },
    "notes": "Cliente indicado por Carlos",
    "tags": ["indicação", "prioridade"],
    "vehicles_count": 3,
    "metadata": {},
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-04T14:20:00Z"
  }
}

PUT /v1/clients/:id

Atualiza um cliente existente.

Request

curl -X PUT https://api.shopcar.com.br/v1/clients/cli_abc123def456 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+55 11 88888-7777",
    "segment": "vip",
    "notes": "Cliente VIP - atendimento prioritário"
  }'

Response

{
  "success": true,
  "data": {
    "id": "cli_abc123def456",
    "phone": "+55 11 88888-7777",
    "segment": "vip",
    "notes": "Cliente VIP - atendimento prioritário",
    "updated_at": "2026-02-04T15:00:00Z"
  }
}

DELETE /v1/clients/:id

Desativa um cliente (soft delete).

Clientes com veículos ativos não podem ser desativados. Remova os veículos primeiro.

Request

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

Response

{
  "success": true,
  "data": {
    "id": "cli_abc123def456",
    "status": "inactive",
    "deactivated_at": "2026-02-04T15:30:00Z"
  }
}

GET /v1/clients/:id/vehicles

Lista os veículos de um cliente.

Request

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

Response

{
  "success": true,
  "data": [
    {
      "id": "veh_xyz789",
      "title": "Honda Civic EXL 2.0 2024",
      "brand": "Honda",
      "model": "Civic",
      "phase": "em-vitrine",
      "priority": "alta",
      "status": "disponivel",
      "price": 142900.00,
      "created_at": "2026-01-20T10:00:00Z"
    },
    {
      "id": "veh_abc123",
      "title": "Toyota Corolla XEi 2.0 2023",
      "brand": "Toyota",
      "model": "Corolla",
      "phase": "vendido",
      "priority": "media",
      "status": "vendido",
      "price": 135000.00,
      "created_at": "2025-06-15T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "pages": 1
  }
}

Segmentos de Cliente

SegmentoDescrição
vipClientes VIP - atendimento diferenciado
premiumClientes premium - prioridade alta
regularClientes regulares
occasionalClientes ocasionais

Erros Comuns

CódigoErroSolução
400Invalid typeUse: PF ou PJ
400Invalid CPF formatUse formato: 123.456.789-00
400Invalid CNPJ formatUse formato: 12.345.678/0001-90
404Client not foundVerifique o ID do cliente
422Duplicate CPFCPF já cadastrado
422Duplicate CNPJCNPJ já cadastrado
422Client has active vehiclesRemova os veículos antes de desativar

Veículos (Vehicles)

Criar, listar, atualizar e gerenciar veículos do inventário via API.

Atividades

Registrar e acompanhar atividades, tarefas e prazos via API.

On this page

ClientesGET /v1/clientsQuery ParametersRequestResponsePOST /v1/clientsRequest Body - Pessoa Física (PF)Request Body - Pessoa Jurídica (PJ)Objeto AddressRequest - Pessoa FísicaRequest - Pessoa JurídicaResponseGET /v1/clients/:idRequestResponsePUT /v1/clients/:idRequestResponseDELETE /v1/clients/:idRequestResponseGET /v1/clients/:id/vehiclesRequestResponseSegmentos de ClienteErros Comuns