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

# Clientes

> Cadastre quem paga você e ligue cada cobrança a um cliente.

Um cliente é quem paga as suas cobranças. Ligar a cobrança a ele (`customerId`) deixa o extrato e o painel mais claros e permite ver tudo o que aquela pessoa pagou. E-mail, celular e CPF/CNPJ ficam criptografados e só voltam para a sua conta.

## Criar um cliente

[`POST /v1/customers`](https://docs.wyzecash.com.br/referencia/clientes/criar-cliente) · escopo `customers:write`

**name** `string` *required*

2 a 120 caracteres.

**email** `string | null`

E-mail válido.

**phone** `string | null`

Celular com DDD (com ou sem +55), só números ou formatado.

**document** `string | null`

CPF ou CNPJ válido, com ou sem pontuação.

```bash theme={null}
curl -X POST https://api.wyzecash.com.br/v1/customers \
  -H "Authorization: Bearer bk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ana Souza", "email": "ana@exemplo.com", "phone": "11999998888", "document": "123.456.789-09" }'
```

```json theme={null}
{
  "id": "0d6c1a7e-5b7f-4f3e-9b2a-1c2d3e4f5a6b",
  "name": "Ana Souza",
  "email": "ana@exemplo.com",
  "phone": "11999998888",
  "document": "12345678909",
  "createdAt": "2026-10-08T15:00:00.000Z"
}
```

## Listar, ver, alterar e excluir

| Método | Rota | Escopo | O que faz |
| - | - | - | - |
| GET | [`/v1/customers`](https://docs.wyzecash.com.br/referencia/clientes/listar-clientes) | `customers:read` | todos os clientes ativos (lista simples, sem cursor) |
| GET | [`/v1/customers/{id}`](https://docs.wyzecash.com.br/referencia/clientes/consultar-cliente) | `customers:read` | um cliente |
| PATCH | [`/v1/customers/{id}`](https://docs.wyzecash.com.br/referencia/clientes/editar-cliente) | `customers:write` | muda `name`, `email`, `phone` ou `document`; `null` limpa o campo |
| DELETE | [`/v1/customers/{id}`](https://docs.wyzecash.com.br/referencia/clientes/excluir-cliente) | `customers:write` | esconde o cliente (`{ "removed": true }`); as cobranças antigas mantêm o nome dele |

## Clientes que vêm do link de pagamento

Quando um [link de pagamento](https://docs.wyzecash.com.br/endpoints/links-de-pagamento.md) pede dados (`customerFields`), quem paga vira cliente automaticamente e a cobrança já nasce ligada a ele.


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