WooContaAzul - Integração WooCommerce com Conta Azul

Plugin WordPress/WooCommerce para integração automática com a API do Conta Azul. Envia automaticamente pedidos pagos para o sistema ERP Conta Azul.

Desenvolvido por: Daniel Paz | WebOption

📋 Funcionalidades

• ✅ Autenticação OAuth 2.0 com Conta Azul
• ✅ Envio automático de pedidos pagos para o Conta Azul
• ✅ Envio manual de pedidos via admin
• ✅ Renovação automática de access tokens
• ✅ Mapeamento completo de clientes, produtos e vendas
• ✅ Suporte a diferentes métodos de pagamento
• ✅ Log de erros e debug
• ✅ Painel administrativo completo
• ✅ Visualização de status de envio na lista de pedidos

📦 Requisitos

• WordPress 5.8 ou superior
• WooCommerce 5.0 ou superior
• PHP 7.4 ou superior
• Conta no Conta Azul
• Credenciais de API (Client ID e Client Secret)

🚀 Instalação

1. Faça upload da pasta woocontaazul para o diretório /wp-content/plugins/
2. Ative o plugin através do menu 'Plugins' no WordPress
3. Acesse Conta Azul no menu do WordPress
4. Configure suas credenciais da API

⚙️ Configuração

1. Obter Credenciais da API

1. Acesse o Portal de Desenvolvedores do Conta Azul
2. Crie uma nova aplicação
3. Anote o Client ID e Client Secret

2. Configurar o Plugin

1. No WordPress, vá em Conta Azul > Configurações
2. Insira o Client ID e Client Secret
3. Salve as configurações
4. Clique em "Conectar com Conta Azul"
5. Faça login na sua conta do Conta Azul
6. Autorize a aplicação
7. Você será redirecionado de volta ao WordPress

📖 Como Usar

Envio Automático

1. Ative a opção "Envio Automático" nas configurações
2. Quando um pedido for marcado como "Processando" ou "Concluído" e estiver pago, será automaticamente enviado para o Conta Azul

Envio Manual

1. Abra um pedido no WooCommerce
2. Procure pelo box "Conta Azul" na lateral direita
3. Clique em "Enviar para Conta Azul"

Visualizar Status de Envio

• Lista de Pedidos: Uma coluna "Conta Azul" mostra o status com ícones

  • ✓ Verde = Enviado com sucesso
  • ⚠ Vermelho = Erro no envio
  • ● Laranja = Processando
  • — Cinza = Não enviado

• Detalhes do Pedido: O box "Conta Azul" mostra informações detalhadas incluindo:

  • Status do envio
  • ID da venda no Conta Azul
  • Data e hora do envio
  • Mensagens de erro (se houver)

Visualizar Logs

1. Vá em Conta Azul > Logs
2. Visualize todos os pedidos enviados e seus status

🔧 Configurações Avançadas

Modo Debug

Ative o Modo Debug nas configurações para registrar logs detalhados no arquivo wp-content/debug.log:

1. Ative o modo debug nas configurações do plugin
2. Certifique-se de que o WP_DEBUG_LOG está ativado no wp-config.php:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

🗺️ Mapeamento de Dados

Cliente (Customer)

O plugin mapeia automaticamente os dados do cliente do WooCommerce para o Conta Azul:

• Nome completo
• Email
• Telefone
• CPF/CNPJ (se disponível via plugins de campos extras)
• Endereço completo

Produtos (Products)

Cada item do pedido é enviado com:

• Descrição (nome do produto)
• Quantidade
• Preço unitário
• Valor total

Pagamento (Payment)

O plugin mapeia métodos de pagamento comuns:

• Transferência bancária → BANK_CHECK
• Cheque → CHECK
• Dinheiro na entrega → CASH
• PayPal → CASH
• Stripe → CREDIT_CARD

Descontos e Frete

• Descontos de cupons são enviados automaticamente
• Valor do frete é incluído quando aplicável

🔄 Fluxo de Autenticação OAuth 2.0

O plugin implementa o fluxo completo de OAuth 2.0:

1. Autorização: Usuário faz login no Conta Azul e autoriza a aplicação
2. Exchange: O código de autorização é trocado por access_token e refresh_token
3. Uso: O access_token é usado em todas as requisições à API
4. Renovação: Quando o access_token expira, o refresh_token é usado automaticamente para obter um novo

🐛 Solução de Problemas

Erro: "Client ID e Client Secret são obrigatórios"

• Certifique-se de ter inserido as credenciais corretas nas configurações
• Salve as configurações antes de tentar conectar

Erro: "Refresh token não encontrado"

• Faça a autorização novamente clicando em "Conectar com Conta Azul"
• Verifique se suas credenciais estão corretas

Pedidos não estão sendo enviados automaticamente

• Verifique se a opção "Envio Automático" está ativada
• Certifique-se de que o pedido está marcado como pago
• Verifique se você está conectado ao Conta Azul
• Ative o modo debug e verifique os logs

Erro na API

• Teste a conexão clicando em "Testar Conexão" nas configurações
• Verifique se suas credenciais estão corretas e ativas
• Certifique-se de que sua conta no Conta Azul está ativa

📝 Estrutura de Arquivos

woocontaazul/
├── woocontaazul.php                 # Arquivo principal do plugin
├── README.md                        # Este arquivo
├── .htaccess                        # Proteção de arquivos
├── includes/
│   ├── class-wca-oauth.php         # Gerencia autenticação OAuth 2.0
│   ├── class-wca-api.php           # Comunicação com API do Conta Azul
│   ├── class-wca-woocommerce.php   # Integração com WooCommerce
│   ├── class-wca-admin.php         # Interface administrativa
│   └── index.php                    # Proteção de diretório
└── assets/
    ├── css/
    │   ├── admin.css                # Estilos do admin
    │   └── index.php                # Proteção de diretório
    └── js/
        ├── admin.js                 # JavaScript do admin
        └── index.php                # Proteção de diretório

🔗 Links Úteis

• Documentação da API Conta Azul
• Portal de Desenvolvedores
• Referência da API v2

📄 Licença

Este plugin é software livre licenciado sob GPL v2 ou posterior.

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

1. Faça um Fork do projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

🔒 Segurança

Práticas de Segurança Implementadas

• ✅ Verificação de nonces em todos os formulários e requisições AJAX
• ✅ Sanitização de todos os inputs do usuário
• ✅ Escapamento de todos os outputs
• ✅ Verificação de capacidades/permissões de usuário
• ✅ Proteção contra acesso direto aos arquivos
• ✅ Proteção de diretórios com index.php
• ✅ .htaccess para proteção adicional
• ✅ Validação rigorosa de dados antes de salvar
• ✅ Tokens OAuth armazenados com segurança
• ✅ Logs sensíveis apenas em modo debug

Reportar Vulnerabilidades

Se você descobrir uma vulnerabilidade de segurança, por favor envie um email para suporte@weboption.com.br ao invés de abrir uma issue pública.

🆘 Suporte

• Website: WebOption
• Email: contato@weboption.com.br
• Desenvolvedor: Daniel Paz

📋 Changelog

1.0.0 - 2026-01-25

• ✨ Versão inicial
• ✅ Implementação completa de OAuth 2.0
• ✅ Envio automático de pedidos pagos
• ✅ Interface administrativa completa
• ✅ Sistema de logs
• ✅ Suporte a renovação automática de tokens
• ✅ Ambientes separados (Homologação e Produção)
• ✅ Melhorias de segurança
• ✅ Plugin renomeado para WooContaAzul

Desenvolvido com ❤️ por Daniel Paz - WebOption

Para a comunidade WordPress/WooCommerce

Hooks Disponíveis

Actions

• wcca_before_send_order - Disparado antes de enviar um pedido
• wcca_after_send_order - Disparado após enviar um pedido com sucesso
• wcca_send_order_error - Disparado quando há erro ao enviar um pedido

Filters

• wcca_sale_data - Permite modificar os dados da venda antes de enviar
• wcca_customer_data - Permite modificar os dados do cliente antes de enviar
• wcca_payment_type - Permite personalizar o tipo de pagamento

Exemplo de Uso de Hooks

// Modificar dados da venda antes de enviar
add_filter('wcca_sale_data', function($sale_data, $order) {
    // Adicionar campo personalizado
    $sale_data['custom_field'] = 'valor';
    return $sale_data;
}, 10, 2);

// Executar ação após envio bem-sucedido
add_action('wcca_after_send_order', function($order_id, $result) {
    // Seu código aqui
    error_log('Pedido ' . $order_id . ' enviado com sucesso!');
}, 10, 2);

📋 Changelog

1.0.0 - 2026-01-25

• Versão inicial
• Implementação completa de OAuth 2.0
• Envio automático de pedidos pagos
• Interface administrativa
• Sistema de logs
• Suporte a renovação automática de tokens