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:
- Busca um cliente existente pelo email + organização
- Se não encontrar, cria um novo cliente
- Registra os dados do comprador para processamento de pagamentos
- Associa a venda e/ou assinatura ao cliente
Via API
Você pode criar clientes diretamente pela API:
const customer = await chargefy.customers.create({
email: "[email protected]",
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"
}
});
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.
// Criar com external_id
const customer = await chargefy.customers.create({
email: "[email protected]",
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"
});
user_metadata permite armazenar dados adicionais do cliente em formato JSON:
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:
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:
Solicitar Código
O cliente informa seu email e recebe um código OTP de 6 dígitos.
Autenticar
O cliente informa o código e recebe um token de sessão (chargefy_cst_xxx).
Acessar Portal
Com o token, o cliente pode visualizar suas assinaturas, vendas e benefícios.
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:
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.
// 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:
- Busca um registro existente pelo
taxpayer_id
- Se não encontrar, busca pelo email
- Se nenhum for encontrado, cria um novo registro na plataforma Chargefy
- 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 |
