IPs do conector¶

Para: Adm — Conferido em 2026-10-18.

A seção Lista de IPs permitidos da tela Chaves e IPs registra de onde o conector da operação chama a API. Incluir um IP exige a aprovação de outra pessoa e uma espera de 24 horas; remover é imediato. A lista é opcional e altamente recomendada: sem ela a operação funciona; com ela, o Dracma recusa chamadas de qualquer outra origem.

O que é¶

Cada operação tem uma lista de endereços IP e redes (CIDR) de onde o seu conector faz chamadas. A tela mostra, para cada entrada, a rede (IP / CIDR), o rótulo, quem incluiu e quando. Entradas criadas junto com a operação aparecem como incluídas pelo provisionamento.

Quem usa a tela: só o Administrador do tenant. A seção fica na mesma página das Chaves de API.

Quando usar¶

Mantenha a lista com os endereços de saída reais do conector (o NAT do cluster, o IP fixo do servidor). Ela diz de onde a integração pode chamar, e a tabela de chaves mostra o último IP de cada chave para você comparar.

O IP que vale é o de origem visto pelo Dracma. Se o conector sai por proxy, NAT ou provedor de nuvem, cadastre o IP público de saída, não o endereço interno da máquina. Cuidado com IP dinâmico: se o endereço de saída mudar, as chamadas passam a receber 403 ip_not_allowed até a nova entrada ser aprovada e cumprir a espera de 24 horas. Antes de cadastrar, confirme que o IP de saída é fixo.

Inclua um IP novo antes de mudar a rede do conector (novo provedor, novo cluster, ambiente de recuperação), contando com pelo menos 24 horas mais o tempo de uma segunda pessoa aprovar.

Como fazer¶

Incluir um IP¶

1. Em Incluir IP na lista, informe o IP ou CIDR (por exemplo 203.0.113.0/24).
2. Dê um rótulo de 1 a 80 caracteres (por exemplo "cluster principal").
3. Escreva o motivo (de 10 a 1000 caracteres).
4. Clique em Pedir inclusão. É preciso confirmação recente de identidade.
5. O pedido aparece em Pedidos em andamento. Outro Administrador o aprova com um motivo.
6. Depois da aprovação, o pedido fica Aprovado, no time-lock e a entrada entra na lista 24 horas depois. Durante a espera, qualquer Administrador pode cancelar.

É o mesmo fluxo do pedido de chave nova: veja os detalhes em Chaves de API.

Formato aceito¶

A lista aceita apenas redes pequenas: o tamanho mínimo da rede é /24 em IPv4 e /56 em IPv6. Em outras palavras, o número depois da barra tem de ser igual ou maior que o mínimo:

Tipo	Aceito	Recusado
IPv4	/24 a /32 (de 256 endereços a 1)	/23 ou menor número (rede maior) e /0
IPv6	/56 a /128	/55 ou menor número
IP sem máscara	vale como /32 (IPv4) ou /128 (IPv6)	—

Outras regras:

• O endereço deve ser o início da rede: 203.0.113.5/24 é recusado; use 203.0.113.0/24.
• Não há máscara com zero à esquerda nem endereço com identificador de zona.
• Uma entrada repetida é recusada com "Este IP já está na lista."

Remover um IP¶

1. Na linha da entrada, escreva o motivo para remover (de 10 a 1000 caracteres).
2. Clique em Remover agora. É preciso confirmação recente. Uma pessoa basta e vale na hora.
3. Se a lista ficar vazia, a tela avisa: "IP removido. A lista ficou vazia".

Incluir e remover não são simétricos: remover é restritivo e imediato; incluir amplia a lista e por isso passa por aprovação e espera.

Aviso para informar IP e webhook¶

Enquanto a operação não tem IP liberado, o painel mostra um aviso pedindo que você informe. Quando falta a URL do webhook, mostra outro aviso: sem URL cadastrada, a operação não recebe avisos de pagamento e você depende de consultar a API. Os avisos são mais fortes em operação Real do que em Teste, e só aparecem a quem pode gerenciar o item (o aviso de IP, a quem gerencia chaves; o de webhook, a quem vê webhooks). Se o painel não conseguir saber o estado do webhook, ele não mostra aviso.

Cada aviso tem Lembrar depois: ele some por 7 dias para você (o adiamento é por pessoa e fica guardado no servidor, então vale em qualquer navegador) e volta sozinho. Adiar não configura nada e não bloqueia nada.

Bloquear para os IPs vistos¶

Depois das primeiras chamadas, o Dracma guarda por 30 dias os IPs de origem das chamadas autenticadas da operação. Se a operação ainda não tem IP liberado, o painel mostra Vimos chamadas destes IPs com até 10 endereços (primeira e última vez e quantidade de chamadas) e o botão Bloquear para estes IPs.

O botão só vale depois que você confirma, e aí vale na hora. Como ele apenas aperta o acesso (só entram IPs que o Dracma já viu chamando, cada um como /32 em IPv4 ou /128 em IPv6, com o rótulo "visto nas primeiras chamadas"), basta a confirmação recente de identidade: não precisa de aprovação de outra pessoa nem de espera. A confirmação mostra a lista exata, o aviso de IP dinâmico e como desfazer. O atalho só existe enquanto a operação ainda não tem IP liberado. Afrouxar continua com as regras de sempre: incluir um IP que não foi visto (ou mais um IP numa lista que já existe) é um pedido de inclusão com aprovação de outro Administrador e espera de 24 horas.

Antes de confirmar:

• confira se todos os IPs da lista são mesmo do seu conector; remova da sua cabeça os de teste de bancada e de redes que você não usa em produção;
• se o seu IP de saída é dinâmico, não bloqueie por esses IPs: o conector perderia o acesso quando o endereço mudar;
• para desfazer, remova as entradas em Chaves e IPs (a remoção vale na hora, com uma pessoa): sem nenhum IP liberado a operação volta a aceitar qualquer origem com a chave.

Diagnóstico de 403¶

Se uma chamada com chave válida volta 403 com code: ip_not_allowed, a operação tem IPs liberados e a origem vista pelo Dracma não está entre eles. O roteiro é:

1. Abra Chaves e IPs e veja o banner Chave usada de IP fora da lista: ele traz a chave, quantas recusas houve nas últimas 24 horas e o último IP.
2. Se o IP é do seu conector, peça a inclusão (aprovação + 24 horas). Se não é, revogue a chave.
3. Na tabela, a coluna Recusas em 24 h separa os 401 dos 403.

Exemplos¶

Todos os endereços são de documentação.

Entrada	Resultado
203.0.113.10	Aceita, vira 203.0.113.10/32.
198.51.100.0/24	Aceita.
198.51.100.0/22	Recusada: a rede é maior que /24.
198.51.100.7/24	Recusada: o endereço não é o início da rede.
2001:db8:abcd::/56	Aceita.
2001:db8::/32	Recusada: a rede é maior que /56.

Erros e casos de borda¶

Mensagem	Causa	O que fazer
"IP ou CIDR inválido (IPv4 de /24 a /32, IPv6 de /56 a /128)."	Formato fora do aceito.	Corrija conforme a tabela acima.
"O rótulo precisa ter de 1 a 80 caracteres."	Rótulo vazio ou longo.	Ajuste.
"Este IP já está na lista."	A entrada já existe (already_exists).	Nenhuma.
"Pedido de IP enviado. Precisa da aprovação de outra pessoa e do time-lock de 24 h."	Confirmação do pedido.	Peça aprovação a outro Administrador.
"Quem pediu não pode aprovar o próprio pedido."	self_review_forbidden.	Peça a outro Administrador.
"Confirme com o fator forte para concluir."	step_up_required.	Use Confirmar identidade agora.
"Este item já foi decidido ou revogado."	O pedido já terminou ou a entrada já foi removida.	Recarregue a página.

Casos de borda:

• Lista vazia. Não bloqueia nenhuma chamada, em nenhum ambiente. Alguns textos da tela podem ainda dizer que sem IP nenhuma chamada passa; vale o que está aqui.
• Esvaziar a lista libera a operação. Remover a última entrada faz a operação voltar a aceitar qualquer origem com a chave válida.
• Entrada duplicada no meio da espera. Se a mesma rede for incluída por outro pedido durante as 24 horas, o segundo pedido termina como Falhou, sem efeito.
• Várias redes. Inclua uma entrada por pedido. Na criação da operação o formulário aceita até 50 entradas de uma vez.

Veja também¶

• Chaves de API
• Rede, allowlist e mTLS
• Tenants e operações
• Autenticação HMAC