Pular para conteúdo

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.), o ui_hint atual, 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 o woocommerce-wrapper e o genai-wrapper resolvam as credenciais do lojista no banco merchants-db e 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.