Este artigo reúne os erros mais comuns de plataformas que operam no modelo parceiro (partner) e cadastram clientes como afiliados. Para o passo a passo completo da integração, veja o guia de integração para parceiros.
"Um IP permitido é obrigatório para uma aplicação com escopo que envia dinheiro"
Quando aparece: ao criar o AppID da afiliada (POST /api/v1/partner/application) com um escopo que movimenta dinheiro, como ACCOUNT_WITHDRAW_POST.
Por que acontece: aplicações que enviam dinheiro precisam de pelo menos um IP permitido, como proteção caso a credencial vaze.
Como resolver: cadastre o IP de saída do seu servidor na sua empresa parceira. Ele passa a valer para todas as afiliadas, inclusive as que forem criadas depois. Outra opção é enviar o IP no campo allowedIPs da própria requisição.
"Conta bancária da empresa não encontrada" ao consultar o extrato da afiliada
Quando aparece: ao consultar o extrato ou as transações com o AppID da afiliada, mesmo que a consulta de uma cobrança específica funcione.
Por que acontece: o AppID da afiliada é vinculado à conta dela no momento em que é criado. Se ele foi gerado antes da conta ser aprovada, ficou sem esse vínculo.
Como resolver: depois da conta aprovada, gere um novo AppID para a afiliada com POST /api/v1/partner/application, usando um nome diferente do anterior. Se o nome for o mesmo, a API devolve o AppID que já existia. Depois, troque a credencial no seu sistema.
Como evitar: no seu fluxo, só gere o AppID da afiliada depois que a conta estiver aprovada.
"Apenas uma aplicação MASTER pode ler outra conta"
Quando aparece: ao tentar consultar a conta de uma afiliada usando o AppID da sua empresa parceira, informando a conta da afiliada no parâmetro.
Como resolver: para consultar extrato, transações e saldo de uma afiliada, use sempre o AppID da própria afiliada. O AppID da empresa parceira serve para as rotas de parceiro (criar afiliada, consultar afiliada e gerar credenciais).
O menu "Minhas empresas" não aparece no sandbox
O modelo parceiro precisa ser habilitado também na sua conta de sandbox. Fale com o nosso time informando o CNPJ da conta de testes.
No sandbox, cadastre as afiliadas pela API (POST /api/v1/partner/company), que é o mesmo fluxo que você vai usar em produção.
O cliente não recebeu o e-mail para completar o cadastro
O reenvio do e-mail de cadastro exige permissão na conta da afiliada:
- No painel, solicite a permissão pela opção de reenviar o e-mail.
- O administrador da conta aprova em Usuários > Permissões > Solicitações de permissão.
Você também pode enviar ao cliente o linkOnboarding retornado na criação da afiliada, que leva direto para o cadastro.
O cliente já tem conta na Woovi
Criar a afiliada pela API sempre cria uma empresa nova. Se o cliente já tem uma conta Woovi e quer usá-la com a sua plataforma, fale com o nosso time: o vínculo de uma conta existente com a empresa parceira é feito por nós.
Um saque foi tarifado quando eu esperava que fosse gratuito
A gratuidade do saque depende do valor e da titularidade do destino. Saques para uma chave de outro titular, como o CPF de um sócio da afiliada, são tarifados mesmo acima do valor de isenção. Leve em conta essa regra ao calcular o saldo e as taxas no seu sistema.
O pedido aparece como pago, mas o valor não está no saldo
Antes de concluir que houve divergência, confira se a cobrança teve estorno ou contestação (MED). Esses eventos reduzem o saldo depois do pagamento e chegam por webhook:
- PIX_TRANSACTION_REFUND_SENT_CONFIRMED: estorno enviado ao pagador
- OPENPIX:DISPUTE_CREATED: contestação aberta pelo pagador
Para conferir a movimentação completa da afiliada, consulte o extrato com o AppID dela.
A credencial de uma afiliada foi exposta
Se um AppID foi compartilhado em um canal aberto (e-mail, grupo de mensagens, print), gere uma nova credencial e desative a antiga.
Ainda com dúvida? Fale com o nosso time pelo chat.