Documentation Index Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
Use this file to discover all available pages before exploring further.
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.ioSandbox 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 -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 Payment Links GET/POST/PATCH/DELETE /payment-links/Links de pagamento 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 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 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:
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.
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 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
Webhooks Configurar notificações em tempo real
