API de Mapas Octacore

Visão Geral

A API de Mapas Octacore é a camada única de mapas, geolocalização e inteligência operacional para sistemas terceiros. O cliente chama apenas a Octacore; não precisa integrar diretamente com Google, OpenStreetMap, OSRM, Nominatim, Redis, PostGIS ou provedores climáticos.

Início Rápido

Use este caminho para validar uma credencial e executar busca, rota e inteligência climática em poucos minutos. Todos os endpoints privados usam a mesma base URL e o header x-api-key.

export OCTACORE_API_KEY="SUA_CHAVE_OCTACORE"
export OCTACORE_BASE_URL="https://mapas.octacore.com.br/api"

# 1. Validar credencial
curl "$OCTACORE_BASE_URL/client/me" \
  -H "x-api-key: $OCTACORE_API_KEY"

# 2. Buscar um endereço ou local
curl "$OCTACORE_BASE_URL/search?q=Piracicamirim%20Piracicaba&city=Piracicaba&state=SP" \
  -H "x-api-key: $OCTACORE_API_KEY"

# 3. Calcular rota
curl "$OCTACORE_BASE_URL/route?origin=-22.72652,-47.64999&destination=-22.74217,-47.62528" \
  -H "x-api-key: $OCTACORE_API_KEY"

# 4. Obter decisão climática compacta por bairro
curl "$OCTACORE_BASE_URL/weather/location?query=Piracicamirim&city=Piracicaba&state=SP&profile=delivery_moto" \
  -H "x-api-key: $OCTACORE_API_KEY"

Não coloque a chave em JavaScript público, iframe, URL, analytics ou repositório. Para acompanhamento do usuário final, use o token temporário de /acompanhar/{public_token}.

Portal do Cliente

O portal de homologação permite validar uma chave Octacore, consultar plano, valor simbólico/configurável, uso, cota, erros, endpoints, cidades, webhooks e rodar o teste de integração.

https://mapas.octacore.com.br/portal

GET /api/client/portal-summary?days=7
GET /api/client/plan
GET /api/client/errors?days=7
GET /api/client/usage/cities?days=7
GET /api/client/integration-check

Use o portal em homologação controlada. Em produção, a chave deve ficar no backend do cliente ou em cofre de segredos.

Fluxo de Integração Recomendado

Plataforma Completa de Mapas

A Octacore oferece as categorias de capacidade esperadas de uma plataforma moderna de mapas: Maps, Places, Geocoding, Directions/Routes, Matrix, Navigation, Tracking, Geofencing e Location Intelligence.

A infraestrutura é prioritariamente autohospedada e controlada pela Octacore. O cliente integra somente https://mapas.octacore.com.br/api; componentes como OpenStreetMap, MapLibre, OSRM, Nominatim, PostGIS, Redis e providers externos permanecem atrás do contrato da API.

Equivalência de categoria significa atender os mesmos tipos de necessidade de integração. Não significa copiar interface, algoritmo, base de dados ou contrato de outro fornecedor.

curl https://mapas.octacore.com.br/api/public/platform-manifest

O manifesto é também um contrato verificável de prontidão. Cada categoria informa status, endpoint principal, demonstração pública, dependências abstratas e disponibilidade do contrato. A cobertura distingue as cinco regiões geográficas das seis bases publicadas, incluindo a base dedicada de São Paulo.

{
  "readiness": {
    "status": "operational",
    "operational_capabilities": 8,
    "total_capabilities": 8,
    "coverage": {
      "geographic_regions": 5,
      "published_map_bases": 6,
      "processed_routing_bases": 6
    }
  }
}

A troca de provider, cache ou base regional ocorre no backend Octacore e não deve exigir mudança emergencial no aplicativo do cliente.

Inteligência Octacore

A Octacore não substitui o sistema do cliente. Ela fornece sinais prontos para que o cliente construa checkout, despacho, roteirização, acompanhamento, auditoria, antifraude operacional, frota e experiência final com menos integrações externas.

GET /api/search?q=Paulista 1000 Sao Paulo
GET /api/route-alternatives?origin=-23.55052,-46.63331&destination=-23.58917,-46.63465
GET /api/weather/intelligence?lat=-23.55052&lng=-46.63331&profile=delivery_moto
POST /api/decision/delivery
POST /api/webhooks

Os sinais avançados são opcionais. Uma integração simples pode usar apenas rotas e geocode; uma operação madura pode combinar rota, clima, zonas, ETA, tracking e webhooks sem trocar de contrato de API.

Capacidades Avançadas

A Octacore fornece uma camada de inteligência para o cliente decidir melhor dentro do próprio sistema. Esses recursos são opcionais: o operador pode usar tudo no painel, o entregador pode ver apenas rota e ETA, e o usuário final pode receber somente acompanhamento público.

curl "https://mapas.octacore.com.br/api/public/advanced-capabilities"

Limites de segurança: não exponha x-api-key em frontend público, não exponha chaves Google, não publique dados privados de frota em endpoint público e não prometa tráfego ao vivo sem provider oficial configurado.

Modelo de Provedores e Fallback Google

A Octacore usa provedores próprios e cache como caminho principal, com Google como fallback de segurança para todos os serviços elegíveis, conforme configuração operacional por cliente e contrato.

O cliente não recebe chave Google. O cliente usa apenas a chave Octacore em x-api-key. A decisão entre cache, OpenStreetMap/OSRM e Google acontece no backend da Octacore.

Política efetiva por credencial

Cada credencial pode permitir fallback ou operar em modo local-only. A política é aplicada de verdade aos endpoints privados e também separa os caches: uma credencial local não reutiliza resposta Google produzida por outra credencial.

Consulte source para saber a origem efetiva. Valores comuns incluem nominatim, osrm, cache, google_geocoding_fallback, google_directions_fallback e osrm_route_fallback.

Se uma multi-rota precisar degradar e a otimização solicitada não puder ser preservada, a resposta informa optimization_requested, optimization_preserved=false e um item em warnings. O percurso continua utilizável na ordem informada.

Responsabilidades

Octacore

• API evolutiva, credenciais, escopos, rate limit, cotas e auditoria técnica.
• Geocoding, rotas, tracking, cache, mapa operacional e fallback Google gerenciado.
• Monitoramento operacional e suporte conforme contrato.

Cliente

• Cadastro oficial de usuários, motoristas, frota, lojas, pedidos e regras comerciais.
• Proteção da chave Octacore no backend ou cofre de segredos.
• Envio de dados operacionais mínimos quando quiser exibir pins ou tracking.

Experiências por Público

A Octacore entrega a infraestrutura de mapas e inteligência; o cliente decide quais recursos aparecem para cada público. O mapa operacional completo não precisa ser a mesma tela do entregador ou do usuário final.

curl "https://mapas.octacore.com.br/api/public/experience-profiles"
curl "https://mapas.octacore.com.br/api/public/surface-profiles"
curl "https://mapas.octacore.com.br/api/client/surface-policy" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Use /api/public/surface-profiles como referência pública de produto e /api/client/surface-policy para consultar a política efetiva da credencial. O backend do cliente deve aplicar essa política antes de entregar dados para operador, entregador, usuário final ou subcliente.

Recursos como /api/weather/intelligence e motor de decisão são sinais avançados para integradores. Eles agregam valor, mas não são obrigatórios para uma rota simples, mapa de entregador ou acompanhamento do usuário final.

Embeds e Presets Visuais

Para acelerar homologação, a Octacore fornece URLs públicas e snippets de iframe para demos visuais. Esses embeds são seguros para apresentação porque não recebem x-api-key. Dados privados do cliente devem passar pelo backend do cliente, por GeoJSON autenticado ou por token público de tracking.

curl "https://mapas.octacore.com.br/api/public/embed-examples"

<iframe
  src="https://mapas.octacore.com.br/acompanhar/{public_token}"
  width="100%"
  height="640"
  loading="lazy"
  title="Acompanhamento Octacore"></iframe>

Nunca coloque a chave Octacore em iframe, JavaScript público, query string ou analytics. A tela de acompanhamento por token mostra apenas a sessão permitida; o mapa operacional completo permanece para equipe autorizada.

Autenticação, Escopos e Limites

Base de produção:

https://mapas.octacore.com.br/api

Header obrigatório para chamadas privadas:

x-api-key: SUA_CHAVE_OCTACORE

A chave completa aparece somente na criação ou na rotação. Depois disso, a Octacore guarda apenas hash e usa o prefixo visível para suporte, auditoria e identificação operacional.

Cada credencial pode ter rate limit, cota mensal e allowlist de IP. Excesso de limite retorna 429.

Portal da credencial

O cliente pode validar a própria chave, conferir chaves ativas por prefixo e acompanhar consumo sem acessar endpoints administrativos:

curl https://mapas.octacore.com.br/api/client/me \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl https://mapas.octacore.com.br/api/client/keys \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/client/usage?days=7" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Antes de ir para produção, rode o check autenticado de integração:

curl https://mapas.octacore.com.br/api/client/integration-check \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

A rotação é executada pela equipe Octacore. A chave antiga pode permanecer ativa por uma janela combinada para permitir troca sem parada no backend do cliente.

Capacidades e Contrato da Credencial

Antes de integrar, o cliente pode consultar o contrato operacional da própria chave: escopos, limites, política de providers, cobertura e smoke tests recomendados.

curl "https://mapas.octacore.com.br/api/capabilities" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/client/contract" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Para demonstrações públicas sem chave:

curl "https://mapas.octacore.com.br/api/public/capabilities"

Kit de Integração e Compatibilidade

Para reduzir dependência técnica no cliente, a Octacore publica um kit com contrato de integração, coleção Postman e exemplos mínimos em JavaScript, PHP e Python. Os exemplos já incluem x-request-id, timeout e retry apenas para 429, timeouts e 5xx.

Também mantemos guias internos/protegidos de operação e cenários de decisão para onboarding assistido. O cliente recebe os exemplos públicos e a equipe Octacore usa os documentos internos no admin para configurar credenciais, chaves, cotas, fallback, pins, clima, webhooks e homologação.

Os SDKs públicos incluem helpers para search, route, deliveryCheck, weatherRegionalIntelligence e routeAlternativesWeather. No JavaScript também há decisionDelivery com POST pronto, timeout e retry seguro.

Política de evolução

• Todos os endpoints de API usam o prefixo /api.
• Novos campos podem ser adicionados sem quebrar clientes existentes; ignore campos desconhecidos.
• Campos atuais não devem mudar de significado sem janela de migração.
• Mudanças incompatíveis devem ser evitadas e, quando inevitáveis, comunicadas com no mínimo 90 dias.
• Chaves Google e documentos internos permanecem no backend/admin da Octacore.

curl https://mapas.octacore.com.br/api/public/integration-kit
curl https://mapas.octacore.com.br/api/public/platform-manifest
curl https://mapas.octacore.com.br/api/public/decision-recipes
curl https://mapas.octacore.com.br/api/public/api-catalog
curl https://mapas.octacore.com.br/api/public/readiness
curl https://mapas.octacore.com.br/api/public/postman-collection
curl https://mapas.octacore.com.br/api/public/sdk/manifest
curl https://mapas.octacore.com.br/api/public/sdk/javascript

Workflows recomendados

curl "https://mapas.octacore.com.br/api/weather/regional-intelligence?city=S%C3%A3o%20Paulo&neighborhood=Paulista" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/route-alternatives-weather?origin=-23.55052,-46.63331&destination=-23.58917,-46.63465&sample_points=5" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Catálogo Público da API

O catálogo público é o inventário seguro da plataforma para terceiros. Ele mostra capacidades, escopos, endpoints, casos de uso, demos públicas e fluxos recomendados sem expor OpenAPI privado, rotas administrativas, chaves Google, segredos ou documentos internos.

curl "https://mapas.octacore.com.br/api/public/api-catalog"

O cliente deve integrar somente endpoints documentados com prefixo /api. O catálogo pode receber novos campos; mantenha o parser tolerante a campos desconhecidos.

Validar a Própria Credencial

curl "https://mapas.octacore.com.br/api/client/me" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/client/usage?days=7" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/client/usage/endpoints?days=7" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Homologação Assistida

Para cada cliente, a Octacore cria uma credencial própria com escopos, cota mensal, rate limit e, quando necessário, allowlist de IP. A chave é entregue por canal seguro e deve ser usada apenas em backend, serviço interno, aplicativo protegido ou ambiente de homologação controlado.

Cenários mínimos

curl "https://mapas.octacore.com.br/api/client/me" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/geocode?address=Teatro%20Amazonas%20Manaus&limit=1" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/route?origin=-23.96083,-46.33361&destination=-23.99306,-46.25639" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Se a Octacore criar um pin demo para sua homologação, abra https://mapas.octacore.com.br/map, informe sua x-api-key na seção Pins operacionais e carregue pins, tracking e locais. O pin demo confirma autenticação, isolamento por cliente e renderização no mapa.

Roteiro de Apresentação

Use o mapa público em modo apresentação para demonstrar os cenários em sequência. A barra inferior do mapa troca os presets sem sair da tela e o painel lateral mostra o endpoint, o payload e um resumo JSON da resposta.

Durante a apresentação, comece pela dor do cliente: endereço confiável, rota confiável, frota visível, área controlada e decisão com dados.

Mapa Interativo de Teste

Use o mapa abaixo para validar busca, rota, matriz, pins, tracking, raio, polígono, retângulo, zonas e contexto operacional sem sair da documentação.

Para pins privados, informe uma x-api-key de homologação no campo Pins operacionais do mapa. A chave fica apenas no navegador do operador durante o teste.

Mapas de Exemplo por Cenário

Os mapas abaixo carregam cenários de demonstração reais da interface pública. Eles servem para homologar visualmente o comportamento que o cliente pode consumir via API ou incorporar em sua própria plataforma.

Simulador público guiado

Os presets executam fluxos completos no mapa de homologação. Em produção, o cliente escolhe quais recursos aparecem para operador, entregador e usuário final.

Bases regionais disponíveis

A renderização visual aceita tiles=sao-paulo, tiles=sudeste, tiles=sul, tiles=centro-oeste, tiles=nordeste e tiles=norte. A API escolhe OSRM regional automaticamente quando os pontos pertencem à mesma região operacional.

Casos de Uso Recomendados

Busca de Endereços

Todos os endpoints privados usam o prefixo /api. A evolução acontece por compatibilidade de contrato e documentação, mantendo URLs simples para os clientes.

Autocomplete

curl "https://mapas.octacore.com.br/api/search?q=Avenida%20Boa%20Viagem%20Recife&city=Recife&state=PE" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Geocode

curl "https://mapas.octacore.com.br/api/geocode?address=Teatro%20Amazonas%20Manaus&limit=1" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Reverse Geocode

curl "https://mapas.octacore.com.br/api/reverse-geocode?lat=-23.55052&lng=-46.63331" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Checagem Pública de Rota com Google

A Octacore pode oferecer uma checagem pública e sanitizada de rota contra Google Directions para demonstração, auditoria de qualidade e suporte. Ela não expõe chave Google, não roda no navegador do cliente e não substitui o roteador próprio como caminho principal.

Por padrão, o endpoint responde com status disabled até que a Octacore ative routing.public_google_check_enabled no admin/env e configure a chave Google Directions no backend. Mesmo ativado, ele é rate-limited por IP e retorna apenas distância, duração, diferença percentual e decisão resumida.

curl "https://mapas.octacore.com.br/api/public/route/google-check?origin=-23.55052,-46.63331&destination=-23.56168,-46.65614&local_distance_meters=6200&local_duration_seconds=980"

{
  "status": "checked",
  "provider": "google_directions",
  "google": { "distance_meters": 6400, "duration_seconds": 1020 },
  "comparison": {
    "distance_delta_percent": 3.23,
    "duration_delta_percent": 4.08,
    "decision": "compatível"
  },
  "security_note": "Resposta sanitizada: sem chave, sem URL assinada e sem payload bruto do provider."
}

Use isso como ferramenta de confiança e diagnóstico. A política de fallback real continua por cliente, no backend, e a chave Google permanece restrita ao admin/servidor.

Busca Unificada e Validação

Use /api/search quando quiser um único campo inteligente. O parâmetro q aceita endereço, rua, bairro, cidade, CEP, coordenada, loja, hub ou local cadastrado pelo cliente. A resposta informa o tipo em kind: rua, bairro, cidade, cep, coordenada ou local_cadastrado.

A busca combina locais do cliente, municípios oficiais, OpenStreetMap/Nominatim, cache e Google fallback quando configurado. A base local nacional é o caminho principal; Google fica como segurança por cliente.

Campo único

curl "https://mapas.octacore.com.br/api/search?q=Congresso%20Nacional%20Brasilia&limit=5" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

CEP

curl "https://mapas.octacore.com.br/api/search?q=80020-901%20Curitiba" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Coordenada

curl "https://mapas.octacore.com.br/api/search?q=-23.55052,-46.63331" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Normalizar e validar

curl "https://mapas.octacore.com.br/api/address/normalize?address=Avenida%20Boa%20Viagem%20Recife" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/address/validate?address=Rua%20Augusta,%201500,%20Sao%20Paulo%20-%20SP" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Locais do cliente

curl "https://mapas.octacore.com.br/api/places/client?q=Loja%20Centro&limit=10" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Cobertura e geofence

curl "https://mapas.octacore.com.br/api/coverage/check?origin=-23.55052,-46.63331&destination=-23.56168,-46.65614&max_distance_km=10" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl -X POST "https://mapas.octacore.com.br/api/geofence/check" \
  -H "content-type: application/json" \
  -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{"lat":-23.55052,"lng":-46.63331,"geojson":{"type":"Polygon","coordinates":[[[-46.70,-23.60],[-46.60,-23.60],[-46.60,-23.50],[-46.70,-23.50],[-46.70,-23.60]]]}}'

Correção de acento e digitação: consultas como Sao Jose Rio Preto são normalizadas para encontrar São José do Rio Preto quando a base local ou o fallback retornam esse resultado.

Rotas, Distância, Matriz e Entrega

Distância e tempo

curl "https://mapas.octacore.com.br/api/distance?origin=-23.55052,-46.63331&destination=-22.90556,-47.06083" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Rota completa

curl "https://mapas.octacore.com.br/api/route?origin=-23.55052,-46.63331&destination=-22.90556,-47.06083" \
	  -H "x-api-key: SUA_CHAVE_OCTACORE"

Rotas alternativas

Use strategy=fastest, shortest ou balanced. A API retorna até três geometrias e informa recommended_route_id. O cliente pode aceitar a recomendação ou permitir que o usuário escolha outro route_id.

curl "https://mapas.octacore.com.br/api/route-alternatives?origin=-23.55052,-46.63331&destination=-23.58917,-46.63465&strategy=balanced&limit=3" \
	  -H "x-api-key: SUA_CHAVE_OCTACORE"

As alternativas atuais comparam tempo e distância sobre a malha OSRM. Restrições como pedágio, altura, peso, tipo de veículo ou clima exigem perfis e dados adicionais e não devem ser inferidas apenas pela geometria.

Matriz

curl "https://mapas.octacore.com.br/api/matrix?origin=-23.55052,-46.63331&destinations=-22.90556,-47.06083%7C-23.96083,-46.33361" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Delivery check

curl "https://mapas.octacore.com.br/api/delivery-check?origin=-23.55052,-46.63331&destination=-23.96083,-46.33361&max_distance_km=10" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Motor de Decisão Operacional

A Octacore fornece inteligência para o sistema do cliente decidir melhor. Nós não cobramos usuários finais, não controlamos motoristas, não definimos preço e não substituímos a regra comercial do cliente. A API retorna score, motivos, alertas, rota, zonas, clima e recomendação técnica.

Decisão de entrega, atendimento ou deslocamento

curl -X POST "https://mapas.octacore.com.br/api/decision/delivery" \
  -H "content-type: application/json" \
  -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{
    "origin": "-23.55052,-46.63331",
    "destination": "-23.56168,-46.65614",
    "profile": "delivery_moto",
    "include_weather": true,
    "include_zones": true
  }'

A resposta indica aprovado, aprovado_com_alerta ou bloqueado, sempre com motivos explicáveis. O cliente decide como aplicar isso no checkout, despacho ou painel operacional.

Melhor origem entre loja, hub ou entregador

curl -X POST "https://mapas.octacore.com.br/api/decision/best-origin" \
  -H "content-type: application/json" \
  -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{
    "destination": "-23.56168,-46.65614",
    "origins": ["-23.55052,-46.63331", "-23.56603,-46.69396", "-23.58917,-46.63465"],
    "strategy": "balanced",
    "profile": "delivery_moto"
  }'

Perfis prontos

curl "https://mapas.octacore.com.br/api/decision/profiles" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Perfis como delivery_moto, delivery_carro, tecnico_campo e logistica_leve são presets de inteligência. Eles podem evoluir por cliente sem alterar o contrato principal.

Navegação, Voz e Clima Aplicado à Rota

/api/navigation entrega geometria e instruções passo a passo em português. Cada etapa contém distância, duração, distância restante, manobra, coordenada e um objeto voice com texto, SSML e distância sugerida para o anúncio. A síntese e a reprodução do áudio ficam no aplicativo do cliente.

curl "https://mapas.octacore.com.br/api/navigation?origin=-23.55052,-46.63331&destination=-23.58917,-46.63465" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

{
  "steps": [{
    "instruction": "Vire à direita na Avenida Paulista.",
    "distance_meters": 420,
    "remaining_distance_meters": 3100,
    "maneuver": { "type": "turn", "modifier": "right" },
    "voice": {
      "text": "Vire à direita na Avenida Paulista.",
      "ssml": "<speak>Vire à direita na Avenida Paulista.</speak>",
      "announce_at_meters": 150
    }
  }]
}

/api/weather/location é o endpoint recomendado para a maioria das integrações por bairro, região, endereço ou nome de local. Ele resolve e valida o local dentro da cidade/UF e devolve um contrato compacto com location, conditions, decision e meta. Para nomes genéricos como “Centro”, envie sempre city e state.

/api/weather/point recebe coordenadas e entrega variáveis meteorológicas detalhadas. /api/weather/intelligence acrescenta qualidade do ar, score, mensagens e explicação técnica. Use esses endpoints quando precisar auditar ou interpretar os sinais brutos; para automação operacional simples, prefira /api/weather/location.

/api/weather/regional-intelligence usa coletores temporizados somente para pontos previamente cadastrados. Verifique coverage.matched_filter: quando for false, areas fica vazio e o cliente deve usar /api/weather/point com coordenadas exatas.

No contrato compacto, confira meta.valid_until, meta.data_age_seconds e meta.stale antes de aplicar a decisão. Nos endpoints detalhados, use forecast_window, source_trace, confidence e decision_explain para auditoria técnica.

/api/route-weather amostra a previsão na origem, no destino e ao longo do percurso, estimando risco de chuva, vento e baixa visibilidade no horário esperado de passagem. O provider climático inicial usa Open-Meteo sem chave para beta; a Octacore pode trocar por API comercial sem mudar o contrato entregue ao cliente.

curl "https://mapas.octacore.com.br/api/route-weather?origin=-23.55052,-46.63331&destination=-23.96083,-46.33361&sample_points=5" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/weather/point?lat=-23.55052&lng=-46.63331" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/weather/location?query=Piracicamirim&city=Piracicaba&state=SP&profile=delivery_moto" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/weather/intelligence?lat=-23.55052&lng=-46.63331&profile=delivery_moto" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/weather/regional-intelligence?city=S%C3%A3o%20Paulo&neighborhood=Paulista" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/weather/regional-intelligence?region=sudeste" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/weather/sources" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/weather/public-poll-sources" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/route-weather/provider" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/route-weather/events?origin=-23.55052,-46.63331&destination=-23.96083,-46.33361&risk_threshold=75" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/route-alternatives-weather?origin=-23.55052,-46.63331&destination=-23.96083,-46.33361&sample_points=5" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Para operações dinâmicas, use /api/route-weather/events. Ele retorna eventos normalizados como weather.risk.high quando algum trecho da rota passa do limite configurado. No endpoint privado, emit_webhooks=true emite esses eventos para webhooks cadastrados pelo cliente.

{
  "current": {
    "is_raining_now": false,
    "raining_now_confidence": "baixa",
    "precipitation_mm": 0,
    "weather_description": "parcialmente nublado"
  },
  "forecast": {
    "precipitation_probability_percent": 35,
    "rain_intensity": "sem_chuva",
    "wind_gust_kmh": 21
  },
  "decision": {
    "can_operate": true,
    "recommended_action": "monitorar",
    "confidence": "média",
    "recalculate_after_seconds": 600
  },
  "forecast_window": {
    "expected_start_at": "2026-06-13T18:00:00.000Z",
    "forecast_start_at": "2026-06-13T18:00"
  },
  "source_trace": {
    "provider_name": "Open-Meteo Forecast",
    "provider_docs": "https://open-meteo.com/en/docs",
    "cache_ttl_seconds": 600
  }
}

Fontes climáticas e política de integração

A Octacore não depende de scraping de sites públicos comerciais. Fontes como Climatempo, Windguru, Windy e Google entram apenas por API oficial, contrato, chave ou URL autorizada. Fontes abertas/oficiais como Open-Meteo, CPTEC/INPE e INMET podem alimentar adapters internos, sempre retornando o mesmo contrato Octacore para o cliente.

Também mantemos coletores públicos temporizados em /api/weather/public-poll-sources. Por padrão eles consultam Open-Meteo Forecast, Open-Meteo Air Quality e INMET Avisos Ativos para bairros de São Paulo, Campinas, Santos e capitais por região do Brasil. As fontes privadas ficam prontas para ativação posterior no admin/env, sem mudar os endpoints usados pelos clientes.

Novos pontos monitorados podem ser adicionados por configuração em WEATHER_PUBLIC_REGION_POINTS, com id, label, region, state, city, neighborhood, lat e lng. O timer padrão roda a cada 900 segundos, com cache e timeout, para não transformar a API do cliente em dependência direta de terceiros.

GET /api/public/weather/sources
GET /api/public/weather/regional-intelligence?city=Sao%20Paulo&neighborhood=Paulista
GET /api/public/weather/public-poll-sources

A comparação meteorológica não substitui alertas oficiais. O campo de alagamento é um sinal hidrológico regional e nunca deve ser interpretado como confirmação de uma rua alagada. Quando a API climática definitiva for escolhida, ela entra como adapter interno mantendo estes endpoints.

Confiabilidade e Escolha do Endpoint Climático

Escolha o endpoint pelo nível de detalhe necessário. O monitoramento regional não é uma busca climática universal: ele consulta apenas pontos fixos alimentados pelo timer.

Status operacional

decision.status é adequado para automação; decision.signals explica a causa e decision.recommendations sugere ações. A regra final continua pertencendo ao cliente.

Como interpretar confiança

Probabilidade não é volume

precipitation_probability_percent informa a chance de precipitação na janela. precipitation_mm estima o volume. Uma previsão de 65% e 0,2 mm sugere possibilidade relevante de garoa fraca, não chuva intensa.

Horários e validade

Os timestamps usam ISO 8601 e normalmente UTC (Z). O frontend deve converter para o fuso local. Por exemplo, 18:00Z corresponde a 15:00 em Brasília quando o offset é UTC-03:00. Respeite também forecast_window, generated_at, valid_until e recalculate_after_seconds.

Exemplo: Piracicaba

# 1. Localizar a cidade
curl "https://mapas.octacore.com.br/api/geocode?address=Piracicaba%2C%20SP" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

# 2. Consultar o clima no ponto exato
curl "https://mapas.octacore.com.br/api/weather/point?lat=-22.711323&lng=-47.813840" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

# Consulta direta por bairro, já com validação geográfica e inteligência
curl "https://mapas.octacore.com.br/api/weather/location?query=Piracicamirim&city=Piracicaba&state=SP&profile=delivery_moto" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

# Guia estruturado para SDKs e onboarding
curl "https://mapas.octacore.com.br/api/public/weather-guide"

Bairros e regiões de Piracicaba

Para comparar regiões, consulte origem e destino por /api/weather/location e reutilize location.lat/location.lng em /api/route-weather ou /api/route-alternatives-weather. O retorno operacional contém somente location, conditions, decision e meta. Recalcule quando o veículo mudar de bairro, quando a janela de SLA se aproximar ou após meta.refresh_after_seconds.

{
  "location": { "name": "Piracicamirim", "city": "Piracicaba", "state": "SP", "lat": -22.7422, "lng": -47.6253 },
  "conditions": {
    "now": { "raining": true, "description": "garoa leve", "temperature_c": 20.5 },
    "forecast": { "rain_probability_percent": 90, "precipitation_mm": 0.2 },
    "air_quality": { "aqi": 65, "level": "baixo" }
  },
  "decision": {
    "status": "attention",
    "score": 63,
    "can_operate": true,
    "compare_route": true,
    "signals": ["chovendo agora", "probabilidade de chuva 90%"],
    "recommendations": ["preferir rota com menor exposição"]
  },
  "meta": { "valid_until": "2026-06-15T15:15:47.406Z", "data_age_seconds": 20, "stale": false }
}

Para decisões críticas, combine atualização frequente, alertas oficiais, mais de um provider quando contratado e regras próprias. A previsão é inteligência de apoio, não garantia da condição em uma rua específica.

Locais e Busca por Raio

Locais são pontos fixos do cliente, como loja, hub, base técnica, filial, armário inteligente ou ponto de retirada. Eles são cadastrados pelo cliente via API e podem ser exibidos no mapa como pins fixos.

curl -X POST "https://mapas.octacore.com.br/api/locations" \
  -H "content-type: application/json" \
  -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{"name":"Hub Boa Viagem","type":"hub","address":"Avenida Boa Viagem, Recife - PE","lat":-8.11731,"lng":-34.89486,"metadata":{"external_id":"hub-recife-1"}}'

curl "https://mapas.octacore.com.br/api/radius-search?lat=-23.55052&lng=-46.63331&radius_km=5&type=merchant" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Zonas, Bairros e Raios Operacionais

Zonas são regras operacionais configuradas pela Octacore no admin para cada operação. Uma zona pode ser um raio, um polígono, uma lista de bairros, cidades ou estados. Ela pode ficar visível no mapa ou oculta apenas para regras internas.

Testar raio sem chave

curl "https://mapas.octacore.com.br/api/public/coverage-area?lat=-23.55052&lng=-46.63331&radius_km=3&label=Centro"

Consultar contexto de bairros e zonas

curl "https://mapas.octacore.com.br/api/delivery-context?origin=-23.55052,-46.63331&destination=-23.56168,-46.65614" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Exemplo de configuração operacional

{
  "id": "campinas-barao-geraldo-cobertura",
  "name": "Barão Geraldo - cobertura",
  "active": true,
  "visibility": "visible",
  "apply_to": "destination",
  "signal": "coverage",
  "tags": ["brasilia", "cobertura"],
  "geometry": {
    "kind": "circle",
    "center": { "lat": -15.7942, "lng": -47.8822 },
    "radius_km": 5
  },
  "match": {
    "neighborhoods": ["Asa Sul"],
    "cities": ["Brasília"],
    "states": ["DF"]
  }
}

No mapa público em /map, use Raio, Polígono ou Retângulo para testar áreas. Depois de desenhar, arraste vértices ou use Expandir/Reduzir para ajustar a geometria. Selecione origem e destino e clique em “Testar contexto operacional” para ver bairros, zonas, sinais e rota retornados pela API pública de teste.

Geofences Persistentes por Cliente

Geofences persistentes são polígonos administrados pelo próprio cliente. Podem representar cobertura, restrição, hub, condomínio, área de risco, campanha ou qualquer regra espacial. Todos os dados ficam isolados pela credencial.

curl -X POST "https://mapas.octacore.com.br/api/geofences" \
  -H "content-type: application/json" \
  -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{
    "name":"Cobertura Centro",
    "type":"coverage",
    "geojson":{"type":"Polygon","coordinates":[[[-46.66,-23.57],[-46.62,-23.57],[-46.62,-23.54],[-46.66,-23.54],[-46.66,-23.57]]]},
    "schedule":{"timezone":"America/Sao_Paulo","days":["mon","tue","wed","thu","fri"],"start":"08:00","end":"22:00"},
    "rules":{"priority":10,"allow_delivery":true},
    "metadata":{"external_id":"area-centro"}
  }'

Consultar ponto e exportar GeoJSON

curl "https://mapas.octacore.com.br/api/geofences/check?lat=-23.55052&lng=-46.63331" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/geofences/geojson" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Importar FeatureCollection

curl -X POST "https://mapas.octacore.com.br/api/geofences/import" \
  -H "content-type: application/json" \
  -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{"geojson":{"type":"FeatureCollection","features":[{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-46.66,-23.57],[-46.62,-23.57],[-46.62,-23.54],[-46.66,-23.54],[-46.66,-23.57]]]},"properties":{"name":"Área 1","type":"coverage"}}]}}'

GeoJSON sempre usa [longitude, latitude]. A importação aceita até 100 áreas por chamada; prefira polígonos simplificados para reduzir latência e tamanho de payload. inside_any indica presença geométrica, enquanto operational_inside_any também considera o dia, horário e fuso definidos em schedule.

Pins Operacionais e Tracking

Pins são um espelho operacional para mapa e tracking. O cadastro mestre de usuário, técnico, motorista, frota, loja ou ativo continua no sistema do cliente. A Octacore guarda apenas o necessário para desenhar e atualizar o ponto no mapa.

O cliente decide o que cada pin representa: veículo, técnico, entregador, vendedor, usuário de campo, ativo móvel, loja temporária ou equipe. O identificador estável deve ser enviado em external_id, permitindo sincronizar o mesmo objeto ao longo do tempo.

curl -X POST "https://mapas.octacore.com.br/api/fleet/vehicles" \
  -H "content-type: application/json" \
  -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{"external_id":"tecnico-42","label":"Técnico 42","vehicle_type":"technician","status":"active","lat":-23.55052,"lng":-46.63331}'

Atualizar posição do pin

curl -X POST "https://mapas.octacore.com.br/api/fleet/vehicles/ID_DO_PIN/position" \
  -H "content-type: application/json" \
  -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{"lat":-23.56168,"lng":-46.65614,"heading":120,"speed_mps":7.5,"accuracy_meters":10,"status":"active"}'

Abrir tracking vinculado ao pin

curl -X POST "https://mapas.octacore.com.br/api/tracking/sessions" \
  -H "content-type: application/json" \
  -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{"external_id":"pedido-123","label":"Entrega Pedido 123","vehicle_external_id":"tecnico-42","destination_lat":-23.56168,"destination_lng":-46.65614}'

Enviar posição com idempotência

curl -X POST "https://mapas.octacore.com.br/api/tracking/sessions/ID_DA_SESSAO/positions" \
  -H "content-type: application/json" \
  -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{"event_id":"gps-pedido-123-000042","recorded_at":"2026-06-12T14:30:00.000Z","lat":-23.555,"lng":-46.640,"heading":90,"speed_mps":8.2,"accuracy_meters":12}'

event_id evita duplicatas em reenvios. recorded_at preserva a ordem real capturada pelo dispositivo, mesmo quando pacotes chegam atrasados.

A criação retorna public_map_url no formato /acompanhar/{public_token}. Essa tela mostra somente posição atual, destino, rota, distância e previsão, sendo adequada para entregador, técnico ou cliente final. O mapa completo em /map permanece como ambiente operacional e de homologação.

Carregar pins no mapa

curl "https://mapas.octacore.com.br/api/tracking/fleet/geojson?status=all&max_age_minutes=1440&limit=1000" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

No mapa público, a chave fica somente no navegador de teste do operador. Em produção, recomenda-se servir os dados de pins pelo backend do cliente ou por sessão protegida, nunca expondo a chave Octacore em página pública aberta.

Fluxo completo de homologação

# 1. Validar a credencial
curl "https://mapas.octacore.com.br/api/client/me" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

# 2. Criar um pin operacional
curl -X POST "https://mapas.octacore.com.br/api/fleet/vehicles" \
  -H "content-type: application/json" \
  -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{"external_id":"tecnico-demo-1","label":"Técnico Demo 1","vehicle_type":"technician","status":"active","lat":-23.56168,"lng":-46.65614}'

# 3. Atualizar a posição do pin
curl -X POST "https://mapas.octacore.com.br/api/fleet/vehicles/ID_DO_PIN/position" \
  -H "content-type: application/json" \
  -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{"lat":-23.56603,"lng":-46.69396,"heading":120,"speed_mps":7.5,"accuracy_meters":10,"status":"active"}'

# 4. Criar tracking vinculado ao pin
curl -X POST "https://mapas.octacore.com.br/api/tracking/sessions" \
  -H "content-type: application/json" \
  -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{"external_id":"atendimento-demo-1","label":"Atendimento Demo 1","vehicle_external_id":"tecnico-demo-1","destination_lat":-23.55052,"destination_lng":-46.63331}'

# 5. Carregar GeoJSON no mapa
curl "https://mapas.octacore.com.br/api/fleet/vehicles/geojson?active=true&limit=1000" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/tracking/fleet/geojson?status=all&max_age_minutes=1440&limit=1000" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

ETA Inteligente e Webhooks

O ETA começa com a previsão do OSRM e é corrigido progressivamente pelo andamento da sessão e pelo histórico isolado do cliente. Ao concluir uma sessão, a Octacore compara previsão inicial e tempo realizado, agrupando amostras por cidade, horário e tipo de operação quando esses valores são enviados em metadata.

curl "https://mapas.octacore.com.br/api/tracking/sessions/ID_DA_SESSAO/eta" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

{
  "eta": {
    "duration_seconds": 842,
    "baseline_duration_seconds": 790,
    "correction_factor": 1.066,
    "confidence": "média",
    "historical_samples": 12,
    "model": "osrm+historico+progresso"
  }
}

Webhooks avisam o backend do cliente sem exigir polling contínuo. Além de geofence, tracking e clima, a API emite eventos de ETA, qualidade de endereço, fallback e cota.

curl -X POST "https://mapas.octacore.com.br/api/webhooks" \
  -H "content-type: application/json" \
  -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{"url":"https://cliente.exemplo.com/webhooks/mapas","events":["eta.updated","route.risk_changed","weather.window_changed","address.low_confidence","fallback.used","quota.warning"]}'

A criação retorna um secret uma única vez. Em cada entrega, calcule HMAC SHA-256 sobre o corpo bruto e compare com x-octacore-signature, no formato sha256=HEX. Valide também x-octacore-event-id para processar cada evento uma única vez.

Homologar e acompanhar entregas

curl -X POST "https://mapas.octacore.com.br/api/webhooks/ID_DO_WEBHOOK/test" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/webhooks/health" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/webhooks/events/history?limit=50" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Rotação e recuperação

# Gera um novo segredo e invalida o anterior para novas entregas
curl -X POST "https://mapas.octacore.com.br/api/webhooks/ID_DO_WEBHOOK/rotate-secret" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

# Reenvia todas as entregas associadas a um evento específico
curl -X POST "https://mapas.octacore.com.br/api/webhooks/events/ID_DO_EVENTO/replay" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

# Recoloca entregas encerradas como failed na fila
curl -X POST "https://mapas.octacore.com.br/api/webhooks/deliveries/redrive?limit=100" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Use replay para um evento conhecido e redrive após corrigir uma indisponibilidade geral do receptor. O sistema cliente deve deduplicar por x-octacore-event-id, pois uma recuperação pode reenviar um evento já processado.

const crypto = require("node:crypto");

function assinaturaValida(rawBody, secret, recebido) {
  const esperado = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(recebido));
}

O endpoint deve usar HTTPS e responder com HTTP 2xx rapidamente. A Octacore valida DNS e bloqueia redes privadas, repete falhas com backoff exponencial e encerra após oito tentativas. A fila e os monitores são processados automaticamente; o cliente não precisa chamar /api/webhooks/process. Processe o trabalho pesado de forma assíncrona no sistema cliente.

Eventos e entregas terminais são mantidos por 90 dias por padrão. Itens ainda pendentes, em retry ou processamento não são removidos pela retenção automática.

Inteligência de Operação, SLA e Mapa de Calor

Além de mapa, busca e rota, a Octacore entrega endpoints para apoiar decisão operacional. Eles são opcionais: o cliente continua dono da promessa comercial, fila, aceite de motorista, preço, pagamento e comunicação com o usuário final.

Score unificado por público

/api/operation/decision-score é o caminho recomendado quando o cliente quer uma resposta única para operador, entregador, usuário final ou subcliente. O campo audience controla a exposição: operador recebe evidências completas; entregador recebe rota/ETA/ação objetiva; usuário final recebe status simplificado; subcliente recebe visão agregada e filtrada.

curl -X POST "https://mapas.octacore.com.br/api/operation/decision-score" \
  -H "content-type: application/json" \
  -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{
    "origin":"-23.55052,-46.63331",
    "destination":"-23.56168,-46.65614",
    "profile":"delivery_moto",
    "prep_time_minutes":12,
    "promised_sla_minutes":45,
    "audience":"operator",
    "drivers":[
      {"id":"moto-01","lat":-23.5489,"lng":-46.6388,"status":"online","current_orders":1},
      {"id":"moto-02","lat":-23.5660,"lng":-46.6940,"status":"offline","current_orders":0}
    ]
  }'

Decisão operacional completa

/api/operation/decision combina SLA, risco de rota, melhor motorista e melhor origem quando esses dados são enviados. É um endpoint para checkout, torre de controle, roteirização leve e despacho de delivery.

curl -X POST "https://mapas.octacore.com.br/api/operation/decision" \
  -H "content-type: application/json" \
  -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{
    "origin":"-23.55052,-46.63331",
    "destination":"-23.56168,-46.65614",
    "profile":"delivery_moto",
    "prep_time_minutes":12,
    "promised_sla_minutes":45,
    "neighborhood":"Paulista",
    "drivers":[
      {"id":"moto-01","lat":-23.5489,"lng":-46.6388,"status":"online","current_orders":1},
      {"id":"moto-02","lat":-23.5660,"lng":-46.6940,"status":"online","current_orders":0}
    ],
    "origins":[
      {"id":"loja-centro","point":"-23.55052,-46.63331","prep_time_minutes":12},
      {"id":"loja-paulista","point":"-23.56603,-46.69396","prep_time_minutes":6}
    ]
  }'

Mapa de calor para painel do cliente

O heatmap privado usa dados do próprio cliente autenticado. Ele ajuda a identificar bairros com maior concentração de entregas, frota parada, tracking recorrente, regiões com SLA apertado e pontos onde vale abrir hub ou ajustar cobertura.

O que esquenta o mapa hoje: cada posição de tracking_positions aumenta o calor da célula como histórico de deslocamento/entrega; cada veículo ativo em fleet_vehicles aumenta o calor pela posição atual ou recente da frota; e cada evento enviado para /api/operation/heatmap/events aumenta o calor de demanda. O parâmetro source permite separar essas leituras: tracking, fleet, demand ou all.

Exemplo público sem chave: /api/public/operation/heatmap/demo não usa dados privados de nenhum cliente. Quando a equipe Octacore alimenta a base interna de demonstração pelo admin, esse endpoint mostra sinais persistidos dessa base separada. Se a base demo estiver vazia, ele retorna uma amostra pública calculada com fórmula, componentes por célula e recomendação operacional para o visitante testar a camada visual. O dado real de produção vem sempre dos endpoints autenticados do cliente.

Dashboard público da demo: /api/public/operation/heatmap/dashboard resume a mesma base demo em formato executivo: bairros quentes, tipos de evento, leitura por hora, ações sugeridas, explicação das fontes e preview das células do heatmap. É ideal para demonstrar como um cliente enxergaria demanda por região antes de conectar pedidos reais.

Fórmula da amostra pública: peso = demanda*1.15 + veículos ativos*1.6 + atrasos*5 + modificador climático + lacuna de cobertura. Na produção, esses componentes são alimentados pelos eventos reais do cliente: pedidos, checkouts, tracking, frota, SLA, zonas e clima.

O que ainda não entra automaticamente no peso privado: faturamento ou quantidade de vendas por integração externa não aparecem sozinhos. Pedidos, checkout e demanda entram no calor quando o cliente envia eventos operacionais com coordenada e peso. Clima e chuva podem ser combinados pela decisão operacional, rota climática e SLA.

A resposta é um GeoJSON pronto para mapa, com summary, top_cells, source_breakdown, density_level e recomendação operacional. Assim o cliente pode desenhar a camada e também tomar decisão no backend sem depender da tela visual.

O cliente decide o que ativar e apresentar ao seu público. Um operador pode ver calor de demanda, frota offline, risco climático e SLA; um entregador pode receber só rota, ETA e alerta objetivo; um usuário final pode ver apenas acompanhamento e previsão; e um subcliente pode ver relatório agregado sem frota individual.

curl "https://mapas.octacore.com.br/api/operation/heatmap?days=7&precision=3&source=all" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/public/operation/heatmap/dashboard?days=7"

curl -X POST "https://mapas.octacore.com.br/api/operation/heatmap/events" \
  -H "content-type: application/json" \
  -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{
    "event_id":"pedido-123-criado",
    "event_type":"order_created",
    "lat":-23.56168,
    "lng":-46.65614,
    "weight":3,
    "city":"São Paulo",
    "state":"SP",
    "neighborhood":"Paulista"
  }'

curl "https://mapas.octacore.com.br/api/operation/heatmap?days=7&precision=3&source=demand" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

{
  "type": "FeatureCollection",
  "summary": {
    "total_cells": 18,
    "total_weight": 240,
    "hot_cells": 4,
    "density_level": "media",
    "source_breakdown": { "tracking": 180, "fleet": 60 },
    "recommendation": "Há pontos quentes relevantes. Compare com clima, geofences e histórico de ETA antes de mudar a operação."
  },
  "top_cells": [
    { "rank": 1, "lat": -23.562, "lng": -46.656, "weight": 42, "intensity": 1 }
  ],
  "features": []
}

Para demonstrar sem chave, use o mapa público em /map?demo=heatmap, o GeoJSON /api/public/operation/heatmap/demo ou o painel JSON /api/public/operation/heatmap/dashboard. Para validar dados reais de um cliente, use /api/operation/heatmap com x-api-key e envie eventos por /api/operation/heatmap/events. No admin, a seção Base demo de pedidos gera pedidos simulados em uma credencial interna Octacore Demo Signals, separada dos clientes reais.

Tráfego em tempo real e OSRM

O OSRM próprio da Octacore entrega roteamento local, matriz, distância e navegação com base OSM processada. Ele não traz trânsito em tempo real nativamente. Para ETA ao vivo, a Octacore combina tracking, histórico, clima, zonas e pode receber um provedor externo de velocidade/incidentes quando configurado.

Perfis de veículo e operação

Os endpoints de rota aceitam profile para deixar claro o tipo de cálculo pedido pelo cliente. Hoje o roteador próprio usa o perfil técnico OSRM driving para a geometria e registra o perfil operacional na resposta. Perfis como delivery_moto, delivery_carro, tecnico_campo e logistica_leve são aplicados principalmente nos endpoints de decisão, SLA, risco, clima e despacho.

curl "https://mapas.octacore.com.br/api/public/routing/profiles"

curl "https://mapas.octacore.com.br/api/public/route?origin=-23.55052,-46.63331&destination=-23.56168,-46.65614&profile=delivery_moto"

A resposta de rota inclui profile.requested, profile.native_osrm_profile, profile.duration_adjusted_by_profile e profile.traffic_adjusted. Assim o integrador sabe quando o ETA é estático, quando veio de fallback e quando um sinal externo de trânsito for habilitado no futuro.

curl "https://mapas.octacore.com.br/api/public/traffic/status"

curl "https://mapas.octacore.com.br/api/traffic/status" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Use a duração OSRM como ETA base. Quando houver trânsito contratado, a resposta de status passa a indicar o provider configurado e os endpoints de decisão podem aplicar esse sinal junto com SLA, clima e histórico. Google Routes/Traffic pode entrar como fallback ou sinal; HERE e TomTom são bons candidatos para fluxo/incidentes; Mapbox deve ser avaliado por cobertura; Waze for Cities depende de parceria.

Exemplos rápidos

curl -X POST "https://mapas.octacore.com.br/api/delivery/sla-check" \
  -H "content-type: application/json" -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{"origin":"-23.55052,-46.63331","destination":"-23.56168,-46.65614","prep_time_minutes":12,"promised_sla_minutes":45}'

curl -X POST "https://mapas.octacore.com.br/api/route/risk" \
  -H "content-type: application/json" -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{"origin":"-23.55052,-46.63331","destination":"-23.96083,-46.33361","profile":"delivery_moto"}'

curl -X POST "https://mapas.octacore.com.br/api/route/resequence" \
  -H "content-type: application/json" -H "x-api-key: SUA_CHAVE_OCTACORE" \
  -d '{"origin":"-23.55052,-46.63331","stops":[{"id":"a","point":"-23.56168,-46.65614","priority":8},{"id":"b","point":"-23.56603,-46.69396","priority":4}]}'

Todos os retornos trazem generated_at, tipo de inteligência, score/recomendação quando aplicável e evidências. O cliente pode registrar essas evidências no pedido, atendimento ou despacho sem depender de programadores para interpretar provedores externos.

Qualidade, Políticas e Observabilidade

A Octacore entrega sinais para o backend do cliente tomar decisões. Esses recursos são opcionais e não alteram os fluxos básicos de busca e rota.

Score de qualidade do endereço

/api/address/quality classifica endereço completo, incompleto ou ambíguo. A resposta informa presença de CEP, número, cidade, UF e logradouro, confiança da coordenada, problemas encontrados e recomendação: aceitar, confirmar ou pedir complemento.

curl "https://mapas.octacore.com.br/api/address/quality?address=Avenida%20Paulista,%201000&city=Sao%20Paulo&state=SP"   -H "x-api-key: SUA_CHAVE_OCTACORE"

Para demonstração sem chave, use /api/public/address/quality.

Motor de decisão configurável

A política pode definir pesos de chuva, atraso e distância, distância máxima, níveis climáticos de alerta e bloqueio, tipo de veículo, horários de pico e bairros críticos. O contrato dos endpoints permanece o mesmo; a configuração da credencial é aplicada no backend.

curl "https://mapas.octacore.com.br/api/client/decision-policy"   -H "x-api-key: SUA_CHAVE_OCTACORE"

Observabilidade exclusiva da credencial

/api/client/observability mostra somente dados do cliente autenticado: volume, erros, latência média e p95, uso de fallback e entregas de webhooks. Dados globais e de outros clientes ficam restritos ao admin Octacore.

curl "https://mapas.octacore.com.br/api/client/observability?days=30"   -H "x-api-key: SUA_CHAVE_OCTACORE"

Status e pacotes de integração

A página /status e o endpoint /api/public/status apresentam a situação dos componentes sem expor infraestrutura ou segredos. /api/public/integration-packages lista receitas para delivery, farmácia, mercado, assistência técnica, logística leve, rastreamento público e frota interna.

/api/public/data-quality/brazil comprova cobertura de municípios, centroides, UFs, mapas visuais e bases de roteamento sem revelar caminhos internos do servidor.

/api/public/webhook-catalog lista os eventos disponíveis e descreve o gatilho e o controle de volume de cada um.

Municípios

A base local contém os municípios oficiais do Brasil, com código IBGE, UF, centroides e geometria de cobertura. O cliente pode consultar o país inteiro ou restringir a cobertura por UF e município.

curl "https://mapas.octacore.com.br/api/municipalities?q=Manaus&limit=10" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/municipalities/3509502" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/municipalities/coverage?q=Manaus&limit=10" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Bairros e regiões

Para SLA por bairro, geofences, mapa de calor e cobertura operacional, use os endpoints de bairro. Eles retornam disponibilidade de clima, heatmap, geofence e checagem de cobertura.

curl "https://mapas.octacore.com.br/api/neighborhoods/search?q=Piracicamirim&city=Piracicaba&state=SP" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

curl "https://mapas.octacore.com.br/api/coverage/neighborhood-check?q=Piracicamirim&city=Piracicaba&state=SP" \
  -H "x-api-key: SUA_CHAVE_OCTACORE"

Segurança, Resiliência e Concorrência

Timeouts e retries

• Use timeout de até 5 segundos em consultas simples e até 15 segundos em rotas, salvo contrato diferente.
• Repita somente timeouts, 429 e 5xx, com backoff exponencial, jitter e limite de tentativas.
• Não repita automaticamente erros 400 e 401.
• Reduza concorrência em 429 e respeite Retry-After quando presente.
• Use circuit breaker para impedir cascatas durante indisponibilidade externa.

Links públicos e GeoJSON

• Trate o token de acompanhamento como segredo temporário, compartilhe apenas com o destinatário e encerre a sessão ao concluir.
• O corpo JSON padrão aceita até 256 KB. O geofence aceita até 100 áreas e 10.000 coordenadas.
• GeoJSON usa a ordem [longitude, latitude]; simplifique polígonos muito detalhados.

Cache, Performance e Boas Práticas

A Octacore usa Redis para reduzir latência, proteger provedores e evitar custo desnecessário. O cliente não precisa chamar Redis nem conhecer a chave interna de cache; basta consumir a API e tratar o campo source como informativo.

• Use idempotência em tracking com event_id para tolerar retries sem duplicar posições.
• Use backoff exponencial com jitter em 429 e 5xx.
• Não armazene x-api-key em frontend público, analytics, query string ou logs.
• Faça cache próprio apenas para decisões comerciais do seu sistema; a camada de mapas já possui cache central na Octacore.

Tratamento de Erros

Todas as respostas incluem x-request-id. Em erros, esse valor também aparece no JSON como request_id. Guarde-o para suporte e correlação de logs.

{
  "error": true,
  "code": "WEATHER_LOCATION_NOT_FOUND",
  "message": "Não foi possível localizar o bairro ou local dentro da cidade e UF informadas.",
  "details": {},
  "request_id": "req_...",
  "retryable": false,
  "docs_url": "https://mapas.octacore.com.br/docs#erros",
  "suggested_action": "Revise parâmetros, tipos, coordenadas e limites antes de repetir."
}

Quando repetir uma chamada

tentativa 1: aguardar aproximadamente 250 ms
tentativa 2: aguardar aproximadamente 500 ms
tentativa 3: aguardar aproximadamente 1.000 ms

Adicione jitter aleatório e mantenha o mesmo x-request-id da operação lógica.

SLA e Suporte

Para suporte, envie cliente, ambiente, endpoint, horário, status HTTP, code, request_id retornado e exemplo de request sem a chave.

Checklist de Homologação

• Validar a chave em /api/client/me.
• Confirmar escopos, rate limit, cota e política de fallback Google.
• Testar busca unificada em /api/search com endereço, CEP, cidade e coordenada.
• Testar endereços reais em /api/search ou /api/geocode.
• Testar rotas reais em /api/distance ou /api/route.
• Testar municípios relevantes em regiões diferentes, como Manaus, Recife, Brasília, Curitiba, Campinas e Santos.
• Garantir que o sistema cliente trata 401, 429 e 5xx.
• Confirmar que logs do cliente não gravam a chave.
• Enviar event_id e recorded_at nas posições de tracking.
• Validar retries com backoff, jitter e limite de tentativas.

Teste mínimo: /api/client/me, /api/geocode?address=Teatro Amazonas Manaus e /api/distance retornando HTTP 200.