Consultar um cliente

Recupera a ficha completa de um cliente pelo seu ID público (cus_...), incluindo dados pessoais, documento, telefone, e-mails adicionais, metadados e as relações vinculadas (transações recentes, endereços e cartões tokenizados). Use quando precisar exibir um perfil, sincronizar um cliente com o seu CRM ou conferir os dados antes de criar uma cobrança.

GET /v1/customers/{customerId}

Como funciona

Esta é uma operação de leitura: ela não altera nada no servidor, é segura para repetir quantas vezes quiser (idempotente por natureza) e devolve o objeto completo do cliente — diferente da listagem, que retorna uma projeção leve de cada cliente (só os campos principais, sem as relações).

Ao receber a requisição, a API:

1. Valida o formato do customerId (precisa seguir o padrão prefixo_valor, ex.: cus_01hqzvabc).
2. Localiza o cliente que pertence à conta dona da SelectKey enviada. Você só enxerga clientes da sua própria conta (ou subconta).
3. Monta a resposta agregando, no mesmo objeto, as relações do cliente:
   • transactions[] — transações recentes (com amount, originalAmount, status, method);
   • addresses[] — endereços cadastrados, com o endereço principal marcado por primary;
   • cards[] — cartões tokenizados (guardados de forma segura), expostos apenas pelos primeiros e últimos dígitos e por um fingerprint, nunca pelo número completo.
4. Inclui o bloco merchant (quem é o lojista dono do recurso) e o bloco _links (links HATEOAS — atalhos prontos com a URL e o método de cada próxima ação possível: atualizar, excluir, listar etc.).

Quando usar (e quando não usar)

Use quando você já tem o id do cliente e precisa do registro completo: tela de perfil, atendimento de suporte, conferência de endereço/contato antes do checkout, ou sincronização pontual.

Não use para:

• Buscar por e-mail, documento, nome ou referência externa — você ainda não tem o id. Para isso use a listagem com filtros (parâmetros email, document, name, externalreference).
• Varrer todos os clientes em lote — pagine pela listagem.
• Detectar mudanças de estado (ex.: cliente ficou delinquent) por checagem repetida. A API proíbe polling; assine eventos de webhook para ser notificado. Veja Proibição de Polling.

Requisição

Headers

Por ser um GET sem corpo, não há Content-Type nem X-Idempotency-Key aqui. Veja Autenticação e Convenções.

Parâmetro de caminho

Exemplo curl

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

Resposta

200 OK — o corpo é o objeto completo do cliente. Valores monetários (ex.: transactions[].amount) são inteiros em centavos (5000 = R$ 50,00) e todos os timestamps são ISO 8601 em UTC (sufixo Z).

{
  "id": "cus_01hqzvabc",
  "firstName": "João",
  "lastName": "Silva",
  "email": "[email protected]",
  "birthdate": "1990-05-15",
  "gender": "male",
  "document": {
    "type": "cpf",
    "number": "12345678901"
  },
  "telephone": {
    "countryCode": "55",
    "areaCode": "11",
    "number": "999999999",
    "line": "5511999999999"
  },
  "available": true,
  "delinquent": false,
  "externalReference": "CRM-98765",
  "additionalEmails": [
    "[email protected]"
  ],
  "metadata": {
    "source": "website"
  },
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-10T09:15:25.000Z",
  "geolocation": null,
  "transactions": [
    {
      "id": "tra_01hqzvabc",
      "amount": 5000,
      "originalAmount": 5000,
      "status": "approved",
      "method": "credit",
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "addresses": [
    {
      "id": "addr_01hqzvabc",
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Sala 1",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "postcode": "01310100",
      "latitude": null,
      "longitude": null,
      "line": "Av. Paulista, 1000 - Bela Vista, São Paulo - SP, 01310100",
      "line1": "Av. Paulista, 1000",
      "line2": "Bela Vista",
      "line3": "São Paulo - SP",
      "primary": true,
      "metadata": {},
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "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"
    }
  ],
  "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."
    }
  }
}

Campos da resposta

Dados do cliente

document (objeto)

telephone (objeto)

transactions[] — transações recentes do cliente (projeção leve)

addresses[] — endereços do cliente

cards[] — cartões tokenizados do cliente

merchant e _links

Erros

A API responde erros com um envelope padrão cujo identificador estável é error.code — sempre trate pelo code, nunca pela message. Veja Tratamento de Erros e o Catálogo de Códigos de Erro.

Exemplo de 404 (cliente inexistente):

{
  "error": {
    "code": "customerNotFound",
    "statusCode": 404,
    "category": "client",
    "message": "Customer not found."
  }
}

Boas práticas

• Trate o ID como opaco. Guarde a string cus_... inteira; não a construa nem dependa do seu tamanho. Veja Convenções.
• Não use leitura repetida para detectar mudanças. Para saber quando um cliente muda, assine webhooks — polling é proibido e desperdiça seu limite de requisições.
• Não dependa da lista para detalhes. A listagem omite transactions, addresses e cards; faça o GET individual quando precisar deles.
• Converta dinheiro só na exibição. transactions[].amount vem em centavos; divida por 100 apenas para mostrar ao usuário.
• Mascare dados sensíveis na interface. Ao exibir documento ou cartão, mostre apenas o necessário (ex.: últimos dígitos) e respeite a proteção de dados pessoais (LGPD).
• Aproveite o fingerprint do cartão para reconhecer o mesmo cartão entre transações sem manipular o número real.
• Use _links para navegar. Em vez de montar URLs à mão para atualizar ou excluir, siga o href e o method que vêm em _links.
• Diferencie 400 de 404 no tratamento de erro, conforme o aviso acima.

Veja também

• Visão geral de Clientes — o modelo do objeto e o ciclo de vida do recurso.
• Listar clientes — busca por e-mail, documento, nome e referência externa, com paginação.
• Criar cliente e Atualizar cliente — operações de escrita.
• Excluir cliente — remoção do recurso.
• Convenções · Autenticação · Tratamento de Erros · Proibição de Polling