Skip to main content

Visão Geral

A integração com Woovi (OpenPix) cria conversões automaticamente quando um pagamento via PIX é confirmado. Perfeito para quem aceita PIX como forma de pagamento!
Pré-requisito: A SDK JavaScript deve estar instalada no seu site! Ela é responsável por salvar o cookie com o código do afiliado. Esta integração Woovi é complementar à SDK.
Quando usar:
  • Você usa Woovi/OpenPix para processar PIX
  • Quer automação total de conversões
  • Aceita pagamentos instantâneos via PIX
  • Já tem a SDK instalada

Como Funciona

  1. SDK salva cookie: Cliente acessa com ?ref=CODIGO, SDK salva no cookie
  2. additionalInfo na cobrança: Seu backend lê o cookie e passa para a Woovi
  3. Cliente escaneia QR Code e paga o PIX
  4. Woovi confirma o pagamento
  5. Woovi envia webhook com o código do afiliado
  6. Conversão é criada automaticamente
Papel da SDK: Ela salva o código do afiliado em um cookie que dura 30 dias. Seu backend lê esse cookie e passa para a Woovi via additionalInfo.

Configuração

Passo 1: Ative a Integração no Dashboard

  1. Vá em “Configurações”“Integrações”
  2. Encontre o card da Woovi
  3. Clique em “Ativar”
  4. Anote a URL do Webhook (você vai precisar)
A URL será algo como:

Passo 2: Crie o Webhook na Woovi

  1. Acesse o Dashboard da Woovi
  2. Clique em “Novo Webhook”
  3. Cole a URL do webhook copiada no passo anterior
  4. Selecione os eventos:
    • OPENPIX:CHARGE_COMPLETED
    • OPENPIX:CHARGE_EXPIRED (opcional)
  5. Clique em “Criar”
A Woovi envia um evento de teste automaticamente. Se retornar sucesso, está tudo certo!

Passo 3: Configure sua Chave API (opcional)

Se quiser validar assinaturas dos webhooks:
  1. Na Woovi, vá em “API/Plugins”“Chaves de API”
  2. Copie sua App ID
  3. No Affiliatus, em “Integrações”“Woovi”
  4. Cole o App ID e salve
A validação de assinatura é opcional mas recomendada para segurança adicional.

Enviando Código do Afiliado

Você precisa incluir o código do afiliado no campo additionalInfo ao criar a cobrança PIX:

API da Woovi

O campo affiliate_code no additionalInfo é obrigatório para rastrear o afiliado!

Exemplos de Implementação

Next.js/React

Componente React:

Node.js (Express)


PHP (Laravel)


Python (Django)


Testando a Integração

1. Ambiente de Teste da Woovi

  1. Use o ambiente de sandbox da Woovi
  2. Crie uma cobrança de teste com additionalInfo
  3. Simule o pagamento no painel
  4. Verifique se a conversão apareceu no dashboard

2. Use Webhooks de Teste

No dashboard da Woovi:
  1. Vá em “Webhooks”
  2. Clique em “Testar Webhook”
  3. A Woovi enviará um evento de teste
  4. Verifique se retornou 200 OK

3. PIX Real (Ambiente de Produção)

Para testar com PIX real:
  1. Crie uma cobrança com valor baixo (ex: R$ 1,00)
  2. Pague o PIX com seu celular
  3. Aguarde confirmação (geralmente instantâneo)
  4. Verifique a conversão no dashboard

Solução de Problemas

Conversão não é criada

Possíveis causas:
  1. additionalInfo não enviado
    • Verifique se affiliate_code está no additionalInfo
    • Confira no evento do webhook na Woovi
  2. Código de afiliado inválido
    • O código deve corresponder a um afiliado ativo
    • Verifique em “Afiliados” se o código existe
  3. Webhook não configurado
    • Confirme que o webhook está ativo na Woovi
    • Verifique se o evento OPENPIX:CHARGE_COMPLETED está selecionado
  4. Integração não ativada
    • Vá em “Integrações” e ative a Woovi
    • Salve as configurações

Webhook retorna erro

Causa: URL incorreta ou evento de teste não reconhecido. Solução:
  1. Verifique se a URL está correta
  2. Confirme que a integração está ativa
  3. Eventos de teste são ignorados - isso é normal!

Valor da conversão está errado

O valor é capturado diretamente da Woovi em centavos e convertido para reais. Exemplo:
  • Woovi: value: 9900 (centavos)
  • Conversão: order_value: 99.00 (reais)
Se o valor estiver incorreto, verifique o value enviado na criação da cobrança.

Campos Suportados no additionalInfo

Exemplo completo:

Diferenças entre Woovi e OpenPix

Woovi e OpenPix são o mesmo serviço! OpenPix foi renomeado para Woovi.
  • A API continua usando o domínio openpix.com.br
  • Os eventos de webhook usam prefixo OPENPIX:
  • A documentação está em developers.openpix.com.br
Use os termos de forma intercambiável - ambos funcionam!

Boas Práticas

Faça

  • Sempre teste no ambiente de sandbox primeiro
  • Inclua affiliate_code no additionalInfo
  • Use correlationID único para cada cobrança
  • Monitore os logs de webhook na Woovi
  • Armazene o chargeId para referência

Não Faça

  • Não exponha seu App ID no frontend
  • Não crie cobranças duplicadas com mesmo correlationID
  • Não esqueça de converter valores para centavos
  • Não desative o webhook sem avisar os afiliados

Comparação com Stripe

Use Woovi para clientes brasileiros e Stripe para internacionais!

Próximos Passos

Aprovar conversões

Aprenda a aprovar conversões automáticas

Integração Stripe

Automatize conversões via cartão

SDK JavaScript

Rastreamento manual via JavaScript

Dashboard

Acompanhe métricas em tempo real

Precisa de Ajuda?

Sim! A Woovi suporta cobranças recorrentes. Cada pagamento gera uma nova conversão.
Sim. Configure o tempo de expiração na criação da cobrança. O padrão é 24 horas.
A conversão permanece. Você pode rejeitá-la manualmente se necessário.
Sim! A SDK é obrigatória para salvar o código do afiliado no cookie. Sem ela, você não terá como passar o código do afiliado para a Woovi.
No momento, apenas Woovi/OpenPix tem integração nativa. Para outros, use SDK JavaScript.
Dúvidas? Entre em contato pelo suporte ou consulte a documentação da Woovi.