Para movimentar dinheiro pela API da Woovi — Pix out, saque, transferência — a aplicação precisa ter pelo menos um IP permitido cadastrado. É o princípio de uma allowlist: só um servidor conhecido consegue ordenar uma saída de dinheiro, mesmo que o AppID vaze. Sem nenhum IP cadastrado, a chamada é recusada com HTTP 401. Este artigo explica onde cadastrar o IP e, principalmente, como quem opera no modelo parceiro (partner) resolve isso de uma vez para todas as empresas afiliadas. ## Onde o IP pode estar cadastrado Na hora da requisição, a Woovi monta a lista de IPs permitidos somando três origens: * Aplicação (AppID): IPs cadastrados na própria aplicação que faz a chamada. * Empresa: IPs cadastrados na empresa dona da aplicação. * Empresa parceira: IPs cadastrados na empresa parceira (partner) da qual a empresa é afiliada. Basta que o IP de origem da requisição apareça em uma dessas três listas para a chamada ser autorizada. Não é preciso repetir o mesmo IP nos três lugares. ## Se você é parceiro, cadastre o IP na empresa parceira Quem opera no modelo parceiro concentra a integração em um único backend: o parceiro é dono do servidor que dispara as chamadas, e as afiliadas são apenas as empresas em nome das quais o dinheiro se move. Cadastrar o IP afiliada por afiliada seria repetir a mesma informação dezenas ou centenas de vezes. Por isso, o IP cadastrado na empresa parceira vale para todas as empresas afiliadas a ela. Na prática: * Cadastre o IP de saída do seu servidor uma vez, na sua empresa parceira. * Todas as afiliadas existentes passam a aceitar chamadas vindas desse IP. * Toda afiliada nova já nasce coberta, sem nenhum cadastro extra. * Ao criar a aplicação de uma afiliada, o IP do parceiro já satisfaz a exigência de IP permitido. Se uma afiliada específica usa o próprio servidor para movimentar dinheiro, aí sim cadastre o IP dela na empresa afiliada ou na aplicação dela. As listas se somam, então isso convive com o IP do parceiro. No app da Woovi, a lista de IPs da sua empresa parceira fica em Parceiros, na aba Segurança. É essa lista que todas as afiliadas herdam. Link direto: ![](https://chat.woovi.io/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBaG1uIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--d23a2555cec7d5aea6ccace248db3d5aabc4ef2b/03-parceiros-seguranca.png) ## Como cadastrar o IP na sua empresa No app da Woovi, com uma conta que tenha permissão de segurança: * Acesse API/Plugins e abra a aba IPs permitidos (o mesmo cadastro também aparece em Segurança, na aba IPs permitidos). * Clique em Adicionar IP e informe o endereço de saída do seu servidor. * Confirme a operação com a autenticação multifator (MFA) da sua conta. O IP passa a valer para todas as aplicações daquela empresa. Para remover, use a mesma tela — a remoção também pede confirmação por MFA. Link direto: ![](https://chat.woovi.io/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBaFduIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--35cad25a414f864d5f56f436635668780347725c/01-seguranca-ips-permitidos.png) ![](https://chat.woovi.io/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBaGluIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--d145f48eb89a0d84d07a593035d33c0cf1cdac3c/02-adicionar-novo-ip.png) ## Como cadastrar o IP em uma aplicação específica Se você prefere restringir por aplicação, abra API/Plugins, selecione a aplicação (AppID) e cadastre o IP na seção de IPs permitidos da própria aplicação. Use esse caminho quando cada integração roda em um servidor diferente e você quer isolar o alcance de cada credencial. Link direto: ## Como o parceiro cadastra o IP de uma afiliada Além do IP na própria empresa parceira, o parceiro pode cadastrar um IP diretamente em uma afiliada, sem depender do acesso do lojista: abra Parceiros, vá em Empresas, selecione a empresa e use a aba Segurança, em IPs permitidos. A operação também é confirmada por MFA e fica registrada na auditoria. Link direto: ![](https://chat.woovi.io/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBaFNuIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--de0a05950a830847b08da4ab98db3767fa7bff11/04-afiliada-ips-permitidos.png) ## Criando a aplicação da afiliada já com IP pela API de parceiro Ao criar a aplicação de uma afiliada pela API de parceiro, você pode enviar os IPs permitidos junto no campo allowedIPs: ``` POST /api/v1/partner/application Authorization: Content-Type: application/json { "application": { "name": "Loja Exemplo", "type": "API", "scopes": ["PAYMENT_POST", "ACCOUNT_WITHDRAW_POST"], "allowedIPs": ["203.0.113.10"] }, "taxID": { "taxID": "00000000000191", "type": "BR_CNPJ" } } ``` ## Formatos aceitos e o que não é aceito * Endereços IPv4 e IPv6 públicos. * Faixas em notação CIDR, informadas sempre como endereço de rede (por exemplo, 203.0.113.0/24). O uso de faixas precisa ser habilitado para a sua conta — fale com o suporte. * Faixas muito amplas são recusadas: o mínimo é /16 em IPv4 e /32 em IPv6. * IPs privados e reservados (10.x, 192.168.x, 127.0.0.1, entre outros) não são aceitos, porque não identificam um servidor na internet. ## Erros mais comuns * "É necessário um IP permitido nesta aplicação para movimentar dinheiro" (HTTP 401): a aplicação tem permissão de saída de dinheiro, mas nenhum IP foi cadastrado na aplicação, na empresa ou na empresa parceira. Cadastre o IP e repita a chamada. * "Este IP não tem permissão para acessar este ambiente" (HTTP 401): existe lista cadastrada, mas a chamada veio de outro IP. Compare o IP informado na mensagem com o que está cadastrado — normalmente é um servidor novo, um IP de saída que mudou ou uma rotina agendada rodando em outra máquina. * Erro ao criar a aplicação de uma afiliada com escopo de saída de dinheiro: envie allowedIPs na criação ou cadastre o IP antes na empresa parceira. ## Boas práticas * Use um IP de saída fixo (NAT gateway, IP elástico) no servidor que chama a API. IP dinâmico quebra a integração sem aviso. * Cadastre também o IP de homologação e o das rotinas agendadas, não só o do servidor principal. * Revise a lista periodicamente e remova IPs de servidores desativados. * Trate a lista de IPs como camada extra, não substituta: continue protegendo o AppID e o clientSecret. Ficou com dúvida sobre qual IP cadastrar ou sobre o modelo de parceria da sua conta? Fale com o suporte da Woovi.