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
- Confirme que o container
b2cestá em execução e que recebePOST /api/v1/events/com202. - Para um checkout parado, procure o telefone e o
merchant_idnos logs do B2C e do WhatsApp Entrypoint; o segundo mostra se o evento foi encaminhado. - Verifique Redis antes de apagar estado. Chaves de FSM e checkout carregam o contexto da compra; removê-las reinicia a conversa do cliente.
- Para falhas após o pedido, confirme o tópico
order.updatede a assinatura do webhook no WooCommerce. O B2C rejeita assinatura inválida com401. - 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.