> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kavropay.online/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestão de Clientes (Customers API)

> Cadastre e gerencie a base de clientes pagadores da sua conta via API.

## Criar Cliente

`POST /v1/customers`

```bash theme={null}
curl -X POST https://api.kavropay.online/v1/customers \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Renata Alcantara",
    "document": "98765432100",
    "email": "renata@email.com",
    "phone": "21999998888"
  }'
```

**Resposta (HTTP 201 Created)**

```json theme={null}
{
  "id": "cus_abc123def456",
  "name": "Renata Alcantara",
  "document": "98765432100",
  "email": "renata@email.com",
  "phone": "21999998888",
  "created_at": "2026-08-26T12:00:00.000Z"
}
```

## Consultar Cliente

`GET /v1/customers/{id}`  •  escopo `payments:read`

Busca os dados de um cliente específico pelo ID retornado na criação.

```bash theme={null}
curl https://api.kavropay.online/v1/customers/cus_abc123def456 \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

**Resposta (HTTP 200 OK)**

```json theme={null}
{
  "id": "cus_abc123def456",
  "name": "Renata Alcantara",
  "document": "98765432100",
  "email": "renata@email.com",
  "phone": "21999998888",
  "created_at": "2026-08-26T12:00:00.000Z"
}
```

## Listar Clientes

`GET /v1/customers`

```bash theme={null}
curl "https://api.kavropay.online/v1/customers?search=Renata&limit=10" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

**Resposta (HTTP 200 OK)**

```json theme={null}
{
  "data": [
    {
      "id": "cus_abc123def456",
      "name": "Renata Alcantara",
      "document": "98765432100",
      "email": "renata@email.com",
      "phone": "21999998888",
      "created_at": "2026-08-26T12:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}
```

<CardGroup cols={2}>
  <Card title="Anterior: Status Unificado" icon="arrow-left" horizontal href="/status-unificado" />

  <Card title="Próximo: Saques PIX" icon="arrow-right" horizontal href="/saques-pix" />
</CardGroup>