> ## 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 `id` identifica o customer.**

  O e-mail é um dado de contato e pode aparecer em mais de um customer da mesma
  organização. Ao criar um customer diretamente pela API, você decide quando
  reutilizar um `id` que já conhece e quando criar outro cadastro.
</Info>

## Como os recursos se relacionam

| Recurso              | Relação com o `customer`                   |
| -------------------- | ------------------------------------------ |
| Comprador            | É representado pelo cadastro do cliente.   |
| Métodos de pagamento | Ficam salvos no cliente.                   |
| Assinaturas          | Apontam para o cliente assinante.          |
| Invoices             | Apontam para o cliente cobrado.            |
| Pagamentos           | Compõem o histórico financeiro do cliente. |

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. Obrigatório, mas não único dentro da organização.          |
| `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`. Cada chamada de criação aceita
    um novo customer, mesmo quando outro cadastro já usa o mesmo e-mail. Se
    houver `document`, ele não pode pertencer a outro customer ativo da
    organização.
  </Step>

  <Step title="O checkout resolve sozinho no confirm">
    Quando o comprador confirma um checkout, a Chargefy mantém o customer fixado
    na sessão. Sem customer fixado, procura primeiro um cadastro ativo com o
    mesmo CPF/CNPJ e, depois, o cadastro ativo mais antigo com o mesmo e-mail,
    sempre dentro da mesma organização e do mesmo ambiente. Só cria um novo
    customer quando nenhum deles existe.
  </Step>
</Steps>

<Note>
  Para controlar sem ambiguidade qual histórico o checkout deve usar, crie a
  sessão passando `customer`. A busca por documento ou e-mail existe como
  resolução do checkout hospedado; ela não transforma o e-mail em chave única da
  API. Veja [Checkout Sessions](/payments/create-checkout-page).
</Note>

## Criar um cliente

Só o `email` é obrigatório. Envie `document` quando precisar identificar o cliente por CPF ou CNPJ; esse campo é único por organização.

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

<Info>
  Repetir o e-mail não causa conflito. O `POST /v1/customers` retorna `409
      customer_document_exists` somente quando o CPF/CNPJ informado já pertence a
  outro customer ativo da organização.
</Info>

### 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={"theme":"css-variables"}
curl https://api.chargefy.io/v1/customers/cus_kmCDW4tZJsBZcEko \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+5511988887777" }'
```

| Campo                           | Observação                                                               |
| ------------------------------- | ------------------------------------------------------------------------ |
| `email`                         | Não pode ficar vazio. Pode repetir em outros customers da organização.   |
| `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={"theme":"css-variables"}
{
  "metadata": {}
}
```

<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={"theme":"css-variables"}
  curl "https://api.chargefy.io/v1/customers?limit=20" \
    -H "Authorization: Bearer {{API_KEY}}"
  ```

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

  ```bash Próxima página (cursor) theme={"theme":"css-variables"}
  curl "https://api.chargefy.io/v1/customers?limit=20&starting_after=cus_kmCDW4tZJsBZcEko" \
    -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={"theme":"css-variables"}
curl -X DELETE https://api.chargefy.io/v1/customers/cus_kmCDW4tZJsBZcEko \
  -H "Authorization: Bearer {{API_KEY}}"
```

<AccordionGroup>
  <Accordion title="O que o parceiro vê">
    A resposta é `{ "id": "cus_kmCDW4tZJsBZcEko", "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>

<Note>
  Depois da remoção, aquele `id` deixa de estar disponível nos caminhos
  públicos. Você pode criar outro customer com o mesmo e-mail, assim como já
  pode fazer enquanto existem outros customers ativos com esse endereço.
</Note>

## Webhooks

Mudanças no cliente disparam eventos no payload 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>