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 id identifica o customer.O e-mail é um dado de contato e pode aparecer em mais de um customer da mesma organização. Ao criar um customer diretamente pela API, você decide quando reutilizar um id que já conhece e quando criar outro cadastro.

Como os recursos se relacionam

Recurso	Relação com o `customer`
Comprador	É representado pelo cadastro do cliente.
Métodos de pagamento	Ficam salvos no cliente.
Assinaturas	Apontam para o cliente assinante.
Invoices	Apontam para o cliente cobrado.
Pagamentos	Compõem o histórico financeiro do cliente.

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. Obrigatório, mas não único dentro da organização.
`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. Cada chamada de criação aceita um novo customer, mesmo quando outro cadastro já usa o mesmo e-mail. Se houver document, ele não pode pertencer a outro customer ativo da organização.

O checkout resolve sozinho no confirm

Quando o comprador confirma um checkout, a Chargefy mantém o customer fixado na sessão. Sem customer fixado, procura primeiro um cadastro ativo com o mesmo CPF/CNPJ e, depois, o cadastro ativo mais antigo com o mesmo e-mail, sempre dentro da mesma organização e do mesmo ambiente. Só cria um novo customer quando nenhum deles existe.

Para controlar sem ambiguidade qual histórico o checkout deve usar, crie a sessão passando customer. A busca por documento ou e-mail existe como resolução do checkout hospedado; ela não transforma o e-mail em chave única da API. Veja Checkout Sessions.

Criar um cliente

Só o email é obrigatório. Envie document quando precisar identificar o cliente por CPF ou CNPJ; esse campo é único por organização.

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

curl https://api.chargefy.io/v1/customers \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "billing_address": {
      "city": "São Paulo",
      "country": "BR",
      "line1": "Av. Paulista, 1000",
      "postal_code": "01310-100",
      "state": "SP"
    },
    "document": "12345678901",
    "email": "nome@email.com",
    "name": "Cliente Exemplo",
    "phone": "+5511999990000"
  }'

curl https://api.chargefy.io/v1/customers \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "billing_name": "Empresa Exemplo LTDA",
    "document": "12345678000190",
    "document_type": "cnpj",
    "email": "nome@email.com"
  }'

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

Repetir o e-mail não causa conflito. O POST /v1/customers retorna 409 customer_document_exists somente quando o CPF/CNPJ informado já pertence a outro customer ativo da organização.

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_kmCDW4tZJsBZcEko \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+5511988887777" }'

Campo	Observação
`email`	Não pode ficar vazio. Pode repetir em outros customers da organização.
`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": {}
}

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}}"

curl "https://api.chargefy.io/v1/customers?email=nome@email.com" \
  -H "Authorization: Bearer {{API_KEY}}"

curl "https://api.chargefy.io/v1/customers?limit=20&starting_after=cus_kmCDW4tZJsBZcEko" \
  -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_kmCDW4tZJsBZcEko \
  -H "Authorization: Bearer {{API_KEY}}"

O que o parceiro vê

A resposta é { "id": "cus_kmCDW4tZJsBZcEko", "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.

Depois da remoção, aquele id deixa de estar disponível nos caminhos públicos. Você pode criar outro customer com o mesmo e-mail, assim como já pode fazer enquanto existem outros customers ativos com esse endereço.

Webhooks

Mudanças no cliente disparam eventos no payload 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.

Pagamentos online

Integrações avançadas

Payment Intents e cobranças

Formas de pagamento

Customers

Faturas

Assinaturas

Operação financeira

Gestão de clientes

Como os recursos se relacionam

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

​Como os recursos se relacionam

​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

Como os recursos se relacionam

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