API de controle de assinaturas

Um sistema de assinaturas parece um CRUD, mas o ponto difícil está fora dele: quem confirma o pagamento é um provedor externo, que avisa por webhook quando quiser. Até lá, a assinatura precisa estar num estado coerente, e quando o aviso chega, ele precisa ser aplicado uma única vez, mesmo que chegue repetido.

Construí uma API que cuida de planos, assinaturas e todo o ciclo de vida delas: criação, ativação, suspensão por falha de pagamento, renovação, upgrade, downgrade e cancelamento, além de uma trilha de eventos e um relatório de métricas.

Decidi que as atualizações de cobrança não acontecem na requisição. Cada ação grava um evento e o publica num exchange do RabbitMQ; dois workers consomem as filas e são eles que mudam a assinatura. A API responde rápido, e o processamento pode falhar e tentar de novo sem o cliente perceber.

1. →Requisição validada
2. →Evento gravado e publicado
3. →Fila
4. →Worker atualiza a assinatura
5. →Evento marcado como processado
6. ↳falha depois de 3 tentativas: mensagem vai para a dead letter queue

No webhook de pagamento, a API valida o payload, a assinatura e o valor pago, grava o evento e responde 202 Accepted. Nada é alterado ali. O worker é quem ativa, suspende ou renova a assinatura, e a data da próxima cobrança só avança quando o pagamento quita o ciclo vencido. Assim, confirmações repetidas não acumulam meses. O processamento é idempotente: um evento já processado que volta do broker não muda nada.

A API não usa sessão nem cookie. Defini uma credencial por tipo de rota:

Algumas escolhas tinham custo, e eu preferi assumi-las de forma explícita a esconder.

Para operar a API sem Postman, criei um painel em HTML, CSS e JavaScript puros, servido pela própria aplicação. Ele assina as chamadas ao webhook no navegador e mostra a assinatura antes e depois do processamento, deixando visível que quem a alterou foi o worker.

Desenvolvi com TDD, feature por feature. Os testes rodam sobre H2 em memória, com relógio fixo e sem broker, então não dependem de nada externo. O verify falha se a cobertura de linhas ou de branches ficar abaixo de 100%, e o GitHub Actions roda esse gate a cada push, seguido do build da imagem Docker.

testes automatizados

319

de linhas e branches cobertos

100%

mais código de teste que de produção

1,8×

Cobertura total não substitui o teste de verdade: ao rodar contra PostgreSQL e RabbitMQ reais, encontrei e corrigi dois defeitos que a suíte em memória não pegava.

Com docker compose --profile app up --build, sobem o PostgreSQL, o RabbitMQ e a aplicação, com o schema criado pelo Flyway. A API está documentada no Swagger e no README, com arquitetura, fluxos de evento, contrato JSON e endpoints.

Um outbox transacional, para eliminar as mensagens publicadas antes do commit, e um limite de requisições global com armazenamento compartilhado, como Redis, para quando a aplicação rodar com várias réplicas.