Integrações B2C
O Agente B2C atua como um maestro na jornada de vendas: ele não mantém catálogo próprio, não processa pagamentos e não conecta diretamente à Meta. Em vez disso, ele orquestra serviços especializados dentro e fora da plataforma.
Esta página apresenta o mapa dessas integrações, o papel de cada serviço parceiro e como falhas são tratadas de forma transparente.
1. Mapa de Conexões do Agente B2C
flowchart TB
customer[Cliente no WhatsApp] <--> wpp_entry[WhatsApp Entrypoint]
subgraph Core["Plataforma EcomSmart"]
wpp_entry <--> b2c[Agente B2C]
b2c <--> ai[GenAI Wrapper]
b2c <--> woo_wrap[WooCommerce Wrapper]
b2c <--> redis[(Redis: Sessões e FSM)]
b2c --> pg[(PostgreSQL: Histórico)]
end
subgraph External["Serviços Externos"]
woo_wrap <--> store[(Loja WooCommerce)]
ai <--> weaviate[(Weaviate: Catálogo Vetorial)]
b2c -.-> viacep[ViaCEP: Consulta de Endereço]
end
style b2c fill:#e0f2fe,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
style wpp_entry fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#15803d
style Core fill:#f8fafc,stroke:#cbd5e1,color:#475569
style External fill:#f8fafc,stroke:#cbd5e1,color:#475569
2. As 4 Integrações Principais
1. WhatsApp Entrypoint (Canais e Formulários Nativos)
O whatsapp-entrypoint é o canal exclusivo de entrada e saída de mensagens entre a Meta e o Agente B2C.
* Mensagens interativas: Envio de botões de ação rápida (ex: "Ver Carrinho"), menus de lista e cards de produtos com foto e preço.
* WhatsApp Flows (coleta_endereco_v2): Quando o cliente chega no checkout, o agente dispara um formulário nativo na tela do WhatsApp. O cliente preenche CEP, rua, número e complemento em uma interface visual fluida, sem precisar responder perguntas repetitivas no chat.
2. WooCommerce Wrapper (Motor Comercial)
O woocommerce-wrapper é a ponte segura com o e-commerce do lojista:
* Catálogo e variações: Consulta de estoque, fotos, descrições e variações (ex: tamanho P/M/G ou voltagem).
* Cálculo de frete: O agente envia o CEP e o carrinho para simular as modalidades de entrega disponíveis na loja (ex: Correios, Jadlog, Motoboy local).
* Criação de pedidos: Quando o cliente escolhe a forma de entrega, o agente cria o pedido oficial no WooCommerce com status pending.
3. GenAI Wrapper (Inteligência e Descoberta)
O genai-wrapper garante que o cliente encontre o que deseja mesmo usando linguagem coloquial:
* Roteamento de Intenção (/intent): Analisa a mensagem para classificar se o cliente quer comprar, tirar dúvidas de entrega ou falar com atendimento humano.
* Busca Semântica Vetorial: Conecta-se à base de produtos no Weaviate. Se o cliente pesquisar "tênis para correr no asfalto", o modelo encontra os calçados certos mesmo que a palavra "asfalto" não esteja no título.
* Recomendações e Cross-selling: Analisa os itens do carrinho para sugerir complementos inteligentes antes da conclusão da compra.
4. Persistência e Memória (Redis & PostgreSQL)
- Redis: Mantém o estado da FSM (
IDLE,DISCOVERING, etc.), oui_hintatual, o carrinho em montagem e os dados temporários do formulário de endereço com expiração automática (TTL). - PostgreSQL: Registra cada mensagem enviada e recebida (
platform.b2c_messages) e consolida as métricas da sessão de conversa (platform.b2c_conversation_sessions) para o painel do lojista.
3. Fluxo de Integração em Uma Compra
O diagrama de sequência abaixo ilustra a cooperação entre os componentes durante o processo de compra:
sequenceDiagram
autonumber
actor Cliente as Cliente (WhatsApp)
participant WPP as WhatsApp Entrypoint
participant B2C as Agente B2C
participant AI as GenAI Wrapper
participant WC as WooCommerce Wrapper
Cliente->>WPP: "Quero ver tênis esportivo"
WPP->>B2C: Evento de mensagem (texto)
B2C->>AI: Busca semântica ("tênis esportivo")
AI-->>B2C: IDs dos produtos mais relevantes
B2C->>WC: Detalhes, preços e fotos dos produtos
WC-->>B2C: Dados atualizados de estoque e valor
B2C->>WPP: Envia carrossel/lista de produtos
WPP->>Cliente: Exibe opções de tênis
Cliente->>WPP: Toca em "Comprar" (seleciona item)
WPP->>B2C: Evento de produto selecionado
B2C->>B2C: Atualiza carrinho no Redis
B2C->>WPP: Dispara WhatsApp Flow de Endereço
WPP->>Cliente: Abre tela de endereço
Cliente->>WPP: Envia endereço preenchido
WPP->>B2C: Payload do Flow de endereço
B2C->>WC: Simula frete para o CEP informado
WC-->>B2C: Opções: PAC (R$ 15), Sedex (R$ 28)
B2C->>WPP: Envia botões para escolha de frete
WPP->>Cliente: Exibe opções de entrega
4. Tratamento de Falhas e Tolerância
| Ponto de Falha | O que o Agente B2C faz | O que o cliente percebe |
|---|---|---|
| Instabilidade no WooCommerce | Mantém os itens do carrinho seguros no Redis e avisa que está reconectando com o sistema da loja. | O carrinho não é perdido e a tentativa é retomada automaticamente. |
5. Contratos HTTP e Especificação de Endpoints
Para os desenvolvedores que forem estender ou auditar as integrações do B2C, os contratos internos seguem convenções padronizadas:
1. Headers HTTP Obrigatórios
Todas as requisições disparadas pelo B2C para serviços internos da rede Docker exigem cabeçalhos de contexto e autorização:
X-Merchant-ID: 7a8f9c12-3b45-4e67-8901-234567890abc
X-Internal-Key: <chave-secreta-interna-definida-em-env>
X-API-Key: <chave-da-api-do-lojista>
Content-Type: application/json
X-Merchant-ID: OBRIGATÓRIO. Permite que owoocommerce-wrappere ogenai-wrapperresolvam as credenciais do lojista no bancomerchants-dbe isolem a busca no tenant correspondente do Weaviate.X-Internal-Key: Impede que requisições não autorizadas da rede chamem endpoints restritos.
2. Endpoints Internos Consumidos pelo B2C
[b2c_handler]
│
├──► woocommerce_wrapper
│ ├── GET /api/v1/products/{id} (Detalhes e variações de produto)
│ ├── POST /api/v1/shipping/calculate (Simulação de frete com regras e CEP)
│ ├── POST /api/v1/orders (Criação de pedido em status pending)
│ └── GET /api/v1/orders/{id}/payment (Consulta status e chave Pix)
│
├──► genai_wrapper
│ ├── POST /intent (Identificação de intenção do cliente)
│ ├── POST /vector/search (Busca semântica no tenant da loja)
│ └── POST /recommend/checkout (Recomendação de itens complementares)
│
└──► whatsapp_entrypoint
├── POST /api/v1/messages/send (Texto, botões e listas interativas)
└── POST /api/v1/flows/send (Disparo de tela do WhatsApp Flow)
3. Processamento Assíncrono com conversation-outcome-worker
Para não travar a resposta dos webhooks da Meta, quando uma conversa é concluída ou abandonada:
1. O b2c_handler grava o evento de encerramento no Redis.
2. O serviço em segundo plano conversation-outcome-worker consome o evento e consolida métricas, tempo de atendimento e faturamento na tabela platform.b2c_conversation_sessions no PostgreSQL de forma totalmente assíncrona.