Pular para o conteúdo
API do Faturei Hoje

IPs permitidos

A lista de IPs permitidos é uma trava por chave: só autentica quem chega de um endereço da lista. Lista vazia aceita qualquer IP.

É a trava mais fácil de ligar e a que mais derruba integração sem ninguém entender por quê. Esta página existe para você decidir com clareza.

Quando usar

Seção intitulada “Quando usar”

Use a lista quando o endereço de saída de quem chama é fixo e está sob seu controle:

  • servidor dedicado ou máquina virtual com IP próprio;
  • saída por NAT gateway com endereço fixo;
  • proxy seu na frente da integração.

Não use a lista quando quem chama é função sem servidor, contêiner com escala automática, hospedagem gerenciada, computador de escritório com link residencial ou a máquina de uma pessoa. Nesses casos o endereço muda sem aviso.

A lista não substitui o cuidado com a chave. Ela serve para reduzir o estrago de uma chave vazada, porque a chave sozinha deixa de bastar.

Qual endereço a API compara

Seção intitulada “Qual endereço a API compara”

O endereço de onde a chamada chega até nós. Na prática é o IP de saída do servidor que faz a chamada, não o IP do seu usuário final e não o da sua rede de escritório, a menos que a chamada saia de lá.

Quando a chamada passa pela nossa borda, o endereço considerado é o que a borda informa como origem. Quando ela chega direto, é o endereço que o servidor vê na conexão.

Se a API não consegue determinar o endereço com confiança e a lista não está vazia, a chamada é recusada. Chave sem lista não é afetada por isso.

Formato aceito

Seção intitulada “Formato aceito”

Cada chave aceita até 20 entradas, IPv4 e IPv6, endereço solto ou faixa:

198.51.100.7
198.51.100.0/24
2001:db8::1
2001:db8::/32

Endereço solto vale como a máquina exata (/32 no IPv4, /128 no IPv6).

IPv4 e IPv6 convivem na mesma lista. Se o seu servidor sai ora por um, ora por outro, os dois endereços precisam estar lá.

A máscara é aplicada ao salvar

Seção intitulada “A máscara é aplicada ao salvar”

Se você digitar 203.0.113.5/24, a entrada é guardada como 203.0.113.0/24, porque é isso que a faixa significa. A comparação sempre foi pelos bits do prefixo; guardar o endereço como foi digitado fazia a tela dizer uma coisa e o efeito ser outro.

O painel mostra o valor já normalizado. O que está na tela é exatamente o que vale. Se o endereço apareceu diferente do que você digitou, foi a máscara.

Entradas que viram o mesmo valor depois da normalização contam como uma só.

Entrada inválida não passa

Seção intitulada “Entrada inválida não passa”

Entrada fora do formato não é aceita nem descartada em silêncio: o formulário recusa a mudança inteira. Descartar em silêncio poderia esvaziar a lista, e lista vazia libera qualquer IP.

Como editar a lista

Seção intitulada “Como editar a lista”

No menu da chave, em Editar nome e IPs. O formulário pede a sua senha, e só OWNER e ADMIN editam. Editar amplia acesso, porque apagar a lista libera qualquer endereço, então a ação pede o mesmo papel da emissão da chave.

A lista que você salva substitui a anterior inteira. Para acrescentar um endereço, salve a lista completa com ele dentro.

OWNER e ADMIN recebem e-mail da alteração.

Quando a chamada é recusada

Seção intitulada “Quando a chamada é recusada”

Chamada vinda de endereço fora da lista recebe o mesmo 401 de chave inválida. A resposta não diz que o motivo foi o IP, de propósito: resposta diferente por motivo diria a quem está testando chaves ao acaso quando ele acertou a chave e errou só o endereço.

Quem diz é o painel. A tentativa aparece em Ver uso, com o endereço que chegou e o horário.

Roteiro quando a integração para com 401 e a chave tem lista:

  1. Abra Ver uso na chave e leia o endereço da chamada recusada.
  2. Compare com a lista, já normalizada, na tela da chave.
  3. Se for um endereço seu que você não conhecia, acrescente. Se não for seu, revogue a chave e siga Boas práticas de chave.

Se nenhuma linha aparece em Ver uso, o problema não é o IP: a API não chegou a reconhecer de qual chave se trata. O roteiro completo do 401 está em Autenticação.

Próximo passo

Seção intitulada “Próximo passo”