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

​
URLs Base

AmbienteURL
Produçãohttps://api.chargefy.io
Sandboxhttps://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étodoPrefixoCaso de Uso
Supabase JWTeyJhbGciOiJIUzI1NiIs...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 -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:
APIBase PathAutenticaçãoDescrição
Core API/api/v1/JWTAPI principal para gerenciar recursos da organização
Customer Portal API/api/v1/customer-portal/CSTAPI self-service para operações do cliente

​
Core API — Endpoints Principais

RecursoEndpointsDescrição
CheckoutsGET/POST/PATCH /checkouts/Criar e gerenciar sessões de checkout
Checkout LinksGET/POST/PATCH/DELETE /checkout-links/Links de checkout compartilháveis
ProductsGET/POST/PATCH/DELETE /products/Produtos e preços
CustomersGET/POST/PATCH/DELETE /customers/Gestão de clientes
SubscriptionsGET/PATCH /subscriptions/Assinaturas e recorrência
SalesGET /sales/Vendas e transações Zoop
DiscountsGET/POST/PATCH/DELETE /discounts/Cupons e descontos
FilesGET/POST/DELETE /files/Upload e gestão de arquivos
WebhooksGET/POST/PATCH/DELETE /webhooks/Configuração de webhooks
MetricsGET /metrics/Métricas e analytics
EventsGET /events/Log de eventos
OrganizationsGET/PATCH /organizations/Configuração da organização

​
Customer Portal API

RecursoEndpointsDescrição
Customer SessionPOST /customer-portal/sessions/Criar sessão do cliente
SubscriptionsGET/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âmetroTipoDefaultDescrição
pageinteger1Número da página
limitinteger10Itens 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:
PlanoLimitePeríodo
Sandbox100 reqpor minuto
Produção1.000 reqpor 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ódigoDescrição
200Sucesso
201Recurso criado
204Sucesso sem conteúdo (ex: DELETE)
400Requisição inválida (parâmetros faltando ou incorretos)
401Não autenticado (token ausente ou inválido)
403Sem permissão (escopo insuficiente)
404Recurso não encontrado
422Erro de validação
429Rate limit excedido
500Erro 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