API Reference

Referência completa da API REST da Chargefy

A API da Chargefy permite que você integre pagamentos, assinaturas, checkout e gestão de clientes diretamente na sua aplicação.

​

URLs Base

Ambiente	URL
Produção	https://api.chargefy.io
Sandbox	https://sandbox-api.chargefy.io

Todas as requisições devem usar HTTPS. Requisições HTTP serão rejeitadas.

​

Autenticação

A API suporta dois métodos de autenticação:

Método	Prefixo	Caso de Uso
Supabase JWT	eyJhbGciOiJIUzI1NiIs...	Integrações server-side, automações, backend
Customer Session Token (CST)	chargefy_cst_	Portal do cliente, operações self-service

Inclua o token no header Authorization:

cURL

curl -X GET https://api.chargefy.io/api/v1/products/ \
  -H "Authorization: Bearer <supabase_jwt>"

Obtenha o JWT via supabase.auth.getSession(). Consulte o guia de Autenticação para detalhes. Consulte o guia de Autenticação para detalhes sobre todos os métodos.

​

Core API vs Customer Portal API

A API da Chargefy é dividida em duas camadas:

API	Base Path	Autenticação	Descrição
Core API	/api/v1/	JWT	API principal para gerenciar recursos da organização
Customer Portal API	/api/v1/customer-portal/	CST	API self-service para operações do cliente

​

Core API — Endpoints Principais

Recurso	Endpoints	Descrição
Checkouts	GET/POST/PATCH /checkouts/	Criar e gerenciar sessões de checkout
Checkout Links	GET/POST/PATCH/DELETE /checkout-links/	Links de checkout compartilháveis
Products	GET/POST/PATCH/DELETE /products/	Produtos e preços
Customers	GET/POST/PATCH/DELETE /customers/	Gestão de clientes
Subscriptions	GET/PATCH /subscriptions/	Assinaturas e recorrência
Sales	GET /sales/	Vendas e transações Zoop
Discounts	GET/POST/PATCH/DELETE /discounts/	Cupons e descontos
Files	GET/POST/DELETE /files/	Upload e gestão de arquivos
Webhooks	GET/POST/PATCH/DELETE /webhooks/	Configuração de webhooks
Metrics	GET /metrics/	Métricas e analytics
Events	GET /events/	Log de eventos
Organizations	GET/PATCH /organizations/	Configuração da organização

​

Customer Portal API

Recurso	Endpoints	Descrição
Customer Session	POST /customer-portal/sessions/	Criar sessão do cliente
Subscriptions	GET/PATCH /customer-portal/subscriptions/	Gerenciar assinaturas

​

Paginação

Endpoints de listagem retornam resultados paginados. Use os parâmetros page e limit para navegar:

GET /api/v1/products/?page=1&limit=20

​

Resposta Paginada

{
  "items": [
    { "id": "prod_123", "name": "Plano Pro", "..." : "..." }
  ],
  "pagination": {
    "total_count": 45,
    "max_page": 3
  }
}

Parâmetro	Tipo	Default	Descrição
page	integer	1	Número da página
limit	integer	10	Itens por página (máx: 100)

​

Ordenação e Filtros

A maioria dos endpoints de listagem suporta ordenação e filtros:

# Ordenar por data de criação (mais recente primeiro)
GET /api/v1/products/?sorting=-created_at

# Filtrar por tipo
GET /api/v1/products/?type=recurring

# Combinar filtros e ordenação
GET /api/v1/subscriptions/?product_id=prod_123&sorting=-created_at&limit=50

​

Rate Limits

Para garantir estabilidade, a API aplica limites de taxa de requisição:

Plano	Limite	Período
Sandbox	100 req	por minuto
Produção	1.000 req	por minuto

Quando o limite é atingido, a API retorna 429 Too Many Requests com o header Retry-After.

​

Formato de Erros

Erros seguem um formato consistente:

{
  "error": "Descrição do erro",
  "detail": "Informações adicionais quando disponíveis"
}

​

Códigos de Status

Código	Descrição
200	Sucesso
201	Recurso criado
204	Sucesso sem conteúdo (ex: DELETE)
400	Requisição inválida (parâmetros faltando ou incorretos)
401	Não autenticado (token ausente ou inválido)
403	Sem permissão (escopo insuficiente)
404	Recurso não encontrado
422	Erro de validação
429	Rate limit excedido
500	Erro interno do servidor

​

Idempotência

Para operações POST, você pode incluir o header Idempotency-Key para garantir que a operação seja executada apenas uma vez:

curl -X POST https://api.chargefy.io/api/v1/checkouts/ \
  -H "Authorization: Bearer <supabase_jwt>..." \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "prod_123"}'

​

Próximos Passos

Autenticação

Configurar tokens de acesso

Sandbox

Testar no ambiente de desenvolvimento

SDK TypeScript

Instalar o SDK oficial

Webhooks

Configurar notificações em tempo real