GET /api/v1/customers/external/:external_id

Retorna um cliente pelo seu identificador externo

Busca um cliente utilizando o external_id definido no momento da criação ou atualização. Útil para integrar o Chargefy com o seu próprio sistema sem precisar armazenar o ID interno do Chargefy.

​

Autenticação

Requer Organization Access Token (OAT) via header Authorization: Bearer. Escopos necessários: web:read, web:write, customers:read ou customers:write.

​

Parâmetros de Caminho

external_id · string · required

Identificador externo único do cliente dentro da organização. Deve corresponder exatamente ao valor definido via external_id na criação ou atualização do cliente.

​

Resposta

Retorna o objeto completo do cliente correspondente ao external_id informado. Retorna 404 Not Found caso nenhum cliente ativo seja encontrado com esse identificador.

id · string

ID único interno do cliente no Chargefy.

email · string

Email do cliente.

name · string

Nome do cliente.

external_id · string

ID externo associado ao cliente.

organization_id · string

ID da organização à qual o cliente pertence.

taxpayer_id · string

CPF ou CNPJ do cliente (se informado).

billing_address · object

Endereço de cobrança do cliente (se informado).

user_metadata · object

Metadados personalizados associados ao cliente.

created_at · string

Data e hora de criação no formato ISO 8601.

updated_at · string

Data e hora da última atualização no formato ISO 8601.

​

Exemplo

cURL

curl -X GET "https://api.chargefy.io/api/v1/customers/external/user_001" \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN"

​

Resposta de Exemplo

{
  "id": "cus_def456",
  "email": "[e-mail]",
  "name": "João Santos",
  "external_id": "user_001",
  "organization_id": "org_xyz",
  "taxpayer_id": "12345678901",
  "phone": "11999990000",
  "billing_name": "João Santos",
  "billing_address": {
    "line1": "Av. Paulista, 1000",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01310-100",
    "country": "BR"
  },
  "user_metadata": {
    "source": "api",
    "plan": "pro"
  },
  "created_at": "2026-03-12T10:00:00Z",
  "updated_at": "2026-03-12T10:00:00Z"
}