Criar um cliente

Visão Geral

Este endpoint permite cadastrar um novo cliente no sistema, fornecendo funcionalidades para armazenar informações pessoais, documentos, dados de contato e endereços. É especialmente útil para iniciar relacionamentos com novos usuários, possibilitar operações financeiras e garantir conformidade com requisitos legais.

Precauções

ATENÇÃO! Por favor, leia estas informações importantes antes de usar este endpoint.

• Dados Sensíveis: As informações de clientes são consideradas dados sensíveis e devem ser tratadas conforme as regulamentações de proteção de dados (LGPD/GDPR).
• Validação de Documentos: Certifique-se de que os documentos fornecidos (CPF/CNPJ) sejam válidos para evitar problemas futuros.
• E-mails Únicos: O sistema não permite dois clientes com o mesmo endereço de e-mail.

Descrição

O endpoint Criar Cliente permite cadastrar um novo cliente no sistema, armazenando informações essenciais como nome, documento, contato e endereço. Os dados são validados para garantir integridade e conformidade com requisitos legais, permitindo que você mantenha uma base de clientes consistente e atualizada.

Requisição

POST /v1/customers

Este endpoint é idempotente: reenvie o mesmo header de idempotência para não criar clientes duplicados em caso de retentativa.

Parâmetros da Requisição

Corpo da Requisição (Body)

{
  "firstName": "João",
  "lastName": "Silva",
  "email": "[email protected]",
  "document": {
    "type": "cpf",
    "number": "12345678900"
  },
  "telephone": {
    "countryCode": "55",
    "areaCode": "11",
    "number": "987654321",
    "line": "11987654321"
  },
  "gender": "male",
  "birthdate": "1990-01-01",
  "metadata": {
    "source": "website",
    "campaign": "black_friday"
  },
  "externalReference": "CUSTOMER_ID_12345",
  "additionalEmails": [
    "[email protected]",
    "[email protected]"
  ]
}

Endereços não fazem parte do corpo do cliente. Para associar um endereço, crie o cliente primeiro e depois use Criar Endereço (POST /v1/addresses) informando o customerId.

Atributos do Corpo da Requisição

Resposta - 201 Created

Se a requisição for bem-sucedida, o servidor retornará um código de status HTTP 201 Created e os detalhes do cliente recém-criado, incluindo o ID gerado pelo sistema.

Exemplo de Resposta

{
  "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-01-01",
  "gender": "male",
  "available": true,
  "delinquent": false,
  "externalReference": "CUSTOMER_ID_12345",
  "additionalEmails": [
    "[email protected]"
  ],
  "metadata": {
    "source": "website"
  },
  "createdAt": "2026-04-12T17:56:33.000Z",
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/customers/cus_01hqzvabc",
      "method": "GET",
      "description": "Read a customer."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/customers",
      "method": "POST",
      "description": "Create a new customer."
    },
    "update": {
      "href": "https://api.selectwin.io/v1/customers/cus_01hqzvabc",
      "method": "PUT",
      "description": "Update the customer."
    },
    "delete": {
      "href": "https://api.selectwin.io/v1/customers/cus_01hqzvabc",
      "method": "DELETE",
      "description": "Delete the customer."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/customers",
      "method": "GET",
      "description": "List all customers."
    }
  }
}

Atributos da Resposta

Create retorna o objeto base do cliente (sem os embeds transactions/subscriptions/addresses/cards) + merchant + _links.

Respostas de Erro

400 Bad Request

Ocorre quando a requisição contém dados inválidos ou está mal formatada.

{
  "error": {
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      {
        "firstName": "The firstName field must be between 2 and 255 characters."
      }
    ]
  }
}

409 Conflict

Ocorre quando já existe um cliente com o mesmo e-mail (customerEmailTaken) ou documento (customerDocumentTaken).

{
  "error": {
    "status": "Conflict",
    "statusCode": 409,
    "category": "conflict",
    "message": "A customer with this email already exists."
  }
}

Casos de Uso

1. Novo Usuário: Criar um perfil de cliente quando um novo usuário se registra em sua plataforma
2. Checkout de Convidado: Armazenar informações do cliente durante um processo de checkout sem conta
3. Migração de Dados: Importar clientes de sistemas legados para a plataforma Selectwin
4. Prospecção: Registrar potenciais clientes capturados em ações de marketing

Melhores Práticas

1. Validar Antes de Enviar: Implemente validações do lado do cliente para todos os campos antes de enviar a requisição
2. Armazenar o ID: Guarde o ID do cliente retornado para referência em operações futuras
3. Enviar Apenas o Necessário: Inclua apenas os campos realmente necessários para sua operação
4. Tratar Dados Sensíveis: Adote medidas de segurança adicionais ao lidar com documentos e dados pessoais

Integração com Outros Endpoints

• Use Consultar Cliente para verificar os dados do cliente após a criação
• Use Atualizar Cliente para complementar informações parcialmente enviadas
• Use Criar Endereço para adicionar múltiplos endereços ao cliente