{"id":32930011,"url":"https://github.com/mcemy/busca-cep-e-corretores","last_synced_at":"2026-05-02T08:34:49.167Z","repository":{"id":323413574,"uuid":"1093144616","full_name":"mcemy/busca-cep-e-corretores","owner":"mcemy","description":"Node-RED + BrazilAPI: Busca de CEP com mapas interativos e catálogo de corretoras. Geocoding automático garante mapas para todos os CEPs válidos usando Leaflet.js e Nominatim. Inclui MQTT e SQLite.","archived":false,"fork":false,"pushed_at":"2025-11-10T01:15:40.000Z","size":84,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-10T03:09:49.878Z","etag":null,"topics":["api-integration","brasil","brazilapi","cep","geocoding","interactive-maps","leaflet","maps","mqtt","node-red","nominatim","openstreetmap","sqlite"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mcemy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-10T01:00:46.000Z","updated_at":"2025-11-10T01:23:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mcemy/busca-cep-e-corretores","commit_stats":null,"previous_names":["mcemy/busca-cep-e-corretores"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mcemy/busca-cep-e-corretores","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcemy%2Fbusca-cep-e-corretores","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcemy%2Fbusca-cep-e-corretores/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcemy%2Fbusca-cep-e-corretores/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcemy%2Fbusca-cep-e-corretores/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mcemy","download_url":"https://codeload.github.com/mcemy/busca-cep-e-corretores/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcemy%2Fbusca-cep-e-corretores/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32528386,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T01:12:54.858Z","status":"online","status_checked_at":"2026-05-02T02:00:05.923Z","response_time":132,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-integration","brasil","brazilapi","cep","geocoding","interactive-maps","leaflet","maps","mqtt","node-red","nominatim","openstreetmap","sqlite"],"created_at":"2025-11-11T13:00:58.836Z","updated_at":"2026-05-02T08:34:49.161Z","avatar_url":"https://github.com/mcemy.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# BrazilAPI Node-RED Integration\n\n[![Node-RED](https://img.shields.io/badge/Node--RED-v4.1.1-red)](https://nodered.org/)\n[![BrazilAPI](https://img.shields.io/badge/BrazilAPI-v2-green)](https://brasilapi.com.br/)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n🚀 Aplicação Node-RED que integra com a BrazilAPI para fornecer catálogo de corretoras e busca de CEP com mapas interativos.\n\n## 🎥 Demonstração em Vídeo\n\nAssista ao vídeo de demonstração (40 segundos) mostrando todas as funcionalidades:\n\n[![📹 Assistir Demo](https://img.shields.io/badge/▶️-Assistir%20Demonstração-blue?style=for-the-badge)](https://screenapp.io/app/v/7AwZtwR7CV)\n\n## ✨ Funcionalidades Principais\n\n### 📊 1. Catálogo de Corretoras\n\n- 📋 Lista todas as corretoras disponíveis da BrazilAPI\n- 🏢 Formato: \"Nome - Cidade / CNPJ\"\n- 🎨 Interface limpa e estilizada\n- 🔍 Busca em tempo real por nome, cidade ou CNPJ\n\n### 📍 2. Buscador de CEP\n\n- **🔗 Opção 1**: Via parâmetro de rota (`/cep/:zipcode`)\n- **📝 Opção 2**: Formulário com campo de busca\n- 🗺️ Exibe endereço completo com mapa interativo\n- ⚠️ Tratamento de erros para CEPs inválidos\n- 📌 Coordenadas geográficas automáticas\n\n### 🎁 Funcionalidades Bonus\n\n- 🗺️ **Mapas Interativos**: Leaflet.js com markers e popups personalizados\n- 🌍 **Geocoding Automático**: Nominatim API para CEPs sem coordenadas\n- 🎨 **UI Moderna**: Gradientes, animações e design responsivo\n- 📡 **MQTT Integration**: Broker Aedes para mensagens em tempo real\n- 💾 **SQLite Database**: Histórico completo de buscas\n- ⏳ **Loading States**: Feedback visual durante carregamento\n- 🛡️ **Error Handling**: Tratamento robusto de erros e fallbacks\n\n## 🚀 Melhorias Implementadas\n\n### 🗺️ Mapas Interativos com Geocoding Automático\n\n**❌ Problema Identificado:**  \nA BrazilAPI nem sempre retorna coordenadas geográficas para todos os CEPs, resultando em páginas sem mapa.\n\n**✅ Solução Implementada:**\n\n1. 🔍 **Detecção Inteligente**: Verifica se a API retornou coordenadas\n2. 🌍 **Geocoding Automático**: Se não houver coordenadas, busca via Nominatim (OpenStreetMap)\n3. ⏳ **Loading Visual**: Exibe spinner enquanto busca as coordenadas\n4. 🛡️ **Fallback Robusto**: Mensagem clara se não for possível obter o mapa\n\n**🔧 Tecnologias Adicionadas:**\n\n- 📚 **Leaflet.js v1.9.4**: Biblioteca open-source de mapas interativos\n- 🌐 **Nominatim API**: Serviço de geocoding gratuito do OpenStreetMap\n- ⚡ **JavaScript Async/Await**: Para requisições assíncronas\n\n**🎯 Resultado:**\n\n- ✅ **100% dos CEPs válidos** agora exibem mapas interativos\n- ✅ Zoom, arrastar e markers clicáveis\n- ✅ Experiência consistente para todos os usuários\n\n## 📋 Requisitos\n\n- 🟢 Node.js (v14 ou superior)\n- 📦 npm ou yarn\n\n## 🔧 Instalação\n\n**1️⃣ Clone o repositório:**\n\n```bash\ngit clone https://github.com/mcemy/busca-cep-e-corretores.git\ncd busca-cep-e-corretores\n```\n\n**2️⃣ Instale o Node-RED globalmente (se ainda não tiver):**\n\n```bash\nnpm install -g node-red\n```\n\n**3️⃣ Instale as dependências Node-RED:**\n\n```bash\nnpm install node-red-dashboard\nnpm install node-red-contrib-aedes\nnpm install node-red-node-sqlite\n```\n\nOu instale via Node-RED Palette Manager:\n\n- 📊 `node-red-dashboard`\n- 📡 `node-red-contrib-aedes` (para MQTT)\n- 💾 `node-red-node-sqlite` (para database)\n\n**4️⃣ Importe os fluxos:**\n\n- ▶️ Inicie o Node-RED: `node-red`\n- 🌐 Abra o navegador: `http://localhost:1880`\n- ☰ Vá em Menu → Import\n- 📋 Copie o conteúdo de `flows.json` e cole\n- ✅ Clique em \"Import\"\n\n## 🎮 Como Usar\n\n### ▶️ Iniciando a Aplicação\n\n**1️⃣ Inicie o Node-RED:**\n\n```bash\nnode-red\n```\n\n**2️⃣ Aguarde a mensagem:** \"Server now running at http://127.0.0.1:1880/\"\n\n### 🌐 Acessando as Funcionalidades\n\n#### 📊 Catálogo de Corretoras\n\n- **🔗 URL**: `http://localhost:1880/brokers`\n- 📋 Lista todas as corretoras disponíveis da BrazilAPI\n- 🔄 Dados carregados automaticamente ao abrir a página\n- 🔍 Busca em tempo real por nome, cidade ou CNPJ\n\n#### 📍 Busca de CEP - Opção 1 (Parâmetro de Rota)\n\n- **🔗 URL**: `http://localhost:1880/cep/\u003czipcode\u003e`\n- **📝 Exemplo**: `http://localhost:1880/cep/01310100`\n- ✏️ Substitua `\u003czipcode\u003e` por qualquer CEP brasileiro válido\n\n#### 📍 Busca de CEP - Opção 2 (Formulário)\n\n- **🔗 URL**: `http://localhost:1880/search-cep`\n- ✏️ Digite o CEP no campo de busca\n- 🔍 Clique no botão \"Buscar\"\n- ✅ Resultados exibidos abaixo com mapa interativo\n\n#### 📊 Dashboard (Bonus)\n\n- **🔗 URL**: `http://localhost:1880/ui`\n- 🎨 Dashboard interativo com todas as funcionalidades\n- 📡 Atualizações em tempo real via MQTT\n- 📜 Visualizador de histórico de buscas\n\n### 📡 Integração MQTT\n\nA aplicação inclui um broker MQTT para atualizações em tempo real:\n\n- **🔌 Broker**: `localhost:1883`\n- **📢 Tópicos**:\n  - `brazilapi/cep/search` - Publica buscas de CEP\n  - `brazilapi/brokers/list` - Publica atualizações da lista de corretoras\n\n**🧪 Para testar o MQTT:**\n\n```bash\n# 📥 Subscrever às buscas de CEP\nmosquitto_sub -h localhost -t \"brazilapi/cep/search\"\n\n# 📤 Publicar uma busca de CEP\nmosquitto_pub -h localhost -t \"brazilapi/cep/search\" -m \"01310100\"\n```\n\n### 💾 Database\n\nO histórico de buscas é armazenado em banco SQLite:\n\n- 📂 **Localização**: `~/.node-red/cep_history.db`\n- 📊 **Tabela**: `searches` (zipcode, result, timestamp)\n\n## 🧪 Testando a Aplicação\n\n### 📊 Testar Catálogo de Corretoras\n\n1. 🌐 Abra o navegador: `http://localhost:1880/brokers`\n2. ✅ Verifique se as corretoras estão listadas no formato: \"Nome - Cidade / CNPJ\"\n3. 🎨 Confirme que o estilo foi aplicado corretamente\n4. 🔍 Teste a busca digitando nome, cidade ou CNPJ\n\n### 📍 Testar Busca de CEP - Opção 1\n\n**✅ CEPs válidos para testar:**\n\n```url\nhttp://localhost:1880/cep/01310100  (✅ Av. Paulista, São Paulo)\nhttp://localhost:1880/cep/20040020  (✅ Rio de Janeiro)\nhttp://localhost:1880/cep/30130100  (✅ Belo Horizonte)\n```\n\n**❌ CEP inválido (deve mostrar erro):**\n\n```url\nhttp://localhost:1880/cep/00000000\n```\n\n### 📍 Testar Busca de CEP - Opção 2\n\n1. 🌐 Abra: `http://localhost:1880/search-cep`\n2. ✏️ Digite o CEP: `01310100`\n3. 🔍 Clique em \"Buscar\"\n4. ✅ Verifique se os resultados e o mapa aparecem corretamente\n\n### 📊 Testar Dashboard\n\n1. 🌐 Abra: `http://localhost:1880/ui`\n2. 🔄 Navegue pelas abas\n3. ✅ Teste todas as funcionalidades do dashboard\n\n## 🔌 Endpoints da API\n\n### 📊 GET /brokers\n\nRetorna página HTML com lista de corretoras\n\n### 📍 GET /cep/:zipcode\n\nRetorna página HTML com detalhes do CEP\n\n- **📋 Parâmetro**: zipcode (8 dígitos)\n\n### 📝 GET /search-cep\n\nRetorna página HTML com formulário de busca\n\n### 🔄 POST /api/cep\n\nRetorna JSON com dados do CEP\n\n- **📋 Body**: `{ \"cep\": \"01310100\" }`\n\n## 📁 Estrutura do Projeto\n\n```plaintext\nbusca-cep-e-corretores/\n├── 📄 README.md           # Este arquivo\n├── 📄 flows.json          # Fluxos do Node-RED\n├── 📄 package.json        # Dependências Node.js\n├── 📄 package-lock.json   # Versões fixas das dependências\n└── 📄 .gitignore          # Arquivos ignorados pelo Git\n```\n\n## 🛠️ Stack Técnico\n\n- 🔴 **Node-RED**: Plataforma de programação baseada em fluxos\n- 🇧🇷 **BrazilAPI**: API pública de dados brasileiros\n- 📡 **MQTT**: Broker Aedes para mensagens em tempo real\n- 💾 **SQLite**: Banco de dados local para histórico\n- 🗺️ **Leaflet.js**: Mapas interativos\n- 🌍 **Nominatim**: Geocoding via OpenStreetMap\n- 🎨 **HTML/CSS/JavaScript**: Estilização frontend\n\n## 🔧 Troubleshooting\n\n### ⚠️ Porta já em uso\n\nSe a porta 1880 já estiver em uso, você pode mudá-la:\n\n```bash\nnode-red -p 1881\n```\n\n### ❌ Não consegue conectar ao MQTT\n\nCertifique-se de que o nó broker Aedes está deployed e rodando no fluxo.\n\n### ❌ Erros no Database\n\nO arquivo do banco é criado automaticamente. Se houver problemas:\n\n```bash\nrm ~/.node-red/cep_history.db\n# Reinicie o Node-RED para recriar\n```\n\n### ⚠️ Rate Limiting da API\n\nA BrazilAPI pode limitar requisições. Se encontrar problemas, aguarde alguns momentos entre as requisições.\n\n## 👨‍💻 Desenvolvimento\n\nPara modificar os fluxos:\n\n1. 🌐 Abra o editor Node-RED: `http://localhost:1880`\n2. ✏️ Edite os nós e conexões\n3. 🚀 Clique em \"Deploy\" para aplicar as mudanças\n\n\n## 📝 Notas Importantes\n\n- ✅ Todos os CEPs devem ter 8 dígitos (com ou sem hífen)\n- ✅ A aplicação aceita ambos os formatos: 01310-100 ou 01310100\n- ✅ Mensagens de erro são exibidas para CEPs inválidos\n- ✅ A interface é totalmente responsiva e funciona em dispositivos móveis\n- ✅ 100% dos CEPs válidos exibem mapas interativos\n- ✅ Geocoding automático para CEPs sem coordenadas na API\n\n```\n\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcemy%2Fbusca-cep-e-corretores","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmcemy%2Fbusca-cep-e-corretores","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcemy%2Fbusca-cep-e-corretores/lists"}