Pular para conteúdo

Agente B2C

O serviço b2c conduz a compra do cliente final pelo WhatsApp. Ele recebe eventos já normalizados pelo WhatsApp Entrypoint, mantém o contexto da conversa e decide a próxima interação: apresentar produtos, ajustar o carrinho, abrir o Flow de endereço ou criar o pedido.

Para entender a experiência do cliente, consulte a Jornada e Máquina de Estados. Esta página explica como manter o serviço em produção.

Papel na plataforma

flowchart LR
    customer([Cliente]) --> meta[WhatsApp]
    meta --> wpp[WhatsApp Entrypoint]
    wpp --> b2c[Agente B2C]
    b2c <--> redis[(Redis)]
    b2c --> genai[GenAI Wrapper]
    b2c --> woo[WooCommerce Wrapper]
    b2c --> platform[Frontend Entrypoint]
    b2c --> wpp
    woo --> payment[WooCommerce / pagamento]

    style customer fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
    style b2c fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
    style redis fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e

É responsabilidade do B2C

  • Interpretar mensagens, botões, carrinho nativo e respostas do Flow de endereço.
  • Orquestrar busca, recomendações e checkout conforme o contexto da conversa.
  • Criar o pedido na loja e entregar ao cliente o caminho de pagamento.
  • Processar o webhook assinado do WooCommerce para atualizar a conversa após o pagamento.

Não é responsabilidade do B2C

  • Receber ou descriptografar webhooks públicos da Meta: essa é a função do WhatsApp Entrypoint.
  • Falar diretamente com Mercado Pago: o pagamento é mediado pelo WooCommerce e seu plugin.
  • Ser a fonte definitiva de catálogo, pedidos ou dados da loja. Esses dados pertencem ao WooCommerce e à plataforma.

Caminhos de processamento

Entrada Processamento Resultado esperado
Mensagem, botão ou pedido nativo O evento é aceito e processado em background pela FSM. O cliente recebe a próxima mensagem, lista de produtos ou ação de carrinho.
Resposta do Flow de endereço O serviço devolve imediatamente a tela ou resposta esperada pelo Flow. Endereço validado e opções de entrega ou frete apresentadas.
Webhook order.updated do WooCommerce A assinatura é validada, o pedido é localizado e a FSM recebe o novo status. Cliente é avisado sobre confirmação, falha ou outro estado terminal do pedido.

Contratos internos e públicos

As rotas de eventos e Flow são internas. Elas exigem X-Internal-Key com o valor configurado em B2C_INTERNAL_API_KEY e devem ser chamadas somente pelo WhatsApp Entrypoint na rede Docker.

Método Rota Consumidor Uso
POST /api/v1/events/ WhatsApp Entrypoint Aceita eventos de conversa e responde 202; o trabalho segue em background.
POST /api/v1/flow-exchange/ WhatsApp Entrypoint Responde de forma síncrona à navegação do Flow de endereço já descriptografado.
POST /internal/products/invalidate/{merchant_id} WooCommerce Wrapper Invalida o cache de produto, opcionalmente de um produto específico.
POST /internal/xml-catalog/invalidate/{merchant_id} WooCommerce Wrapper Invalida o catálogo XML em cache quando configurado.
GET /pay/wc/{merchant_id}/{order_id} Cliente final Redireciona para a URL de pagamento temporária armazenada pelo checkout.
POST /pay/wc-webhook/{merchant_id} WooCommerce Recebe atualizações de pedido; valida X-WC-Webhook-Signature.

As páginas estáticas em /pay/success, /pay/failure e /pay/pending são os retornos visuais do fluxo de pagamento.

Estado, isolamento e dependências

O estado efêmero é separado por loja e telefone no Redis. Ele guarda a FSM, sessão do checkout, endereço, pagamento temporário e locks de processamento. O serviço é configurado para falhar de forma fechada quando o lock Redis não está disponível (REDIS_LOCK_FAIL_CLOSED=true no Compose principal), evitando duas ações concorrentes na mesma compra.

Dependência Por que é necessária Sintoma quando indisponível
Redis Contexto da conversa, checkout e proteção contra concorrência. A conversa não deve avançar; verifique conectividade e TTLs.
WhatsApp Entrypoint Entrada de eventos e saída de mensagens. Não chegam novos eventos ou não há resposta ao cliente.
GenAI Wrapper Intenção, busca semântica e recomendações. Busca ou recomendações podem falhar ou usar caminhos de recuperação.
WooCommerce Wrapper Produtos, frete, pedidos e cache de catálogo. Não é possível concluir catálogo, entrega ou pedido.
Frontend Entrypoint Contexto e credenciais ativas de cada loja. Eventos podem ser rejeitados por loja ausente ou inativa.

Configuração essencial

Variável Finalidade
B2C_INTERNAL_API_KEY Protege os endpoints internos chamados pelo WhatsApp Entrypoint.
REDIS_URL Conexão obrigatória para estado e locks de checkout.
WHATSAPP_URL e WPP_API_KEY Envio de mensagens e ações no WhatsApp.
WOOCOMMERCE_URL e WC_API_KEY Consulta de produtos, frete e pedidos.
AI_UTILS_URL Chamadas ao GenAI Wrapper.
PLATFORM_API_URL e PLATFORM_API_INTERNAL_KEY Resolução do contexto e credenciais da loja.
PUBLIC_BASE_URL Base pública usada nos links de pagamento.

Diagnóstico rápido

  1. Confirme que o container b2c está em execução e que recebe POST /api/v1/events/ com 202.
  2. Para um checkout parado, procure o telefone e o merchant_id nos logs do B2C e do WhatsApp Entrypoint; o segundo mostra se o evento foi encaminhado.
  3. Verifique Redis antes de apagar estado. Chaves de FSM e checkout carregam o contexto da compra; removê-las reinicia a conversa do cliente.
  4. Para falhas após o pedido, confirme o tópico order.updated e a assinatura do webhook no WooCommerce. O B2C rejeita assinatura inválida com 401.
  5. O B2C não expõe uma rota de healthcheck dedicada. O Compose atual verifica disponibilidade pelo processo; use os logs e uma requisição controlada ao serviço para diagnóstico até existir uma rota explícita.

Para investigar uma compra

Correlacione sempre merchant_id, telefone do cliente e order_id. Esses três identificadores conectam o evento de entrada, o estado no Redis, as chamadas ao WooCommerce e o webhook de pagamento.