Referência da API

Listar clientes

Retorna a lista paginada de clientes da sua conta. Suporta busca textual em nome/email/documento. Resultados ordenados por `createdAt DESC` (mais recentes primeiro).

GET/v2/customers

Paginação 0-indexed

page Diferente do resto do mundo: `page=0` é a primeira página, não `page=1`. Se você passar `page=1` esperando o primeiro resultado, vai receber o segundo bloco e pular os primeiros 20 clientes.

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

pagenumber (query, 0-indexed)opcional

Página, começando em 0. Padrão: 0.

Exemplo: 0

limitnumber (query)opcional

Quantidade por página. Padrão: 20. Máximo: 100 (valores acima são clampados).

Exemplo: 20

searchstring (query)opcional

Busca textual case-insensitive em `name`, `email` e `document`. Para o `document`, o servidor extrai apenas os dígitos do termo antes de buscar — então `"123.456"` casa com `"12345678901"`.

Exemplo: joão

includeDeletedboolean (query, string)opcional

Passe `true` para incluir clientes arquivados na resposta. Padrão: false (apenas ativos).

Exemplo: true

Respostas

200

Lista retornada. Campos no result são um subset reduzido (sem endereço, notes ou metadata) — para o objeto completo, faça GET /v2/customers/:id.

JSON

{
  "result": [
    {
      "id": "c8a5f4d2-1b3e-4c9f-8a7d-2e5f6c1d4b9a",
      "name": "João Silva",
      "email": "joao.silva@exemplo.com",
      "document": "12345678901",
      "phone": "11987654321",
      "city": "São Paulo",
      "state": "SP",
      "deletedAt": null,
      "createdAt": "2026-05-26T14:32:01.923Z"
    },
    {
      "id": "d9b6e5f3-2c4f-5d0a-9b8e-3f6g7d2e5c1b",
      "name": "Maria Souza",
      "email": "maria@exemplo.com",
      "document": "98765432100",
      "phone": "11912345678",
      "city": "Rio de Janeiro",
      "state": "RJ",
      "deletedAt": null,
      "createdAt": "2026-05-25T10:15:00.000Z"
    }
  ],
  "totalCount": 42
}

Exemplos

cURL

# Primeira página (page=0!)
curl -X GET "https://api.pagnovo.com/v2/customers" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)"
 
# Busca por documento
curl -X GET "https://api.pagnovo.com/v2/customers?search=12345678&limit=50" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)"
 
# Incluir deletados
curl -X GET "https://api.pagnovo.com/v2/customers?includeDeleted=true" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)"

JavaScript

const token = Buffer.from("secret:" + process.env.PAGNOVO_SECRET_KEY).toString("base64");
 
// Itera todas as paginas — note o page=0 inicial
let page = 0;
const limit = 100;
const all = [];
 
while (true) {
  const res = await fetch(
    `https://api.pagnovo.com/v2/customers?page=${page}&limit=${limit}`,
    { headers: { Authorization: `Basic ${token}` } },
  );
  const { result, totalCount } = await res.json();
  all.push(...result);
  if (all.length >= totalCount) break;
  page++;
}
 
console.log("total:", all.length);