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

{
  "id": "cus_123",
  "object": "customer",
  "billing_address": {
    "city": "São Paulo",
    "country": "BR",
    "line1": "Av. Paulista, 1000",
    "line2": null,
    "postal_code": "01310-100",
    "state": "SP"
  },
  "billing_name": null,
  "created_at": "2026-05-16T14:09:27Z",
  "document": "12345678901",
  "document_type": "cpf",
  "email": "nome@email.com",
  "livemode": false,
  "metadata": {
    "reference_id": "ref_456"
  },
  "name": "Cliente Exemplo",
  "phone": "+5511999990000",
  "updated_at": null
}
Cria um recurso customer. O document (CPF/CNPJ) é a chave de identidade por organização: se já existir outro cliente ativo com o mesmo documento, a criação retorna 409 customer_document_exists. O email não é único — o mesmo email pode pertencer a vários clientes. Quando você envia document, a Chargefy reaproveita o cadastro financeiro interno se já existir — o reuso é transparente e não aparece na resposta. Para correlacionar o cliente com um ID do seu sistema, use metadata. Qualquer chave funciona (ex.: reference_id); o objeto inteiro é retornado em todos os webhooks.

​
Autenticação

A API key da própria organização atua diretamente. A API key de plataforma exige o header Organization: <organization_id> apontando para uma organização conectada ativa.

​
Attributes

​
billing_address
object
Endereço de cobrança estruturado.
​
billing_name
string
Razão social ou nome de cobrança.
​
document
string
CPF ou CNPJ, apenas dígitos. Único por organização: enviar um documento que já pertence a outro cliente ativo retorna 409 customer_document_exists.
​
document_type
string
cpf ou cnpj. Quando omitido, inferimos pelo comprimento de document.
​
email
string
required
Email do cliente. Não precisa ser único — o mesmo email pode pertencer a vários clientes.
​
metadata
object
Objeto livre string → string para correlacionar com o seu sistema. Padrão {}. Use chaves como reference_id, internal_user_id, etc.
​
name
string
Nome do cliente.
​
phone
string
Telefone do cliente.
curl -X POST "https://api.chargefy.io/v1/customers" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "nome@email.com"
  }'

​
Resposta

200 OK com o objeto customer completo. Todo campo declarado pelo DTO público é sempre retornado; vazio é null ou {}. Quando billing_address é não-nulo, todas as chaves do endereço são retornadas (chaves faltantes viram null).
CampoTipoObservação
idstringID do cliente (cus_*)
objectstringSempre "customer"
emailstringPode repetir entre clientes
namestring | null—
phonestring | null—
documentstring | nullCPF/CNPJ apenas dígitos
document_typestring | nullcpf ou cnpj
billing_namestring | null—
billing_addressobject | null{ line1, line2, city, state, postal_code, country }
livemodebooleantrue em produção; false em ambiente de teste
metadataobjectEco do metadata enviado
created_atstringISO 8601
updated_atstring | nullISO 8601
{
  "id": "cus_123",
  "object": "customer",
  "billing_address": {
    "city": "São Paulo",
    "country": "BR",
    "line1": "Av. Paulista, 1000",
    "line2": null,
    "postal_code": "01310-100",
    "state": "SP"
  },
  "billing_name": null,
  "created_at": "2026-05-16T14:09:27Z",
  "document": "12345678901",
  "document_type": "cpf",
  "email": "nome@email.com",
  "livemode": false,
  "metadata": {
    "reference_id": "ref_456"
  },
  "name": "Cliente Exemplo",
  "phone": "+5511999990000",
  "updated_at": null
}

​
Erros comuns

StatuscodeQuando ocorre
400parameter_missingemail ausente
400invalid_request_errordocument_type diferente de cpf/cnpj; billing_address ou metadata não-objeto
409customer_document_existsOutro cliente ativo com o mesmo document na organização

​
Webhook

A criação dispara customer.created com o customer completo em data.object (mesmo formato da resposta).