> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /api/v1/buyers/

> Retorna uma lista paginada de compradores da organização

Lista todos os compradores que realizaram transações na organização autenticada. Os compradores são filtrados automaticamente pelo contexto da organização do token — nunca é necessário passar `organization_id` como parâmetro.

## Autenticação

Requer **Organization Access Token (OAT)** via header `Authorization: Bearer`.

Escopos necessários: `web:read`, `web:write` ou `buyers:read`.

## Parâmetros de Query

**email** `string`

Filtrar por e-mail (busca parcial, sem diferença de maiúsculas/minúsculas)

**page** `integer` (default: 1)

Número da página

**limit** `integer` (default: 20)

Itens por página

## Resposta

**items** `array`

Lista de objetos de comprador

**Propriedades do comprador**

**id** `string`

ID interno do comprador

**email** `string`

E-mail do comprador

**first\_name** `string`

Nome

**last\_name** `string`

Sobrenome

**taxpayer\_id** `string`

CPF do comprador

**phone** `string`

Telefone

**zoop\_buyer\_id** `string`

ID do comprador no gateway de pagamentos (campo da API)

**created\_at** `string`

Data de criação (ISO 8601)

**pagination** `object`

**Propriedades**

**total\_count** `integer`

Total de itens

**max\_page** `integer`

Número máximo de páginas

## Exemplo

```bash cURL theme={null}
curl -X GET "https://api.chargefy.io/api/v1/buyers/?page=1&limit=20" \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN"
```

```typescript SDK theme={null}
import { Chargefy } from '@chargefy/sdk';

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
});

const buyers = await chargefy.buyers.list({ page: 1, limit: 20 });
```

## Resposta de Exemplo

```json theme={null}
{
  "items": [
    {
      "id": "b1a2c3d4e5f6",
      "email": "comprador@exemplo.com",
      "first_name": "João",
      "last_name": "Silva",
      "taxpayer_id": "12345678901",
      "phone": "11999990000",
      "zoop_buyer_id": "gw_buyer_abc123",
      "created_at": "2026-03-01T10:00:00Z"
    }
  ],
  "pagination": {
    "total_count": 150,
    "max_page": 8
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.