Consultar um cliente

Visão Geral

Este endpoint permite recuperar informações detalhadas de um cliente específico, fornecendo todos os dados associados ao cliente através de seu identificador único. É especialmente útil para verificar informações de contato, visualizar dados de endereçamento e acessar metadados antes de realizar operações.

Precauções

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

• Permissões de Acesso: Verifique se você possui permissões para acessar as informações do cliente solicitado.
• Proteção de Dados: As informações retornadas contêm dados pessoais sensíveis e devem ser tratadas com segurança.
• Caching: Considere implementar estratégias de cache para reduzir chamadas repetitivas à API.

Descrição

O endpoint Consultar Cliente permite recuperar todos os detalhes de um cliente específico a partir de seu ID único. A resposta inclui informações pessoais, documentos, dados de contato, endereços e qualquer metadado personalizado associado ao cliente.

Requisição

GET /v1/customers/{customerId}

Parâmetros de Caminho (Path) e Consulta (Query)

Resposta - 200 OK

Se a requisição for bem-sucedida, o servidor retornará um código de status HTTP 200 OK e os detalhes completos do cliente solicitado.

Exemplo de Resposta

Resposta no nível raiz. O objeto base do cliente é estendido com quatro embeds — transactions[], subscriptions[], addresses[] e cards[] — cada um sendo o item do endpoint de lista do respectivo recurso (limitado aos 100 mais recentes; um embed vazio degrada para []). Inclui também merchant + _links.

{
  "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",
  "transactions": [
    { "id": "tra_01hqzvabc", "status": "approved", "amount": 5000 }
  ],
  "subscriptions": [
    { "id": "sub_01hqzvabc", "status": "active" }
  ],
  "addresses": [
    {
      "id": "addr_01hqzvabc",
      "ownerType": "customer",
      "ownerId": "cus_01hqzvabc",
      "street": "Av. Paulista",
      "city": "São Paulo",
      "primary": true
    }
  ],
  "cards": [
    {
      "id": "card_01hqzvabc",
      "brand": "visa",
      "last4": "4242"
    }
  ],
  "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

Resposta inclui o objeto base + 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": [
      {
        "customerId": "The format of the customer ID is invalid."
      }
    ]
  }
}

404 Not Found

Ocorre quando o customerId não existe ou não pertence à sua conta (customerNotFound).

{
  "error": {
    "status": "Not Found",
    "statusCode": 404,
    "category": "resource",
    "message": "Customer not found."
  }
}

Casos de Uso

1. Verificação de Perfil: Exibir informações detalhadas do cliente em uma página de perfil
2. Preparação para Checkout: Recuperar dados de endereço e contato antes de iniciar um processo de pagamento
3. Confirmação de Identidade: Verificar documentos e dados de contato para processos de verificação
4. Suporte ao Cliente: Acessar detalhes do cliente durante atendimento de suporte

Melhores Práticas

1. Armazenar em Cache: Implemente estratégias de cache para dados que não mudam com frequência
2. Tratamento de Erros Robusto: Implemente tratamento adequado para erros 404 (cliente não encontrado)
3. Limitação de Exibição: Ao exibir dados para usuários finais, considere ocultar partes sensíveis de documentos
4. Verificação de Permissões: Sempre verifique se o usuário tem permissão para acessar os dados do cliente

Integração com Outros Endpoints

• Use Atualizar Cliente para modificar as informações após visualizá-las
• Use Listar Clientes para buscar múltiplos clientes com filtros
• Use Listar Endereços para visualizar todos os endereços associados ao cliente