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

# Clientes

> Crie, filtre, consulte e remova clientes do merchant.

Clientes representam as pessoas associadas às cobranças do merchant. O `id` retornado em todas as operações pode ser usado no campo opcional `customerId` de `POST /checkouts`.

<CardGroup cols={3}>
  <Card title="Criar cliente" icon="user-plus">
    Requer uma API key `FULL_ACCESS`.
  </Card>

  <Card title="Listar clientes" icon="list">
    Aceita API keys `READ_ONLY` e `FULL_ACCESS`.
  </Card>

  <Card title="Remover clientes" icon="user-minus">
    A remoção exige uma API key `FULL_ACCESS`.
  </Card>
</CardGroup>

## Criar um cliente

```bash theme={null}
curl --request POST 'https://api-sandbox.fortalpay.tech/v1/customers' \
  --header 'Authorization: ApiKey <full_access_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Maria Silva",
    "email": "maria@example.com",
    "document": "529.982.247-25",
    "phone": "(85) 99999-9999"
  }'
```

### Campos da requisição

| Campo      | Obrigatório | Regra                                                                              |
| ---------- | ----------- | ---------------------------------------------------------------------------------- |
| `name`     | Sim         | Não pode ser vazio e aceita até 150 caracteres.                                    |
| `email`    | Sim         | Não pode ser vazio e deve ser um e-mail válido com até 150 caracteres.             |
| `document` | Não         | CPF ou CNPJ com até 20 caracteres. A formatação é removida antes do armazenamento. |
| `phone`    | Não         | Telefone com até 20 caracteres. A formatação é removida antes do armazenamento.    |

O nome é normalizado, o e-mail é armazenado em letras minúsculas e documento e telefone ficam somente com dígitos. Se o documento já estiver associado à conta do merchant, a API reutiliza o cliente existente.

<Info>
  A criação retorna HTTP `200` e expõe o identificador público no campo `id`, assim como as rotas de listagem e consulta.
</Info>

## Listar clientes

```bash theme={null}
curl --request GET 'https://api-sandbox.fortalpay.tech/v1/customers?page=0&size=20' \
  --header 'Authorization: ApiKey <api_key>'
```

A listagem retorna somente clientes associados ao merchant da API key, ordenados pela data de criação em ordem decrescente. O tamanho efetivo da página é limitado a 100.

### Filtrar clientes

Use `search` para buscar de uma vez por nome, e-mail, documento ou telefone:

```bash theme={null}
curl --request GET 'https://api-sandbox.fortalpay.tech/v1/customers?search=Maria&page=0&size=20' \
  --header 'Authorization: ApiKey <api_key>'
```

Também é possível combinar filtros específicos. Todos os filtros informados são aplicados em conjunto.

| Parâmetro  | Comportamento                                                  |
| ---------- | -------------------------------------------------------------- |
| `search`   | Busca parcial geral por nome, e-mail, documento e telefone.    |
| `name`     | Busca parcial sem diferenciar maiúsculas e minúsculas.         |
| `email`    | Busca parcial sem diferenciar maiúsculas e minúsculas.         |
| `document` | Busca parcial; pontuação de CPF ou CNPJ é ignorada.            |
| `phone`    | Busca parcial; formatação é ignorada.                          |
| `status`   | Correspondência exata sem diferenciar maiúsculas e minúsculas. |

## Consultar pelo identificador

```bash theme={null}
curl --request GET 'https://api-sandbox.fortalpay.tech/v1/customers/<customer_id>' \
  --header 'Authorization: ApiKey <api_key>'
```

Um identificador inexistente, removido ou pertencente a outro merchant retorna `404`.

## Remover um cliente

```bash theme={null}
curl --request DELETE 'https://api-sandbox.fortalpay.tech/v1/customers/<customer_id>' \
  --header 'Authorization: ApiKey <full_access_api_key>'
```

A remoção é lógica e retorna HTTP `204` sem corpo. O cliente deixa de aparecer na listagem e não pode mais ser consultado ou usado em novas cobranças pelo merchant. Registros históricos permanecem preservados.

## Campos retornados

| Campo        | Tipo           | Descrição                                |
| ------------ | -------------- | ---------------------------------------- |
| `id`         | UUID           | Identificador público do cliente.        |
| `name`       | string         | Nome normalizado.                        |
| `email`      | string \| null | E-mail normalizado em letras minúsculas. |
| `document`   | string \| null | CPF ou CNPJ somente com dígitos.         |
| `phone`      | string \| null | Telefone somente com dígitos.            |
| `status`     | enum           | Estado do cliente. Atualmente, `ACTIVE`. |
| `created_at` | date-time      | Data de criação.                         |
| `updated_at` | date-time      | Data da última atualização.              |