Integração ACP Sistemas - WordPress Plugin

Plugin WordPress profissional para integração bidirecional com o Sistema ACP. Automatiza a sincronização de produtos, categorias e imagens do ACP para o WordPress, além de capturar e enviar orçamentos do site para o sistema de gestão.

Índice

• Funcionalidades
• Arquitetura e Design de Solução
• Integração com Sistema ACP
• Instalação
• Configuração
• Requisitos e Compatibilidade
• Segurança e Logs
• Suporte e Manutenção
• Changelog

---

Funcionalidades

Sincronização Automática (ACP → WordPress)

O plugin realiza sincronização unidirecional de dados do Sistema ACP para o WordPress:

Produtos

• Importação completa de produtos com todos os atributos
• SKU, nome, descrição e preços
• Quantidade disponível em estoque
• Status de disponibilidade
• Atualização incremental via timestamp (apenas dados modificados)

Categorias Hierárquicas

• Sincronização de linhas de produtos (categorias pai)
• Sincronização de grupos de produtos (subcategorias)
• Manutenção da hierarquia completa
• Associação automática de produtos às categorias corretas

Imagens e Galerias

• Download e importação de imagens principais de produtos
• Criação automática de galerias com múltiplas imagens
• Upload para biblioteca de mídia do WordPress
• Associação correta com produtos

Integração de Orçamentos (WordPress → ACP)

Captura de solicitações de orçamento do site e envio para o Sistema ACP:

Cadastro de Clientes

• Captura de dados do formulário (nome, documento, contatos)
• Criação automática de clientes no sistema ACP
• Validação de dados antes do envio

Envio de Pedidos

• Processamento de carrinho de produtos
• Datas de retirada e devolução
• Informações de entrega e observações
• Integração com formulários WordPress (JetEngine, Contact Form 7, etc.)

Gestão Operacional

Sincronização Agendada

• Execução automática via WP-Cron a cada hora
• Controle de habilitação/desabilitação no painel
• Registro de timestamp da última execução

Sincronização Manual

• Botão de sincronização forçada no painel administrativo
• Útil para testes e atualizações imediatas
• Feedback visual do processo

Sistema de Logs

• Registro detalhado de todas as operações
• Rastreabilidade completa de erros e sucessos
• Arquivos organizados por data
• Máscaramento de informações sensíveis

---

Arquitetura e Design de Solução

Diagrama de Fluxo de Dados

flowchart TB
    ACPSystem[Sistema ACP<br/>API REST]
    WPPlugin[Plugin WordPress]
    WPDatabase[(WordPress Database)]
    WPAdmin[WordPress Admin]
    Frontend[Frontend Website]

    ACPSystem -->|GET: Produtos, Categorias, Imagens| WPPlugin
    WPPlugin -->|POST: Orçamentos, Clientes| ACPSystem
    WPPlugin -->|CRUD Operations| WPDatabase
    WPAdmin -->|Configuração & Sync Manual| WPPlugin
    Frontend -->|Formulário de Orçamento| WPPlugin

    subgraph "Plugin Architecture"
        direction TB
        Scheduler[Schedule Service]
        AppService[Application Service]

        subgraph "Domain Services"
            ProductSvc[Product Service]
            CategorySvc[Category Service]
            ImageSvc[Image Service]
            OrderSvc[Order Service]
        end

        subgraph "Infrastructure"
            APIService[API Service]
            LogHelper[Log Helper]
            SettingHelper[Setting Helper]
        end

        Scheduler --> AppService
        AppService --> ProductSvc
        AppService --> CategorySvc
        AppService --> ImageSvc
        OrderSvc --> APIService
        ProductSvc --> APIService
        CategorySvc --> APIService
        ImageSvc --> APIService
        APIService --> LogHelper
        AppService --> SettingHelper
    end

Arquitetura em Camadas

O plugin segue uma arquitetura modular em camadas bem definidas:

Camada de Apresentação

• Interface administrativa WordPress (Settings Page)
• Formulários de configuração com abas organizadas
• Dashboard de sincronização manual
• Feedback visual e validação de configurações

Camada de Aplicação

• Application Service: Orquestra o fluxo de sincronização
• Coordena a execução sequencial dos serviços de domínio
• Gerencia transações e controle de estado

Camada de Serviços de Domínio

• Product Service: Sincronização de produtos e atributos
• Category Service: Gestão de taxonomias e hierarquias
• Image Service: Download e processamento de imagens
• Order Service: Processamento e envio de orçamentos

Camada de Infraestrutura

• API Service: Comunicação HTTP com sistema ACP
• Log Helper: Sistema de logs estruturado
• Setting Helper: Gerenciamento de configurações
• Admin API: Interface com WordPress Admin API

Padrões de Design Aplicados

Singleton Pattern

Todas as classes de serviço implementam o padrão Singleton, garantindo uma única instância durante a execução:

public static function instance() {
    if (is_null(self::$_instance)) {
        self::$_instance = new self();
    }
    return self::$_instance;
}

Service Layer Pattern

Separação clara de responsabilidades por domínio de negócio, facilitando manutenção e testes.

Configuration Management

Centralização de configurações via WordPress Options API, com helpers dedicados para acesso.

Dependency Injection

Serviços recebem dependências via construtor ou métodos factory, reduzindo acoplamento.

Fluxo de Sincronização

sequenceDiagram
    participant Cron as WP-Cron
    participant Scheduler as Schedule Service
    participant App as Application Service
    participant API as API Service
    participant ACP as Sistema ACP
    participant WP as WordPress DB

    Cron->>Scheduler: Executa (a cada hora)
    Scheduler->>App: sync_data()

    App->>API: get_products(last_timestamp)
    API->>ACP: wsobteritensekits.rule
    ACP-->>API: JSON Response
    API-->>App: Produtos processados
    App->>WP: Salva/Atualiza produtos

    App->>API: get_categories()
    API->>ACP: wsobtermenulinhas.rule
    ACP-->>API: JSON Response
    API-->>App: Categorias processadas
    App->>WP: Salva/Atualiza categorias

    App->>API: get_images(product_ids)
    API->>ACP: wsobterlistaimagens.rule
    ACP-->>API: Lista de imagens
    API->>ACP: wsobterimagem.rule (loop)
    ACP-->>API: Binário da imagem
    API-->>App: URLs locais das imagens
    App->>WP: Associa imagens aos produtos

    App->>WP: Atualiza last_sync_timestamp
    App->>Scheduler: Retorna status

Etapas Detalhadas:

1. Trigger: WP-Cron executa o job agendado a cada hora
2. Orquestração: Application Service coordena a sincronização
3. Consulta Incremental: API Service consulta apenas dados modificados desde o último timestamp
4. Processamento de Categorias: Cria hierarquia de taxonomias (linhas → grupos)
5. Processamento de Produtos: Cria/atualiza custom post types com metadados
6. Download de Imagens: Faz download paralelo e upload para biblioteca de mídia
7. Atualização de Timestamp: Registra data/hora da sincronização para próxima execução
8. Log de Operações: Todas as etapas são registradas para auditoria

---

Integração com Sistema ACP

Requisitos da API ACP

Para estabelecer comunicação com o Sistema ACP, são necessários os seguintes parâmetros:

Parâmetro	Descrição	Exemplo
Host	URL base do servidor ACP (incluindo protocolo e porta)	https://servidor.acp.com.br:8443
Context	Subdomínio ou contexto da API	api ou acp-api
Token	Chave de autenticação da API	abc123def456...
Org	Identificador da organização	001
SYS	Identificador do sistema	WBS (padrão)

Endpoints Utilizados

O plugin consome os seguintes endpoints da API ACP:

Produtos

POST {host}/{context}/wsobteritensekits.rule

Parâmetros:

• org: ID da organização
• token: Token de autenticação
• sys: Sistema (WBS)
• timestamp: Data da última sincronização (formato: dd/MM/yyyy HH:mm:ss)

Resposta: Array de produtos com SKU, nome, descrição, preço, quantidade, status, categoria.

Categorias - Linhas

POST {host}/{context}/wsobtermenulinhas.rule

Parâmetros:

• org: ID da organização
• token: Token de autenticação
• sys: Sistema (WBS)

Resposta: Array de linhas de produtos (categorias pai).

Categorias - Grupos

POST {host}/{context}/wsobtermenulinhasgrupos.rule

Parâmetros:

• org: ID da organização
• token: Token de autenticação
• sys: Sistema (WBS)

Resposta: Array de grupos com referência à linha pai (subcategorias).

Imagens - Lista

POST {host}/{context}/wsobterlistaimagens.rule

Parâmetros:

• org: ID da organização
• token: Token de autenticação
• sys: Sistema (WBS)
• skus: Array de SKUs dos produtos

Resposta: Array com lista de imagens disponíveis por produto.

Imagens - Download

POST {host}/{context}/wsobterimagem.rule

Parâmetros:

• org: ID da organização
• token: Token de autenticação
• sys: Sistema (WBS)
• sku: SKU do produto
• filename: Nome do arquivo de imagem

Resposta: Binário da imagem (JPEG, PNG, etc.).

Orçamentos - Cliente

POST {host}/{context}/wsincluircliente.rule

Parâmetros:

• org: ID da organização
• token: Token de autenticação
• sys: Sistema (WBS)
• nome: Nome do cliente
• documento: CPF/CNPJ
• telefone: Telefone de contato
• email: E-mail

Resposta: ID do cliente criado ou existente.

Orçamentos - Pedido

POST {host}/{context}/wsincluirorcamento.rule

Parâmetros:

• org: ID da organização
• token: Token de autenticação
• sys: Sistema (WBS)
• cliente_id: ID do cliente
• data_retirada: Data de retirada (dd/MM/yyyy)
• data_devolucao: Data de devolução (dd/MM/yyyy)
• endereco: Endereço de entrega
• observacoes: Observações adicionais
• itens: Array de produtos [{sku, quantidade}, ...]

Resposta: ID do orçamento criado no sistema ACP.

Autenticação e Segurança

Autenticação via Token

• Token enviado no corpo de todas as requisições
• Validação no lado do servidor ACP
• Token configurável no painel administrativo do WordPress

Segurança da Comunicação

• Suporte a HTTPS/TLS
• Token nunca exposto em logs (mascarado como abc1****)
• Validação de resposta da API antes de processar
• Tratamento de erros HTTP (timeout, 404, 500, etc.)

Headers HTTP

Content-Type: application/json
Accept: application/json

Exemplo de Requisição

POST https://servidor.acp.com.br:8443/api/wsobteritensekits.rule

{
  "org": "001",
  "token": "abc123def456ghi789",
  "sys": "WBS",
  "timestamp": "01/01/2024 00:00:00"
}

Exemplo de Resposta

{
  "success": true,
  "data": [
    {
      "sku": "PROD001",
      "nome": "Cadeira de Escritório",
      "descricao": "Cadeira ergonômica com apoio lombar",
      "preco": 450.00,
      "quantidade": 15,
      "status": "disponivel",
      "linha": "MOB",
      "grupo": "ESCRITORIO"
    }
  ]
}

---

Instalação

Pré-requisitos

Antes de instalar o plugin, certifique-se de que seu ambiente atende aos requisitos:

• WordPress 3.9 ou superior
• PHP 7.4 ou superior
• Acesso administrativo ao WordPress
• Credenciais de acesso à API do Sistema ACP

Passo a Passo

1. Download do Plugin

Clone o repositório ou baixe o arquivo ZIP:

git clone https://github.com/seu-usuario/acp-system-integration.git

2. Upload para WordPress

Copie a pasta do plugin para o diretório de plugins do WordPress:

cp -r acp-system-integration /var/www/html/wp-content/plugins/

Ou faça upload via painel administrativo:

• Acesse Plugins > Adicionar Novo
• Clique em Fazer Upload do Plugin
• Selecione o arquivo ZIP
• Clique em Instalar Agora

3. Ativação

• Acesse WordPress Admin > Plugins
• Localize Integração - ACP Sistemas
• Clique em Ativar

4. Verificação

Após ativação, você verá um novo item no menu:

• Settings > Integração ACP Sistemas

---

Configuração

O plugin possui um painel administrativo completo com 5 abas de configuração.

Aba 1: API

Configurações de conexão com o Sistema ACP.

Campo	Descrição	Obrigatório	Exemplo
Host	URL do servidor ACP (protocolo + domínio + porta)	Sim	https://acp.empresa.com.br:8443
Context	Subdomínio/contexto da API	Sim	api
Org	Identificador da organização	Sim	001
Token	Token de autenticação da API	Sim	abc123def456...
SYS	Identificador do sistema	Sim	WBS
Executar JOB	Habilitar sincronização automática via cron	Não	☑ Ativado

Notas:

• O token é mascarado na interface após salvar
• Teste a conexão antes de ativar a sincronização automática
• O job será executado a cada hora se habilitado

Aba 2: Categorias

Configuração da taxonomia de categorias de produtos.

Campo	Descrição	Obrigatório	Padrão
Category Taxonomy Slug	Slug da taxonomia customizada para categorias	Sim	product-category

Mapeamento:

• Linhas ACP → Categorias Pai WordPress
• Grupos ACP → Subcategorias WordPress

Exemplo de Hierarquia:

Mobiliário (linha)
  ├─ Escritório (grupo)
  ├─ Residencial (grupo)
  └─ Escolar (grupo)

Aba 3: Produtos

Configuração do post type e campos customizados de produtos.

Campo	Descrição	Obrigatório	Exemplo
Post Type	Slug do custom post type para produtos	Sim	product
Campo: Status	Meta key para status do produto	Sim	_product_status
Campo: SKU	Meta key para código SKU	Sim	_product_sku
Campo: Descrição	Meta key para descrição completa	Sim	_product_description
Campo: Galeria	Meta key para array de IDs de imagens	Sim	_product_gallery
Campo: Quantidade	Meta key para quantidade em estoque	Sim	_product_quantity

Notas:

• Os campos customizados devem estar previamente criados no WordPress
• Recomenda-se usar plugins como ACF ou JetEngine para gerenciar campos
• O SKU é usado como chave única para evitar duplicatas

Aba 4: Orçamento

Configuração de captura de formulários e envio de orçamentos.

Hooks de Formulários

Campo	Descrição	Exemplo
Form Hook	Action hook disparado ao submeter formulário	jet-engine/forms/handler/after-send

Hooks compatíveis:

• JetEngine: jet-engine/forms/handler/after-send
• Contact Form 7: wpcf7_mail_sent
• Gravity Forms: gform_after_submission
• WPForms: wpforms_process_complete

Mapeamento de Campos

Campo	Descrição	Exemplo de Key
Nome	Campo com nome do cliente	nome_cliente
Documento	CPF ou CNPJ	cpf_cnpj
Telefone	Telefone de contato	telefone
Email	E-mail do cliente	email
Data Retirada	Data de retirada do produto	data_retirada
Data Devolução	Data de devolução do produto	data_devolucao
Endereço	Endereço de entrega	endereco_entrega
Observações	Observações adicionais	observacoes
Carrinho	Campo com array de produtos e quantidades	cart_items

Formato esperado do carrinho:

[
    ['sku' => 'PROD001', 'quantidade' => 2],
    ['sku' => 'PROD002', 'quantidade' => 1]
]

Aba 5: Sincronizar

Dashboard de sincronização manual.

Informações Exibidas:

• Data e hora da última sincronização bem-sucedida
• Status do job automático (ativo/inativo)
• Botão para forçar sincronização imediata

Sincronização Manual:

1. Clique em Sincronizar Agora
2. Aguarde o processamento (pode levar alguns minutos)
3. Verifique o resultado na mensagem de feedback
4. Consulte os logs em caso de erro

Importante:

• A sincronização manual não afeta o timestamp do cron
• Use para testes ou correções pontuais
• Evite executar múltiplas sincronizações simultâneas

Salvando Configurações

• Clique em Salvar Configurações ao final de cada aba
• Validação automática de campos obrigatórios
• Mensagens de erro indicam campos ausentes ou inválidos
• Configurações são armazenadas no banco de dados do WordPress (wp_options)

---

Requisitos e Compatibilidade

Requisitos Mínimos

Requisito	Versão/Especificação
WordPress	3.9 ou superior
PHP	7.4 ou superior
MySQL	5.6 ou superior
Extensões PHP	curl, json, gd ou imagick
Permissões	Escrita em wp-content/uploads e wp-content/plugins/acp-system-integration/logs
API ACP	Acesso via HTTP/HTTPS com token válido

Requisitos Recomendados

Requisito	Versão/Especificação
PHP	8.0 ou superior
WordPress	6.0 ou superior
Memória PHP	256 MB ou superior
Tempo de Execução	300 segundos (5 minutos)
WP-Cron	Habilitado (ou cron real do servidor)

Compatibilidade com Plugins

Totalmente Compatível

• ✅ JetEngine (formulários e custom post types)
• ✅ Advanced Custom Fields (ACF)
• ✅ Contact Form 7
• ✅ WPForms
• ✅ Gravity Forms
• ✅ Elementor
• ✅ WooCommerce (coexistência, não integração direta)

Pode Requerer Configuração

• ⚠️ Plugins de cache (desabilitar cache para páginas de orçamento)
• ⚠️ Plugins de segurança (liberar IP do servidor ACP)
• ⚠️ CDN (configurar para servir imagens do upload)

Configuração de Servidor

Apache (.htaccess)

O plugin cria automaticamente um arquivo .htaccess na pasta logs/ para proteger os arquivos de log:

# .htaccess na pasta logs/
Order Deny,Allow
Deny from all

Nginx

Adicione ao seu nginx.conf:

location ~* /wp-content/plugins/acp-system-integration/logs/ {
    deny all;
    return 403;
}

PHP Configuration

Recomendações no php.ini:

max_execution_time = 300
memory_limit = 256M
post_max_size = 32M
upload_max_filesize = 32M

WP-Cron Alternativo

Para melhor performance, desabilite o WP-Cron e configure cron real:

wp-config.php:

define('DISABLE_WP_CRON', true);

Crontab do servidor:

*/60 * * * * wget -q -O - https://seusite.com.br/wp-cron.php?doing_wp_cron > /dev/null 2>&1

---

Segurança e Logs

Práticas de Segurança

Proteção de Dados Sensíveis

• Token de API mascarado na interface (mostra apenas primeiros 4 caracteres)
• Token nunca exposto em logs completos
• Arquivos de log protegidos por .htaccess
• Diretório de logs não navegável via web

Validação de Dados

• Sanitização de todas as entradas de usuário via sanitize_text_field()
• Validação de nonces em todos os formulários admin
• Escapamento de saídas com esc_html(), esc_url(), etc.
• Verificação de capabilities do WordPress antes de operações sensíveis

Segurança de Comunicação

• Suporte a HTTPS/TLS para comunicação com API ACP
• Validação de certificados SSL
• Timeout de requisições (60 segundos por padrão)
• Retry logic para falhas temporárias

Controle de Acesso

• Apenas usuários com capability manage_options podem configurar o plugin
• Formulários protegidos por nonce
• Verificação de permissões em todas as páginas admin

Sistema de Logs

Localização dos Logs

Os logs são armazenados em:

wp-content/plugins/acp-system-integration/logs/

Formato dos Logs

Cada arquivo de log contém entradas no formato:

[2024-04-25 15:30:45] [INFO] Iniciando sincronização de produtos
[2024-04-25 15:30:47] [SUCCESS] 127 produtos sincronizados com sucesso
[2024-04-25 15:30:48] [WARNING] Produto SKU PROD999 sem imagem disponível
[2024-04-25 15:30:50] [ERROR] Falha ao conectar com API ACP: timeout

Níveis de Log

Nível	Descrição	Uso
INFO	Informações gerais de execução	Início/fim de processos
SUCCESS	Operação concluída com sucesso	Sincronizações bem-sucedidas
WARNING	Alertas não críticos	Dados ausentes, fallbacks
ERROR	Erros que impedem operação	Falhas de API, exceções
DEBUG	Informações detalhadas para debug	Payloads, respostas (exceto tokens)

Rotação de Logs

• Logs são organizados por data: sync-2024-04-25.log
• Arquivos antigos podem ser removidos manualmente
• Recomenda-se manter logs dos últimos 30 dias

Máscaramento de Dados Sensíveis

Tokens são automaticamente mascarados nos logs:

Token: abc1**** (mascarado nos logs)
API Response: {"success": true, "data": [...]} (token removido)

Consulta de Logs

Os logs podem ser acessados:

1. Via SFTP/SSH no servidor
2. Via plugin de gerenciamento de arquivos WordPress
3. Diretamente pelo painel admin (se implementado recurso de visualização)

Exemplo de visualização via SSH:

cd wp-content/plugins/acp-system-integration/logs
tail -f sync-$(date +%Y-%m-%d).log

Troubleshooting via Logs

Problema: Sincronização não está funcionando

[ERROR] Job execution failed: API connection timeout

Solução: Verificar conectividade com servidor ACP, firewall, certificados SSL.

Problema: Produtos não aparecem no site

[WARNING] Custom post type 'produto' not registered

Solução: Verificar se o post type está criado e configurado corretamente na aba Produtos.

Problema: Imagens não são importadas

[ERROR] Image download failed for SKU PROD001: HTTP 404

Solução: Verificar se o produto possui imagens cadastradas no sistema ACP.

---

Suporte e Manutenção

Informações do Plugin

• Nome: Integração ACP Sistemas
• Versão: 1.0.0
• Autor: Marcelo Zanatta
• Licença: GPLv2 or later
• Licença URI: http://www.gnu.org/licenses/gpl-2.0.html
• Text Domain: acp-system-integration
• Requires WordPress: 3.9+
• Requires PHP: 7.4+

Perguntas Frequentes (FAQ)

1. O plugin funciona com qualquer tema WordPress?

Sim, o plugin é independente de tema. Ele trabalha com custom post types e taxonomias padrão do WordPress.

2. Posso desabilitar a sincronização automática?

Sim, desmarque a opção "Executar JOB" na aba API do painel de configurações.

3. Como faço para sincronizar apenas algumas categorias?

Atualmente o plugin sincroniza todas as categorias disponíveis na API ACP. Filtros customizados podem ser implementados por desenvolvedores.

4. O plugin funciona com WooCommerce?

O plugin não integra diretamente com WooCommerce, mas pode coexistir. Para usar produtos do WooCommerce, configure o Post Type como product e ajuste os campos customizados.

5. O que acontece se a API ACP ficar offline?

O plugin registra o erro nos logs e tenta novamente na próxima execução do cron. Nenhum dado é perdido no WordPress.

6. Posso usar em múltiplos sites WordPress?

Sim, cada instalação precisa de sua própria configuração de API (token, org, etc.).

Licença

Este plugin é software livre; você pode redistribuí-lo e/ou modificá-lo sob os termos da GNU General Public License conforme publicada pela Free Software Foundation; tanto a versão 2 da Licença, ou (a seu critério) qualquer versão posterior.

Este plugin é distribuído na esperança de que seja útil, mas SEM QUALQUER GARANTIA; mesmo sem a garantia implícita de COMERCIALIZAÇÃO ou ADEQUAÇÃO A UM DETERMINADO PROPÓSITO. Veja a GNU General Public License para mais detalhes.

---

Changelog

1.0.0 - 2023-11-12

Initial Release

• ✨ Sincronização automática de produtos via WP-Cron
• ✨ Sincronização de categorias hierárquicas (linhas e grupos)
• ✨ Download e importação de imagens e galerias
• ✨ Captura e envio de formulários de orçamento
• ✨ Cadastro automático de clientes no sistema ACP
• ✨ Painel administrativo completo com 5 abas de configuração
• ✨ Sistema de logs estruturado com níveis (INFO, SUCCESS, WARNING, ERROR)
• ✨ Sincronização manual via botão no dashboard
• ✨ Sincronização incremental via timestamp
• ✨ Proteção de dados sensíveis (máscaramento de tokens)
• ✨ Validação de nonces e sanitização de dados
• ✨ Compatibilidade com formulários JetEngine, Contact Form 7, Gravity Forms
• ✨ Suporte a custom post types e taxonomias customizadas
• 🔒 Proteção de diretório de logs via .htaccess
• 📚 Documentação completa no README.md

---