Agente B2B
O serviço b2b é o assistente operacional do lojista no WhatsApp. Ele guia o cadastro e a manutenção de produtos, mantém o rascunho da operação e aciona WooCommerce e recursos de IA somente nos momentos corretos.
Para conhecer as telas e decisões do lojista, consulte a Jornada de Catálogo. Esta página descreve o serviço como unidade técnica da plataforma.
Papel na plataforma
flowchart LR
merchant([Lojista]) --> meta[WhatsApp]
meta --> wpp[WhatsApp Entrypoint]
wpp --> b2b[Agente B2B]
b2b <--> redis[(Redis)]
b2b --> genai[GenAI Wrapper]
b2b --> woo[WooCommerce Wrapper]
b2b --> platform[Frontend Entrypoint]
b2b --> wpp
style merchant fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
style b2b fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
style redis fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
O agente B2B faz
- Navega pelas telas do WhatsApp Flow para criar, alterar ou excluir produtos.
- Mantém o rascunho em Redis até a confirmação do lojista.
- Coordena a revisão de descrição e a melhoria de imagens em mensagens de chat.
- Publica as alterações aprovadas no WooCommerce e comunica o resultado pelo WhatsApp.
O agente B2B não faz
- Descriptografa payloads de Flow ou atende diretamente a API pública da Meta.
- Substitui o WooCommerce como sistema de catálogo.
- Torna uma alteração permanente antes da confirmação explícita no fim da jornada.
Dois caminhos, uma operação
| Caminho | Quando é usado | Característica |
|---|---|---|
| Flow exchange | O lojista navega por formulários, categorias, imagens e revisão de produto. | A resposta precisa ser síncrona para o WhatsApp renderizar a próxima tela. |
| Eventos de conversa | O lojista aprova ou edita conteúdo de IA, escolhe imagem e confirma ações no chat. | O endpoint devolve 202 imediatamente e conclui o trabalho em background. |
flowchart TB
start([Evento do lojista]) --> kind{Tipo de interação}
kind -->|WhatsApp Flow| exchange[Flow exchange]
kind -->|Mensagem ou botão| events[Evento de conversa]
exchange --> draft[(Rascunho no Redis)]
events --> lock[Lock por telefone]
lock --> fsm[FSM e sequência de chat]
fsm --> draft
draft --> approval{Lojista aprovou?}
approval -->|Não| draft
approval -->|Sim| woo[WooCommerce]
woo --> notify[Resposta no WhatsApp]
style start fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
style draft fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
style woo fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#15803d
Contratos internos
Os endpoints abaixo são internos à rede Docker e exigem X-Internal-Key, configurado por B2B_INTERNAL_API_KEY.
| Método | Rota | Consumidor | Uso |
|---|---|---|---|
POST |
/api/v1/events/ |
WhatsApp Entrypoint | Aceita mensagens, botões e respostas finais de Flow; responde 202 e despacha em background. |
POST |
/api/v1/flow-exchange/ |
WhatsApp Entrypoint | Recebe payload do Flow já descriptografado e retorna a próxima tela. |
POST |
/api/v1/admin/invalidate-flow-cache |
Frontend Entrypoint e serviços internos | Descarta o cache local de configuração para que Flow, token e telefone administrativo sejam carregados novamente. |
GET |
/api/v1/health |
Orquestração e diagnóstico | Retorna o estado básico do processo (status: ok). |
GET |
/provisioning-manifest |
Provisionamento interno | Expõe os ativos de Flow que o serviço declara para provisionamento. |
O POST /api/v1/events/ tem ACK rápido para não exceder o tempo da Meta. Falhas posteriores são registradas como Background event dispatch failed; o serviço tenta avisar o lojista com uma mensagem de instabilidade temporária.
Estado e publicação
O Redis mantém o rascunho do produto, a FSM e resultados temporários de IA. Um lock por telefone impede que dois cliques ou reentregas de webhook alterem a mesma operação em paralelo. Com REDIS_LOCK_FAIL_CLOSED=true, ausência do Redis interrompe a operação em vez de permitir concorrência insegura.
| Dependência | Papel | Atenção operacional |
|---|---|---|
| Redis | Rascunho, FSM, resultados temporários e lock da conversa. | Não limpe chaves de um lojista sem confirmar que não há uma edição ativa. |
| WhatsApp Entrypoint | Encaminha eventos e executa mensagens e Flows. | Erros de entrega podem deixar o lojista esperando embora o rascunho exista. |
| GenAI Wrapper | Descrições e melhoria de imagens. | Operações podem ser demoradas; acompanhe logs por telefone e request id. |
| WooCommerce Wrapper | Consulta e publicação de produtos, categorias, variações e mídia. | Valide SKU e dados finais antes da publicação. |
| Frontend Entrypoint | Configuração central, credenciais e ativos ativos de Flow. | Após mudar credenciais ou Flow, invalide o cache de configuração. |
Configuração essencial
| Variável | Finalidade |
|---|---|
B2B_INTERNAL_API_KEY |
Protege eventos, Flow exchange e rotas administrativas internas. |
REDIS_URL |
Armazena estado e lock de cada jornada administrativa. |
WHATSAPP_URL e WPP_API_KEY |
Cliente interno para mensagens, mídia e WhatsApp Flows. |
WOOCOMMERCE_URL e WC_API_KEY |
Catálogo, categorias, mídia, produtos e variações. |
AI_UTILS_URL |
Geração de descrições e processamento de imagens. |
PLATFORM_API_URL e PLATFORM_API_INTERNAL_KEY |
Configuração central, credenciais e dados da loja. |
Diagnóstico rápido
- Confirme
GET /api/v1/healthantes de investigar a jornada. - Se uma tela de Flow não avança, verifique o WhatsApp Entrypoint e depois
POST /api/v1/flow-exchange/no B2B. Essa rota deve responder no próprio ciclo da interação. - Se o chat recebeu
202, mas não houve resultado, procureBackground event dispatch failedcom o telefone do lojista. O ACK confirma somente o recebimento, não a conclusão. - Para um rascunho inconsistente, identifique primeiro a operação e o telefone. Limpar estado Redis encerra a edição em andamento e deve ser a última medida.
- Quando uma troca de credenciais, telefone administrativo ou Flow não aparece, chame a rota de invalidação de cache depois do provisionamento bem-sucedido.
Investigação de publicação
Use telefone do lojista, merchant_id e identificador do produto como trilha de correlação. Eles permitem seguir a operação pelo WhatsApp Entrypoint, B2B, GenAI Wrapper e WooCommerce Wrapper.