Buscar cliente

Retorna o cliente completo (todos os campos, incluindo endereço e metadata) acompanhado de **estatísticas agregadas**: assinaturas ativas, faturas em aberto e total pago histórico. As stats são calculadas em real-time no momento da requisição.

GET/v2/customers/:id

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

idstring (path, UUID)obrigatório

UUID do cliente.

Exemplo: c8a5f4d2-1b3e-4c9f-8a7d-2e5f6c1d4b9a

Respostas

200

Cliente encontrado. O bloco stats agrega informação dos recursos vinculados:

activeSubscriptions — assinaturas em status ACTIVE ou TRIAL
openInvoicesCount — faturas em PENDING ou OVERDUE
paidInvoicesCount — número de faturas em status PAID (histórico)
paidAmountTotal — soma de amountPaid das faturas pagas, em centavos

JSON

{
  "id": "c8a5f4d2-1b3e-4c9f-8a7d-2e5f6c1d4b9a",
  "createdByUserId": "u-1234",
  "name": "João Silva",
  "email": "joao.silva@exemplo.com",
  "document": "12345678901",
  "phone": "11987654321",
  "birthDate": "1990-05-15T00:00:00.000Z",
  "cep": "01310100",
  "address": "Avenida Paulista",
  "addressNumber": "1000",
  "complement": "Sala 501",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "notes": "Cliente recorrente do plano premium",
  "metadata": { "source": "landing-page" },
  "deletedAt": null,
  "createdAt": "2026-05-26T14:32:01.923Z",
  "updatedAt": "2026-05-26T14:32:01.923Z",
  "stats": {
    "activeSubscriptions": 2,
    "openInvoicesCount": 1,
    "paidInvoicesCount": 14,
    "paidAmountTotal": 15400
  }
}

404

Cliente não encontrado nessa conta. Note que clientes são isolados por seller — o ID precisa pertencer à conta dona da API key.

JSON

{
  "status": 404,
  "error": "Cliente nao encontrado"
}

Exemplos

cURL

curl -X GET "https://api.pagnovo.com/v2/customers/c8a5f4d2-1b3e-4c9f-8a7d-2e5f6c1d4b9a" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)"

JavaScript

const token = Buffer.from("secret:" + process.env.PAGNOVO_SECRET_KEY).toString("base64");
 
const res = await fetch(
  `https://api.pagnovo.com/v2/customers/${customerId}`,
  { headers: { Authorization: `Basic ${token}` } },
);
 
if (res.status === 404) return null;
 
const customer = await res.json();
console.log(`${customer.name} — ${customer.stats.activeSubscriptions} assinaturas ativas`);
console.log(`Faturado: R$ ${(customer.stats.paidAmountTotal / 100).toFixed(2)}`);