> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usealpa.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Clientes
> Gerencie seus clientes e suas informações cadastrais. Crie, liste e consulte dados de clientes de forma simples e segura
## Visão geral
A **API de Clientes** permite gerenciar informações cadastrais dos seus clientes de forma centralizada. Você pode criar novos clientes, listar todos os cadastrados e consultar informações específicas.
## Funcionalidades
* **Cadastro completo**: Nome, email, telefone, CPF/CNPJ e endereço
* **Validação automática**: CPF/CNPJ e email são validados automaticamente
* **Busca e filtros**: Liste clientes com paginação e filtros
* **Integração**: Associe clientes a transações e links de pagamento
* **Segurança**: Todos os dados são criptografados e protegidos
## Criando seu primeiro cliente
### Requisição Básica
```bash theme={null}
curl -X POST "https://alpa-sistema-api.onrender.com/api/v1/clients" \
-H "Authorization: Bearer SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "João Silva",
"email": "joao.silva@email.com",
"phone": "11987654321",
"document": "12345678900"
}'
```
### Resposta
```json theme={null}
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "João Silva",
"email": "joao.silva@email.com",
"phone": "11987654321",
"document": "12345678900",
"documentType": "CPF",
"createdAt": "2025-12-30T00:00:00.000Z",
"updatedAt": "2025-12-30T00:00:00.000Z"
}
}
```
## Campos disponíveis
### Campos obrigatórios
| Campo | Tipo | Descrição |
| ------- | ------ | ---------------------------------------------- |
| `name` | string | Nome completo do cliente. Mínimo 3 caracteres. |
| `email` | string | Email válido do cliente. |
### Campos opcionais
| Campo | Tipo | Descrição |
| ---------- | ------ | --------------------------------------------------------- |
| `phone` | string | Telefone com DDD. Apenas números. Exemplo: "11987654321". |
| `document` | string | CPF (11 dígitos) ou CNPJ (14 dígitos). Apenas números. |
| `address` | object | Endereço completo do cliente. |
### Estrutura do endereço (`address`)
| Campo | Tipo | Descrição |
| -------------- | ------ | ----------------------------------------- |
| `street` | string | Nome da rua/avenida. |
| `number` | string | Número do imóvel. |
| `complement` | string | Complemento (apto, sala, etc). |
| `neighborhood` | string | Bairro. |
| `city` | string | Cidade. |
| `state` | string | Estado (UF). Exemplo: "SP", "RJ". |
| `zipCode` | string | CEP. Apenas números. Exemplo: "01310100". |
**Exemplo:**
```json theme={null}
{
"address": {
"street": "Avenida Paulista",
"number": "1578",
"complement": "Andar 5",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"zipCode": "01310200"
}
}
```
## 📖 Exemplos Completos
### Cliente Pessoa Física Completo
```javascript theme={null}
const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/clients', {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'Maria Santos',
email: 'maria.santos@email.com',
phone: '21987654321',
document: '12345678900',
address: {
street: 'Rua das Flores',
number: '123',
complement: 'Apto 45',
neighborhood: 'Centro',
city: 'Rio de Janeiro',
state: 'RJ',
zipCode: '20010020'
}
})
});
```
### Cliente Pessoa Jurídica
```javascript theme={null}
const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/clients', {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'Empresa XYZ Ltda',
email: 'contato@empresaxyz.com.br',
phone: '1133334444',
document: '12345678000190', // CNPJ
address: {
street: 'Avenida Brigadeiro Faria Lima',
number: '3477',
neighborhood: 'Itaim Bibi',
city: 'São Paulo',
state: 'SP',
zipCode: '04538133'
}
})
});
```
### Cliente Simples (Apenas Dados Essenciais)
```javascript theme={null}
const response = await fetch('https://alpa-sistema-api.onrender.com/api/v1/clients', {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'Pedro Oliveira',
email: 'pedro.oliveira@email.com'
})
});
```
## Listando clientes
### Listar Todos os Clientes
```bash theme={null}
curl -X GET "https://alpa-sistema-api.onrender.com/api/v1/clients?page=1&limit=20" \
-H "Authorization: Bearer SUA_API_KEY"
```
### Resposta
```json theme={null}
{
"success": true,
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "João Silva",
"email": "joao.silva@email.com",
"phone": "11987654321",
"document": "12345678900",
"documentType": "CPF",
"createdAt": "2025-12-30T00:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"totalPages": 1
}
}
```
### Parâmetros de Paginação
| Parâmetro | Tipo | Descrição | Padrão |
| --------- | ------ | ------------------------------------------------ | ------ |
| `page` | number | Número da página. | 1 |
| `limit` | number | Quantidade de registros por página. Máximo: 100. | 20 |
## Consultando um cliente específico
```bash theme={null}
curl -X GET "https://alpa-sistema-api.onrender.com/api/v1/clients/{id}" \
-H "Authorization: Bearer SUA_API_KEY"
```
### Resposta
```json theme={null}
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "João Silva",
"email": "joao.silva@email.com",
"phone": "11987654321",
"document": "12345678900",
"documentType": "CPF",
"address": {
"street": "Avenida Paulista",
"number": "1578",
"complement": "Andar 5",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"zipCode": "01310200"
},
"createdAt": "2025-12-30T00:00:00.000Z",
"updatedAt": "2025-12-30T00:00:00.000Z"
}
}
```
## Validações automáticas
### CPF/CNPJ
* CPF deve ter 11 dígitos
* CNPJ deve ter 14 dígitos
* Validação de dígitos verificadores
* Apenas números são aceitos
### Email
* Formato válido de email
* Domínio válido
### Telefone
* Apenas números
* DDD + número (10 ou 11 dígitos)
### CEP
* Apenas números
* 8 dígitos
## Casos de uso
### E-commerce
Cadastre clientes durante o checkout e mantenha histórico de compras.
### Assinaturas
Gerencie base de assinantes com dados completos para cobrança recorrente.
### Marketplace
Centralize informações de compradores de múltiplos vendedores.
### CRM
Integre com seu sistema de CRM para gestão completa de relacionamento.
## Boas práticas
**Dados mínimos**: Colete apenas os dados necessários para sua operação. Nem sempre é preciso solicitar endereço completo.
**LGPD**: Certifique-se de ter consentimento do cliente para armazenar seus dados pessoais. Implemente políticas de privacidade adequadas.
**Validação no frontend**: Valide CPF/CNPJ e email no frontend antes de enviar para a API para melhor experiência do usuário.
## Erros comuns
### Email já cadastrado
```json theme={null}
{
"success": false,
"error": {
"code": "DUPLICATE_EMAIL",
"message": "Email já cadastrado no sistema"
}
}
```
### CPF/CNPJ inválido
```json theme={null}
{
"success": false,
"error": {
"code": "INVALID_DOCUMENT",
"message": "CPF/CNPJ inválido"
}
}
```
### Campos obrigatórios ausentes
```json theme={null}
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Nome e email são obrigatórios"
}
}
```
## 📚 Próximos Passos
Veja todos os endpoints disponíveis
Associe clientes a transações
Crie links personalizados para seus clientes
Receba notificações em tempo real