WP Manifestindependent plugin directory
manifest / ecommerce / bv-cielo

BV Cielo

Plugin WordPress financeiro da BV Locadora: integração Cielo e atualizações via GitHub Releases.

★ 0stars

Install

Download source zip No release zip yet

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.zip
Updates itself. It ships its own updater (Plugin Update Checker), so new versions appear under Dashboard → Updates.

Plugin 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

  1. Revisar código, DDL em includes/Install.php e documentação. Fazer backup do banco e guardar a chave criptográfica separadamente.
  2. Copiar a pasta bv-cielo para wp-content/plugins/bv-cielo de um WordPress de homologação. Não copiar sobre o legado.
  3. 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.
  4. Ativar manualmente. A ativação executará dbDelta para 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.
  5. Atribuir perfis em Usuários. Conferir BV Cielo → Configurações. Segredos não aparecem no formulário.
  6. 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.

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.