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://app.woovi.com/home/partner/tab/security
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://app.woovi.com/home/security/tabs/allowed-ips
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: https://app.woovi.com/home/applications/tab/list
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://app.woovi.com/home/partner/tab/company-list
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: <AppID do parceiro>
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.