Visão geral

O recurso Clientes (customer) representa as pessoas físicas ou jurídicas que compram de você ou interagem com a sua plataforma. Um cliente reúne identidade (nome, documento, e-mail, telefone), seus endereços e cartões tokenizados, e serve de âncora para transações, assinaturas e relatórios. Esta página explica o modelo do objeto, o ciclo de vida e todas as operações disponíveis; cada operação tem sua própria página detalhada.

O que é um cliente

Em termos práticos, o cliente é o "cadastro" central de quem paga. Você normalmente o cria uma vez (no checkout, no onboarding ou ao importar seu CRM) e o reutiliza em cada cobrança. Guardar o id do cliente (cus_...) no seu sistema permite:

• Cobrar de novo sem repedir os dados (cartões ficam vinculados ao cliente).
• Consultar o histórico de transações daquele comprador.
• Sincronizar seu CRM via externalReference e metadata.

Tokenizar significa substituir um dado sensível (como o número do cartão) por uma referência segura (um token). Os cartões aparecem no cliente apenas como card_... com bandeira e últimos dígitos — nunca o número completo.

O recurso segue as Convenções da API: campos em camelCase, IDs opacos no formato prefixo_valor, datas em ISO 8601 UTC e dinheiro sempre em centavos (inteiro). O prefixo de um cliente é sempre cus_.

Modelo do objeto

O exemplo abaixo é a forma completa retornada por uma leitura (GET /v1/customers/{customerId}). Os comentários explicam cada bloco — repare que transactions[] só aparece na leitura.

{
  "id": "cus_01hqzvabc",                  // ID opaco do cliente (prefixo cus_)
  "firstName": "João",
  "lastName": "Silva",
  "email": "[email protected]",
  "birthdate": "1990-05-15",              // data pura YYYY-MM-DD (sem hora)
  "gender": "male",                       // enum: male | female | other
  "document": {
    "type": "cpf",                        // enum: cpf | cnpj | passport
    "number": "12345678901"               // somente dígitos para cpf/cnpj
  },
  "telephone": {
    "countryCode": "55",
    "areaCode": "11",
    "number": "999999999",
    "line": "5511999999999"               // composto pela API (read-only)
  },
  "available": true,                      // cliente ativo/utilizável
  "delinquent": false,                    // marcado como inadimplente?
  "externalReference": "CRM-98765",       // sua referência no seu sistema
  "additionalEmails": [                   // e-mails extras (máx. 20)
    "[email protected]"
  ],
  "metadata": {                           // pares chave/valor livres (máx. 20)
    "source": "website"
  },
  "geolocation": null,                    // pode vir null
  "transactions": [                       // SÓ na leitura (read) — projeção leve
    {
      "id": "tra_01hqzvabc",
      "amount": 5000,                     // centavos = R$ 50,00
      "originalAmount": 5000,
      "status": "approved",
      "method": "credit",
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "addresses": [                          // endereços vinculados (ver Addresses)
    {
      "id": "addr_01hqzvabc",
      "street": "Av. Paulista",
      "number": "1000",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "postcode": "01310100",
      "primary": true,
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "cards": [                              // cartões tokenizados (ver Cards)
    {
      "id": "card_01hqzvabc",
      "holderName": "JOÃO SILVA",
      "brand": "visa",
      "firstDigits": "411111",
      "lastDigits": "1111",
      "fingerprint": "fp_a1b2c3d4",
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-10T09:15:25.000Z",
  "merchant": {                           // contexto do lojão dono da chave
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": { "self": { "href": "...", "method": "GET" } }  // HATEOAS (ver abaixo)
}

Campos principais

Ciclo de vida

Um cliente não tem uma máquina de estados com muitas transições; o que muda ao longo do tempo são suas flags (available, delinquent) e os recursos vinculados. O fluxo típico é:

• Criação retorna o objeto já com available: true e delinquent: false.
• Atualização com PUT substitui o conjunto de campos permitidos; com PATCH atualiza só o que você enviar.
• delinquent e available são derivados pela plataforma (histórico de pagamentos, regras internas) — você lê esses campos, não os define manualmente.
• Exclusão remove o cliente e retorna uma confirmação (deleted: true). Avalie as implicações antes — veja a página Excluir.

Operações

Todas as chamadas exigem o cabeçalho de autenticação SelectKey e usam a base https://api.selectwin.io/v1.

curl https://api.selectwin.io/v1/customers/cus_01hqzvabc \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Em produção a chave começa com sl_live_; em sandbox, com sl_test_. Nunca use Authorization: Bearer/Basic. Veja Autenticação.

Conceitos e relações

Documentos suportados

Telefone

Você envia o telefone em partes (countryCode, areaCode, number); a API devolve essas partes e o campo composto line (read-only). Não envie line na requisição.

externalReference e metadata

São os dois mecanismos para amarrar o cliente ao seu mundo: use externalReference para o identificador único do cliente no seu sistema (ideal para deduplicação via filtro na listagem) e metadata para anotações estruturadas (máximo 20 chaves; prefira valores curtos).

HATEOAS (_links)

Cada resposta traz _links com as próximas ações possíveis (self, read, update, delete, list, create) já com href e method prontos. Em vez de montar URLs à mão, prefira seguir esses links. Veja Recursos.

Recursos relacionados

• Endereços — endereços de cobrança/entrega vinculados ao cliente (addr_...).
• Cartões — cartões tokenizados do cliente (card_...), reutilizáveis em cobranças.
• Transações — pagamentos referenciam o cliente; aparecem resumidos em transactions[] na leitura.
• Webhook Events — notificações em tempo real de mudanças. Reaja a elas em vez de fazer polling (veja Proibição de Polling).

Erros comuns do recurso

Trate sempre pelo error.code (estável), nunca pela message. Estes são os códigos específicos de Clientes; os transversais (401, 403, 422, 429, 500) valem para todos os recursos.

Catálogo completo em Códigos de Erro; estrutura do envelope em Tratamento de Erros.

Boas práticas

• Guarde o id do cliente (cus_...) no seu sistema e trate-o como string opaca; é a chave para cobrar de novo e consultar histórico.
• Deduplique antes de criar. Antes de um POST, filtre a listagem por email, document ou externalreference para evitar customerAlreadyExists (409).
• Use externalReference para o ID do seu CRM e metadata para anotações — assim você correlaciona os dois sistemas sem campos paralelos.
• Envie documentos só com dígitos (cpf/cnpj) e lembre-se do tipo passport para clientes estrangeiros.
• Não dependa da forma de um endpoint em outro. Se precisa de transactions[], faça o Read; a listagem e o create/update não trazem esse campo.
• Use X-Idempotency-Key nas criações para evitar clientes duplicados em caso de retentativa de rede (veja Idempotência).
• Reaja a webhooks para saber de mudanças em vez de ficar relendo o cliente em laço.
• Resolva concorrência pelo updatedAt. Em atualizações simultâneas, compare o updatedAt antes de sobrescrever para não perder edições.

Veja também

• Criar Cliente
• Consultar Cliente
• Atualizar Cliente
• Listar Clientes
• Excluir Cliente
• Convenções da API · Autenticação · Paginação · Códigos de Erro