Visão geral

Introdução

O recurso de Clientes é um componente fundamental da Selectwin API, permitindo o gerenciamento completo de informações de clientes em sua plataforma. Este recurso fornece suporte para criação, consulta, atualização, exclusão e listagem de perfis de clientes, sendo vital para operações comerciais, processamento de pagamentos e análise de dados.

A API de Clientes foi projetada com foco em segurança, consistência e flexibilidade, permitindo que os desenvolvedores implementem soluções robustas para gestão de relacionamento com clientes (CRM) e operações de venda.

Conceito e Funcionalidade

Os Clientes representam entidades (pessoas físicas ou jurídicas) que realizam transações financeiras ou interagem com sua plataforma dentro do domínio de negócio. Este recurso é essencial para operações como processamento de pagamentos, gestão de endereços, análise de comportamento de compra e personalização da experiência do usuário.

Os clientes podem ter múltiplos documentos, informações de contato e endereços associados. O recurso de Clientes mantém relacionamentos com outros recursos da API, como Cartões, Endereços, Transações e Carteiras, permitindo uma gestão centralizada e coesa das informações dos usuários.

Estrutura do Objeto Cliente

O objeto Cliente contém informações detalhadas sobre a pessoa física ou jurídica. A estrutura básica inclui:

{
  "id": "cus_01hqzvabc",
  "firstName": "João",
  "lastName": "Silva",
  "email": "[email protected]",
  "document": {
    "type": "cpf",
    "number": "12345678900"
  },
  "telephone": {
    "countryCode": "55",
    "areaCode": "11",
    "number": "987654321",
    "line": "11987654321"
  },
  "birthdate": "1990-05-15",
  "gender": "male",
  "available": true,
  "delinquent": false,
  "externalReference": "CRM-98765",
  "additionalEmails": ["[email protected]"],
  "metadata": {
    "source": "website"
  },
  "createdAt": "2026-04-12T17:56:33.000Z",
  "updatedAt": "2026-04-12T17:56:33.000Z"
}

Notas importantes (fidelidade à API):

• Respostas individuais (create/read/update) incluem merchant + _links no nível raiz.
• Read (GET /v1/customers/{customerId}) adiciona ao objeto base os embeds transactions[], subscriptions[], addresses[] e cards[] (cada um o item do endpoint de lista do respectivo recurso, limitado aos 100 mais recentes).
• Create/Update retornam apenas o objeto base do cliente (sem os embeds).
• O objeto NÃO contém geolocation. telephone é um objeto { countryCode, areaCode, number, line } (todas as partes podem ser null); document é { type, number } (ou null).
• List: envelope paginado com itens completos do cliente + merchant + _links.
• List-all (GET /v1/customers/listall): array de projeções resumidas (sem merchant/_links).
• Delete: { id, resource: "customer", deleted: true, merchant, _links }.
• Export (POST /v1/customers/export): { succeeded: true }.

Recursos Disponíveis

Endpoints auxiliares: GET /v1/customers/listall (listagem resumida não paginada) e POST /v1/customers/export.

Validações e Segurança

O recurso de Clientes implementa diversas validações para garantir a integridade e precisão dos dados:

1. Validação de Documentos - CPF e CNPJ são validados quanto ao formato e dígitos verificadores; passaporte é alfanumérico (5–15 caracteres)
2. Validação de E-mail - Garante que os endereços de e-mail (principal e adicionais) estejam em formato válido
3. Consistência de Telefone - Cada parte do telefone (countryCode, areaCode, number, line) é validada como dígitos quando informada
4. Data de Nascimento - Validada no formato YYYY-MM-DD

As informações dos clientes são armazenadas de forma segura, seguindo padrões rígidos de proteção de dados pessoais e em conformidade com regulamentações como LGPD (Brasil) e GDPR (Europa).

Tipos de Documento Suportados

O campo document.type aceita exatamente os valores abaixo (minúsculas):

document.number aceita de 5 a 20 caracteres. Quando document.type não é informado, o número é aceito como dígitos (8–20). CPF/CNPJ são normalizados para apenas dígitos.

Webhooks Acionados

Casos de Uso Comuns

• Integração com CRM: Sincronize dados de clientes entre seu CRM e a plataforma Selectwin
• Checkout Personalizado: Utilize dados de clientes para oferecer uma experiência de checkout personalizada
• Análise de Dados: Colete e analise informações de clientes para insights de negócio
• Gestão de Relacionamento: Mantenha informações atualizadas para melhorar o relacionamento com clientes
• Segmentação de Público: Crie segmentos de clientes para campanhas de marketing direcionadas
• Retenção de Clientes: Analise comportamentos e histórico para estratégias de retenção
• Verificação de Risco: Utilize informações de clientes para análises de risco em transações

Melhores Práticas

1. Validar Dados Antes do Envio - Implemente validações do lado do cliente antes de enviar dados para a API
2. Armazenar Referências - Mantenha o ID do cliente para referências futuras em suas transações
3. Utilizar Metadados - Aproveite o campo de metadados para armazenar informações personalizadas do seu negócio
4. Manter Dados Atualizados - Atualize regularmente as informações dos clientes para garantir precisão
5. Implementar Tratamento de Erros - Desenvolva rotinas de tratamento para lidar com falhas nas requisições
6. Validar Autenticidade - Implemente medidas adicionais para verificar a autenticidade dos clientes
7. Proteger Dados Sensíveis - Trate informações pessoais com os devidos cuidados de segurança e privacidade

Solução de Problemas Comuns

Integração com Outros Recursos

O recurso de Clientes integra-se com:

• Endereços: Associação de endereços a clientes para entregas e faturamento
• Cartões: Associação de cartões de pagamento a perfis de clientes
• Transações: Processamento de pagamentos relacionados a clientes específicos
• Carteiras: Gerenciamento de carteiras digitais associadas a clientes
• Webhooks: Notificações em tempo real sobre mudanças em clientes
• Utils: Validação de documentos e outros dados de clientes