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
curl -X POST "https://upay-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
{
"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”. |
{
"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
const response = await fetch('https://upay-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
const response = await fetch('https://upay-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)
const response = await fetch('https://upay-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
curl -X GET "https://upay-sistema-api.onrender.com/api/v1/clients?page=1&limit=20" \
-H "Authorization: Bearer SUA_API_KEY"
Resposta
{
"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
curl -X GET "https://upay-sistema-api.onrender.com/api/v1/clients/{id}" \
-H "Authorization: Bearer SUA_API_KEY"
Resposta
{
"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
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
{
"success": false,
"error": {
"code": "DUPLICATE_EMAIL",
"message": "Email já cadastrado no sistema"
}
}
CPF/CNPJ inválido
{
"success": false,
"error": {
"code": "INVALID_DOCUMENT",
"message": "CPF/CNPJ inválido"
}
}
Campos obrigatórios ausentes
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Nome e email são obrigatórios"
}
}
📚 Próximos Passos
