Pular para conteúdo

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

  1. Confirme GET /api/v1/health antes de investigar a jornada.
  2. 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.
  3. Se o chat recebeu 202, mas não houve resultado, procure Background event dispatch failed com o telefone do lojista. O ACK confirma somente o recebimento, não a conclusão.
  4. 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.
  5. 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.