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 /api/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
store_idstring-Filtrar por loja
searchstring-Buscar por nome, email, CPF ou CNPJ
sortstring-created_atOrdenação (prefixo - para descendente)

Request

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

Response

{
  "success": true,
  "data": [
    {
      "id": "uuid-do-cliente",
      "type": "PF",
      "name": "João da Silva",
      "display_name": null,
      "email": "joao.silva@email.com",
      "phone": "+55 11 99999-8888",
      "mobile_phone": null,
      "whatsapp": "+55 11 99999-8888",
      "cpf": "123.456.789-00",
      "rg": null,
      "birth_date": "1985-06-15",
      "gender": "masculino",
      "marital_status": null,
      "nationality": null,
      "segment": "premium",
      "source": null,
      "status": "active",
      "store_id": "uuid-da-loja",
      "created_at": "2026-01-15T10:30:00Z"
    },
    {
      "id": "uuid-da-empresa",
      "type": "PJ",
      "name": "AutoPeças ABC Ltda",
      "display_name": "AutoPeças ABC",
      "email": "contato@autopecasabc.com.br",
      "phone": "+55 11 3333-4444",
      "mobile_phone": null,
      "whatsapp": null,
      "cnpj": "12.345.678/0001-90",
      "legal_name": "AutoPeças ABC Comércio e Serviços Ltda",
      "trade_name": "AutoPeças ABC",
      "state_registration": null,
      "segment": "vip",
      "status": "active",
      "store_id": "uuid-da-loja",
      "created_at": "2026-01-10T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

POST /api/v1/clients

Cria um novo cliente.

Request Body — Pessoa Física (PF)

CampoTipoObrigatórioDescrição
typestringSimTipo: PF
namestringSimNome completo
display_namestringNãoApelido ou nome de exibição
emailstringNãoEmail
phonestringNãoTelefone fixo
mobile_phonestringNãoCelular
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
segmentstringNãoSegmento: vip, premium, regular, occasional
sourcestringNãoOrigem do cliente
store_idstringNãoID da loja
addressobjectNãoEndereço completo (ver abaixo)
notesstringNãoObservações
tagsarrayNãoTags/etiquetas
credit_limitnumberNãoLimite de crédito

Request Body — Pessoa Jurídica (PJ)

CampoTipoObrigatórioDescrição
typestringSimTipo: PJ
namestringSimRazão social ou nome fantasia
display_namestringNãoNome de exibição
legal_namestringNãoRazão social
trade_namestringNãoNome fantasia
emailstringNãoEmail
phonestringNãoTelefone
mobile_phonestringNãoCelular
whatsappstringNãoWhatsApp
cnpjstringNãoCNPJ
state_registrationstringNãoInscrição estadual
municipal_registrationstringNãoInscrição municipal
segmentstringNãoSegmento: vip, premium, regular, occasional
sourcestringNãoOrigem do cliente
store_idstringNãoID da loja
addressobjectNãoEndereço completo (ver abaixo)
notesstringNãoObservações
tagsarrayNãoTags/etiquetas
credit_limitnumberNãoLimite de crédito

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://dashboard.ecosysauto.ai/api/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",
    "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://dashboard.ecosysauto.ai/api/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"
  }'

Response (201 Created)

{
  "success": true,
  "data": {
    "id": "uuid-do-cliente",
    "type": "PF",
    "name": "João da Silva",
    "display_name": null,
    "email": "joao.silva@email.com",
    "phone": "+55 11 99999-8888",
    "mobile_phone": null,
    "whatsapp": null,
    "cpf": "123.456.789-00",
    "rg": null,
    "birth_date": "1985-06-15",
    "gender": null,
    "marital_status": null,
    "nationality": null,
    "segment": "premium",
    "source": null,
    "status": "active",
    "address": {
      "street": "Rua das Flores",
      "number": "123",
      "complement": null,
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zip_code": "01234-567",
      "country": null
    },
    "notes": null,
    "tags": [],
    "credit_limit": null,
    "store_id": null,
    "created_at": "2026-02-04T10:30:00Z",
    "updated_at": "2026-02-04T10:30:00Z"
  }
}

GET /api/v1/clients/:id

Busca um cliente específico.

Request

curl -X GET https://dashboard.ecosysauto.ai/api/v1/clients/uuid-do-cliente \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": {
    "id": "uuid-do-cliente",
    "type": "PF",
    "name": "João da Silva",
    "display_name": null,
    "email": "joao.silva@email.com",
    "phone": "+55 11 99999-8888",
    "mobile_phone": null,
    "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",
    "segment": "premium",
    "source": "indicacao",
    "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"],
    "credit_limit": null,
    "store_id": "uuid-da-loja",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-04T14:20:00Z"
  }
}

PUT /api/v1/clients/:id

Atualiza um cliente existente. Todos os campos são opcionais — envie apenas o que deseja alterar.

Campos Atualizáveis

Todos os campos listados no POST são atualizáveis, incluindo o objeto address parcialmente.

Request

curl -X PUT https://dashboard.ecosysauto.ai/api/v1/clients/uuid-do-cliente \
  -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": "uuid-do-cliente",
    "phone": "+55 11 88888-7777",
    "segment": "vip",
    "notes": "Cliente VIP — atendimento prioritário",
    "updated_at": "2026-02-04T15:00:00Z"
  }
}

DELETE /api/v1/clients/:id

Desativa um cliente (soft delete — define is_active como false).

Esta operação não exclui o cliente permanentemente. Para reativá-lo, use PUT /api/v1/clients/:id com qualquer campo válido (o cliente continuará existindo no sistema).

Request

curl -X DELETE https://dashboard.ecosysauto.ai/api/v1/clients/uuid-do-cliente \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

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

Segmentos de Cliente

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

Erros Comuns

CódigoErroSolução
400Campo 'name' é obrigatórioInclua o campo name
400Campo 'type' é obrigatório. Use: PF ou PJUse PF ou PJ
400Nenhum campo para atualizarEnvie ao menos um campo no body do PUT
404Cliente não encontradoVerifique o ID do cliente
422CPF já cadastradoCPF já existe no time
422CNPJ já cadastradoCNPJ já existe no time

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 /api/v1/clientsQuery ParametersRequestResponsePOST /api/v1/clientsRequest Body — Pessoa Física (PF)Request Body — Pessoa Jurídica (PJ)Objeto AddressRequest — Pessoa FísicaRequest — Pessoa JurídicaResponse (201 Created)GET /api/v1/clients/:idRequestResponsePUT /api/v1/clients/:idCampos AtualizáveisRequestResponseDELETE /api/v1/clients/:idRequestResponseSegmentos de ClienteErros Comuns