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

# Gestão de Clientes

> O objeto customer — o comprador (pessoa física ou jurídica) que reúne identidade, dados de cobrança e todo o histórico financeiro.

Um **customer** é o **comprador** — a pessoa física ou jurídica que compra de você. Ele reúne num só lugar a identidade e os dados de cobrança (nome, e-mail, telefone, CPF/CNPJ, nome de cobrança e endereço) e é o fio que liga todo o histórico de uma pessoa: pagamentos, assinaturas, invoices e métodos de pagamento salvos.

<Info>
  **O e-mail é a chave única dentro da organização.**

  O mesmo comprador continua sendo o mesmo `customer` por mais checkouts que ele faça — o e-mail (em minúsculas) identifica unicamente o cliente dentro da sua organização. Tentar criar um segundo cliente com um e-mail já em uso retorna `409`.
</Info>

## Modelo conceitual

```mermaid theme={}
flowchart LR
  B((Comprador)) -- e-mail único --> C[Customer]
  C --> PM[Métodos de pagamento]
  C --> SUB[Assinaturas]
  C --> INV[Invoices]
  C --> PAY[Pagamentos]
```

O `customer` é o ponto de ancoragem. Métodos de pagamento salvos, assinaturas, invoices e pagamentos apontam para ele — por isso o cliente nunca some de verdade quando há histórico (veja [Remover um cliente](#remover-um-cliente)).

## Anatomia do cliente

Este é o contrato público completo, retornado em `create`, `get`, `update`, itens de `list` e em `data.object` dos webhooks `customer.*`.

| Campo             | Tipo             | Descrição                                                                     |
| ----------------- | ---------------- | ----------------------------------------------------------------------------- |
| `id`              | `string`         | Identificador único. Usa o prefixo `cus_*`.                                   |
| `object`          | `string`         | Sempre `"customer"`.                                                          |
| `email`           | `string`         | E-mail do cliente. **Chave única** dentro da organização. Obrigatório.        |
| `name`            | `string \| null` | Nome do cliente.                                                              |
| `phone`           | `string \| null` | Telefone do cliente.                                                          |
| `document`        | `string \| null` | CPF ou CNPJ, **apenas dígitos**.                                              |
| `document_type`   | `string \| null` | `cpf` ou `cnpj`. Inferido pelo comprimento de `document` quando omitido.      |
| `billing_name`    | `string \| null` | Nome ou razão social usada em cobrança, quando diferente de `name`.           |
| `billing_address` | `object \| null` | Endereço de cobrança estruturado.                                             |
| `livemode`        | `boolean`        | `true` em produção; `false` em ambiente de teste.                             |
| `metadata`        | `object`         | Pares `string → string` livres, controlados por você. `{}` quando vazio.      |
| `created_at`      | `string`         | Data de criação em ISO 8601.                                                  |
| `updated_at`      | `string \| null` | Data da última atualização em ISO 8601; `null` enquanto nunca foi atualizado. |

O schema público campo a campo está em [Objeto customer](/api-reference/customers).

<Note>
  O cliente **não** carrega `organization_id` no payload — o escopo já vem da autenticação. E **não** existe `external_id`: a correlação com o seu sistema é via `metadata` (veja [Correlação com o seu sistema](#correlacao-com-o-seu-sistema)).
</Note>

### Endereço de cobrança

`billing_address` é um objeto estruturado. Quando não-nulo, todas as chaves são retornadas — as faltantes vêm como `null`.

| Campo         | Descrição                              |
| ------------- | -------------------------------------- |
| `line1`       | Rua, número e complemento principal.   |
| `line2`       | Complemento opcional.                  |
| `city`        | Cidade.                                |
| `state`       | Estado ou província.                   |
| `postal_code` | CEP ou código postal.                  |
| `country`     | País em código ISO de 2 letras (`BR`). |

## Como um cliente nasce

Há dois caminhos, e ambos chegam no mesmo objeto.

<Steps>
  <Step title="Você cria pela API">
    `POST /v1/customers` com pelo menos `email`. Útil quando o cadastro do comprador já existe no seu sistema antes da primeira cobrança.
  </Step>

  <Step title="O checkout resolve sozinho no confirm">
    Quando um comprador finaliza um checkout, a Chargefy resolve o cliente **no momento do confirm**: se a sessão foi criada vinculada a um cliente (campo `customer`), ela permanece **travada** nesse cliente; caso contrário, um **novo** cliente é criado com os dados preenchidos. A resolução acontece uma única vez por checkout.
  </Step>
</Steps>

<Note>
  **O e-mail não é uma chave de identidade.** Vários clientes podem ter o mesmo e-mail na mesma organização — a identidade é o `id` do cliente, não o e-mail. A Chargefy **não** reaproveita um cliente existente buscando pelo e-mail: a menos que a sessão seja criada com um `customer`, cada checkout cria um cliente novo. Para reusar um cliente que já existe no seu sistema, faça o lookup na sua base e crie a sessão passando o `customer` — veja [Criando checkout sessions](/guides/creating-checkout-sessions).
</Note>

## Criar um cliente

Só o `email` é obrigatório. Quando você envia `document`, a Chargefy já pré-prepara o cadastro financeiro interno para acelerar a primeira cobrança — esse passo é transparente e não aparece na resposta.

<CodeGroup>
  ```bash Mínimo (só e-mail) theme={}
  curl https://api.chargefy.io/v1/customers \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "nome@email.com"
    }'
  ```

  ```bash Pessoa física (CPF + cobrança) theme={}
  curl https://api.chargefy.io/v1/customers \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "billing_address": {
        "city": "São Paulo",
        "country": "BR",
        "line1": "Av. Paulista, 1000",
        "postal_code": "01310-100",
        "state": "SP"
      },
      "document": "12345678901",
      "email": "nome@email.com",
      "name": "Cliente Exemplo",
      "phone": "+5511999990000"
    }'
  ```

  ```bash Pessoa jurídica (CNPJ) theme={}
  curl https://api.chargefy.io/v1/customers \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "billing_name": "Empresa Exemplo LTDA",
      "document": "12345678000190",
      "document_type": "cnpj",
      "email": "nome@email.com"
    }'
  ```

  ```bash Correlacionando com o seu sistema theme={}
  curl https://api.chargefy.io/v1/customers \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "nome@email.com",
      "metadata": {
        "internal_user_id": "id_456",
        "reference_id": "id_789"
      }
    }'
  ```
</CodeGroup>

<Warning>
  Se já existir um cliente ativo com o mesmo `email` na organização, o create retorna `409` (`A customer with this email already exists`). Para alterar esse cliente, use o update em vez de tentar recriá-lo.
</Warning>

### Documento (CPF/CNPJ)

`document` aceita apenas dígitos — máscara e pontuação são normalizadas. O `document_type` é opcional:

| Você envia                                | Resultado                                           |
| ----------------------------------------- | --------------------------------------------------- |
| `document` sem `document_type`            | A Chargefy infere `cpf` ou `cnpj` pelo comprimento. |
| `document` + `document_type` explícito    | Usa o valor enviado; precisa ser `cpf` ou `cnpj`.   |
| `document_type` diferente de `cpf`/`cnpj` | Retorna `400`.                                      |

<Note>
  O documento é a chave **soberana da identidade de pagamento**. Cartões e demais instrumentos salvos são organizados por essa identidade — documentos diferentes resultam em identidades de pagamento diferentes, com instrumentos salvos separados. Isso protege contra atrelar um cartão à pessoa errada. Por isso o documento entra no fluxo de cobrança, e não apenas no cadastro do cliente.
</Note>

## Atualizar um cliente

O update é **merge**: você envia só os campos que mudam, e os ausentes ficam como estão. É um `POST` no próprio recurso (não há `PUT`/`PATCH` na API).

```bash theme={}
curl https://api.chargefy.io/v1/customers/cus_123 \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+5511988887777" }'
```

| Campo                           | Observação                                                                                     |
| ------------------------------- | ---------------------------------------------------------------------------------------------- |
| `email`                         | Não pode ficar vazio. Continua único na organização — colidir com outro cliente retorna `409`. |
| `name`, `phone`, `billing_name` | Envie `null` (ou string vazia) para limpar.                                                    |
| `document` / `document_type`    | Enviar qualquer um dos dois reavalia o par; `document` nulo limpa ambos.                       |
| `billing_address`               | Substitui o objeto inteiro; `null` limpa.                                                      |
| `metadata`                      | Substitui o objeto inteiro.                                                                    |

<Tip>
  A resposta direta do update **não** traz diff — só o objeto completo atualizado. Quem precisa saber o que mudou (e os valores anteriores) lê o webhook `customer.updated`, que carrega `data.previous_attributes`.
</Tip>

## Correlação com o seu sistema

Não existe campo `external_id` no cliente. Para amarrar um `customer` ao ID do seu próprio sistema, use `metadata` — um objeto livre `string → string` que a Chargefy guarda e devolve em toda resposta e em todos os webhooks daquele cliente.

```json theme={}
{
  "metadata": {
    "crm_account": "id_456",
    "internal_user_id": "id_789"
  }
}
```

<Note>
  `metadata` é sempre opcional e nunca interpretado pela Chargefy — é só armazenado e ecoado de volta. Use qualquer chave que faça sentido para você (`reference_id`, `internal_user_id`, `crm_account`).
</Note>

## Métodos de pagamento

Os métodos de pagamento salvos pertencem ao cliente, mas **não** vêm embutidos no objeto `customer`. Eles são lidos por um endpoint próprio.

<Note>
  O cliente não expõe um campo de método de pagamento padrão. Para listar ou inspecionar os cartões e demais instrumentos de um cliente, use o recurso [Métodos de pagamento](/api-reference/payment-methods).
</Note>

## Listar e filtrar

`GET /v1/customers` lista os clientes ativos da organização, do mais recente para o mais antigo, com paginação por cursor (`starting_after`, `ending_before`, `limit`). Há um filtro por `email`.

<CodeGroup>
  ```bash Listar (página) theme={}
  curl "https://api.chargefy.io/v1/customers?limit=20" \
    -H "Authorization: Bearer {{API_KEY}}"
  ```

  ```bash Buscar por e-mail theme={}
  curl "https://api.chargefy.io/v1/customers?email=nome@email.com" \
    -H "Authorization: Bearer {{API_KEY}}"
  ```

  ```bash Próxima página (cursor) theme={}
  curl "https://api.chargefy.io/v1/customers?limit=20&starting_after=cus_123" \
    -H "Authorization: Bearer {{API_KEY}}"
  ```
</CodeGroup>

Clientes removidos não aparecem na listagem. Veja [Listar customers](/api-reference/customers/list) para o contrato completo.

## Remover um cliente

`DELETE /v1/customers/{id}` expressa "tirar de uso". Internamente é um **soft-delete**: o registro permanece no banco para preservar o histórico financeiro (pagamentos, assinaturas, invoices), mas some de todos os caminhos de leitura — get, list e qualquer fluxo público.

```bash theme={}
curl -X DELETE https://api.chargefy.io/v1/customers/cus_123 \
  -H "Authorization: Bearer {{API_KEY}}"
```

<AccordionGroup>
  <Accordion title="O que o parceiro vê">
    A resposta é `{ "id": "cus_123", "object": "customer", "deleted": true }`. Para quem consome a API, o cliente **deixou de existir**: consultá-lo depois retorna `404` e ele não aparece mais na listagem.
  </Accordion>

  <Accordion title="O que acontece por baixo">
    O histórico associado (vendas, assinaturas, invoices) continua íntegro para auditoria e conciliação. O cliente apenas fica invisível na API; nenhum registro financeiro é apagado.
  </Accordion>
</AccordionGroup>

<Warning>
  O e-mail de um cliente removido fica liberado: você pode criar um novo cliente com o mesmo e-mail depois da remoção — será um `customer` novo, com novo `id`.
</Warning>

## Webhooks

Mudanças no cliente disparam eventos no envelope padrão. O payload sempre carrega o `customer` completo em `data.object`; eventos de update também trazem `data.previous_attributes` com os valores anteriores dos campos alterados.

| Evento                                                         | Quando dispara                                              |
| -------------------------------------------------------------- | ----------------------------------------------------------- |
| [`customer.created`](/api-reference/webhooks/customer.created) | Cliente criado (via API ou resolvido no checkout).          |
| [`customer.updated`](/api-reference/webhooks/customer.updated) | Algum campo do cliente mudou. Inclui `previous_attributes`. |
| [`customer.deleted`](/api-reference/webhooks/customer.deleted) | Cliente removido (soft-delete).                             |

## Autenticação e escopos

| Tipo de chave                  | Comportamento                                                                                    |
| ------------------------------ | ------------------------------------------------------------------------------------------------ |
| API key da própria organização | Atua direto na organização dona da chave; o header `Organization` é proibido.                    |
| API key de plataforma          | Exige o header `Organization: <organization_id>` apontando para uma organização conectada ativa. |

As operações exigem escopo `read` para `GET` e `write` para `POST`/`DELETE`.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Objeto customer" icon="user" href="/api-reference/customers">
    Schema público completo e campos retornados.
  </Card>

  <Card title="Criar cliente (API)" icon="code" href="/api-reference/customers/create">
    Contrato do `POST /v1/customers`.
  </Card>

  <Card title="Métodos de pagamento" icon="credit-card" href="/api-reference/payment-methods">
    Cartões e instrumentos salvos do cliente.
  </Card>

  <Card title="Assinaturas" icon="rotate" href="/api-reference/subscriptions">
    Como o cliente vira uma cobrança recorrente.
  </Card>
</CardGroup>