Criar um cliente

Cria um novo cliente (um "customer") na sua conta Selectwin a partir do nome, documento, e-mail e telefone. Use este endpoint para registrar a pessoa que vai pagar antes de cobrá-la, vincular cartões e endereços, e correlacionar com o seu sistema via externalReference.

POST /v1/customers

Como funciona

Um cliente é o registro de quem compra de você. Ele guarda os dados de identificação (nome, documento, contato) e funciona como um "guarda-chuva" ao qual outros recursos se ligam: endereços (addresses), cartões tokenizados (cards) e transações.

Ao chamar POST /v1/customers, o servidor:

1. Valida o corpo (campos obrigatórios, formato do e-mail, dígitos do documento e do telefone).
2. Cria o cliente e gera um identificador público opaco no formato cus_....
3. Retorna 201 Created com o objeto completo do cliente, incluindo id, timestamps createdAt/updatedAt, o bloco merchant (a conta dona do registro) e os links HATEOAS (_links) para as próximas operações.

Tokenizar = transformar um dado sensível (como o número de um cartão) em uma referência segura. O cliente não recebe dados de cartão neste endpoint: cartões e endereços entram como recursos vinculados depois da criação, e aparecem nas listas cards[] e addresses[] da resposta (vazias em um cliente recém-criado).

O cliente nasce com dois status booleanos que você verá na resposta:

• available — indica se o cliente está ativo/utilizável (true em um cliente novo).
• delinquent — indica inadimplência (false em um cliente novo).

Idempotência

Criar é uma operação de escrita. Para evitar criar o mesmo cliente duas vezes caso a rede falhe e você precise repetir a requisição, envie o cabeçalho X-Idempotency-Key. Com a mesma chave, a API retorna o resultado da primeira chamada em vez de criar um duplicado. Veja Idempotência.

Quando usar (e quando não)

Use quando:

• Um novo usuário se cadastra na sua plataforma e você quer um registro persistente para cobranças futuras.
• Você vai importar/migrar clientes de um sistema legado (preencha externalReference com o ID de origem).
• Você captura leads em marketing e quer registrá-los desde já.

Pense duas vezes / alternativas:

• Se o cliente já pode existir (mesmo e-mail/documento), criar de novo retorna 409 customerAlreadyExists. Prefira buscar antes com Listar clientes usando os filtros email, document ou externalreference, e crie só se não encontrar.
• Para completar dados de um cliente já existente, use Atualizar cliente — não crie um novo.
• Endereços e cartões não entram no corpo deste endpoint; eles são recursos próprios vinculados ao cliente após a criação.

Requisição

Cabeçalhos

Corpo da requisição

Campos seguem camelCase, datas usam ISO 8601 / YYYY-MM-DD e valores monetários (quando houver, em outros endpoints) são inteiros em centavos. Detalhes em Convenções.

Exemplo de requisição

curl -X POST https://api.selectwin.io/v1/customers \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 7e2b9c1a-4f3d-4a8e-9b21-3c0d5f6a7b8c" \
  -d '{
    "firstName": "João",
    "lastName": "Silva",
    "email": "[email protected]",
    "document": {
      "type": "cpf",
      "number": "12345678901"
    },
    "telephone": {
      "countryCode": "55",
      "areaCode": "11",
      "number": "999999999"
    },
    "gender": "male",
    "birthdate": "1990-01-15",
    "externalReference": "CRM-USER-001",
    "additionalEmails": [
      "[email protected]"
    ],
    "metadata": {
      "crmId": "lead-42"
    }
  }'

O corpo mínimo válido é só o essencial — firstName, lastName e email:

{
  "firstName": "João",
  "lastName": "Silva",
  "email": "[email protected]"
}

Resposta

201 Created

A resposta é o objeto completo do cliente recém-criado. Note que addresses e cards vêm como listas (vazias em um cliente novo, pois ainda não há nada vinculado), geolocation pode vir null e o telephone ganha um campo derivado line (o número concatenado).

{
  "id": "cus_01hqzvabc",
  "firstName": "João",
  "lastName": "Silva",
  "email": "[email protected]",
  "birthdate": "1990-01-15",
  "gender": "male",
  "document": {
    "type": "cpf",
    "number": "12345678901"
  },
  "telephone": {
    "countryCode": "55",
    "areaCode": "11",
    "number": "999999999",
    "line": "5511999999999"
  },
  "geolocation": null,
  "available": true,
  "delinquent": false,
  "externalReference": "CRM-USER-001",
  "additionalEmails": [
    "[email protected]"
  ],
  "addresses": [],
  "cards": [],
  "metadata": {
    "crmId": "lead-42"
  },
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/customers",
      "method": "POST",
      "description": "Create a new customer."
    },
    "read": {
      "href": "https://api.selectwin.io/v1/customers/cus_01hqzvabc",
      "method": "GET",
      "description": "Read a 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."
    }
  }
}

Campos principais da resposta

Erros

Trate sempre pelo error.code (estável), nunca pela message. Veja o envelope em Tratamento de Erros e a lista completa no Catálogo de Códigos de Erro.

Exemplo de erro de validação (400), com detalhes por campo em error.params:

{
  "error": {
    "code": "invalidParameters",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      { "email": "email must be a valid email address" }
    ]
  }
}

Boas práticas

• Cheque duplicidade antes de criar. Consulte Listar clientes por email, document ou externalreference; só crie se não houver correspondência. Isso evita o 409 customerAlreadyExists.
• Envie X-Idempotency-Key. Em retries por timeout/rede, garante que você não cria o mesmo cliente duas vezes.
• Guarde o id retornado (cus_...) no seu banco, associado ao registro local — ele é a chave para ler, atualizar, cobrar e vincular cartões/endereços.
• Use externalReference com o ID do seu sistema. Facilita reconciliação e buscas futuras sem depender de e-mail.
• Documento só com dígitos. Para cpf/cnpj, remova pontuação antes de enviar (12345678901, não 123.456.789-01).
• Envie só o necessário. Campos opcionais ausentes não atrapalham; menos dados pessoais = menos exposição sob LGPD/GDPR.
• Valide no cliente antes do POST. Cheque formato de e-mail, dígitos de documento e telefone para reduzir idas e vindas com 400.
• Não faça parsing do id. O prefixo cus_ é só para leitura humana; trate o ID como string opaca e estável.

Veja também

• Visão geral de Clientes — o modelo do objeto, status e relações.
• Ler cliente — consultar a ficha completa (inclui transactions).
• Atualizar cliente — completar ou corrigir dados (PUT/PATCH).
• Listar clientes — buscar e filtrar antes de criar.
• Excluir cliente — remover um cliente.
• Convenções · Autenticação · Idempotência · Tratamento de Erros