Clientes

Gerencie os clientes cadastrados na loja. Suporta pessoa física (PF) e pessoa jurídica (PJ).

Listar clientes

GET /api/v1/customers

Query parameters

Parâmetro	Tipo	Descrição
search	string	Busca por nome, e-mail ou razão social
status	string	Filtrar: active ou inactive
type	string	Filtrar: pf (pessoa física) ou pj (pessoa jurídica)
email	string	Busca exata por e-mail
cpf	string	Filtrar por CPF
cnpj	string	Filtrar por CNPJ
sort	string	Campo de ordenação (padrão: created_at)
direction	string	asc ou desc (padrão: desc)
per_page	integer	Itens por página (máx: 100, padrão: 25)

Exemplo

curl -X GET "https://sualoja.com.br/api/v1/customers?type=pf&status=active" \
  -H "X-API-Key: SUA_CHAVE"

Resposta

{
  "data": [
    {
      "id": 5,
      "type": "pf",
      "name": "João Silva",
      "email": "joao@email.com",
      "cpf": "123.456.789-00",
      "cnpj": null,
      "company_name": null,
      "phone": "(11) 3456-7890",
      "mobile": "(11) 98765-4321",
      "status": "active",
      "birth_date": "1990-05-15",
      "addresses": [
        {
          "id": 1,
          "label": "Casa",
          "cep": "01001-000",
          "street": "Rua A",
          "number": "100",
          "complement": "Apto 42",
          "district": "Centro",
          "city": "São Paulo",
          "state": "SP",
          "is_default": true
        }
      ],
      "orders_count": 8,
      "created_at": "2026-01-20T14:00:00Z",
      "updated_at": "2026-03-10T09:30:00Z"
    }
  ]
}

Buscar cliente

GET /api/v1/customers/{id}

Retorna o cliente com endereços e contagem de pedidos.

Criar cliente

POST /api/v1/customers

Campos

Campo	Tipo	Obrigatório	Descrição
name	string	✅	Nome completo ou razão social
email	string	✅	E-mail (deve ser único)
type	string	✅	pf (pessoa física) ou pj (pessoa jurídica)
password	string	✅	Senha (mínimo 6 caracteres)
cpf	string		CPF (para PF)
cnpj	string		CNPJ (para PJ)
company_name	string		Razão social (para PJ)
phone	string		Telefone fixo
mobile	string		Celular
status	string		active ou inactive (padrão: active)
birth_date	date		Data de nascimento (formato: YYYY-MM-DD)

Exemplo

curl -X POST https://sualoja.com.br/api/v1/customers \
  -H "X-API-Key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Santos",
    "email": "maria@email.com",
    "type": "pf",
    "password": "senha123",
    "cpf": "987.654.321-00",
    "mobile": "(11) 91234-5678"
  }'

Resposta 201 Created

{
  "data": {
    "id": 6,
    "type": "pf",
    "name": "Maria Santos",
    "email": "maria@email.com",
    "cpf": "987.654.321-00",
    "status": "active",
    "orders_count": 0
  }
}

Atualizar cliente

PUT /api/v1/customers/{id}

Aceita os mesmos campos do POST, todos opcionais. O campo password é opcional na atualização.

Exemplo

curl -X PUT https://sualoja.com.br/api/v1/customers/6 \
  -H "X-API-Key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "(11) 3456-7890",
    "mobile": "(11) 99876-5432"
  }'

Desativar cliente

DELETE /api/v1/customers/{id}

Soft delete

A exclusão de clientes não remove o registro. O status é alterado para inactive, preservando o histórico de pedidos.

Resposta

{
  "message": "Cliente desativado."
}

Tipos de cliente

Tipo	Descrição	Campos específicos
pf	Pessoa Física	cpf, birth_date
pj	Pessoa Jurídica	cnpj, company_name