> ## 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.

# Create a Customer

> Cria um cliente.

Cria um recurso `customer`. O `document` (CPF/CNPJ) é a chave de identidade por
organização: se já existir outro cliente ativo com o mesmo documento, a criação
retorna `409 customer_document_exists`. O `email` **não** é único — o mesmo email
pode pertencer a vários clientes. Quando você envia `document`, a Chargefy
reaproveita o cadastro financeiro interno se já existir — o reuso é transparente
e não aparece na resposta.

Para correlacionar o cliente com um ID do seu sistema, use `metadata`. Qualquer
chave funciona (ex.: `reference_id`); o objeto inteiro é retornado em todos
os webhooks.

## Autenticação

A API key da própria organização atua diretamente. A API key de plataforma exige o
header `Organization: <organization_id>` apontando para uma organização
conectada ativa.

## Attributes

<ParamField body="billing_address" type="object">
  Endereço de cobrança estruturado.

  <Expandable title="billing_address">
    <ParamField body="city" type="string" />

    <ParamField body="country" type="string">
      Código ISO de 2 letras (ex.: `BR`).
    </ParamField>

    <ParamField body="line1" type="string" />

    <ParamField body="line2" type="string" />

    <ParamField body="postal_code" type="string" />

    <ParamField body="state" type="string" />
  </Expandable>
</ParamField>

<ParamField body="billing_name" type="string">
  Razão social ou nome de cobrança.
</ParamField>

<ParamField body="document" type="string">
  CPF ou CNPJ, apenas dígitos. Único por organização: enviar um documento que já
  pertence a outro cliente ativo retorna `409 customer_document_exists`.
</ParamField>

<ParamField body="document_type" type="string">
  `cpf` ou `cnpj`. Quando omitido, inferimos pelo comprimento de `document`.
</ParamField>

<ParamField body="email" type="string" required>
  Email do cliente. Não precisa ser único — o mesmo email pode pertencer a
  vários clientes.
</ParamField>

<ParamField body="metadata" type="object">
  Objeto livre `string → string` para correlacionar com o seu sistema. Padrão
  `{}`. Use chaves como `reference_id`, `internal_user_id`, etc.
</ParamField>

<ParamField body="name" type="string">
  Nome do cliente.
</ParamField>

<ParamField body="phone" type="string">
  Telefone do cliente.
</ParamField>

<RequestExample>
  ```bash cURL theme={}
  curl -X POST "https://api.chargefy.io/v1/customers" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "nome@email.com"
    }'
  ```
</RequestExample>

## Resposta

`200 OK` com o objeto `customer` completo. Todo campo declarado pelo DTO
público é sempre retornado; vazio é `null` ou `{}`. Quando `billing_address`
é não-nulo, todas as chaves do endereço são retornadas (chaves faltantes
viram `null`).

| Campo             | Tipo             | Observação                                            |
| ----------------- | ---------------- | ----------------------------------------------------- |
| `id`              | `string`         | ID do cliente (`cus_*`)                               |
| `object`          | `string`         | Sempre `"customer"`                                   |
| `email`           | `string`         | Pode repetir entre clientes                           |
| `name`            | `string \| null` | —                                                     |
| `phone`           | `string \| null` | —                                                     |
| `document`        | `string \| null` | CPF/CNPJ apenas dígitos                               |
| `document_type`   | `string \| null` | `cpf` ou `cnpj`                                       |
| `billing_name`    | `string \| null` | —                                                     |
| `billing_address` | `object \| null` | `{ line1, line2, city, state, postal_code, country }` |
| `livemode`        | `boolean`        | `true` em produção; `false` em ambiente de teste      |
| `metadata`        | `object`         | Eco do `metadata` enviado                             |
| `created_at`      | `string`         | ISO 8601                                              |
| `updated_at`      | `string \| null` | ISO 8601                                              |

<ResponseExample>
  ```json 200 theme={}
  {
    "id": "cus_123",
    "object": "customer",
    "billing_address": {
      "city": "São Paulo",
      "country": "BR",
      "line1": "Av. Paulista, 1000",
      "line2": null,
      "postal_code": "01310-100",
      "state": "SP"
    },
    "billing_name": null,
    "created_at": "2026-05-16T14:09:27Z",
    "document": "12345678901",
    "document_type": "cpf",
    "email": "nome@email.com",
    "livemode": false,
    "metadata": {
      "reference_id": "ref_456"
    },
    "name": "Cliente Exemplo",
    "phone": "+5511999990000",
    "updated_at": null
  }
  ```

  ```json 409 theme={}
  {
    "error": {
      "code": "customer_document_exists",
      "message": "A customer with this document already exists",
      "param": "document",
      "type": "invalid_request_error"
    }
  }
  ```
</ResponseExample>

## Erros comuns

| Status | `code`                     | Quando ocorre                                                                         |
| ------ | -------------------------- | ------------------------------------------------------------------------------------- |
| `400`  | `parameter_missing`        | `email` ausente                                                                       |
| `400`  | `invalid_request_error`    | `document_type` diferente de `cpf`/`cnpj`; `billing_address` ou `metadata` não-objeto |
| `409`  | `customer_document_exists` | Outro cliente ativo com o mesmo `document` na organização                             |

## Webhook

A criação dispara `customer.created` com o `customer` completo em `data.object`
(mesmo formato da resposta).