O EcomSmart Agents dentro da loja de cada lojista.
Um app por plataforma, publicado na loja de aplicativos de cada uma, para o lojista instalar, conectar o WhatsApp oficial e ligar os agentes sem falar com vendedor. Cada plataforma é um projeto com responsável, fases, especificação e andamento próprios.
Objetivo
Vender o EcomSmart Agents para lojas de R$ 30 mil a R$ 300 mil por mês pelo canal onde elas já procuram ferramenta: a loja de apps da própria plataforma. O app instala em minutos, puxa o histórico de clientes e pedidos, monta o RFV e liga os agentes no WhatsApp oficial do lojista. É o canal de aquisição sem mídia do plano da EcomSmart.
Projetos
O percentual conta as tarefas de cada fase (feita vale 1, em andamento vale meia). Clique no projeto para descer até as fases, a especificação técnica, os dados por agente e os riscos.
- Tarefas
- 1 de 31 feitas
- Fase atual
- Preparação até 04/10
- Próxima entrega
- Conta no Portal de Parceiros Nuvemshop com e-mail @ecomsmart.com.br
- Tarefas
- 1 de 27 feitas
- Fase atual
- Preparação até 11/10
- Próxima entrega
- Conta de parceiro Shopify e taxa única de registro para publicar (US$ 19)
Bling (ERP)
Previsto para janeiro de 2027, sem responsável. Cobre Tray, WooCommerce e marketplaces de uma vez.
Ordem das plataformas
Critério: quantas lojas acima de R$ 30 mil por mês cada plataforma tem, se a loja de apps traz instalação sozinha e quanto o lojista está acostumado a pagar por app.
| # | Plataforma | Tipo | Responsável | Quando | Por que |
|---|---|---|---|---|---|
| 1 | Nuvemshop | Plataforma | FBFelipe Barros | Publicação em 15/12/2026 | Maior base de lojas pequenas e médias do Brasil, com muita loja acima de R$ 30 mil por mês. A loja de apps tem tráfego próprio: o lojista procura, instala e paga sem falar com vendedor. |
| 2 | Shopify | Plataforma | ANAntonio | Publicação em 15/02/2027 | Base que mais cresce entre marcas próprias no Brasil, com ticket maior e hábito de pagar por vários apps. A cobrança recorrente é nativa e o mesmo app vende no mundo inteiro. |
| 3 | Bling | ERP | A definir | Jan/2027 | Um conector cobre Tray, WooCommerce, Loja Integrada e marketplaces, porque o pedido de todas passa pelo ERP. Lojista acima de R$ 30 mil quase sempre usa um. |
| 4 | Tray | Plataforma | A definir | Mar/2027 | Muita loja de R$ 50 mil a R$ 500 mil por mês e pouca concorrência na loja de apps. Venda mais ativa que por instalação. |
| 5 | VTEX | Plataforma | A definir | Sob demanda | Varejo grande, ticket alto, ciclo longo e app na VTEX IO. Entra pela Assessoria, contrato a contrato. |
| 6 | WooCommerce | Plugin | A definir | Sob demanda | Base enorme e espalhada. Barato de fazer depois, porque já temos os WordPress próprios. |
| 7 | Loja Integrada | Plataforma | Não entra | Fora | Maioria abaixo de R$ 30 mil por mês e no plano grátis. Fora do perfil do Hub. |
Cronograma
Barra preenchida é fase entregue; losango é a data de publicação na loja de apps. A linha vermelha é hoje.
App Nuvemshop
FBResponsável: Felipe Barros · fase atual: Preparação · publicação em 15/12/2026Publicar o EcomSmart Agents na Loja de Aplicativos da Nuvemshop até 15/12, com 3 lojas piloto rodando o agente de carrinho na Black Friday, e fazer do app o principal canal de aquisição sem mídia do Hub.
Maior base de lojas pequenas e médias do Brasil, com muita loja acima de R$ 30 mil por mês. A loja de apps tem tráfego próprio: o lojista procura, instala e paga sem falar com vendedor.
Andamento
1Preparação
28/09 a 04/10 · 6 tarefas
Fase17%
- Responsável definido: Felipe BarrosFeito
- Conta no Portal de Parceiros Nuvemshop com e-mail @ecomsmart.com.brA fazer
- App "EcomSmart Agents" criado;
app_ideclient_secretguardados em Secret do cluster, nunca no repositórioA fazer - Duas lojas de demonstração: uma vazia e uma com 500 pedidos e 300 clientes de teste com telefoneA fazer
- Escopos mínimos escolhidos no painel (pedidos, clientes, produtos, cupons, checkouts abandonados)A fazer
- Checklist de homologação montado a partir das regras do portal, com a taxa de comissão da cobrança pela NuvemshopA fazer
2Conector de dados
05/10 a 25/10 · 8 tarefas
Fase0%
- Rota de instalação e callback OAuth: troca do
codeporaccess_tokene grava ouser_id(id da loja)A fazer - Importação do histórico: clientes e pedidos de 24 meses, paginada e dentro do limite de taxaA fazer
- Webhooks de pedido e cliente:
order/created,order/paid,order/cancelled,order/fulfilled,customer/created,customer/updatedA fazer - Webhook
app/uninstalleddesliga os agentes e revoga o tokenA fazer - Webhooks LGPD obrigatórios:
store/redact,customers/redact,customers/data_requestA fazer - Validação HMAC em todo webhook e fila de reprocessamento com retentativaA fazer
- Carrinhos abandonados: webhook se existir; se não, leitura de
/checkoutsa cada 15 minutosA fazer - Telefone normalizado no formato +55 e consentimento de marketing guardado por clienteA fazer
3Experiência no painel
19/10 a 08/11 · 4 tarefas
Fase0%
- App embutido no admin da Nuvemshop com a biblioteca NexoA fazer
- Onboarding em 4 passos: conectar o WhatsApp oficial do lojista, ver o Raio-X da base, escolher o primeiro agente, ligarA fazer
- Tela de resultado: vendas recuperadas por agente, com atribuição por cupom e link rastreadoA fazer
- Ficha da loja de apps: nome, subtítulo, descrição, ícone, 5 capturas e vídeo de 60 segundosA fazer
4Cobrança
02/11 a 15/11 · 3 tarefas
Fase0%
- Decisão: cobrar pela Nuvemshop ou pelo Stripe do Hub (ver decisões)A fazer
- Plano igual ao do site: 7 dias grátis, R$ 99 por agente nos 3 primeiros meses, depois R$ 299A fazer
- App suspenso ou sem pagamento pausa os agentes sem apagar dadosA fazer
5Piloto
09/11 a 06/12 · 4 tarefas
Fase0%
- 3 lojas piloto acima de R$ 30 mil por mês, instaladas pelo link direto antes da listagemA fazer
- Agente de carrinho ligado nas 3 antes de 20/11A fazer
- Relatório da Black Friday por loja: carrinhos, mensagens, vendas recuperadasA fazer
- 3 depoimentos com número para a ficha e para o siteA fazer
6Homologação
23/11 a 15/12 · 3 tarefas
Fase0%
- App enviado para revisão da NuvemshopA fazer
- Apontamentos da revisão corrigidos em até 3 dias úteisA fazer
- Publicado na Loja de AplicativosA fazer
7Crescimento
16/12 a 28/02 · 3 tarefas
Fase0%
- 20 instalações por mês a partir de janeiroA fazer
- Pedido de avaliação no dia 14 de uso para quem teve venda recuperadaA fazer
- Parceria com 5 agências certificadas NuvemshopA fazer
Especificação técnica
| Item | Como é |
|---|---|
| Portal | Portal de Parceiros Nuvemshop; o app nasce ali e ganha app_id e client_secret |
| Instalação | Lojista abre https://www.nuvemshop.com.br/apps/{app_id}/authorize, aceita os escopos e volta para o callback com code |
| Token | POST em https://www.tiendanube.com/apps/authorize/token com client_id, client_secret, grant_type=authorization_code e code. O token não expira; morre na desinstalação |
| API | REST em https://api.nuvemshop.com.br/v1/{store_id}/, JSON |
| Cabeçalhos | Authentication: bearer {token} (é "Authentication", não "Authorization") e User-Agent com nome do app e e-mail de contato, obrigatório |
| Limite de taxa | Balde por loja (na documentação atual, 40 requisições que esvaziam a 2 por segundo). Ler os cabeçalhos x-rate-limit-* e esperar quando zerar |
| Paginação | page e per_page (até 200). Histórico importado em lotes, loja por loja |
| Webhooks | Criados pela API em /webhooks; assinatura HMAC SHA-256 no cabeçalho x-linkedstore-hmac-sha256 com o client_secret |
| LGPD | store/redact, customers/redact e customers/data_request configurados no portal; sem eles o app não passa na revisão |
| Painel | App embutido no admin com Nexo; também pode abrir em página própria |
| Cobrança | Pela Nuvemshop (entra na fatura do lojista, com comissão) ou por fora. Confirmar a taxa no portal na Preparação |
| Teste | Lojas de demonstração criadas pelo portal de parceiros, sem custo |
| Documentação | tiendanube.github.io/api-documentation |
Limites, nomes de escopo e regras de cobrança mudam. Conferir cada linha na documentação oficial durante a Preparação e corrigir aqui o que estiver diferente.
Dados por agente
| Agente | Dado necessário | De onde vem |
|---|---|---|
| Recuperação de Carrinho | Checkouts abandonados com telefone, itens e link de recuperação | /checkouts |
| Disparo para Base RFV | Todos os pedidos pagos por cliente: data, valor, quantidade | /orders, /customers |
| Retenção | Pedido cancelado, pagamento pendente ou vencido | order/cancelled, order/updated |
| E-commerceFlow | Cadastro novo, pedido pago, pedido enviado com rastreio | customer/created, order/paid, order/fulfilled |
| Campanhas Inteligentes | Catálogo, itens por pedido, cupons criados pelo agente | /products, /coupons |
Ficha na loja de apps
| Campo | Conteúdo |
|---|---|
| Nome | EcomSmart Agents |
| Subtítulo | Agentes de IA que recuperam carrinhos e fazem o cliente comprar de novo pelo WhatsApp |
| Categoria | Marketing e WhatsApp |
| Preço exibido | 7 dias grátis; R$ 99 por agente nos 3 primeiros meses; depois R$ 299 |
| Prova | 3 depoimentos das lojas piloto com venda recuperada na Black Friday |
Riscos
| Risco | O que fazemos |
|---|---|
| Revisão da Nuvemshop atrasa e passa de 15/12 | Enviar em 23/11, com o checklist fechado; o piloto roda pelo link direto e não depende da listagem |
| Loja sem WhatsApp oficial trava no onboarding | Passo guiado de criação da WABA e oferta do Hub assistido para quem travar |
| Importação de lojas grandes estoura o limite de taxa | Fila por loja, lotes de 200, retomada do ponto onde parou |
| Cluster sem folga de CPU | Conector roda como worker leve; reservar recurso antes do piloto |
App Shopify
ANResponsável: Antonio · fase atual: Preparação · publicação em 15/02/2027Publicar o EcomSmart Agents na Shopify App Store até 15/02/2027, com 3 lojas brasileiras no piloto em dezembro, e abrir o caminho para vender em dólar fora do Brasil.
Base que mais cresce entre marcas próprias no Brasil, com ticket maior e hábito de pagar por vários apps. A cobrança recorrente é nativa e o mesmo app vende no mundo inteiro.
Andamento
1Preparação
28/09 a 11/10 · 6 tarefas
Fase17%
- Responsável definido: AntonioFeito
- Conta de parceiro Shopify e taxa única de registro para publicar (US$ 19)A fazer
- Loja de desenvolvimento com pedidos e clientes de teste com telefoneA fazer
- App criado com o Shopify CLI no template oficial, embutido no admin com App Bridge e PolarisA fazer
- Pedido de acesso a dados protegidos de clientes (nome, e-mail, telefone, endereço) com a justificativa dos agentesA fazer
- Pedido do escopo
read_all_orders: sem ele a API só entrega 60 dias de pedidos, e o RFV precisa de 24 mesesA fazer
2Conector de dados
12/10 a 08/11 · 7 tarefas
Fase0%
- Instalação gerenciada pela Shopify e troca de token a partir do session tokenA fazer
- Histórico por Bulk Operations do GraphQL Admin: clientes e pedidos de 24 mesesA fazer
- Webhooks:
orders/create,orders/paid,orders/cancelled,orders/fulfilled,customers/create,customers/update,checkouts/create,checkouts/updateA fazer - Webhook
app/uninstalleddesliga os agentesA fazer - Webhooks de privacidade obrigatórios:
customers/data_request,customers/redact,shop/redactA fazer - Validação HMAC (
X-Shopify-Hmac-Sha256) e fila de reprocessamentoA fazer - Detectar checkout externo (Yampi, Cartpanda, Appmax): nesses casos o carrinho abandonado não chega à ShopifyA fazer
3Experiência no painel
26/10 a 22/11 · 3 tarefas
Fase0%
- Mesmo onboarding da Nuvemshop em componentes PolarisA fazer
- Consentimento de marketing do cliente da Shopify respeitado antes de qualquer disparoA fazer
- Ficha em português e inglêsA fazer
4Cobrança
09/11 a 29/11 · 3 tarefas
Fase0%
- Billing API (
appSubscriptionCreate) com 7 dias grátis; obrigatória para app listadoA fazer - Decisão do preço em dólar (ver decisões)A fazer
- Assinatura cancelada ou congelada pausa os agentesA fazer
5Piloto
30/11 a 10/01 · 3 tarefas
Fase0%
- 3 lojas brasileiras pelo link de instalação antes da listagemA fazer
- Mapear quais usam checkout externo e ligar o conector do checkout quando for o casoA fazer
- Campanha de recompra pós-Black Friday rodando nas 3A fazer
6Homologação
11/01 a 15/02 · 3 tarefas
Fase0%
- Checklist de requisitos da App Store e de desempenho do app no adminA fazer
- App enviado para revisãoA fazer
- Apontamentos corrigidos e app publicadoA fazer
7Crescimento
16/02 a 28/02 · 2 tarefas
Fase0%
- 10 instalações por mês no BrasilA fazer
- Buscar o selo Built for Shopify depois de 50 instalaçõesA fazer
Especificação técnica
| Item | Como é |
|---|---|
| Portal | Painel de parceiros e desenvolvedores da Shopify; app configurado em shopify.app.toml pelo Shopify CLI |
| Instalação | Instalação gerenciada: a Shopify pede os escopos do shopify.app.toml; o app troca o session token pelo token de acesso |
| API | Somente GraphQL Admin API; app público novo não é aceito com REST. Versão da API fixada e revisada a cada trimestre |
| Escopos | read_orders, read_all_orders (aprovação), read_customers, read_products, read_checkouts, write_discounts |
| Dados protegidos | Nome, e-mail, telefone e endereço exigem pedido de acesso aprovado pela Shopify. Sem telefone não existe agente de WhatsApp |
| Limite de taxa | Por custo de consulta, em pontos por segundo, que variam com o plano da loja. Histórico sempre por Bulk Operations |
| Webhooks | Assinados em shopify.app.toml; HMAC SHA-256 no cabeçalho X-Shopify-Hmac-Sha256 |
| Privacidade | customers/data_request, customers/redact, shop/redact obrigatórios |
| Painel | App embutido no admin com App Bridge e Polaris; sair do admin para configurar reprova na revisão |
| Cobrança | Billing API em dólar. A Shopify fica com 0% até US$ 1 milhão de receita acumulada do parceiro e 15% depois |
| Brasil | Muitas lojas usam checkout externo (Yampi, Cartpanda, Appmax). Pedido volta para a Shopify, carrinho abandonado não |
| Teste | Lojas de desenvolvimento grátis no painel de parceiros |
| Documentação | shopify.dev/docs/apps e requisitos da App Store |
Limites, nomes de escopo e regras de cobrança mudam. Conferir cada linha na documentação oficial durante a Preparação e corrigir aqui o que estiver diferente.
Dados por agente
| Agente | Dado necessário | De onde vem |
|---|---|---|
| Recuperação de Carrinho | Checkouts abandonados com telefone e link de recuperação | checkouts/create, checkouts/update, abandonedCheckouts |
| Disparo para Base RFV | Pedidos de 24 meses por cliente | Bulk Operations em orders e customers |
| Retenção | Pedido cancelado ou pagamento pendente | orders/cancelled, orders/updated |
| E-commerceFlow | Cadastro novo, pedido pago, envio com rastreio | customers/create, orders/paid, orders/fulfilled |
| Campanhas Inteligentes | Catálogo, itens por pedido, códigos de desconto do agente | products, discountCodeBasicCreate |
Ficha na loja de apps
| Campo | Conteúdo |
|---|---|
| Nome | EcomSmart Agents |
| Subtítulo | AI agents that recover carts and bring customers back on WhatsApp |
| Categoria | Marketing e conversão |
| Preço exibido | 7 dias grátis; preço por agente em dólar a decidir |
| Idiomas | Português e inglês |
Riscos
| Risco | O que fazemos |
|---|---|
Shopify nega o acesso a dados protegidos ou ao read_all_orders | Pedir na primeira semana com justificativa por agente e política de privacidade publicada |
| Checkout externo esconde o carrinho abandonado | Detectar na instalação e oferecer o conector do checkout (Yampi primeiro) |
| Revisão da App Store demora e pede ajustes de desempenho | Rodar o checklist oficial antes de enviar; reservar 5 semanas para a homologação |
| Preço em dólar alto para a loja brasileira | Testar o valor no piloto antes de fechar a ficha |
O que o app vende
O app se chama EcomSmart Agents nas lojas e abre o painel do Hub. Cada agente é um módulo do Hub, com o mesmo preço do site: 7 dias grátis, R$ 99 por agente nos 3 primeiros meses e R$ 299 depois. A mensagem da Meta é paga pela conta WhatsApp do lojista.
Recuperação de Carrinho
Chama no WhatsApp quem saiu com o carrinho cheio, com o link de volta ao checkout.
Disparo para Base RFV
Uma oferta certa por mês para cada faixa da base, pela nota de recência, frequência e valor.
Retenção
Salva pedido cancelado e boleto ou Pix vencido antes de o cliente desistir.
E-commerceFlow
Boas-vindas, pós-compra e aviso de entrega, cada um no momento certo.
Campanhas Inteligentes
Campanhas de data e de cesta (quem comprou A leva B) para a base inteira, com cupom próprio.
Arquitetura comum
Toda plataforma entra pelo mesmo caminho. O que muda de uma para outra é só o conector; núcleo, agentes e painel são os mesmos.
Plataforma
Lojista instala o app e aceita os escopos.
Um por plataforma
OAuth, histórico, webhooks, LGPD e cobrança.
Dados do Hub
Clientes, pedidos e carrinhos no mesmo formato; RFV recalculado todo dia.
Cinco agentes
Decidem quem recebe o quê e quando.
API oficial
Pela WABA do lojista; a venda volta atribuída por cupom e link.
Contrato de todo conector
| Função | O que faz | Quando roda |
|---|---|---|
instalar | Recebe o OAuth, grava a loja e o token em Secret, cria os webhooks | Na instalação |
importar_historico | Clientes e pedidos de 24 meses, em lotes, retomável | Logo depois de instalar |
receber_webhook | Valida HMAC, normaliza e põe na fila | A cada evento |
sincronizar | Confere o que o webhook perdeu e lê carrinhos quando não há webhook | A cada 15 minutos |
desinstalar | Desliga agentes, revoga token, agenda exclusão | No webhook de desinstalação |
apagar_dados | Atende os pedidos de LGPD da plataforma | Nos webhooks de privacidade |
cobrar | Cria a assinatura e pausa agentes sem pagamento | Ao ligar o primeiro agente |
Modelo de dados normalizado
| Entidade | Campos principais |
|---|---|
| Loja | plataforma, id na plataforma, domínio, token (referência ao Secret), plano, status |
| Cliente | id externo, nome, e-mail, telefone +55, consentimento de marketing, notas R, F e V |
| Pedido | id externo, cliente, valor, status de pagamento e envio, cupom, origem do agente |
| Item | pedido, produto, variante, quantidade, preço |
| Carrinho | id externo, cliente ou telefone, itens, valor, link de recuperação, recuperado sim ou não |
| Evento | tipo, carga bruta, recebido em, processado em, tentativas |
Onde roda: no backend do Hub (Django), um app por conector (conectores/nuvemshop, conectores/shopify), workers no cluster com nodeSelector sistema=true. O cluster está sem folga de CPU; reservar recurso antes dos pilotos.
Operação e vendas
Funil de cada app (meta mensal da Nuvemshop a partir de janeiro)
Como o lojista chega
- Busca na loja de apps: ficha com "recuperação de carrinho" e "WhatsApp" no subtítulo, capturas com número real do piloto.
- Raio-X: quem roda o Raio-X numa loja Nuvemshop ou Shopify recebe o botão de instalar o app no resultado.
- Agências parceiras: 5 agências por plataforma, com comissão recorrente.
- Ecom IA Brasil: guia e encontro ao vivo sobre recuperação de carrinho com o app.
Como a loja é atendida
- Suporte: WhatsApp da EcomSmart, resposta em até 4 horas úteis.
- Onboarding: quem instalou e não conectou o WhatsApp em 24 horas recebe contato do time.
- Avaliações: toda avaliação respondida em 24 horas; pedido de avaliação no dia 14 para quem teve venda recuperada.
- Loja travada: oferta do Hub assistido para quem não consegue criar a conta WhatsApp oficial.
O que é monitorado
| Sinal | Alerta quando | Onde |
|---|---|---|
| Webhooks recebidos por loja | Loja ativa fica 6 horas sem evento | Grafana |
| Erros do conector | Mais de 2% de falha em 1 hora | Grafana e WhatsApp do responsável |
| Atraso da fila | Evento esperando mais de 10 minutos | Grafana |
| Token revogado ou app desinstalado | Sempre | Painel do Hub e aviso ao responsável |
| Instalações, ativação e assinaturas | Semanal | Relatório de segunda |
Rotina do programa
Para atualizar o andamento: trocar o status da tarefa em dados/lojas.py ("feito", "andamento", "fazer" ou "bloqueado"), rodar python3 dados/build.py e publicar com scripts/publicar.sh.
Definição de pronto
Técnico
- Instalação e desinstalação limpas na loja de teste, sem erro no log.
- Histórico de 24 meses importado numa loja com mais de 10 mil pedidos.
- Todo webhook validado por HMAC; nenhum evento perdido em 7 dias de piloto.
- Webhooks de privacidade atendidos e testados.
- Monitoramento no Grafana ligado.
Negócio
- App publicado na loja de aplicativos.
- 3 lojas piloto com venda recuperada e depoimento.
- Cobrança funcionando do teste grátis à assinatura.
- Manual de suporte escrito para o time.
- Ficha com capturas e números reais.
Decisões
| Decisão | Recomendação | Quem decide | Prioridade |
|---|---|---|---|
| Nome do app nas lojas | "EcomSmart Agents", com o Hub como nome do painel | Geraldo | Alta |
| Cobrança na Nuvemshop: pela plataforma ou pelo Stripe | Pela Nuvemshop se a comissão ficar abaixo de 20%; a conversão da cobrança nativa compensa | Geraldo e Felipe | Alta |
| Preço na Shopify | US$ 59 por agente, 7 dias grátis, testado no piloto | Geraldo e Antonio | Média |
| Terceiro conector | Bling em janeiro de 2027, com responsável a definir até 15/12 | Geraldo | Média |
| Loja Integrada | Fora do plano | Geraldo | Normal |