Pular para conteúdo

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 ProductDraft permanece 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.