# Clientes

Estas rotas devolvem o **cadastro dos clientes** da empresa: quem são, como falar com eles, onde moram e quanto compraram. Servem para sincronizar a carteira com um CRM externo, medir clientes novos por mês e cruzar o cliente com eventos, orçamentos e cobranças pelo `clientId`.

**Escopo exigido:** `clients:read`. Sem ele, as rotas respondem [`scope_missing`](https://developers.festero.com.br/errors.md#scope_missing).

> **Atenção**: Este é o escopo mais sensível da API
>
> O cadastro sai **completo**: nome, CPF ou CNPJ, e-mail, telefone, endereço e inscrições. Por isso o escopo é separado do CRM, e só quem enxerga os clientes no Festero consegue conceder. Dê esta permissão apenas a sistemas em que você confia e que precisam do cadastro. Continuam fora: anotações internas, o documento do representante legal e qualquer dado de convidado ou de criança.

[Testar na referência interativa](https://developers.festero.com.br/referencia/)

## Listar clientes

### `GET /v1/clients`

Lista os clientes da empresa, da alteração mais antiga para a mais recente, com [paginação por cursor](https://developers.festero.com.br/paginacao.md). Não existe busca por nome, telefone ou documento: a lista inteira sai paginada.

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `isActive` | `true` ou `false` | Só os ativos ou só os inativos. Sem o parâmetro, todos. |
| `createdFrom` | data `yyyy-MM-dd` | Só os cadastrados a partir desta data (inclusive), no horário de Brasília. |
| `createdTo` | data `yyyy-MM-dd` | Só os cadastrados até esta data (inclusive). |
| `updatedSince` | data e hora ISO 8601 | Só os clientes alterados a partir deste instante. |
| `limit` | inteiro | Tamanho da página, de 1 a 100 (padrão 25). |
| `cursor` | texto | O `nextCursor` da página anterior. |

```bash
curl "https://platform.festero.com.br/v1/clients?isActive=true&limit=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```json
{
  "data": [
    {
      "id": "2a7b5c90-31de-4f68-b4a2-6e0d8c19f533",
      "name": "Marina Albuquerque",
      "kind": "person",
      "taxIdType": "cpf",
      "taxId": "11144477735",
      "email": "marina@exemplo.com.br",
      "phone": "71999990000",
      "street": "Rua das Acácias",
      "number": "120",
      "complement": null,
      "neighborhood": "Pituba",
      "postalCode": "41830000",
      "city": "Salvador",
      "state": "BA",
      "municipalRegistration": null,
      "stateRegistration": null,
      "fiscalEmail": null,
      "legalRepresentativeName": null,
      "isActive": true,
      "isAnonymized": false,
      "anonymizedAt": null,
      "eventsCount": 3,
      "createdAt": "2026-03-04T10:21:07-03:00",
      "updatedAt": "2026-09-12T16:40:02-03:00"
    }
  ],
  "nextCursor": null
}
```

## Buscar um cliente

### `GET /v1/clients/{id}`

Devolve um cliente pelo identificador, com os mesmos campos da lista. Responde `404` ([`not_found`](https://developers.festero.com.br/errors.md#not_found)) se ele não existe ou é de outra empresa. A resposta traz `ETag`: veja [Paginação e datas](https://developers.festero.com.br/paginacao.md#recurso-individual-etag).

## Campos do cliente

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | GUID | Identificador do cliente. |
| `name` | texto | Nome. Trechos que parecem telefone, e-mail ou documento aparecem como `[oculto]` (cliente criado pelo WhatsApp às vezes fica com o telefone no nome). |
| `kind` | texto | `person` (pessoa física) ou `company` (empresa), pelo tipo do documento. |
| `taxIdType` | texto ou `null` | `cpf` ou `cnpj`. |
| `taxId` | texto ou `null` | CPF ou CNPJ, só dígitos. |
| `email`, `phone` | texto ou `null` | Contato do cliente, como cadastrado. |
| `street`, `number`, `complement`, `neighborhood`, `postalCode`, `city`, `state` | texto ou `null` | Endereço. `postalCode` só com dígitos. |
| `municipalRegistration`, `stateRegistration`, `fiscalEmail` | texto ou `null` | Dados fiscais, usados na nota fiscal de serviço. |
| `legalRepresentativeName` | texto ou `null` | Representante legal, quando o cliente é uma empresa. O documento dele não sai. |
| `isActive` | booleano | Falso quando o cliente foi inativado. |
| `isAnonymized`, `anonymizedAt` | booleano, data | Verdadeiro quando o cliente pediu a anonimização (LGPD); o nome já vem substituído. |
| `eventsCount` | inteiro | Eventos do cliente em qualquer status, como a tela de Clientes. |
| `createdAt`, `updatedAt` | data e hora | Instantes do cadastro e da última alteração. |

## Resumo de um cliente

### `GET /v1/clients/{id}/summary`

Resume o relacionamento comercial com o cliente.

| Campo | Descrição |
|---|---|
| `eventsCount`, `soldEventsCount` | Eventos em qualquer status e eventos vendidos (`upcoming` e `completed`). |
| `totalSpent` | Soma do valor dos eventos vendidos. |
| `receivedTotal`, `outstandingTotal` | Quanto já foi recebido e quanto falta receber nas contas a receber do cliente. |
| `lastEventDate`, `nextEventDate` | Último evento passado e próximo evento, sem contar rascunhos e cancelados. |
| `openQuotesCount`, `openOpportunitiesCount` | Orçamentos em rascunho ou enviados e oportunidades em aberto. |

Os três campos de dinheiro (`totalSpent`, `receivedTotal`, `outstandingTotal`) só vêm preenchidos quando a credencial **também** tem o escopo [`finance:read`](https://developers.festero.com.br/api/financeiro.md); sem ele ficam `null` e o resto da resposta continua.

## Análise da carteira

### `GET /v1/clients/analytics`

Os mesmos números da aba **Clientes** dos relatórios do Festero: clientes cadastrados, clientes com eventos no período, novos no último mês, receita média por cliente, os 10 que mais geraram receita e os clientes novos por mês (12 meses). A receita é a dos orçamentos aprovados cujo evento não foi cancelado.

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `createdFrom` | data `yyyy-MM-dd` | Só os eventos criados a partir desta data. Sem o parâmetro, toda a história. |
| `createdTo` | data `yyyy-MM-dd` | Só os eventos criados até esta data (inclusive). |

O período filtra os eventos pela **data de criação** (como a tela). Os valores em dinheiro (`averageRevenuePerClient` e `totalRevenue` de cada cliente do ranking) só vêm com `finance:read` também.