Pular para conteúdo

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.


Papel na Plataforma

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

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