WooCommerce Wrapper
O woocommerce-wrapper é o serviço responsável por toda a comunicação entre a plataforma e as lojas virtuais dos lojistas rodando sobre WordPress / WooCommerce. Ele funciona como um agregador de infraestrutura: em vez de integrar separadamente com cada gateway de pagamento ou transportadora, a plataforma aproveita as integrações já configuradas na loja do lojista (notadamente Mercado Pago para pagamentos e Melhor Envio para cálculo de frete).
O serviço é multi-tenant dinâmico: as credenciais de cada loja (consumer_key, consumer_secret e URL base) não ficam em variáveis de ambiente, sendo recuperadas sob demanda através do frontend-entrypoint.
flowchart LR
b2c[Agente B2C] -->|Frete, Link de Pagamento & Pedidos| woo[WooCommerce Wrapper]
b2b[Agente B2B] -->|Cadastro de Produtos & Fotos| woo
woo -->|Store API /v1| store[Store API / Plugins]
woo -->|REST Admin API /v3| admin[WooCommerce REST API]
woo -->|Upload de Fotos| minio[(MinIO / S3)]
woo -->|Indexação de Vetores| ai[GenAI Wrapper]
woo -.->|Egress Proxy Opcional| cf[Cloudflare Worker]
cf -.-> admin
store --> mp[Mercado Pago]
store --> me[Melhor Envio]
style woo fill:#f0f9ff,stroke:#0284c7,stroke-width:2px,color:#0369a1
style minio fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
style ai fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#166534
style admin fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
style store fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
style mp fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
style me fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
style b2c fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
style b2b fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
Limites de Responsabilidade
| É responsabilidade do WooCommerce Wrapper |
NÃO é responsabilidade do Wrapper |
| Simular frete com endereço real através do carrinho de checkout da Store API. |
Conduzir a conversa no WhatsApp ou orquestrar FSM de vendas. |
| Gerar links oficiais de pagamento do Mercado Pago delegados ao plugin da loja. |
Guardar cópia do cartão de crédito ou dados de faturamento. |
| CRUD completo de produtos, variações, atributos e categorias no WooCommerce. |
Gerar descrições ou melhorar imagens com IA (delega ao GenAI Wrapper). |
Enviar imagens de produtos para o bucket MinIO e registrar em product_image_sync. |
Receber webhooks públicos diretos da Meta. |
| Provisionar automaticamente os webhooks de pedidos e produtos nas lojas conectadas. |
Ser a fonte de verdade das conversas (pertence ao PostgreSQL/Redis). |
| Solicitar indexação vetorial e invalidar caches de produtos no Agente B2C. |
|
Duas APIs do WooCommerce: Admin vs Store API
Uma das principais decisões arquiteturais deste módulo é a divisão em dois clientes HTTP especializados:
flowchart TD
subgraph AdminClient [wc_admin.py - REST API v3]
direction TB
adm1[Autenticado via consumer_key / secret]
adm2[CRUD de Produtos, Categorias e Variações]
adm3[Criação de Pedidos e Consulta Administrativa]
adm4[Provisionamento de Webhooks na Loja]
end
subgraph StoreClient [wc_store.py - Store API v1]
direction TB
sto1[Pública / Sessão de Carrinho Guest]
sto2[Simula checkout exatamente como cliente final]
sto3[Calcula opções de frete via plugin Melhor Envio]
sto4[Gera link de pagamento via plugin Mercado Pago]
end
| Característica |
wc_admin.py (REST API wc/v3) |
wc_store.py (Store API wc/store/v1) |
| Autenticação |
HMAC com consumer_key e consumer_secret. |
Pública via cabeçalhos de sessão de carrinho efêmero. |
| Objetivo |
Gestão de dados estruturados e catálogo da loja. |
Reprodução fiel do checkout real da loja e seus plugins. |
| Vantagem |
Controle total de atributos, mídias e metadados. |
Elimina necessidade de credenciais avulsas de frete/pagamento. |
Pipeline de Catálogo e Mídias
Quando um produto é cadastrado no Agente B2B ou sincronizado da loja, o wrapper coordena a persistência e atualização nos sistemas satélites:
sequenceDiagram
autonumber
participant B2B as Agente B2B
participant Wrapper as WooCommerce Wrapper
participant MinIO as MinIO Storage
participant WC as Loja WooCommerce
participant AI as GenAI Wrapper
participant B2C as Agente B2C
B2B->>Wrapper: POST /products/ (dados + foto)
Wrapper->>MinIO: Upload da foto no bucket público
Wrapper->>WC: POST /wp-json/wc/v3/products (com URL da foto)
Wrapper->>AI: POST /vector/index (atualiza Weaviate)
Wrapper->>B2C: POST /internal/products/invalidate/{merchant_id}
Wrapper-->>B2B: Produto criado com ID WooCommerce
Contratos de API Internos
Todas as rotas exigem o cabeçalho X-Internal-Key com o valor de WC_API_KEY:
Produtos e Catálogo (/products/)
| Método |
Rota |
Consumidor |
O que faz |
POST |
/products/ |
Agente B2B |
Cria produto simples ou com variações no WooCommerce. |
PUT |
/products/{product_id} |
Agente B2B |
Atualiza dados, preços ou estoque de um produto existente. |
DELETE |
/products/{product_id} |
Agente B2B |
Remove produto e aciona remoção correspondente no Weaviate. |
GET |
/products/{product_id} |
Agentes |
Busca detalhes completos do produto direto no WordPress. |
GET |
/products/categories |
Agente B2B |
Lista categorias cadastradas na loja do lojista. |
Frete e Pagamento (/shipping/ & /payments/)
| Método |
Rota |
Consumidor |
O que faz |
POST |
/shipping/calculate |
Agente B2C |
Adiciona itens ao carrinho guest na Store API e retorna cotações de frete. |
POST |
/payments/checkout-link |
Agente B2C |
Cria ordem e gera link de pagamento temporário do Mercado Pago. |
Operações Administrativas & Sincronização
| Método |
Rota |
O que faz |
POST |
/merchants/{merchant_id}/full-sync |
Força sincronização completa do catálogo da loja para a plataforma. |
POST |
/merchants/{merchant_id}/product-images/backfill |
Envia imagens pendentes da loja para o MinIO em background. |
POST |
/merchants/{merchant_id}/import-catalog |
Reimporta categorias e atributos no banco de dados local. |
POST |
/merchants/{merchant_id}/setup-webhooks |
Registra os webhooks de notificação na loja WooCommerce. |
GET |
/diagnostics/woocommerce |
Healthcheck de conectividade com a loja, Melhor Envio e Mercado Pago. |
Configuração Essencial
| Variável |
Descrição |
WC_API_KEY |
Chave de segurança para chamadas internas da rede Docker. |
PLATFORM_API_URL |
URL do serviço para obter URL e credenciais do WooCommerce por lojista. |
PLATFORM_API_INTERNAL_KEY |
Chave de autorização no Platform API. |
MINIO_ENDPOINT |
Host e porta do MinIO para armazenamento de fotos (ex: minio:9000). |
MINIO_ACCESS_KEY / SECRET_KEY |
Credenciais administrativas do bucket S3. |
MINIO_BUCKET |
Nome do bucket público de mídias de produtos (ex: ecomsmart-products). |
MEDIA_PUBLIC_BASE_URL |
URL pública pela qual o WordPress consegue baixar as fotos salvas no MinIO. |
EGRESS_PROXY_URL |
(Opcional) URL de Cloudflare Worker para contornar bloqueios de IP de hospedagens. |
EGRESS_PROXY_SECRET |
(Opcional) Token de autenticação no Cloudflare Worker de saída. |
Diagnóstico Rápido
- Erro de autenticação no WooCommerce (401/403): As credenciais do lojista são salvas no banco da plataforma. Verifique se o lojista não revogou as chaves de API no painel do WordPress (
WooCommerce > Configurações > Avançado > REST API).
- Cálculo de frete falhando: O cálculo depende do plugin Melhor Envio instalado e configurado na loja WooCommerce com token válido e dimensões cadastradas nos produtos (peso, altura, largura, comprimento).
- Imagens não aparecem no WordPress: Verifique a variável
MEDIA_PUBLIC_BASE_URL. O WordPress precisa ter acesso HTTP/HTTPS público à URL onde as fotos foram persistidas no MinIO.
- Hospedagem do lojista bloqueando requisições: Muitas hospedagens compartilhadas (Hostinger, Locaweb, etc.) bloqueiam chamadas diretas de IPs de data center (Hetzner, AWS). Nesse caso, ative o
EGRESS_PROXY_URL para que o tráfego saia pelos IPs residuais da Cloudflare.