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:

const customer = await chargefy.customers.create({
  email: "[e-mail]",
  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: "[e-mail]",
  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:

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:

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.

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:

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