Install
This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.
Install straight from GitHub with WP-CLI:
wp plugin install https://github.com/lucasedu191/bv-cielo/archive/refs/heads/main.zipPlugin financeiro independente, versão 1.1.3, preparado para instalação manual em homologação, após revisão. O desenvolvimento não executou instalação, ativação ou conexão com a Cielo no site. O plugin oficial foi preservado.
Estado público atual: no desktop, o cabeçalho mostra um ícone de usuário com Entrar ao lado das redes sociais. No celular, o ícone fica dentro do popup do menu, ao lado do Instagram: círculo azul com símbolo branco, sem texto visível. O clique abre Área do cliente em construção na própria página, sem navegação ou nova aba. O acesso direto ao portal também fica em construção por padrão. A área autenticada foi preservada para homologação e liberação futura.
Em 1.1.2, foi corrigido o contraste do botão: branco na barra azul desktop e azul no cabeçalho móvel branco, com alinhamento central ao grupo social.
Desde 1.1.3, o acesso móvel não fica mais junto ao hambúrguer: abra o menu e use o círculo de usuário após o Instagram em Siga nas redes sociais. O ícone tem nome acessível e mantém o aviso de construção.
Versionamento e atualização pelo WordPress seguem o fluxo do outro plugin BV: commit → push → tag → GitHub Release com ZIP → atualização no painel. Veja RELEASES.md. O Plugin Update Checker 5.6 acompanha o pacote e não exige Composer no servidor. A versão local anterior 1.0.0 precisa ser substituída manualmente uma vez, pois ainda não tinha updater.
O que está implementado
- Área do cliente implementada em
/area-do-cliente-bv/, atualmente em construção: login, locações, cartões e cobranças ficam reservados à homologação até a liberação. O atalho Entrar abre somente o aviso. - Tela Área do cliente para a equipe vincular contas e contratos confirmados; QR Code do portal e de links individuais de cadastro.
- Dashboard por período; cobranças, revisão e confirmação; consulta e conciliação; cancelamento/estorno total condicionado à habilitação.
- Consulta de usuários WordPress e cotações
bvgn_cotacao, sem duplicar cadastros ou alterar tarifas/caução. - Links de cadastro de cartão de 15 minutos, consentimento versionado, captura direta pelo navegador via SOP e validação server-to-server via Zero Auth.
- Vínculos ativos, pendentes, inválidos e revogados; histórico; perfis financeiros; auditoria.
- Cobrança posterior com cartão tokenizado, Card on File e indicador MIT Mastercard, condicionada a habilitação e identificadores originais.
- Produção bloqueada por padrão. Sem recorrência automática ou reenvio de cobrança/estorno.
Links de pagamento são outro produto e estão indisponíveis nesta versão. Pix, débito, captura posterior, POS e SGLOC não foram implementados. Ver pendências e matriz de recursos.
Requisitos
WordPress 6.2+ (mínimo adotado, versão instalada não disponível neste repositório), PHP 7.4+ com OpenSSL/AES-256-GCM, JSON e geração aleatória segura; MySQL/MariaDB com InnoDB e GET_LOCK/RELEASE_LOCK na mesma conexão. Sem Composer. Usar versões de runtime com manutenção de segurança antes da produção; as versões CLI locais são apenas as usadas para compatibilidade.
HTTPS é obrigatório no cadastro. Autorizar saída HTTPS para os hosts listados em CIELO.md. A credencial SOP e a credencial E-commerce precisam corresponder ao mesmo estabelecimento e ambiente. O fluxo exige SOP, Cartão Protegido, Consulta BIN e Zero Auth habilitados, além da aprovação do fluxo PCI e de cobranças sem CVV pela adquirente.
Instalação manual
- Revisar código, DDL em
includes/Install.phpe documentação. Fazer backup do banco e guardar a chave criptográfica separadamente. - Copiar a pasta
bv-cieloparawp-content/plugins/bv-cielode um WordPress de homologação. Não copiar sobre o legado. - Configurar segredos fora do repositório, por variáveis de ambiente ou constantes em
wp-config.php(antes do carregamento do WordPress). Exemplo abaixo usa apenas marcadores; substituir no servidor. - Ativar manualmente. A ativação executará
dbDeltapara quatro tabelas com o prefixo WordPress:bvc_charges,bvc_methods,bvc_links,bvc_audit; criará três perfis e atribuirá capabilities ao administrador. Nada disso foi executado pelo desenvolvimento. Não suporta ativação de rede multisite; instalar individualmente por site. - Atribuir perfis em Usuários. Conferir BV Cielo → Configurações. Segredos não aparecem no formulário.
- Executar o roteiro de TESTES.md com dados fictícios. Só liberar cada flag após confirmar o contrato e a homologação correspondente.
// Marcadores: não são credenciais de teste nem valores utilizáveis.
define('BVC_ENCRYPTION_KEY', '<base64 de 32 bytes aleatórios>');
define('BVC_CONSENT_TEXT', '<texto de autorização aprovado pela BV para o contrato exibido>');
define('BVC_CONSENT_VERSION', '<versão aprovada>');
define('BVC_SANDBOX_MERCHANT_ID', '<MerchantId sandbox>');
define('BVC_SANDBOX_MERCHANT_KEY', '<MerchantKey sandbox>');
define('BVC_SANDBOX_SOP_CLIENT_ID', '<ClientId SOP sandbox>');
define('BVC_SANDBOX_SOP_CLIENT_SECRET', '<ClientSecret SOP sandbox>');
// Flags: ausente ou qualquer valor diferente de "yes" mantém bloqueado.
define('BVC_SANDBOX_SOP_ENABLED', 'no');
define('BVC_SANDBOX_ZEROAUTH_ENABLED', 'no');
define('BVC_SANDBOX_MIT_ENABLED', 'no');
define('BVC_SANDBOX_REFUND_ENABLED', 'no');
define('BVC_PRODUCTION_ENABLED', 'no');
Gerar a chave de 32 bytes com gerenciador de segredos ou ferramenta criptográfica local; manter o resultado fora de logs, Git e conversas. Constantes têm precedência sobre variáveis. Para produção, existem os mesmos nomes substituindo SANDBOX por PRODUCTION, mais BVC_PRODUCTION_ENABLED=yes. A tela muda o ambiente somente quando essa liberação existir. Não reutilizar credenciais ou cartões entre ambientes.
Operação
Acesso com login e locações do cliente
Este é o fluxo implementado para homologação/liberação futura. Em 1.1.1, o público recebe o aviso de construção. Para testar internamente a área completa, um responsável pode configurar BVC_PORTAL_ENABLED=yes fora do código apenas em homologação; o botão público do cabeçalho continua mostrando o aviso nesta versão. Não há liberação automática na atualização.
- Atualizar o plugin para 1.1.0 pelo WordPress. Não é preciso reativar, criar tabelas novas ou salvar links permanentes. A rota
/area-do-cliente-bv/fica disponível automaticamente;/?bvc_portal=1é a alternativa por query string. - Abrir BV Cielo → Área do cliente. Copiar o endereço completo mostrado ou usar o QR Code para abrir no celular. Colocar esse endereço no menu público do site se desejar acesso direto. Na Minha conta do WooCommerce, o atalho é adicionado pelo plugin.
- Usar a conta WordPress já existente do cliente. Caso ainda não exista, um administrador pode usar o botão Criar conta de cliente no WordPress e escolher perfil Cliente ou Assinante. O acesso usa login/recuperação de senha do próprio WordPress, preservando autenticação e plugins de segurança existentes. O plugin não cria contas ou dispara e-mails automaticamente.
- Na mesma tela, buscar a conta por nome/e-mail e vincular o contrato confirmado, veículo/grupo, período e situação. Uma cotação pode ser selecionada como referência; ela não é convertida em locação automaticamente. Conferir o titular antes de confirmar. Alterar o mesmo contrato na mesma conta atualiza o vínculo. Remover da visualização preserva histórico financeiro e consentimentos.
- Cliente abre a área, clica Entrar na minha conta e usa suas credenciais. Vê somente locações explicitamente vinculadas à sua conta; não recebe capabilities administrativas. Se ainda não houver vínculo, aparece orientação para contatar a BV.
- Dentro da locação, Cadastrar cartão para este contrato inicia a captura segura já existente. O contrato e titular vêm da sessão e do vínculo no servidor, não de parâmetros livres do navegador. A captura exige Cielo configurada; a consulta de locações e o login funcionam antes disso. Uma nova emissão é permitida a cada 60 segundos por conta.
- Em Meus cartões, cliente acompanha o estado e pode revogar a própria autorização, com confirmação. Em Minhas cobranças consulta apenas suas próprias cobranças em BRL; não pode cobrar, estornar ou consultar dados de outra conta.
Vínculos financeiros antigos com quote:ID não são atribuídos a contas automaticamente nem expostos por semelhança de nome/e-mail. Eles permanecem no administrativo. Novos vínculos de cartão feitos pelo portal usam user:ID, para aparecerem na conta correta.
Cadastro por link ou QR no atendimento
- Atendente identifica o titular e abre Clientes e cartões, busca nome e seleciona usuário ou cotação. Informa o contrato real e gera link. A cotação não comprova reserva nem identidade. Envia o link manualmente ao titular; nenhuma mensagem é enviada pelo plugin. A tela também apresenta QR Code gerado no navegador com o mesmo link de 15 minutos. Exibir somente ao titular; o QR contém o segredo do link e não deve ser compartilhado publicamente. Esse QR individual não exige login, enquanto o QR geral da área do cliente abre o acesso autenticado.
- Cliente abre o link, confere contrato e aceita o texto. Preenche cartão na página isolada, que usa o script oficial SOP para envio à Cielo. O link é consumido uma vez. O servidor verifica o token via Zero Auth. Sem validação positiva e identificadores originais, o vínculo permanece pendente/indisponível.
- Se necessário, financeiro informa o PaymentId de uma CIT original já existente e confirma a vinculação ao contrato; o plugin consulta e exige mesmo CardToken/bandeira e identificadores válidos. Não cria uma CIT financeira para desbloquear o cadastro. Se a resposta não trouxer os dados exigidos, contatar a Cielo.
- Financeiro prepara cobrança com cliente, contrato, cartão, valor, referência única da despesa e justificativa. Revisa os dados persistidos e confirma na tela seguinte. Valores e destinatário são relidos do servidor.
- Em falha ambígua, usar Consultar e conciliar. Nunca criar outra referência de despesa para contornar o bloqueio. Há no máximo uma tentativa financeira por registro; ausência de resultado na consulta não autoriza retry.
- Estorno total exige permissão específica, motivo, confirmação e consulta prévia. A confirmação definitiva vem de nova consulta. Solicitações pendentes não podem ser repetidas por esta versão.
Listagens usam páginas de 50 registros; o seletor de clientes traz até 30 usuários e 30 cotações por busca. Datas e filtros financeiros são UTC, identificados na tela. Perfis: bvc_finance, bvc_attendant, bvc_readonly. A auditoria associa entidade, usuário, data, ação e resultado; detalhes financeiros ficam na cobrança vinculada.
Desativação e rollback
Desativar manualmente remove a execução dos hooks sem apagar registros, perfis, options ou tokens. Não existe desinstalação destrutiva. Interromper novas operações, conciliar pendências e preservar backup/chave antes de restaurar arquivos. Não restaurar um banco antigo e reenviar operações já transmitidas. O restante do site não depende deste plugin.
Documentos: arquitetura, Cielo, segurança, testes, pendências, diagnóstico.