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

# Gestão de Clientes

> Gerencie seus clientes, visualize histórico de compras e assinaturas.

## Visão Geral

A Chargefy cria e gerencia clientes automaticamente durante o checkout. Cada cliente é vinculado a uma **organização** e pode ter assinaturas, vendas e benefícios associados.

Quando um cliente é criado, a Chargefy registra automaticamente os dados necessários para processar pagamentos via PIX, Cartão de Crédito e Boleto de forma integrada.

## Criação de Clientes

Clientes podem ser criados de duas formas:

### Automaticamente no Checkout

Quando um comprador finaliza um checkout, a Chargefy automaticamente:

1. Busca um cliente existente pelo email + organização
2. Se não encontrar, cria um novo cliente
3. Registra os dados do comprador para processamento de pagamentos
4. Associa a venda e/ou assinatura ao cliente

### Via API

Você pode criar clientes diretamente pela API:

```typescript theme={null}
const customer = await chargefy.customers.create({
  email: "joao@exemplo.com.br",
  name: "João Silva",
  organization_id: "org_xxx",
  billing_address: {
    line1: "Rua das Flores, 123",
    city: "São Paulo",
    state: "SP",
    postal_code: "01234-567",
    country: "BR"
  },
  tax_id: {
    type: "cpf",
    number: "123.456.789-00",
    country: "BR"
  }
});
```

> [!NOTE]
>
> Ao criar um cliente com `tax_id` (CPF/CNPJ), a Chargefy automaticamente registra os dados necessários para processar pagamentos futuros.

## Dados do Cliente

Cada cliente possui os seguintes dados:

| Campo | Descrição |
| - | - |
| `id` | Identificador único |
| `email` | Email do cliente |
| `name` | Nome completo |
| `billing_name` | Nome para cobrança (se diferente) |
| `billing_address` | Endereço de cobrança |
| `tax_id` | CPF ou CNPJ |
| `external_id` | ID externo (seu sistema) |
| `user_metadata` | Dados customizados (JSON) |
| `email_verified` | Se o email foi verificado |
| `can_authenticate` | Se pode acessar o portal do cliente |
| `created_at` | Data de criação |

## Identificação por External ID

Você pode atribuir um `external_id` a cada cliente para referenciar o ID do seu próprio sistema. O `external_id` é único por organização.

```typescript theme={null}
// Criar com external_id
const customer = await chargefy.customers.create({
  email: "maria@exemplo.com.br",
  name: "Maria Santos",
  external_id: "user_12345",
  organization_id: "org_xxx"
});

// Buscar por external_id
const customer = await chargefy.customers.getByExternalId("user_12345");

// Atualizar por external_id
await chargefy.customers.updateByExternalId("user_12345", {
  name: "Maria Santos Silva"
});
```

## Metadata Customizada

O campo `user_metadata` permite armazenar dados adicionais do cliente em formato JSON:

```typescript theme={null}
await chargefy.customers.update(customerId, {
  user_metadata: {
    plano_interno: "enterprise",
    origem: "indicacao",
    nota_interna: "Cliente VIP"
  }
});
```

## Checkout Links para Clientes

Você pode gerar links de checkout pré-preenchidos para clientes específicos:

```typescript theme={null}
const checkoutLink = await chargefy.customers.createCheckoutLink(customerId);
// Link expira em 48 horas
// Dados do cliente são preenchidos automaticamente
```

## Autenticação do Cliente (Portal)

Clientes com `can_authenticate: true` podem acessar o **Portal do Cliente** via magic link:

**1. Solicitar Código**

O cliente informa seu email e recebe um código OTP de 6 dígitos.

**2. Autenticar**

O cliente informa o código e recebe um token de sessão (`chargefy_cst_xxx`).

**3. Acessar Portal**

Com o token, o cliente pode visualizar suas assinaturas, vendas e benefícios.

> [!NOTE]
>
> O código OTP expira em **15 minutos**. A sessão do cliente é válida por **15 dias**.

## Listagem e Filtros

A API permite listar clientes com diversos filtros:

```typescript theme={null}
const customers = await chargefy.customers.list({
  organization_id: "org_xxx",
  query: "joao",          // Busca por nome ou email
  page: 1,
  limit: 20,
  sorting: ["-created_at"] // Mais recentes primeiro
});
```

## Exclusão de Clientes

A exclusão de clientes é **soft delete** — o registro não é removido do banco, apenas marcado com `deleted_at`. Isso preserva o histórico de vendas e assinaturas.

```typescript theme={null}
// Deletar por ID
await chargefy.customers.delete(customerId);

// Deletar por external_id
await chargefy.customers.deleteByExternalId("user_12345");
```

## Processamento de Pagamentos

Quando um cliente é criado com dados fiscais (CPF/CNPJ), a Chargefy:

1. Busca um registro existente pelo `taxpayer_id`
2. Se não encontrar, busca pelo email
3. Se nenhum for encontrado, cria um novo registro na plataforma Chargefy
4. Vincula o registro ao cliente para futuras transações

Essa integração garante que pagamentos via PIX, Cartão e Boleto sejam processados corretamente.

## Escopos de API

| Escopo | Permissão |
| - | - |
| `customers:read` | Listar e visualizar clientes |
| `customers:write` | Criar, atualizar e deletar clientes |

## Webhooks

Eventos disparados para mudanças em clientes:

| Evento | Descrição |
| - | - |
| `customer.created` | Novo cliente criado |
| `customer.updated` | Dados do cliente atualizados |
| `customer.deleted` | Cliente removido (soft delete) |
| `customer.state_changed` | Estado do cliente alterado |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.