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

# Referência

> Cadastre clientes para reutilizar em cobranças e relatórios.

Customers representam os **clientes finais** da sua loja. Cadastrá-los é
**opcional** para criar cobranças, mas traz benefícios:

<CardGroup cols={2}>
  <Card title="Identificação" icon="id-card">
    Suas cobranças vinculam ao customer e ficam fáceis de filtrar/relatar.
  </Card>

  <Card title="Reutilização" icon="recycle">
    Use o mesmo `customerId` em várias cobranças sem reenviar dados.
  </Card>

  <Card title="Personalização" icon="user-pen">
    O nome do customer aparece na confirmação do pagamento PIX.
  </Card>

  <Card title="Filtros" icon="filter">
    Liste cobranças de um customer específico passando `customerId` no `GET`.
  </Card>
</CardGroup>

## Campos

| Campo   | Obrigatório? | Descrição                                                  |
| ------- | ------------ | ---------------------------------------------------------- |
| `email` | **Sim**      | E-mail válido                                              |
| `name`  | Não          | Nome completo (1 a 120 caracteres)                         |
| `taxId` | Não          | CPF (11 dígitos) ou CNPJ (14 dígitos) — único por merchant |
| `phone` | Não          | Telefone/celular (até 20 caracteres)                       |

<Note>
  Não existe um campo separado de "tipo de documento" — `taxId` aceita CPF
  ou CNPJ diretamente (a API identifica pelo tamanho).
</Note>

## Exemplo: criar customer

```bash theme={null}
POST /customers
{
  "email": "joao@exemplo.com",
  "name": "João Silva",
  "taxId": "12345678900",
  "phone": "+5511999999999"
}
```

**Resposta:**

```json theme={null}
{
  "data": {
    "id": "cust_018f3a2b7c4d7c40a1b2",
    "name": "João Silva",
    "email": "joao@exemplo.com",
    "taxId": "12345678900",
    "phone": "+5511999999999",
    "createdAt": "2026-04-19T18:32:11.420Z"
  },
  "error": null,
  "success": true
}
```

<Note>
  Diferente de outros dados sensíveis da API, o `taxId` volta **sem
  máscara** nas respostas — ele pertence ao seu merchant, não é exposto
  publicamente.
</Note>

<Note>
  **`taxId` é único por merchant.** Se você tentar criar um customer com um
  `taxId` já cadastrado, recebe `409 CONFLICT`. Use `GET /customers?taxId=...`
  para buscar antes de criar.
</Note>

## Operações disponíveis

| Operação                             | Endpoint                 |
| ------------------------------------ | ------------------------ |
| [Criar](/pages/customers/create)     | `POST /customers`        |
| [Listar](/pages/customers/list)      | `GET /customers`         |
| [Obter por ID](/pages/customers/get) | `GET /customers/{id}`    |
| [Remover](/pages/customers/delete)   | `DELETE /customers/{id}` |

<Note>
  Não existe rota para editar um cliente já cadastrado. Para corrigir um
  dado, remova (`DELETE`) e cadastre novamente.
</Note>