> For the complete documentation index, see [llms.txt](https://docs.ipcheck.ing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipcheck.ing/developer/pt-br/configuration/optional-api-keys.md). # Chaves de API opcionais Chaves de API opcionais de terceiros e os recursos que cada uma desbloqueia. Nenhuma das chaves desta página é necessária. O MyIP inicia e serve tráfego sem nenhuma delas. Cada chave simplesmente ativa mais uma capacidade. O padrão é sempre o mesmo: 1. Você define uma variável de ambiente e reinicia o backend. 2. O backend expõe um **booleano** (nunca o valor) para essa variável por meio de `GET /api/configs`. 3. O frontend lê esses booleanos e mostra, oculta ou desativa a interface correspondente. {% hint style="info" %} `/api/configs` sempre responde apenas `true` / `false`. Suas chaves ficam no servidor e nunca são enviadas ao navegador. {% endhint %} ## Resumo | Variável de ambiente | Desbloqueia | Custo | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | | `IPINFO_API_KEY` | IPinfo.io como fonte de geolocalização de IP selecionável | Plano gratuito disponível | | `IPAPIIS_API_KEY` | IPAPI.is como fonte de geolocalização de IP selecionável | Veja os preços do provedor | | `IP2LOCATION_API_KEY` | IP2Location.io como fonte de geolocalização de IP selecionável | Plano gratuito disponível | | `GOOGLE_MAP_API_KEY` | Botão de mapa nos cartões de detalhes de IP (Google Static Maps) | Conta do Google Cloud com cobrança habilitada | | `MAC_LOOKUP_API_KEY` | Solicitações autenticadas de MAC Lookup (a ferramenta funciona sem isso) | Plano gratuito disponível | | `CLOUDFLARE_API_KEY` | Painel de informações de ASN (Cloudflare Radar), o mapa de calor de atividade online por país, o feed global de interrupções da Earth Online — e, com os dois abaixo, relatórios compartilháveis | Conta gratuita da Cloudflare | | `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_KV_NAMESPACE_ID` | Relatórios diagnósticos compartilháveis armazenados no Workers KV | Conta gratuita da Cloudflare | | `RIPESTAT_SOURCE_APP` | Não é uma chave — identifica sua implantação para o RIPEstat | Grátis, sem cadastro | {% hint style="warning" %} `/api/configs` pode ser armazenado em cache na borda por uma hora. Depois de adicionar uma chave e reiniciar, um CDN ou navegador pode continuar servindo as antigas flags de recurso por até uma hora. Faça um hard-refresh ou limpe o cache se um novo recurso não aparecer. {% endhint %} ## Fontes de geolocalização de IP O MyIP pode consultar vários bancos de dados de IP. O usuário escolhe o ativo em **Preferências**. As fontes cuja chave está ausente aparecem tachadas e não podem ser selecionadas; se uma escolha salva anteriormente perder sua chave, ela é movida automaticamente para a fonte disponível mais próxima, com um aviso. Três fontes dependem de chave: IPinfo.io, IPAPI.is e IP2Location.io. As outras (IP-API.com, IP.sb, MaxMind) não precisam de chave — veja [Configuração do MaxMind](/developer/pt-br/getting-started/maxmind-setup.md) e [Fontes de dados de IP](/developer/pt-br/architecture/ip-data-sources.md). ### IPinfo.io — `IPINFO_API_KEY` * **Desbloqueia**: `IPinfo.io` no seletor de fonte de IP, servido por `GET /api/ipinfo`. * **Sem ele**: a fonte fica desativada no seletor. (O endpoint em si cai para uma solicitação sem token, mas a interface não a oferecerá.) * **Onde obtê-lo**: cadastre-se em [ipinfo.io](https://ipinfo.io/) e copie o token de acesso do seu painel. {% hint style="info" %} A grafia legada `IPINFO_API_TOKEN` ainda é lida como fallback, então implantações antigas continuam funcionando após uma atualização. Novas configurações devem usar `IPINFO_API_KEY`. {% endhint %} ### IPAPI.is — `IPAPIIS_API_KEY` * **Desbloqueia**: `IPAPI.is` no seletor de fonte de IP, servido por `GET /api/ipapiis`. Esta fonte também retorna flags de hospedagem/proxy. * **Sem ele**: a fonte fica desativada no seletor. Chamar o endpoint diretamente retorna um 500. * **Onde obtê-lo**: cadastre-se em [ipapi.is](https://ipapi.is/). ### IP2Location.io — `IP2LOCATION_API_KEY` * **Desbloqueia**: `IP2Location.io` no seletor de fonte de IP, servido por `GET /api/ip2location`. * **Sem ele**: a fonte fica desativada no seletor. Chamar o endpoint diretamente retorna um 500. * **Onde obtê-lo**: cadastre-se em [ip2location.io](https://www.ip2location.io/). {% hint style="success" %} **A rotação de chaves já vem embutida.** `IPINFO_API_KEY`, `IPAPIIS_API_KEY`, `IP2LOCATION_API_KEY` e `GOOGLE_MAP_API_KEY` todos aceitam uma **lista separada por vírgulas**. Uma chave é escolhida aleatoriamente por solicitação, o que distribui a carga entre várias contas gratuitas. ```bash IPINFO_API_KEY="token_one,token_two,token_three" ``` {% endhint %} ## Google Maps — `GOOGLE_MAP_API_KEY` * **Desbloqueia**: o botão de mapa em um cartão de detalhes de IP. Ele abre um mapa estático centralizado nas coordenadas do IP, servido por `GET /api/map`, com um estilo dedicado para o modo escuro. * **Sem ele**: o botão de mapa nunca é renderizado. Todo o resto do cartão não é afetado. * **Onde obtê-lo**: Google Cloud Console → habilite a **Maps Static API** → crie uma chave de API. É necessário um projeto do Google Cloud com cobrança habilitada. {% hint style="warning" %} Restrinja a chave no Google Cloud (por API e, se possível, por IP) antes de colocá-la em uma instância pública. O backend faz proxy da imagem, então a chave nunca chega aos visitantes — mas uma chave vazada do lado do servidor ainda é um risco de cobrança. {% endhint %} ## MAC Lookup — `MAC_LOOKUP_API_KEY` * **Desbloqueia**: solicitações autenticadas para [maclookup.app](https://maclookup.app/) da ferramenta MAC Lookup (`GET /api/macchecker`). * **Sem ele**: a ferramenta ainda funciona. O backend envia a solicitação sem uma chave, e quaisquer limites que o provedor aplique ao tráfego anônimo se aplicam a você. * **Onde obtê-lo**: registre-se em [maclookup.app](https://maclookup.app/) e crie uma chave de API. Esta é a única chave nesta página que compra throughput em vez de um recurso. ## Cloudflare Radar — `CLOUDFLARE_API_KEY` * **Desbloqueia**: três visualizações da única `GET /api/cfradar` rota. O **ASN Info** botão no bloco ASN de um cartão de detalhes de IP (`?view=asn`): o painel mostra o nome do ASN, país, organização e número estimado de usuários; contagens de prefixos IPv4/IPv6 anunciados; contagens de AS upstream, downstream e de peering; qualidade média da conexão (largura de banda de download/upload, latência, jitter) agregada dos testes de velocidade da Cloudflare executados nesse ASN; além de divisões de tráfego de 7 dias — IPv4 vs IPv6, HTTP vs HTTPS, desktop vs móvel, bot vs humano. O **mapa de calor de atividade online por país** no cartão de detalhes de IP (`?view=country-traffic`) — uma grade de 7×24 horas da semana construída a partir de 28 dias da série temporal horária de requisições HTTP do Radar, mostrando por padrão o tráfego provavelmente humano com um alternador para todo o tráfego. E o **Earth Online** feed global de interrupções (`?view=outages`) — suficiente por si só para exibir a entrada de navegação do painel, apenas interrupções em forks sem backend de pulse beacon. Veja [Recursos vinculados ao IPCheck.ing](/developer/pt-br/configuration/features-tied-to-ipcheck-ing.md). * **Sem ele**: o botão ASN Info fica oculto, o ponto de entrada do mapa de calor por país nunca aparece (ele fica atrás da mesma `cloudFlare` flag em `/api/configs` que o botão ASN Info), e o feed de interrupções permanece desligado — em um fork sem backend de pulse beacon, o painel Earth Online não aparece de forma alguma. Os dois botões vizinhos — **ASN History** e **ASN Connectivity** — continuam funcionando: eles são alimentados pelo RIPEstat e por snapshots locais da CAIDA, não pela Cloudflare. * **Onde obtê-lo**: painel da Cloudflare → **Meu perfil → Tokens de API → Criar token**. O token precisa de acesso de leitura ao Radar. {% hint style="info" %} A grafia legada `CLOUDFLARE_API` ainda é lido como fallback. {% endhint %} Os dados do Radar para o painel ASN Info são buscados em oito segmentos independentes. Se alguns deles falharem, o painel degrada campo por campo em vez de encerrar com erro — ASNs pequenos ou privados legitimamente não têm dados de tráfego. As contagens de relacionamento recebem um fallback extra: quando o segmento de relacionamento do Radar falha ou volta vazio, elas são calculadas a partir do snapshot local da CAIDA em vez disso. O mapa de calor de país é diferente: uma solicitação por país que ou retorna uma matriz ou um valor válido, armazenável em cache `trafficMatrix: null`. ## Relatórios compartilháveis — `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_KV_NAMESPACE_ID` O MyIP pode transformar uma execução diagnóstica em um link de compartilhamento apoiado pelo Cloudflare Workers KV. * **Desbloqueia**: `POST /api/report` (armazenar) e `GET /api/report/:id` (leitura), além da opção de link compartilhável no diálogo de relatório e da página de relatório somente leitura. * **Exige todos os três**: `CLOUDFLARE_API_KEY`, `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_KV_NAMESPACE_ID`. Falte um deles e o recurso permanece desativado. * **Sem eles**: ambos os endpoints respondem `503`, `/api/configs` relatórios `reportSharing: false`, e a interface de compartilhamento nunca aparece. Os usuários ainda podem copiar o relatório como Markdown ou baixá-lo como JSON.
Configurando 1. painel da Cloudflare → **Workers & Pages → KV** → crie um namespace. 2. Copie o **ID hexadecimal** do namespace — não o nome. `CLOUDFLARE_KV_NAMESPACE_ID` espera o ID. 3. Copie seu **ID da conta** do painel para `CLOUDFLARE_ACCOUNT_ID`. 4. Certifique-se de que o token em `CLOUDFLARE_API_KEY` também tenha a permissão **Workers KV Storage: Edit** . O mesmo token é usado para o Radar e para o KV.
Como os relatórios armazenados se comportam: * O corpo do relatório é validado contra uma lista de permissões rígida de esquemas — nenhum texto livre pode ser armazenado. * Os IDs dos relatórios têm 16 bytes aleatórios, codificados em base64url (22 caracteres), então os links são impossíveis de adivinhar. * Cada relatório é gravado com um TTL e expira sozinho no KV. IDs expirados respondem `404`. * Os relatórios nunca são armazenados em cache na borda, na leitura ou na gravação. {% hint style="warning" %} Os endpoints de relatório têm **nenhum limite de taxa dedicado**. Em uma instância pública, cubra-os com o limitador global (veja [Opções de segurança](/developer/pt-br/configuration/security-options.md)) ou com regras de borda. {% endhint %} ## RIPEstat — `RIPESTAT_SOURCE_APP` Isto não é uma chave de API e não precisa de conta. O RIPEstat pede que os chamadores se identifiquem por meio de um parâmetro `sourceapp` ; esta variável o define. O padrão é `myip`. Defina-o para algo que identifique sua implantação (por exemplo `myip-yourdomain`) para que seu tráfego seja distinguível caso o RIPE precise entrar em contato com você sobre isso algum dia. O RIPEstat alimenta o ASN History e o fallback do nome da organização usado pelo ASN Connectivity. Ambos funcionam com ou sem esta variável definida. ## Coisas que não precisam de configuração * **Estrelas do GitHub** (`GET /api/github-stars`) chama a API REST pública do GitHub sem autenticação e fica em cache na borda por um dia. Não há token a definir. * **ASN Connectivity** roda a partir de snapshots locais da CAIDA, com o RIPEstat apenas como fallback para nomes de organizações ausentes. ## Definindo as variáveis {% tabs %} {% tab title="Node (.env)" %} {% code title=".env" %} ```bash IPINFO_API_KEY="your-ipinfo-token" IPAPIIS_API_KEY="your-ipapi-is-key" IP2LOCATION_API_KEY="your-ip2location-key" GOOGLE_MAP_API_KEY="your-google-maps-key" MAC_LOOKUP_API_KEY="your-maclookup-key" CLOUDFLARE_API_KEY="your-cloudflare-token" CLOUDFLARE_ACCOUNT_ID="your-account-id" CLOUDFLARE_KV_NAMESPACE_ID="your-namespace-hex-id" RIPESTAT_SOURCE_APP="myip-yourdomain" ``` {% endcode %} Reinicie o backend depois. Veja [Implantar com Node.js](/developer/pt-br/getting-started/deploy-with-nodejs.md). {% endtab %} {% tab title="Docker" %} ```bash docker run -d -p 18966:18966 \\ -e IPINFO_API_KEY="your-ipinfo-token" \\ -e GOOGLE_MAP_API_KEY="your-google-maps-key" \\ -e CLOUDFLARE_API_KEY="your-cloudflare-token" \\ -e CLOUDFLARE_ACCOUNT_ID="your-account-id" \\ -e CLOUDFLARE_KV_NAMESPACE_ID="your-namespace-hex-id" \\ -e RIPESTAT_SOURCE_APP="myip-yourdomain" \\ --name myip \\ jason5ng32/myip:latest ``` Cada variável nesta página é lida em tempo de execução, então `docker run -e` é suficiente — não é necessário rebuild. Veja [Implantar com Docker](/developer/pt-br/getting-started/deploy-with-docker.md). {% endtab %} {% endtabs %} ## Páginas relacionadas * [Variáveis de Ambiente](/developer/pt-br/reference/environment-variables.md) — a lista completa, incluindo as obrigatórias * [Recursos vinculados ao IPCheck.ing](/developer/pt-br/configuration/features-tied-to-ipcheck-ing.md) — capacidades que dependem de serviços privados * [Endpoints da API](/developer/pt-br/reference/api-endpoints.md) — o que cada rota retorna * [Opções de segurança](/developer/pt-br/configuration/security-options.md) — evite que estranhos consumam sua cota --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.ipcheck.ing/developer/pt-br/configuration/optional-api-keys.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.