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

​
Métodos de Autenticação

MétodoHeaderCaso de Uso
Api KeyX-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:
AmbientePrefixoComportamento
livech_live_…Executa transações Zoop reais, aparece em relatórios financeiros
testch_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:
EscopoPermissão
readListar e consultar recursos (sales, subscriptions, customers, payouts, etc)
writeCriar, atualizar e cancelar recursos (transactions, refunds, subscriptions)
adminReservado 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: '[email protected]' }),
});

// 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