> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usealpa.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Changelog da API
> Mantenha-se atualizado com as mudanças e histórico de versões da API Alpa
Acompanhe as atualizações e o histórico de versões da API.
Este changelog é atualizado continuamente com melhorias, correções e mudanças relevantes.
Sugestões de features ou melhorias podem ser enviadas pelo Dashboard na seção de Feedback.
## Atualizações Recentes
## Sistema de Assinaturas Recorrentes e Cart Abandonment (v2.23.0)
**Novos recursos:**
* **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)
**Novos recursos:**
* **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`
**Novos modelos no banco de dados:**
* `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
Os SDKs oficiais (Node.js, Python, PHP e Java) receberam correções importantes.
**O que mudou:**
* 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
**Novos recursos:**
* **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
**Melhorias:**
* 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
**Segurança:**
* 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)
**Correções:**
* `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
**Novos recursos:**
* **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
**Melhorias:**
* Refinamento completo do Dashboard e painel Admin para dispositivos móveis
* Otimização no carregamento de modais e estados de skeleton
**Correções:**
* 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
Os SDKs oficiais da Alpa estão disponíveis para as principais linguagens de backend.
**SDKs disponíveis:**
* **Node.js / TypeScript** — `@alpa/alpa-js`
* **Python** — `alpa-python`
* **PHP** — `alpa/alpa-php`
* **Java** — `com.alpa:alpa-java`
Todos os SDKs incluem:
* 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
Consulte a aba **SDKs** para instalação e exemplos de uso.
## Sistema completo de Webhooks
**Novos recursos:**
* 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`
**Melhorias:**
* Campo `metadata` adicionado em transações para dados customizados
* Mensagens de erro mais descritivas em toda a API
## Sistema de Cupons de Desconto
**Novos recursos:**
* 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
**Novos recursos:**
* 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
**Melhorias:**
* Paginação aprimorada com metadados completos (`total`, `totalPages`)
* Filtros avançados e ordenação customizável em listagens
## 🎉 Lançamento da API Alpa v1
A API Alpa está no ar. A partir de hoje você pode integrar pagamentos via PIX, Cartão de Crédito/Débito e Boleto ao seu sistema.
**Disponível no lançamento:**
* 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