Skip to main content

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.

​
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: "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"
  }
});
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:
CampoDescrição
idIdentificador único
emailEmail do cliente
nameNome completo
billing_nameNome para cobrança (se diferente)
billing_addressEndereço de cobrança
tax_idCPF ou CNPJ
external_idID externo (seu sistema)
user_metadataDados customizados (JSON)
email_verifiedSe o email foi verificado
can_authenticateSe pode acessar o portal do cliente
created_atData 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: "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: 
await chargefy.customers.update(customerId, {
  user_metadata: {
    plano_interno: "enterprise",
    origem: "indicacao",
    nota_interna: "Cliente VIP"
  }
});
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

EscopoPermissão
customers:readListar e visualizar clientes
customers:writeCriar, atualizar e deletar clientes

​
Webhooks

Eventos disparados para mudanças em clientes:
EventoDescrição
customer.createdNovo cliente criado
customer.updatedDados do cliente atualizados
customer.deletedCliente removido (soft delete)
customer.state_changedEstado do cliente alterado