Changelog da API

​

Sistema de Assinaturas Recorrentes e Cart Abandonment (v2.23.0)

• Planos de Assinatura: Crie planos com nome, preço, intervalo (mensal, anual, etc.), período de trial e limite de assinantes
  • GET/POST /api/subscriptions/plans — listar e criar planos
  • PATCH/DELETE /api/subscriptions/plans/:id — editar e remover planos
  • GET /api/subscriptions/public/:planId — página pública do plano para landing pages
• Checkout público de assinatura: POST /api/subscriptions/checkout — clientes se inscrevem sem autenticação
• Gestão pelo assinante: cancelar, pausar, retomar assinatura e atualizar cartão de cobrança
• Métricas MRR/Churn: GET /api/subscriptions/metrics — MRR, churn rate e assinantes ativos
• Retry automático: POST /api/subscriptions/:id/retry — reprocessa cobranças falhas
• Cart Abandonment:
  • POST /api/payment-links/public/slug/:slug/cart-abandonment — captura clientes que não concluíram o checkout
  • POST /api/payment-links/public/slug/:slug/cart-abandonment/recover — marca abandono como recuperado

​

Sistema completo de Marketing de Afiliados (v2.22.0)

• Marketplace de afiliados: endpoint público (autenticado) GET /api/affiliate/marketplace lista todos os programas ativos com detalhes do produto, comissão e número de afiliados inscritos
• Solicitar afiliação: POST /api/affiliate/join/:programId gera um código de rastreamento único por afiliado no formato NOME-XXXXXX
• Links rastreáveis: URL de divulgação no formato https://checkout.usealpa.com/pay/{slug}?aff={codigo}
• Comissões automáticas: após confirmação do pagamento, a comissão é calculada e creditada automaticamente na carteira do afiliado
• Dois tipos de comissão: PERCENTAGE (percentual do valor pago) ou FIXED (valor fixo em centavos)
• Rastreamento de cliques e conversões por link
• Dashboard do afiliado: endpoints para listar links, comissões e estatísticas consolidadas (/api/affiliate/links, /api/affiliate/commissions, /api/affiliate/stats)
• Gestão pelo anunciante: criar, listar, atualizar e remover programas via /api/affiliate/programs; listar afiliados inscritos via /api/affiliate/programs/:id/links
• Campos de programa: description, rules, affiliatePage, salesPage, cookieDays, extendedCommission

• AffiliateProgram — um por produto, define tipo e valor da comissão
• AffiliateLink — link único por afiliado por programa, com contadores de cliques e conversões
• AffiliateCommission — comissão por transação com status PENDING, PAID ou CANCELLED

​

SDKs: correções no endpoint de validação de cupom

• Corrigido campo amount no body de POST /api/coupons/validate — os SDKs enviavam amountCents incorretamente
• Respostas HTTP 400 com { valid: false } agora são tratadas como resposta válida (cupom inválido), não como erro
• Java: pacote renomeado de com.alpa.sdk para com.alpa
• Java: pom.xml reescrito em UTF-8 (estava em UTF-16, causando falha no Maven)
• JS: script de teste corrigido no package.json

​

Validação de cupom pública, idempotência e split de pagamentos

• Validação de cupom pública: POST /api/coupons/validate não requer autenticação — ideal para validar cupons diretamente no checkout
• Idempotência em transações: requisições POST de transação aceitam header Idempotency-Key, garantindo que retentativas não gerem cobranças duplicadas
• Split de pagamentos: divisão automática entre gateway e lojistas via integração com Pagar.me

• Compressão gzip/brotli automática nas respostas
• Rate limit por userId em rotas autenticadas — evita penalizar clientes legítimos atrás de NAT/proxy compartilhado
• Circuit breaker para PSPs: em caso de instabilidade, erros retornam rapidamente sem travar a requisição

• Validação completa de CPF/CNPJ com verificação dos dígitos verificadores (módulo 11)
• Sanitização XSS no campo metadata de transações
• CORS com origens explicitamente configuradas (removida derivação automática de subdomínios)

• amountCents padronizado em toda a camada de pagamento
• Skew de webhook reduzido para 60s com validação HMAC timing-safe
• Rate limit de login aplicado em todos os ambientes

​

Advanced Sales Tracking e otimizações de interface

• Rastreamento de campanhas: integração nativa com Utmify para captura precisa de UTMs, fbclid, gclid e outros parâmetros
• IP Tracking: captura automática do IP do comprador em transações

• Refinamento completo do Dashboard e painel Admin para dispositivos móveis
• Otimização no carregamento de modais e estados de skeleton

• Corrigido problema de validação de IP obrigatório na API da Utmify para ordens manuais
• Ajustado casing de endpoints internos da API (/utmfy)

​

Lançamento dos SDKs oficiais

• Node.js / TypeScript — @alpa/alpa-js
• Python — alpa-python
• PHP — alpa/alpa-php
• Java — com.alpa:alpa-java

• Funções prontas para todos os endpoints (transações, links de pagamento, produtos, cupons)
• Utilitários de validação de assinatura HMAC para webhooks
• Tratamento de erros tipado

​

Sistema completo de Webhooks

• Criação e gerenciamento de assinaturas de webhook via API
• Suporte aos eventos: transaction.created, transaction.completed, transaction.failed, transaction.updated, payment_link.created, payment_link.updated, balance.updated
• Retry automático para webhooks que falharem na entrega
• Validação de assinatura HMAC-SHA256 via header X-Webhook-Signature

• Campo metadata adicionado em transações para dados customizados
• Mensagens de erro mais descritivas em toda a API

​

Sistema de Cupons de Desconto

• Criação de cupons com desconto fixo (em centavos) ou percentual
• Limites de uso por cupom e por usuário
• Restrição de cupons a produtos específicos
• Campo expiresAt em links de pagamento
• Suporte a URLs de redirecionamento customizadas

​

Gestão de Produtos

• Endpoints para criar, listar, atualizar e remover produtos
• Associação de produtos a links de pagamento
• Controle automático de estoque por produto
• Suporte a múltiplas imagens por produto

• Paginação aprimorada com metadados completos (total, totalPages)
• Filtros avançados e ordenação customizável em listagens

​

🎉 Lançamento da API Alpa v1

• Links de pagamento: criação e gestão de páginas de checkout personalizadas
• Transações: listagem e consulta com filtros por status e método de pagamento
• Autenticação via API Key (Bearer Token)
• Rate limiting e proteção contra abuso
• Documentação completa da API