SESP/sgse-app
2
0
Fork 0
Code Issues 3 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
1ad0ee91cb9e6f5ac08ab08b9a9a6cc82196311f
sgse-app/apps/web/GOOGLE_MAPS_SETUP.md
deyvisonwanderley d6aaa15cf4 feat: enhance point registration and location validation features 
- Refactored the RegistroPonto component to improve the layout and user experience, including a new section for displaying standard hours.
- Updated RelogioSincronizado to include GMT offset adjustments for accurate time display.
- Introduced new location validation logic in the backend to ensure point registrations are within allowed geofenced areas.
- Enhanced the device information schema to capture additional GPS data, improving the reliability of location checks.
- Added new endpoints for managing allowed marking addresses, facilitating better control over where points can be registered.
2025-11-21 05:12:27 -03:00

5.4 KiB
Raw Blame History

📍 Configuração do Google Maps API para Busca de Coordenadas

Este guia explica como configurar a API do Google Maps para obter coordenadas GPS de forma automática e precisa no sistema de Endereços de Marcação.

🎯 Por que usar Google Maps?

  • ✅ Maior Precisão: Resultados mais exatos para endereços brasileiros
  • ✅ Melhor Cobertura: Banco de dados mais completo e atualizado
  • ✅ Geocoding Avançado: Entende melhor endereços incompletos ou parciais

Nota: O sistema funciona perfeitamente sem a API key do Google Maps, usando OpenStreetMap (gratuito). A configuração do Google Maps é opcional.

📋 Passo a Passo

1. Criar Projeto no Google Cloud Platform

  1. Acesse Google Cloud Console
  2. Clique em "Criar Projeto" ou selecione um projeto existente
  3. Preencha o nome do projeto (ex: "SGSE-App")
  4. Clique em "Criar"

2. Ativar a Geocoding API

  1. No menu lateral, vá em "APIs e Serviços" > "Biblioteca"
  2. Procure por "Geocoding API"
  3. Clique no resultado e depois em "Ativar"
  4. Aguarde alguns segundos para a ativação

3. Criar Chave de API

  1. Ainda em "APIs e Serviços", vá em "Credenciais"
  2. Clique em "Criar Credenciais" > "Chave de API"
  3. Copie a chave gerada (você precisará dela depois)

4. Configurar Restrições de Segurança (Recomendado)

Para proteger sua chave de API:

  1. Clique na chave criada para editá-la
  2. Em "Restrições de API":
    • Selecione "Restringir chave"
    • Escolha "Geocoding API"
  3. Em "Restrições de aplicativo":
    • Para desenvolvimento local: escolha "Referenciadores de sites HTTP"
    • Adicione: http://localhost:* e http://127.0.0.1:*
    • Para produção: adicione o domínio do seu site
  4. Clique em "Salvar"

5. Configurar no Projeto

  1. No diretório apps/web/, copie o arquivo de exemplo:

    cp .env.example .env

  2. Abra o arquivo .env e adicione sua chave:

    VITE_GOOGLE_MAPS_API_KEY=sua_chave_aqui

  3. Reinicie o servidor de desenvolvimento:

    npm run dev

6. Verificar se está funcionando

  1. Acesse a página de Endereços de Marcação (/ti/configuracoes-ponto/enderecos)
  2. Clique em "Novo Endereço"
  3. Preencha um endereço e clique em "Buscar GPS"
  4. Se configurado corretamente, verá a mensagem: "Coordenadas encontradas via Google Maps!"

💰 Custos

Google Maps Geocoding API

  • $5.00 por 1.000 requisições (primeiros 40.000 são gratuitos por mês)
  • $0.005 por requisição após os 40.000 gratuitos

💡 Para a maioria dos casos de uso, os 40.000 gratuitos são suficientes!

OpenStreetMap (Fallback)

  • 100% Gratuito e ilimitado
  • Sem necessidade de configuração
  • Precisão levemente menor, mas ainda muito boa

🔄 Como funciona o sistema

O sistema foi projetado para usar uma estratégia de fallback inteligente:

  1. Primeiro: Tenta buscar via Google Maps (se API key configurada)
  2. Se falhar ou não tiver API key: Usa automaticamente OpenStreetMap
  3. Feedback: Informa qual serviço foi usado na mensagem de sucesso

Isso garante que o sistema sempre funcione, mesmo sem a API key do Google Maps.

🔒 Segurança

⚠️ Importante

  • Nunca commite o arquivo .env no Git (já está no .gitignore)
  • Nunca compartilhe sua chave de API publicamente
  • Configure restrições de API no Google Cloud Console
  • Para produção, use variáveis de ambiente seguras no seu provedor de hospedagem

Configuração em Produção

Para ambientes de produção (Vercel, Netlify, etc.):

  1. Acesse as configurações do projeto no seu provedor
  2. Vá em "Environment Variables" ou "Variáveis de Ambiente"
  3. Adicione: VITE_GOOGLE_MAPS_API_KEY com o valor da sua chave
  4. Faça o deploy novamente

❓ Solução de Problemas

A busca não está usando Google Maps

  • Verifique se a variável VITE_GOOGLE_MAPS_API_KEY está no arquivo .env
  • Reinicie o servidor de desenvolvimento
  • Verifique no console do navegador se há erros

Erro: "This API project is not authorized to use this API"

  • Verifique se a Geocoding API está ativada no projeto
  • Aguarde alguns minutos após a ativação (pode levar até 5 minutos)

Erro: "API key not valid"

  • Verifique se copiou a chave corretamente
  • Verifique se as restrições de API permitem o uso da Geocoding API
  • Verifique se as restrições de aplicativo permitem seu domínio/endereço

Mensagem: "Coordenadas encontradas via OpenStreetMap"

  • Isso é normal se:
    • Não há API key configurada
    • A API key não é válida
    • O Google Maps falhou na busca
  • O sistema continua funcionando normalmente com OpenStreetMap

📚 Recursos Úteis

✅ Resumo

  1. ✅ Crie projeto no Google Cloud
  2. ✅ Ative Geocoding API
  3. ✅ Crie chave de API
  4. ✅ Configure restrições (recomendado)
  5. ✅ Adicione VITE_GOOGLE_MAPS_API_KEY no .env
  6. ✅ Reinicie o servidor

Pronto! O sistema agora usará Google Maps para busca de coordenadas com maior precisão.