Gestão de Clientes

Um customer é o comprador — a pessoa física ou jurídica que compra de você. Ele reúne num só lugar a identidade e os dados de cobrança (nome, e-mail, telefone, CPF/CNPJ, nome de cobrança e endereço) e é o fio que liga todo o histórico de uma pessoa: pagamentos, assinaturas, invoices e métodos de pagamento salvos.

O e-mail é a chave única dentro da organização.O mesmo comprador continua sendo o mesmo customer por mais checkouts que ele faça — o e-mail (em minúsculas) identifica unicamente o cliente dentro da sua organização. Tentar criar um segundo cliente com um e-mail já em uso retorna 409.

Modelo conceitual

O customer é o ponto de ancoragem. Métodos de pagamento salvos, assinaturas, invoices e pagamentos apontam para ele — por isso o cliente nunca some de verdade quando há histórico (veja Remover um cliente).

Anatomia do cliente

Este é o contrato público completo, retornado em create, get, update, itens de list e em data.object dos webhooks customer.*.

Campo	Tipo	Descrição
`id`	`string`	Identificador único. Usa o prefixo `cus_*`.
`object`	`string`	Sempre `"customer"`.
`email`	`string`	E-mail do cliente. Chave única dentro da organização. Obrigatório.
`name`	`string \| null`	Nome do cliente.
`phone`	`string \| null`	Telefone do cliente.
`document`	`string \| null`	CPF ou CNPJ, apenas dígitos.
`document_type`	`string \| null`	`cpf` ou `cnpj`. Inferido pelo comprimento de `document` quando omitido.
`billing_name`	`string \| null`	Nome ou razão social usada em cobrança, quando diferente de `name`.
`billing_address`	`object \| null`	Endereço de cobrança estruturado.
`livemode`	`boolean`	`true` em produção; `false` em ambiente de teste.
`metadata`	`object`	Pares `string → string` livres, controlados por você. `{}` quando vazio.
`created_at`	`string`	Data de criação em ISO 8601.
`updated_at`	`string \| null`	Data da última atualização em ISO 8601; `null` enquanto nunca foi atualizado.

O schema público campo a campo está em Objeto customer.

O cliente não carrega organization_id no payload — o escopo já vem da autenticação. E não existe external_id: a correlação com o seu sistema é via metadata (veja Correlação com o seu sistema).

Endereço de cobrança

billing_address é um objeto estruturado. Quando não-nulo, todas as chaves são retornadas — as faltantes vêm como null.

Campo	Descrição
`line1`	Rua, número e complemento principal.
`line2`	Complemento opcional.
`city`	Cidade.
`state`	Estado ou província.
`postal_code`	CEP ou código postal.
`country`	País em código ISO de 2 letras (`BR`).

Como um cliente nasce

Há dois caminhos, e ambos chegam no mesmo objeto.

Você cria pela API

POST /v1/customers com pelo menos email. Útil quando o cadastro do comprador já existe no seu sistema antes da primeira cobrança.

O checkout resolve sozinho no confirm

Quando um comprador finaliza um checkout, a Chargefy resolve o cliente no momento do confirm: se a sessão foi criada vinculada a um cliente (campo customer), ela permanece travada nesse cliente; caso contrário, um novo cliente é criado com os dados preenchidos. A resolução acontece uma única vez por checkout.

O e-mail não é uma chave de identidade. Vários clientes podem ter o mesmo e-mail na mesma organização — a identidade é o id do cliente, não o e-mail. A Chargefy não reaproveita um cliente existente buscando pelo e-mail: a menos que a sessão seja criada com um customer, cada checkout cria um cliente novo. Para reusar um cliente que já existe no seu sistema, faça o lookup na sua base e crie a sessão passando o customer — veja Criando checkout sessions.

Criar um cliente

Só o email é obrigatório. Quando você envia document, a Chargefy já pré-prepara o cadastro financeiro interno para acelerar a primeira cobrança — esse passo é transparente e não aparece na resposta.

curl https://api.chargefy.io/v1/customers \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "nome@email.com"
  }'

Se já existir um cliente ativo com o mesmo email na organização, o create retorna 409 (A customer with this email already exists). Para alterar esse cliente, use o update em vez de tentar recriá-lo.

Documento (CPF/CNPJ)

document aceita apenas dígitos — máscara e pontuação são normalizadas. O document_type é opcional:

Você envia	Resultado
`document` sem `document_type`	A Chargefy infere `cpf` ou `cnpj` pelo comprimento.
`document` + `document_type` explícito	Usa o valor enviado; precisa ser `cpf` ou `cnpj`.
`document_type` diferente de `cpf`/`cnpj`	Retorna `400`.

O documento é a chave soberana da identidade de pagamento. Cartões e demais instrumentos salvos são organizados por essa identidade — documentos diferentes resultam em identidades de pagamento diferentes, com instrumentos salvos separados. Isso protege contra atrelar um cartão à pessoa errada. Por isso o documento entra no fluxo de cobrança, e não apenas no cadastro do cliente.

Atualizar um cliente

O update é merge: você envia só os campos que mudam, e os ausentes ficam como estão. É um POST no próprio recurso (não há PUT/PATCH na API).

curl https://api.chargefy.io/v1/customers/cus_123 \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+5511988887777" }'

Campo	Observação
`email`	Não pode ficar vazio. Continua único na organização — colidir com outro cliente retorna `409`.
`name`, `phone`, `billing_name`	Envie `null` (ou string vazia) para limpar.
`document` / `document_type`	Enviar qualquer um dos dois reavalia o par; `document` nulo limpa ambos.
`billing_address`	Substitui o objeto inteiro; `null` limpa.
`metadata`	Substitui o objeto inteiro.

A resposta direta do update não traz diff — só o objeto completo atualizado. Quem precisa saber o que mudou (e os valores anteriores) lê o webhook customer.updated, que carrega data.previous_attributes.

Correlação com o seu sistema

Não existe campo external_id no cliente. Para amarrar um customer ao ID do seu próprio sistema, use metadata — um objeto livre string → string que a Chargefy guarda e devolve em toda resposta e em todos os webhooks daquele cliente.

{
  "metadata": {
    "crm_account": "id_456",
    "internal_user_id": "id_789"
  }
}

metadata é sempre opcional e nunca interpretado pela Chargefy — é só armazenado e ecoado de volta. Use qualquer chave que faça sentido para você (reference_id, internal_user_id, crm_account).

Métodos de pagamento

Os métodos de pagamento salvos pertencem ao cliente, mas não vêm embutidos no objeto customer. Eles são lidos por um endpoint próprio.

O cliente não expõe um campo de método de pagamento padrão. Para listar ou inspecionar os cartões e demais instrumentos de um cliente, use o recurso Métodos de pagamento.

Listar e filtrar

GET /v1/customers lista os clientes ativos da organização, do mais recente para o mais antigo, com paginação por cursor (starting_after, ending_before, limit). Há um filtro por email.

curl "https://api.chargefy.io/v1/customers?limit=20" \
  -H "Authorization: Bearer {{API_KEY}}"

Clientes removidos não aparecem na listagem. Veja Listar customers para o contrato completo.

Remover um cliente

DELETE /v1/customers/{id} expressa “tirar de uso”. Internamente é um soft-delete: o registro permanece no banco para preservar o histórico financeiro (pagamentos, assinaturas, invoices), mas some de todos os caminhos de leitura — get, list e qualquer fluxo público.

curl -X DELETE https://api.chargefy.io/v1/customers/cus_123 \
  -H "Authorization: Bearer {{API_KEY}}"

O que o parceiro vê

A resposta é { "id": "cus_123", "object": "customer", "deleted": true }. Para quem consome a API, o cliente deixou de existir: consultá-lo depois retorna 404 e ele não aparece mais na listagem.

O que acontece por baixo

O histórico associado (vendas, assinaturas, invoices) continua íntegro para auditoria e conciliação. O cliente apenas fica invisível na API; nenhum registro financeiro é apagado.

O e-mail de um cliente removido fica liberado: você pode criar um novo cliente com o mesmo e-mail depois da remoção — será um customer novo, com novo id.

Webhooks

Mudanças no cliente disparam eventos no envelope padrão. O payload sempre carrega o customer completo em data.object; eventos de update também trazem data.previous_attributes com os valores anteriores dos campos alterados.

Evento	Quando dispara
`customer.created`	Cliente criado (via API ou resolvido no checkout).
`customer.updated`	Algum campo do cliente mudou. Inclui `previous_attributes`.
`customer.deleted`	Cliente removido (soft-delete).

Autenticação e escopos

Tipo de chave	Comportamento
API key da própria organização	Atua direto na organização dona da chave; o header `Organization` é proibido.
API key de plataforma	Exige o header `Organization: <organization_id>` apontando para uma organização conectada ativa.

As operações exigem escopo read para GET e write para POST/DELETE.

Próximos passos

Objeto customer

Schema público completo e campos retornados.

Criar cliente (API)

Contrato do POST /v1/customers.

Métodos de pagamento

Cartões e instrumentos salvos do cliente.

Assinaturas

Como o cliente vira uma cobrança recorrente.

​Modelo conceitual

​Anatomia do cliente

​Endereço de cobrança

​Como um cliente nasce

​Criar um cliente

​Documento (CPF/CNPJ)

​Atualizar um cliente

​Correlação com o seu sistema

​Métodos de pagamento

​Listar e filtrar

​Remover um cliente

​Webhooks

​Autenticação e escopos

​Próximos passos

Objeto customer

Criar cliente (API)

Métodos de pagamento

Assinaturas

Modelo conceitual

Anatomia do cliente

Endereço de cobrança

Como um cliente nasce

Criar um cliente

Documento (CPF/CNPJ)

Atualizar um cliente

Correlação com o seu sistema

Métodos de pagamento

Listar e filtrar

Remover um cliente

Webhooks

Autenticação e escopos

Próximos passos