Integrações B2B
O serviço b2b_handler orquestra as operações de administração e catálogo do lojista. Para permitir que uma loja seja gerenciada inteiramente por mensagens e telas no WhatsApp, ele atua como uma ponte entre a Meta, o motor comercial (WooCommerce) e os modelos generativos de IA.
1. Mapa de Integrações do Domínio B2B
flowchart TB
admin[Lojista / Administrador] <--> wpp_entry[WhatsApp Entrypoint]
subgraph CoreB2B ["Domínio B2B & Infraestrutura"]
direction TB
wpp_entry <--> b2b[b2b_handler]
b2b <--> redis[(Redis: Rascunhos & FSM)]
b2b --> pg[(PostgreSQL: Auditoria)]
end
subgraph ServicosInternos ["Serviços Internos Conectados"]
direction TB
b2b <--> genai[GenAI Wrapper]
b2b <--> woo_wrap[WooCommerce Wrapper]
b2b <--> platform_api[Frontend Entrypoint]
end
subgraph Destinos ["Destinos Externos"]
woo_wrap <--> store[(Loja WooCommerce)]
genai <--> minio[(MinIO: Mídias de Produtos)]
genai <--> ai_models[(Provedores de IA)]
end
style admin fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
style wpp_entry fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#15803d
style b2b fill:#e0f2fe,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
style CoreB2B fill:#f8fafc,stroke:#cbd5e1,color:#475569
style ServicosInternos fill:#f8fafc,stroke:#cbd5e1,color:#475569
style Destinos fill:#f8fafc,stroke:#cbd5e1,color:#475569
2. Endpoints Expostos pelo b2b_handler
O b2b_handler expõe dois endpoints principais, chamados exclusivamente pelo whatsapp-entrypoint dentro da rede Docker privada. Ambos exigem o cabeçalho de autenticação X-Internal-Key:
1. POST /api/v1/flow-exchange/
Responsável pela navegação síncrona entre telas do WhatsApp Flow.
* Payload Recebido: Ação executada pelo usuário, tela atual (screen) e os dados preenchidos no formulário (por exemplo, tipo/categoria, campos dinâmicos e fotos anexadas).
* Resposta Esperada: Próxima tela a ser aberta no app e os dados dinâmicos a serem preenchidos (ex: opções de variação disponíveis).
* Tempo de Resposta: Deve ser curto, pois o WhatsApp aguarda a próxima tela no mesmo ciclo da interação. Processamentos de IA e mídia são desacoplados sempre que possível.
2. POST /api/v1/events/
Recebe interações assíncronas que acontecem fora das telas do Flow:
* Mensagens de texto livre: Perguntas, comandos rápidos ou edições de descrição no chat.
* Cliques de botões no chat: "Aprovar Descrição", "Editar Texto", "Melhorar Imagem", "Confirmar Descarte".
* nfm_reply: Evento disparado pela Meta quando o lojista conclui a última tela do Flow e envia os dados.
3. Protocolos de Integração com Serviços Internos
1. Comunicação com genai-wrapper
O B2B consome três capacidades fundamentais da IA:
* Geração de Descrição Comercial / SEO:
O B2B envia o nome do produto, categoria e fotos para o endpoint /llm/chat. A IA responde com texto formatado contendo bullets de benefícios, especificações técnicas e palavras-chave para busca orgânica.
* Tratamento e Upscale de Fotos:
Fotos enviadas pelo WhatsApp sofrem compressão. O pipeline de imagem envia as fotos para remoção de fundo e enquadramento comercial, salvando os arquivos finais no MinIO.
* Configurações por Loja:
O estilo de redação da IA respeita o campo agent_settings.b2b.description_style configurado na tabela platform.merchants.
2. Comunicação com woocommerce-wrapper
Toda persistência de catálogo é delegada ao woocommerce-wrapper, que possui clientes autenticados para a REST API do WooCommerce de cada loja:
* Headers de Contexto: Toda chamada inclui X-Merchant-ID: <uuid> e X-Internal-Key.
* Operações de Escrita:
- POST /products: Criação do produto pai e variações filhas (variations).
- PUT /products/{id}: Atualização de preço regular, promocional e saldo de estoque.
- DELETE /products/{id}: Exclusão com descarte de cache.
* Upload de Imagens: O B2B encaminha as imagens em Base64; o wrapper as persiste no MinIO e fornece URLs no payload de catálogo do WooCommerce.
4. Diagrama de Sequência: Criação de Produto e Sincronização
sequenceDiagram
autonumber
actor Lojista as Lojista (WhatsApp)
participant WPP as WhatsApp Entrypoint
participant B2B as b2b_handler
participant AI as GenAI Wrapper
participant WC as WooCommerce Wrapper
participant VEC as Weaviate (Busca)
Lojista->>WPP: Preenche última tela do Flow e envia
WPP->>B2B: POST /api/v1/events (nfm_reply)
B2B->>B2B: Salva rascunho completo no Redis
B2B->>AI: Solicita geração de descrição comercial
AI-->>B2B: Retorna texto formatado com benefícios e SEO
B2B->>WPP: Envia mensagem no chat com prévia e botões
WPP->>Lojista: Exibe prévia: [Aprovar] ou [Editar Texto]
Lojista->>WPP: Clica em "Aprovar Produto"
WPP->>B2B: Evento BUTTON_CONFIRM_PRODUCT
B2B->>WC: POST /products (dados + imagens do MinIO)
WC-->>B2B: 201 Created (ID do produto gerado)
B2B->>B2B: Descarta rascunho temporário do Redis
B2B->>WPP: Notifica lojista com link do produto ativo
Note over WC,VEC: Sincronização Reversa Automática
WC->>VEC: Webhook indexa novo produto no tenant vetorial
Note over VEC: Produto imediatamente disponível para o B2C!
5. Resiliência e Recuperação de Sessão
- Rascunhos Inacabados (TTL 48h): Se o lojista fechar o aplicativo do WhatsApp durante o preenchimento das telas ou for atender uma ligação, o rascunho
ProductDraftpermanece intacto no Redis por 48 horas. Ao reabrir o Flow, os dados previamente digitados são recuperados. - Degradação Suave da IA: Caso o provedor de IA (OpenAI / Gemini) esteja indisponível ou com latência excessiva, o B2B não impede o cadastro do produto: ele avisa o lojista e utiliza o nome e atributos básicos fornecidos, permitindo que a loja continue operando.
- Isolamento Concorrente: O lock Redis
b2b:lock:{phone}impede que múltiplos eventos simultâneos corrompam o rascunho ou a sequência de imagens.