Criar um 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"
  }'

{
  "id": "cus_s3gW2LnUPcZTA3YJ",
  "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": {},
  "name": "Cliente Exemplo",
  "phone": "+5511999990000",
  "updated_at": null
}

{
  "error": {
    "code": "customer_document_exists",
    "message": "A customer with this document already exists",
    "param": "document",
    "type": "invalid_request_error"
  }
}

Cria um 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. Só email é obrigatório. Todo o resto tem default (null ou {}) ou é resolvido pela Chargefy. 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

object

Endereço de cobrança estruturado. Padrão: null.

Show billing_address

string

Código ISO de 2 letras (ex.: BR).

string

Razão social ou nome de cobrança. Padrão: null.

string

CPF ou CNPJ. Máscaras são aceitas e normalizadas para somente dígitos. Único por organização: enviar um documento que já pertence a outro cliente ativo retorna 409 customer_document_exists. Padrão: null.

string

Tipo do documento. Quando omitido, inferimos pela quantidade de dígitos de document: 11 dígitos → cpf, 14 dígitos → cnpj. Só válido como cpf ou cnpj — qualquer outro valor retorna 400.

Valor	Descrição
`cpf`	Pessoa física.
`cnpj`	Pessoa jurídica.

string

required

Email do cliente. Normalizado para minúsculas antes de salvar. Não precisa ser único — o mesmo email pode pertencer a vários clientes.

object

Objeto livre string → string para correlacionar com o seu sistema. Padrão: {}. Use chaves como reference_id, internal_user_id, etc.

string

Nome do cliente. Padrão: null.

string

Telefone do cliente. Padrão: null.

O que a Chargefy resolve sozinha

email é normalizado para minúsculas.
document é normalizado para somente dígitos (máscaras como 123.456.789-01 são aceitas).
document_type é inferido pela quantidade de dígitos de document quando omitido (11 → cpf, 14 → cnpj).
Todos os campos não enviados nascem null; metadata nasce {}.

Cenários de criação

(a) Mínimo

Só email. Use quando ainda não há dados fiscais — o documento pode ser adicionado depois com POST /v1/customers/{id}.

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

(b) Com documento (CPF/CNPJ)

O documento é a chave de identidade do cliente na organização: criar outro cliente ativo com o mesmo documento retorna 409 customer_document_exists. Envie com ou sem máscara — a normalização é nossa — e omita document_type para que ele seja inferido pela quantidade de dígitos.

curl -X POST "https://api.chargefy.io/v1/customers" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "123.456.789-01",
    "email": "nome@email.com",
    "name": "Comprador",
    "phone": "+5511999999999"
  }'

(c) Com endereço de cobrança e correlação

billing_name e billing_address alimentam a cobrança; metadata é livre e volta em todas as respostas e webhooks do cliente — use para amarrar o cliente ao identificador do seu sistema.

curl -X POST "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": "Rua Exemplo, 100",
      "postal_code": "01310-000",
      "state": "SP"
    },
    "billing_name": "Comprador",
    "email": "nome@email.com",
    "metadata": {}
  }'

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).

Campo	Tipo	Observação
`id`	`string`	ID do cliente (`cus_*`)
`object`	`string`	Sempre `"customer"`
`email`	`string`	Pode repetir entre clientes
`name`	`string \| null`	—
`phone`	`string \| null`	—
`document`	`string \| null`	CPF/CNPJ apenas dígitos
`document_type`	`string \| null`	`cpf` ou `cnpj`
`billing_name`	`string \| null`	—
`billing_address`	`object \| null`	`{ line1, line2, city, state, postal_code, country }`
`livemode`	`boolean`	`true` em produção; `false` em ambiente de teste
`metadata`	`object`	Eco do `metadata` enviado
`created_at`	`string`	ISO 8601
`updated_at`	`string \| null`	ISO 8601

{
  "id": "cus_s3gW2LnUPcZTA3YJ",
  "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": {},
  "name": "Cliente Exemplo",
  "phone": "+5511999990000",
  "updated_at": null
}

{
  "error": {
    "code": "customer_document_exists",
    "message": "A customer with this document already exists",
    "param": "document",
    "type": "invalid_request_error"
  }
}

Erros comuns

Status	`code`	Quando ocorre
`400`	`parameter_missing`	`email` ausente
`400`	`invalid_request_error`	`document_type` diferente de `cpf`/`cnpj`; `billing_address` ou `metadata` não-objeto
`409`	`customer_document_exists`	Outro 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).

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_s3gW2LnUPcZTA3YJ",
  "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": {},
  "name": "Cliente Exemplo",
  "phone": "+5511999990000",
  "updated_at": null
}

{
  "error": {
    "code": "customer_document_exists",
    "message": "A customer with this document already exists",
    "param": "document",
    "type": "invalid_request_error"
  }
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Autenticação

Attributes

O que a Chargefy resolve sozinha

Cenários de criação

(a) Mínimo

(b) Com documento (CPF/CNPJ)

(c) Com endereço de cobrança e correlação

Resposta

Erros comuns

Webhook

​Autenticação

​Attributes

​O que a Chargefy resolve sozinha

​Cenários de criação

​(a) Mínimo

​(b) Com documento (CPF/CNPJ)

​(c) Com endereço de cobrança e correlação

​Resposta

​Erros comuns

​Webhook

Autenticação

Attributes

O que a Chargefy resolve sozinha

Cenários de criação

(a) Mínimo

(b) Com documento (CPF/CNPJ)

(c) Com endereço de cobrança e correlação

Resposta

Erros comuns

Webhook