~/orcamento
Quer um site ou sistema feito por mim?
Os projetos para clientes passam pela Web4Business, onde a equipe faz o orçamento.
~/redes
Onde me encontrar
- GitHubRepositórios, experimentos e projetos abertos.@cmacetko (abre em nova aba)
- LinkedInA trajetória profissional: mais de duas décadas construindo a web./in/cmacetko (abre em nova aba)
- InstagramO lado colorido: maquiagens, dia a dia e bastidores.@paloma_macetko (abre em nova aba)
- FacebookOnde compartilho a jornada com amigos e comunidade./cmacetko (abre em nova aba)
paloma_macetko:~/projetos/apimagica $ cat README.md
API Mágica
API REST gratuita com o trabalho repetido de todo projeto brasileiro: CEP, QR Code Pix, geradores de CPF e CNPJ, cotação do real. Documentada em Swagger.
- Node.js
- Express 5
- MySQL
- Redis
- OpenAPI
01 · Visão geral
A API que resolve o chato do dev brasileiro
Uma API só para o trabalho repetido de todo projeto brasileiro: consulta de CEP, QR Code Pix, gerador de CPF para testes, cotação do real. Cansei de reescrever as mesmas rotinas a cada site novo e transformei tudo numa API REST gratuita, documentada em Swagger e aberta para quem quiser usar — chave na hora, sem cartão e sem plano pago.
Todo projeto brasileiro recomeça do zero as mesmas integrações chatas. A API Mágica entrega essas peças prontas numa chamada só, de graça e com documentação que dá para testar no navegador.
O que faz
- Endereços: base com 1,3 milhão de CEPs e busca por cidade ou logradouro
- Geradores: QR Code Pix no padrão BR Code, CPF, CNPJ, UUID e senhas
- Rede e finanças: geolocalização por IP, e-mail descartável e cotação do real
- Documentos prontos: política de privacidade e termos de uso em linha com a LGPD
- Documentação interativa em Swagger, com OpenAPI e chave via header X-API-Key
02 · Galeria
Telas do produto no ar
Capturadas de apimagica.com.br. Clique numa tela para ver em tamanho real.
/Página inicial, com um exemplo de requisição de CEP e a resposta em JSON./modulos/enderecosMódulo de endereços: consulta de CEP, busca por logradouro e lista de países./modulos/geradoresGeradores: Pix no padrão BR Code, QR Code, CPF, CNPJ, pessoas, senhas e UUID./modulos/web-pushWeb Push como serviço: projetos, inscrições, envios com fila e diagnóstico./changelogChangelog público com cada módulo novo, melhoria e correção.
03 · Stack
Do que é feito, camada por camada
Tirado do código-fonte e do que roda em produção.
Back-end
Node.js + Express 5- API em ESM organizada por domínio: cada módulo tem rotas, serviço e repositório.
Zod- Valida cada rota e é a fonte da verdade do contrato documentado.
web-push · qrcode · faker- Envio de notificações, geração de QR Code e dados fictícios brasileiros.
Dados e cache
MySQL + mysql2- 24 tabelas em 18 migrations, incluindo a base de CEPs e o histórico de uso.
Redis (ioredis)- Rate limit com script Lua e cache, com Map em memória como reserva.
Front-end
React 18 + Vite 6- Site e painel com CSS Modules; o painel carrega sob demanda.
Pré-renderização- Um HTML por rota com renderToString, mais sitemap, robots e llms.txt.
Recharts- Gráficos de uso da chave no painel.
Integrações
OpenAI- Reescreve o horóscopo do dia, com cache diário no banco.
ExchangeRate · FlagsAPI- Cotação do real e bandeiras dos países.
Resend · Turnstile- E-mails de confirmação e proteção dos formulários.
Documentação
OpenAPI + Swagger UI- Contrato completo e testável no navegador, com chave via X-API-Key.
SKILL.md- O mesmo contrato em formato de skill para agentes de IA.
Qualidade
Vitest + supertest- Cerca de 700 testes entre back-end e front-end.
04 · Destaques
Decisões técnicas que valem a leitura
Rate limit atômico com Lua no Redis
Uma janela deslizante em sorted set avalia dois níveis de limite de uma vez. Se qualquer um estourar, nenhum consome cota — sem condição de corrida entre requisições simultâneas.
Um contrato, dois formatos
O Zod das rotas é a fonte da verdade; dele saem o openapi.json do Swagger e o SKILL.md para agentes, com as URLs trocadas em tempo de execução.
Web Push como serviço
Projetos com chaves VAPID, inscrições com tags, fila de envios com worker que respeita Retry-After, rastreio de cliques e um kit pronto para colar no site.
Cache em dois níveis
Redis quando está disponível e um Map em memória quando não — a API continua de pé mesmo sem o Redis. O horóscopo tem cache diário no banco, aquecido por cron.
1,3 milhão de CEPs importados em streaming
A base de endereços veio de um dump SQL antigo, lido por um parser em streaming para não carregar o arquivo inteiro na memória.
Conta segura sem vazar quem tem cadastro
Tokens guardados só como SHA-256, sessões invalidadas por data (o JWT não tem lista de revogação) e um login que responde igual para e-mail cadastrado ou não.