Clientes

Gerencie os clientes da sua incorporadora. Clientes podem ser Pessoa Física (PF) ou Jurídica (PJ) e são utilizados em vendas de unidades, contratos e relacionamentos comerciais.

GET /v1/clients

Lista todos os clientes da organização.

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)
`type`	string	-	Filtrar por tipo: `PF` ou `PJ`
`status`	string	-	Filtrar por status: `active`, `inactive`
`segment`	string	-	Filtrar por segmento
`search`	string	-	Buscar por nome, email, CPF ou CNPJ
`sort`	string	`-created_at`	Ordenação

Request

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

Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "PF",
      "name": "Maria Santos",
      "email": "maria@email.com",
      "phone": "+55 11 99999-8888",
      "cpf": "123.456.789-00",
      "segment": "premium",
      "status": "active",
      "address": {
        "street": "Rua das Flores",
        "number": "123",
        "neighborhood": "Centro",
        "city": "São Paulo",
        "state": "SP",
        "zip_code": "01000-000"
      },
      "created_at": "2026-02-01T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "pages": 3
  }
}

POST /v1/clients

Cadastra um novo cliente.

Request Body

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome completo (PF) ou razão social (PJ)
`type`	string	Sim	Tipo: `PF` (Pessoa Física) ou `PJ` (Pessoa Jurídica)
`email`	string	Não	Email de contato
`phone`	string	Não	Telefone fixo
`mobile_phone`	string	Não	Celular
`whatsapp`	string	Não	WhatsApp
`cpf`	string	Não	CPF (apenas PF)
`rg`	string	Não	RG (apenas PF)
`birth_date`	string	Não	Data de nascimento (YYYY-MM-DD)
`gender`	string	Não	Gênero
`marital_status`	string	Não	Estado civil
`nationality`	string	Não	Nacionalidade
`cnpj`	string	Não	CNPJ (apenas PJ)
`legal_name`	string	Não	Razão social (PJ)
`trade_name`	string	Não	Nome fantasia (PJ)
`state_registration`	string	Não	Inscrição estadual (PJ)
`municipal_registration`	string	Não	Inscrição municipal (PJ)
`address`	object	Não	Endereço (ver campos abaixo)
`segment`	string	Não	Segmento do cliente
`source`	string	Não	Origem/canal de captação
`notes`	string	Não	Observações
`tags`	array	Não	Array de tags
`credit_limit`	number	Não	Limite de crédito

Campos do endereço (address):

Campo	Tipo	Descrição
`street`	string	Logradouro
`number`	string	Número
`complement`	string	Complemento
`neighborhood`	string	Bairro
`city`	string	Cidade
`state`	string	Estado (UF)
`zip_code`	string	CEP
`country`	string	País

Request

curl -X POST https://api.octabuild.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",
    "cpf": "123.456.789-00",
    "phone": "+55 11 99999-8888",
    "segment": "premium",
    "address": {
      "street": "Rua das Flores",
      "number": "123",
      "city": "São Paulo",
      "state": "SP",
      "zip_code": "01000-000"
    }
  }'

Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "PF",
    "name": "João da Silva",
    "email": "joao.silva@email.com",
    "cpf": "123.456.789-00",
    "phone": "+55 11 99999-8888",
    "segment": "premium",
    "status": "active",
    "address": {
      "street": "Rua das Flores",
      "number": "123",
      "city": "São Paulo",
      "state": "SP",
      "zip_code": "01000-000"
    },
    "created_at": "2026-02-25T10:30:00Z"
  }
}

GET /v1/clients/:id

Busca um cliente específico por ID.

Request

curl -X GET https://api.octabuild.com.br/v1/clients/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

PUT /v1/clients/:id

Atualiza um cliente existente. Envie apenas os campos que deseja atualizar.

Request

curl -X PUT https://api.octabuild.com.br/v1/clients/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": "vip",
    "address": {
      "city": "Campinas",
      "state": "SP"
    }
  }'

DELETE /v1/clients/:id

Desativa um cliente (soft delete). O cliente não é removido permanentemente.

Request

curl -X DELETE https://api.octabuild.com.br/v1/clients/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "inactive",
    "deactivated_at": "2026-02-25T15:00:00Z"
  }
}

Erros Comuns

Código	Erro	Solução
`400`	`Campo 'name' é obrigatório`	Informe o nome do cliente
`400`	`Campo 'type' é obrigatório`	Use `PF` ou `PJ`
`404`	`Cliente não encontrado`	Verifique o ID do cliente
`422`	`CPF já cadastrado`	CPF já existe na organização
`422`	`CNPJ já cadastrado`	CNPJ já existe na organização

Clientes

On this page