Clientes

Buscar Cliente por Documento

Busca direta de um único cliente pelo CPF/CNPJ exato, retornando junto o endereço padrão dele.

Diferente de Listar Clientes, esta chamada não devolve lista nem paginação: retorna o objeto do cliente e o endereço em uma única resposta, pronto para preencher um formulário. Quando o documento não está cadastrado, a resposta é 200 com customer e address em null — não é erro.

Case de uso:

Como checkout próprio, quero consultar o CPF digitado pelo comprador e, se ele já for cliente, preencher nome, e-mail, telefone e endereço automaticamente.

GET/v1/customers

Base URL Produção:https://api.validapay.com.br

Base URL Sandbox:https://sandbox.validapay.com.br

Authorizations

bearer

Authorization

string · header · required

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

customers/read

Query Parameters

Name	Type	Value	Required	Description
lookupDocument	-	11144477735	Optional	CPF (11) ou CNPJ (14), apenas dígitos - required

← Anterior

Listar Clientes

Detalhar Cliente

const url = 'https://sandbox.validapay.com.br/v1/customers?lookupDocument=11144477735?lookupDocument=11144477735';

const options = {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer {{token}}'
  },
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

200200

{
  "customer": {
    "customerId": "cus_xxx",
    "name": "Alexandre Souza",
    "document": "11144477735",
    "email": "alexandre@exemplo.com.br",
    "phone": "5511987654321",
    "status": "ACTIVE"
  },
  "address": {
    "zipCode": "01310100",
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Sala 5",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "cityCode": "3550308"
  }
}

200200 (não encontrado)

{
  "customer": null,
  "address": null
}

← Anterior

Listar Clientes

Detalhar Cliente