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çoValidação automática : CPF/CNPJ e email são validados automaticamenteBusca e filtros : Liste clientes com paginação e filtrosIntegração : Associe clientes a transações e links de pagamentoSeguranç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 namestring Nome completo do cliente. Mínimo 3 caracteres. emailstring Email válido do cliente.
Campos opcionais Campo Tipo Descrição phonestring Telefone com DDD. Apenas números. Exemplo: “11987654321”. documentstring CPF (11 dígitos) ou CNPJ (14 dígitos). Apenas números. addressobject Endereço completo do cliente.
Estrutura do endereço (address) Campo Tipo Descrição streetstring Nome da rua/avenida. numberstring Número do imóvel. complementstring Complemento (apto, sala, etc). neighborhoodstring Bairro. citystring Cidade. statestring Estado (UF). Exemplo: “SP”, “RJ”. zipCodestring CEP. Apenas números. Exemplo: “01310100”.
Exemplo: { "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 pagenumber Número da página. 1 limitnumber 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
Referência da API Veja todos os endpoints disponíveis
Transações Associe clientes a transações
Links de Pagamento Crie links personalizados para seus clientes
Webhooks Receba notificações em tempo real
