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

# Clientes

> Como funcionam os clientes — o cadastro reutilizável, o que o torna único e a diferença para o comprador da transação.

O **cliente** (`cust_`) é o cadastro do comprador na sua conta: nome, e-mail, documento, telefone e,
opcionalmente, endereço. Você o cria uma vez e reutiliza o `id` em transações, pagamentos e
assinaturas, em vez de repetir os dados a cada venda.

Cadastrar é **opcional**. O `POST /transactions` aceita tanto um `customerId` quanto os dados do
comprador soltos — e mesmo com o cadastro, a transação guarda um retrato dele no momento da compra,
que não muda depois. O cliente é o cadastro **atual**; a transação é o que valia **naquele dia**.

<Info>
  Todas as rotas exigem o header `x-api-key` (sua chave de sandbox). Veja
  [Autenticação](/pt-BR/autenticacao). Os exemplos nas páginas de cada endpoint usam a base URL de
  sandbox `https://api.sandbox.z2pay.com/v1`.
</Info>

***

## Endpoints

Cada endpoint tem sua própria página, com os campos aceitos, exemplos e o playground para testar.

| Método  | Rota             | Descrição                                           |
| ------- | ---------------- | --------------------------------------------------- |
| `GET`   | `/customers`     | [Lista clientes com filtros](/pt-BR/customers/list) |
| `GET`   | `/customers/:id` | [Busca um cliente por ID](/pt-BR/customers/get)     |
| `POST`  | `/customers`     | [Cria um cliente](/pt-BR/customers/create)          |
| `PATCH` | `/customers/:id` | [Atualiza um cliente](/pt-BR/customers/update)      |

***

## O que torna um cliente único

**Documento e e-mail não podem se repetir na sua conta.** A checagem vale na criação e na
atualização, e a violação responde **409**, não `400` — é conflito com um cadastro que já existe, não
campo malformado. Para reaproveitar um cliente em vez de criar outro, busque por `?document=` ou
`?email=` em [`GET /customers`](/pt-BR/customers/list).

Na atualização, o conflito é sempre com **outro** cliente: reenviar o documento ou o e-mail que já
são dele mesmo não dá `409`.

<Note>
  **Cliente removido não ocupa mais o documento nem o e-mail.** A checagem só enxerga cadastros
  ativos. Se um cliente foi removido pelo painel, os valores dele voltam a ficar livres e um cadastro
  novo pode usá-los — com um `cust_` diferente, e sem herdar nada do anterior.
</Note>

***

## Não há como remover pela API

O cadastro de cliente não tem rota de remoção na API pública: cria-se e atualiza-se por integração,
mas apagar é ação de painel. Se precisar tirar um cliente, faça pelo dashboard.

**O que já aconteceu não muda.** Transações, pagamentos e assinaturas guardam o retrato do comprador
feito no dia da compra — remover o cadastro depois não reescreveria nada para trás, e é por isso que
a ausência dessa rota não deixa buraco no histórico.

**Para deixar de usar um cliente**, basta parar de referenciá-lo: nada obriga a apagá-lo, e o
`document` continua sendo o caminho para reencontrá-lo em
[`GET /customers`](/pt-BR/customers/list).

***

## Veja também

<CardGroup cols={2}>
  <Card title="Transações" icon="receipt" href="/pt-BR/transactions">
    Onde o cliente é usado — por `customerId` ou pelos dados soltos.
  </Card>

  <Card title="Cartões" icon="credit-card" href="/pt-BR/cards">
    Os cartões salvos de um cliente, para cobrar de novo sem pedir os dados.
  </Card>

  <Card title="Assinaturas" icon="repeat" href="/pt-BR/subscriptions/visao-geral">
    Cobrança recorrente vinculada a um cliente.
  </Card>

  <Card title="Erros" icon="triangle-alert" href="/pt-BR/erros">
    O formato do `409` de duplicidade e dos demais erros.
  </Card>
</CardGroup>