Autenticação

Como autenticar suas requisições à API da Chargefy

A Chargefy oferece dois caminhos de autenticação, cada um pra um tipo de integração.

​

Métodos de Autenticação

Método	Header	Caso de Uso
Api Key	X-Chargefy-Api-Key: ch_live_…	Integrações server-side de parceiros. Token gerado no dashboard da Chargefy, longo-prazo, revogável a qualquer momento. Recomendado pra uso em produção.
Customer Session Token (CST)	Authorization: Bearer <token>	Portal do cliente. Sessão gerada pelo fluxo de login do customer. Não usar pra integração server-side.

​

Api Key

O método principal pra integrações server-side. Cada organização gera os próprios tokens no dashboard da Chargefy, em Settings → Chaves de API.

​

Formato do token

ch_live_AbCd1234EfGh5678IjKl9012MnOp3456Qr
└┬─┘ └─┬┘ └────────────────┬────────────────┘
 │     │                   │
 │     │                   └── 43 caracteres aleatórios (base64url)
 │     └── ambiente: live ou test
 └── prefixo Chargefy

O token aparece uma vez só, no momento da criação. A plataforma guarda apenas o hash — não há como recuperar o texto claro depois. Se perder, revogue e crie uma nova.

​

Como usar

Envie o token no header X-Chargefy-Api-Key:

curl https://api.chargefy.io/v1/sales/ \
  -H "X-Chargefy-Api-Key: ch_live_AbCd1234…"

Alternativa compatível com clients que só aceitam Bearer:

curl https://api.chargefy.io/v1/sales/ \
  -H "Authorization: Bearer ch_live_AbCd1234…"

const response = await fetch('https://api.chargefy.io/v1/sales/', {
  headers: {
    'X-Chargefy-Api-Key': process.env.CHARGEFY_API_KEY!,
  },
});

​

Ambientes

Quando você cria uma chave, escolhe o ambiente:

Ambiente	Prefixo	Comportamento
live	ch_live_…	Executa transações Zoop reais, aparece em relatórios financeiros
test	ch_test_…	Mesmas rotas, mas isolado pra testes/integração. Não produz cobrança real.

Mantenha keys test no seu ambiente de staging e live apenas em produção. Nunca commite em código-fonte.

​

Escopos

Cada chave carrega um ou mais escopos que limitam o que ela pode fazer:

Escopo	Permissão
read	Listar e consultar recursos (sales, subscriptions, customers, etc)
write	Criar, atualizar e cancelar recursos (transactions, refunds, subscriptions)
admin	Reservado pra operações críticas. Não exposto no dashboard atualmente

Hierarquia: write inclui read; admin inclui ambos. Um endpoint que exige scope: 'read' aceita também chaves com write.

Siga o princípio do menor privilégio: crie chaves com read apenas quando a integração só precisa consultar dados. Use write só onde realmente precisa criar/modificar.

​

Obtendo uma chave

1. Entre no dashboard da Chargefy como owner ou admin da organização
2. Abra Settings → Chaves de API
3. Clique em Nova chave
4. Dê um nome descritivo (“Produção”, “Integração X”), escolha ambiente e escopos
5. Clique em Criar chave
6. Copie o token imediatamente — ele aparece uma vez só

Mais detalhes em Gerenciar api keys.

​

Rotação e revogação

• Revogação instantânea: na lista de chaves, clique em Revogar. Requests com aquele token passam a retornar 401 em milissegundos
• Rotação: não há “rotate key” in-place; o workflow é:
  1. Criar chave nova
  2. Atualizar sua aplicação pra usar a nova
  3. Revogar a antiga
• last_used_at: a plataforma guarda o último uso. Chaves não utilizadas há muito tempo podem ser revogadas preventivamente

​

Respostas de autenticação

Credencial ausente ou inválida:

{ "error": "Unauthorized — missing X-Chargefy-Api-Key header" }

{ "error": "Unauthorized — invalid api key" }

{ "error": "Unauthorized — api key revoked" }

{ "error": "Unauthorized — api key expired" }

Escopo insuficiente:

{ "error": "Forbidden — api key lacks required scope \"write\"" }

​

Segurança

• Nunca exponha X-Chargefy-Api-Key em código client-side (browser, mobile). Faça todas as chamadas server-side
• Armazene em variáveis de ambiente (CHARGEFY_API_KEY / CHARGEFY_TEST_KEY), nunca em código-fonte versionado
• Use escopos mínimos necessários
• Revogue imediatamente qualquer chave comprometida (vazamento em log, commit, laptop roubado)
• Revogação é instantânea — não há janela de uso de token antigo

​

Customer Session Token (CST)

Tokens de sessão do cliente são usados pra autenticar operações no portal do cliente (/portal). Não servem pra integração server-side.

​

Como funciona

1. O cliente entra no portal via email/link mágico
2. A aplicação troca o login por um token de sessão curto
3. O token é usado nos endpoints do Customer Portal

// Autenticar cliente
const session = await fetch('https://api.chargefy.io/v1/customer-portal/sessions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: '[e-mail]' }),
});

// Usar token
const { token } = await session.json();

const sales = await fetch('https://api.chargefy.io/v1/customer-portal/sales/', {
  headers: { 'Authorization': `Bearer ${token}` },
});

​

Endpoints acessíveis via CST

O CST dá acesso exclusivo aos endpoints do Customer Portal API:

• Visualizar perfil do cliente
• Listar e gerenciar assinaturas
• Histórico de vendas
• Acessar chaves de licença
• Download de arquivos/benefícios

​

Próximos Passos

Gerenciar Api Keys

Criar, listar, revogar chaves no dashboard

SDK TypeScript

Configura autenticação automaticamente

Ambiente Sandbox

Teste integrações em ambiente isolado

Webhooks

Receba eventos assinados em tempo real