Como o Rally de Vendas funciona por dentro

01

Cadastro

Do clique em "Criar conta" até estar logado no painel — direto ou por link de indicação.

/registro · clique pra abrir (já logado)

Criar conta grátis →Como funciona indicação / afiliados

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1Acessa rallydevendas.com.br/registro OU chega por um link de indicação de um parceiro.

2Preenche e-mail, senha, nome, WhatsApp e nacionalidade (detectada pela localização).

3Clica em "Criar conta".

4Cai direto no painel já logado — sem etapa bloqueante de e-mail.

↓ o sistema reage por baixo

⚙️ O sistema faz

Valida

Confere o token de segurança e os dados; captura nacionalidade e país fiscal.

Cria

Grava o usuário com senha criptografada.

Vincula

Se veio por indicação, conecta vendedor e parceiro automaticamente (vira comissão pro indicador).

Sessão

Inicia a sessão e registra o cadastro para auditoria.

Avisa

Notifica o admin do novo cadastro por Telegram.

⚠️ AtençãoE-mail duplicadoLimite de tentativas (anti-fraude)

02

Conectar conta Mercado Livre

Conectar sua conta do Mercado Livre com segurança para sincronizar anúncios e vendas.

/lojas /contas/ml/connect · clique pra abrir (já logado)

Tela real de Conectar conta Mercado Livre

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1Vai em Lojas → clica "Conectar Mercado Livre".

2Faz login no ML e autoriza o acesso (leitura e escrita).

3Volta pro Rally já com a conta conectada (nome e reputação aparecem).

↓ o sistema reage por baixo

⚙️ O sistema faz

Valida

Confere se você está logado e se o plano permite mais contas.

Protege

Gera um código de segurança único (PKCE) pra ninguém interceptar a conexão.

Troca

Recebe a autorização do ML e troca por um acesso permanente, renovado sozinho a cada 6h.

Criptografa

Guarda o acesso criptografado (AES-256) — o token nunca fica em texto puro.

Indexa

Cria um índice rápido pra receber avisos de venda em tempo real.

🌐 Vai pro Mercado Livre / Pix

Autorização + troca de token no Mercado LivreConsulta seus dados de vendedor (nome, reputação)

⚠️ AtençãoToken expira a cada 6h (renova sozinho)Conta já conectada em outro usuário é recusada

03

Dashboard

Fornecer ao vendedor uma visão centralizada de seu desempenho com KPIs, checklist onboarding, avisos de ação e atalhos rápidos.

/dashboard / /api/widgets/open-orders · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1Acessa o painel pelo menu 'Início > Dashboard' ou abre /dashboard

2Visualiza seu progresso em cards-destaque: faturamento hoje, pedidos da semana, produtos/anúncios, faturamento do mês

3Verifica 3 alertas principais: pedidos Drop a pagar, anúncios sem vincular, contas ML desconectadas

4Completa itens do checklist onboarding (foto, WhatsApp, CPF, conexão ML, colaborador, primeiro anúncio)

5Consulta as notificações recentes e aciona atalhos rápidos (criar produto, novo anúncio, conectar ML, calcular preço, clonar anúncio, estoque, pedidos)

6Acompanha seu gráfico de receita (14 dias vs período anterior) e interage com seções colapsáveis (Gamificação, Pedidos, Gráfico, Ações Rápidas)

↓ o sistema reage por baixo

⚙️ O sistema faz

Autentica

Valida que o usuário está logado e perfil preenchido. Se expirou trial gratuito, bloqueia acesso.

Carrega

Busca métricas do vendedor: receita, pedidos, anúncios, saldo da carteira, contas ML vinculadas e seus status.

Compara

Calcula deltas de receita e pedidos (semana vs semana anterior, mês vs mês anterior) para mostrar crescimento.

Cria KPIs

Monta 4 cards: faturamento hoje, pedidos semana, produtos/anúncios, faturamento mês com sub-métricas e progresso.

Verifica alertas

Identifica: custos Drop pendentes, anúncios desvinculados e contas com token expirado/revogado.

Monta checklist

Retorna 7 etapas onboarding com status (feito/pulado): foto, WhatsApp, CPF, conexão ML, colaborador, sobre você, anúncio.

Renderiza

Compõe a página com hero orientado por valor (Design Language v2), seções colapsáveis, notificações e atalhos contextuais.

⚠️ AtençãoContas ML com token expirado/revogado aparecem em alerta; vendedor deve reconectar via /contas/ml/connect para evitar pausa na sincronia de pedidos.Anúncios sem produto vinculado (unlinked) bloqueiam visibilidade completa; redirecionam para /central/anuncios.Usuários sem conta ML conectada veem CTA em destaque com wizard; sem ao menos uma loja, alguns widgets não carregam (crescimento, gráfico).

04

Assistente de IA

Permitir que vendedores com chave própria de IA (BYOK) consultem o assistente conversacional para análises de vendas, reputação, anúncios e navegação — sem consumir créditos do Rally.

/concierge /perfil?tab=ia /ai/creditos · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1No painel, clique em 'Assistente IA' no menu lateral (só aparece se configurou sua chave). A tela mostra um histórico de conversas e dicas de uso.

2Cole sua chave em Perfil › Inteligência Artificial. Onde CRIAR a chave (Gemini é grátis): acesse aistudio.google.com/apikey, clique em "Create API key" e copie a chave que começa com AIza — cole no Rally. (Claude: console.anthropic.com/settings/keys · ChatGPT: platform.openai.com/api-keys)

3Digite sua pergunta em português: 'Qual é meu melhor anúncio?', 'Quantos pedidos tive?', 'Como criei um novo anúncio?' — a IA entende comandos variados.

4Clique em Enviar. A solicitação entra na fila e é processada em até 30 minutos — resultado aparece aqui no chat + e-mail + WhatsApp.

5Para consultas rápidas (títulos, descrições), use a IA de edição embutida — elas debitam créditos, mas BYOK as libera também.

6Acompanhe seu saldo de créditos em Carteira > Recarregar ou consulte custos antes de enviar com a estimativa automática.

↓ o sistema reage por baixo

⚙️ O sistema faz

autentia

Valida se o usuário está logado; bloqueia acesso a /concierge se não tiver BYOK ativo (redireciona para gate de configuração).

carrega

Recupera histórico de solicitações anteriores do usuário (JSON persistente em storage/concierge_requests.json) — mais recentes primeiro.

processa-entrada

Recebe mensagem do vendedor, valida tamanho (máx 2000 caracteres), anti-flood (20 segundos entre envios) e insere na fila com status 'pending'.

classifica

Determina o intent (criar anúncio, consulta vendas, ajuda geral, etc.) por palavras-chave — custo de créditos depende do tipo.

resolve-chave

Se BYOK ativo: carrega chave criptografada do usuário (AES-256-GCM) e a descriptografa — senão usa Claude/Gemini do sistema. Nenhum crédito consumido em BYOK.

gera-resposta

Envia ao Claude ou Gemini com contexto real do usuário (vendas, reputação, erros recentes, rotas disponíveis); IA sugere ações (abrir wizard, navegar).

persiste

Salva mensagem + resposta no histórico local (IaChatHistoryService) — resgata em próximas visitas; marca como concluída quando operador processa.

🌐 Vai pro Mercado Livre / Pix

POST para Claude/Gemini/OpenAI com pergunta do vendedor + contexto da conta (vendas, reputação, anúncios) — usa a chave BYOK ou a do sistema.GET ao Mercado Livre API (via PainelMlApiController) para enriquecer resposta com dados em tempo real (vendas, envios, ads, promocões).

⚠️ AtençãoBYOK obrigatório para usar /concierge — vendedor precisa conectar chave própria em Perfil > IA antes; sem isso, vê apenas gate de boas-vindas.Consultas datatype (vendas, reputação, envios) debitam 1 crédito do plano; BYOK as libera. Criação de anúncio custa 0 (redireciona direto ao wizard).Fila processa até 30 minutos com operador manual; enquanto isso, mostrar badge 'Na fila' no chat + notificar por email/WhatsApp quando pronto.

05

Anúncios

O vendedor publica, edita e clona seus anúncios no Mercado Livre de forma centralizada, sincronizando dados em tempo real com a plataforma ML.

/central/anuncios /anuncios/criar /anuncios/{id}/editar/clonar · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1Acessa a Central de Anúncios e vê a lista de todos seus anúncios ativos, pausados ou encerrados no Mercado Livre, filtrado por conta e status

2Clica em 'Criar novo anúncio' e passa por um assistente (wizard) visual: seleciona um produto do catálogo Rally, escolhe a conta ML, marca opções de frete e logística, preenche atributos obrigatórios e valida antes de publicar

3Ao publicar, o Rally envia o anúncio (fotos, título, descrição, preço) ao Mercado Livre via API; o anúncio fica ativo imediatamente e aparece na lista com status 'active'

4Clica em um anúncio para editar: ajusta preço, estoque, descrição, fotos ou status (pausar/retomar/encerrar) — o Rally sincroniza as mudanças com o ML em tempo real

5Usa 'Clonar' para duplicar um anúncio existente para outras contas ML, com opção de ajustar preço e saltar itens pausados

6Consulta o histórico de alterações de cada anúncio e verifica a saúde (score, restrições, elegibilidade para catálogo) diretamente na Central

↓ o sistema reage por baixo

⚙️ O sistema faz

Redirecionar

GET /anuncios redireciona permanentemente (301) para /central/anuncios — consolidação da listagem

Carregar

Central carrega anúncios ao vivo do Mercado Livre: faz autenticação OAuth, obtém token fresco, chama GET /users/{mluid}/items?status={filtro} para listar por status (active/paused/closed/under_review)

Filtrar

Aplica filtros avançados: por conta, status, score, logística (Full/Flex/Standard), catálogo vs. tradicional, tipo de listagem (premium/clássica) — tudo via JavaScript no client

Criar

Wizard POST /anuncios coleta produto local + conta ML + atributos obrigatórios, valida com /api/ml/rules/dry-run, sobe fotos (até 6 comprimidas + mais via segunda chamada), publica via POST /items ao ML

Editar

POST /anuncios/{id}/editar faz pre-flight (verifica se está em revisão/encerrado/com vendas), filtra campos bloqueados, envia PUT /items/{ml_id} com mudanças permitidas; se em revisão, aceita só descrição (PUT /items/{id}/description)

Publicar

MlPublisher retry automático (até 4 tentativas): ajusta payload conforme erros ML, descarta campos inválidos, sobe fotos antes do POST /items, posta descrição após criação de item

Clonar

POST /anuncios/{id}/clonar-simples dispara CloneJobService para cada conta destino: cria novo anúncio com mesmo produto e dados, mantém histórico de origem em drop_origin

🌐 Vai pro Mercado Livre / Pix

POST /items — publica novo anúncio com título, descrição, preço, estoque, fotos, atributos, frete e logísticaPUT /items/{id} — atualiza preço, estoque, status ou detalhes do anúncio existente; bloqueado se anúncio está em revisão ou tem vendas em certas categoriasPUT /items/{id}/description — atualiza só descrição quando o anúncio está sob revisão ML (under_review)GET /users/{mluid}/items?status={status}&offset={offset} — lista anúncios da conta: ativos, pausados, encerrados ou em revisão; paginada com 50 itens por pagePOST /pictures — carrega fotos individuais e retorna IDs para referenciar no anúncioGET /items/{id} — sincroniza dados do anúncio (marketplace_data): status atual, vendas, visitas, saúde, logística, categoria

⚠️ AtençãoAnúncios em revisão (under_review) — só descrição é editável; tentar editar outros campos retorna erro ML 'item_status_change_not_allowed' e trava o formulárioAnúncios com vendas (has_bids=true) em categorias restritas — campo título, categoria e tipo de listagem ficam travados; ML recusa PUT. Usuário vê aviso 'anúncio com vendas' ao abrir ediçãoLimite de 6 fotos na primeira chamada — Rally faz segunda chamada POST /pictures + PUT para fotos extras (6-12); falha de upload não bloqueia publicação, mas anúncio fica sem fotos completas

06

Dados Fiscais

Permitir que o vendedor configure NCM, CEST e origem dos produtos para destravar emissão automática de Notas Fiscais Eletrônicas.

/anuncios/fiscais /anuncios/fiscais/validate-ncm /anuncios/fiscais/bulk · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1Acesse o menu 'Dados Fiscais' (grupo Mercado Livre) no painel

2Veja a lista de anúncios dividida em: ⚠ Sem NCM, ✓ Com NCM e Total

3Selecione um ou mais anúncios clicando nos checkboxes e clique em 'Editar Fiscais em Massa'

4Preencha os campos obrigatórios (NCM) e opcionais (CEST, CSOSN/CST, Origem) no modal

5O sistema valida o NCM em tempo real contra a tabela TIPI e mostra se é válido

6Clique em 'Aplicar' para enviar os dados selecionados ao Mercado Livre e gerar as NF-es

↓ o sistema reage por baixo

⚙️ O sistema faz

busca

Sistema carrega todos os anúncios do vendedor e calcula totalizadores (com NCM, sem NCM, total)

filtra

Agrupa anúncios por status de completude fiscal — exibe apenas os solicitados (incomplete, complete ou all)

valida

Quando vendedor digita NCM, sistema faz consulta ao Brasil API para confirmar se o código existe na tabela TIPI

monta

Prepara payload com dados fiscais (ncm, cest, csosn, cst, origin_type) dentro de tax_information

envia

Faz PUT para Mercado Livre em /items/fiscal_information/{item_id} com token OAuth da conta conectada

persiste

Salva resposta do ML localmente em announcements.marketplace_data.tax_information com timestamp sync

notifica

Se sucesso em lote, envia notificação ao vendedor via Telegram com contagem de anúncios atualizados

🌐 Vai pro Mercado Livre / Pix

GET https://brasilapi.com.br/api/ncm/v1/{ncm} — valida NCM contra TIPI (sem autenticação)PUT https://api.mercadolibre.com/items/fiscal_information/{item_id} — envia dados fiscais ao Mercado Livre (requer token OAuth do vendedor)

⚠️ AtençãoML não retorna NCM/CEST via API — dados são cadastrados apenas pelo vendedor; sem NCM correto, o anúncio fica bloqueado em 'invoice_pending' e não gera NF-eValidação NCM é apenas verificação de existência contra TIPI; dados financeiros (CSOSN/CST) ainda exigem conferência manual pela contabilidade do vendedor para consistência com regime tributárioRate limiting: aplicação em lote aguarda 150ms entre cada PUT (proteção contra throttling do ML); lotes de 500+ anúncios podem levar minutos

07

Vendas

Visualizar, filtrar e gerenciar vendas do Mercado Livre — desde a criação do pedido até a entrega — acompanhando etiquetas, notas fiscais e rastreio de envio.

/central/vendas /central/vendas?tab=vendas /central/vendas?tab=envios /central/vendas?tab=frete /central/vendas?tab=financeiro /pedidos /pedidos/{orderId}/ml/etiqueta /ml/nf · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1Vendedor acessa menu Painel > Vendas (no grupo Mercado Livre) e cai em /central/vendas

2Vê uma lista de pedidos com filtros por data, status, conta ML e busca por produto/comprador; KPIs mostram total de vendas, faturamento total, vendas e receita de hoje

3Clica em um pedido para ver detalhe — status, comprador, endereço, número de rastreio; visualiza timeline com eventos (pedido criado, pagamento confirmado, postado, entregue)

4Após o pagamento, baixa etiqueta de envio via botão 'Etiqueta' (entra /ml/etiqueta?ship_id=X) e imprime

5Digita ou escaneia o número de rastreio na etiqueta no sistema do Mercado Livre para atualizar o status

6Acessa /ml/nf para baixar a Nota Fiscal emitida (ou /pedidos/declaracao se for CPF sem NF); acompanha envio via aba 'Envios & Rastreio' que mostra carrier, datas e status em tempo real

↓ o sistema reage por baixo

⚙️ O sistema faz

sincronizar

Sistema sincroniza pedidos via API do Mercado Livre a cada webhook ou cron, consultando os endpoints /orders/search (filtros: paid, confirmed, payment_in_process, cancelled) e /shipments/{id} para obter status, datas e dados do transportista.

armazenar

Todos os dados de vendas são salvos em ml_orders.json local (banco de dados por usuário) com campos: order_id, status, date_created, date_closed, date_shipped, itens, comprador, envio, rastreio e valores (total_amount, comissão).

listar

Ao abrir /central/vendas, carrega os pedidos do JSON local, aplica filtros (data, status, conta, busca), pagina em 50 itens e calcula KPIs (total de vendas, faturamento total, hoje).

enriquecer

Para cada pedido, busca a foto do produto no banco local de anúncios; conecta o account_id à conta ML (nickname) para exibir em qual loja foi vendido (suporta vendedor com múltiplas contas).

detalhar

Ao clicar em /pedidos/{id}, carrega o registro, constrói uma timeline com 5-6 marcos (pedido criado, pagamento confirmado, envio gerado, postado, entregue, cancelado) e calcula prazos (73h para postar após pagamento, alertas de atraso em reputação).

etiqueta

Via /ml/etiqueta?ship_id=X, valida o status+substatus do envio (a etiqueta só existe em ready_to_ship: ready_to_print/printed/in_hub) e baixa o PDF da ML — inclusive Flex (self_service), que sai imediato. Captura proativa: webhook + cron pré-baixam a etiqueta assim que fica pronta, então abre instantânea do cache. Suporta download em lote.

rastreio

Exibe número de rastreio + carrier (Correios, Loggi, etc) vindo do shipment; para Flex (LogBG/Fretecentro), integra webhook de transportista que atualiza status em tempo real com GPS.

🌐 Vai pro Mercado Livre / Pix

GET /orders/search?seller={mlUserId}&order.status=paid,confirmed,payment_in_process,cancelled — busca todas as vendas com status ativoGET /shipments/{shipmentId} — obtém detalhes do envio (status, tracking_number, carrier, logistic_type, receiver_address)GET /shipments/{shipmentId}/label — baixa etiqueta em PDF/ZPL para impressão (via LabelService)GET /invoices/{orderId} — tenta buscar NF-e emitida (se houver CNPJ no vendedor)

⚠️ AtençãoStatus pode ficar desatualizado se webhook do ML falhar — existe re-sync forçada (force=true) para pedidos parados 72h+; vendedor vê 'Enviado' local mas ML ainda diz 'Preparando'Etiqueta só existe quando o ML libera (ready_to_ship). O botão de download só aparece quando ela está REALMENTE pronta — antes disso o sistema mostra o estado certo (Aguardando ML / Aguardando NF / Despachado / Entregue) em vez de um botão que dá erro. Para o que ainda não saiu, há 'Pedir etiqueta ao vendedor' por WhatsApp. Cross-docking (xd_drop_off) pode segurar horas — um monitor diário avisa se uma etiqueta pronta parar de vir.NF-e só aparece para vendedores com CNPJ que emitiram via integração ou automático ML; para CPF ou sem integração, oferece Declaração de Conteúdo (PDF simples) como fallback

08

Clientes

Consultar e enriquecer a base de compradores do Mercado Livre com dados pessoais (nome real, telefone, CPF) via API FonteData ou BigDataCorp, mantendo histórico de contatos (follow-ups).

/clientes /clientes/{ownerId}/{id}/clientes/export · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1O vendedor acessa o menu Clientes no painel e vê a lista de todos os compradores que fizeram pedidos no Mercado Livre, filtrados por nome, tag, sexo, classe social e ordenados por recência, valor ou quantidade de pedidos

2Clica em um comprador para ver seu perfil completo (nome, apelido, telefone, e-mail, endereço, pedidos recentes, histórico de contatos e dados enriquecidos como idade, profissão, classe econômica)

3Edita o perfil manualmente (nome, telefones, e-mails, tags, aniversário, notas) ou clica em Enriquecer para buscar dados reais do CPF na FonteData (R$ 1,06/consulta, descontos em volume)

4Consulta e seleciona o resultado encontrado para preencher automaticamente telefones, e-mails, endereço, classe social, renda, profissão e idade

5Registra follow-ups (ligação, mensagem, e-mail, visita) com data e nota para manter histórico de contatos com cada comprador

6Exporta a base inteira em CSV, XLSX ou TXT (respeitando filtros ativos) para análise em planilha ou importação em CRM externo

↓ o sistema reage por baixo

⚙️ O sistema faz

Sincroniza

Importa automaticamente compradores do Mercado Livre cada vez que há novo pedido (buyer_ml_id como chave de deduplicação). Campos protegidos (nome, telefone, e-mail, tags, aniversário, notas) nunca são sobrescritos pelo auto-sync.

Autenticação

Vendedor vê só seus clientes; gerente vê dos seus vendedores; admin vê todos. Acesso por role na sessão.

Filtra

Busca em tempo real por nome/apelido/e-mail/telefone, agrupa por tags, filtra por sexo/classe (dados enriquecidos) e ordena por data/valor/quantidade.

Enriquece

FonteData (CPF) ou BigDataCorp (nome+CEP) consultam base pública e retornam nome real, telefones com WhatsApp, e-mails, endereço, sexo, idade, profissão, classe social e signo. Cache local: se já enriquecido, devolve sem cobrar novamente.

Edita

Salva manualmente nome, lista de telefones/e-mails, tags, aniversário (DD/MM ou DD/MM/AAAA), notas (máx 1000 chars). Registra quem editou (autor, role, timestamp) no log de auditoria (últimas 60 mudanças).

Follow-ups

Adiciona notas de contato com tipo (ligação/mensagem/e-mail/visita/outro), data (padrão=hoje) e descrição. Remove por ID. Exibe mais recentes primeiro.

Exporta

Monta CSV/TXT/XLSX com 20 colunas (nome, CPF, telefones, e-mails, endereço, classe, renda, profissão, idade, sexo, signo, aniversário, tags, contagem de pedidos, total gasto, última compra, loja, vendedor). Respeita todos os filtros aplicados. XLSX gerado com ZipArchive sem dependências externas. BOM UTF-8 em todos os formatos.

🌐 Vai pro Mercado Livre / Pix

POST https://app.fontedata.com/api/v1/consulta/cadastro-pf-plus (X-API-Key header) — busca por CPF (11 dígitos) e retorna nome, telefones com tipo/operadora/WhatsApp, e-mails, endereço, profissão (CBO), classe social, renda estimada, idade, sexo, aniversário, signo e saldo restante em R$POST https://plataforma.bigdatacorp.com.br/people (headers: TokenId, AccessToken) — busca por nome + CEP e retorna lista com até 5 resultados (nome, CPF, telefones, e-mails). Query format: 'name:NOME address_zipcode:CEP'

⚠️ AtençãoFonteData e BigDataCorp usam modelo de crédito (BYOK: Bring Your Own Key). Cada consulta FonteData custa ~R$ 1,06. Saldo consultado e cacheado localmente. Se saldo insuficiente, exibe URL pra top-up.Campos enriquecidos (class, renda, profissão, idade, sexo, signo) ficam no campo enriched[] e são consultados na view (show.php) — a exportação também os inclui.CPF é campo sensível (LGPD). Só é consultado se preenchido manualmente pelo vendedor; nunca é enviado a BigDataCorp (nome+CEP é alternativa). Log de auditoria (edit_log) registra todas as mudanças manuais.

09

Comunicação

Centralizar e responder perguntas, avaliações, mensagens pós-venda, reclamações e devoluções do Mercado Livre em um único painel por aba.

/central/comunicacao (rota painel) /central/comunicacao?tab=perguntas /central/comunicacao?tab=reviews /central/comunicacao?tab=mensagens /central/comunicacao?tab=reclamacoes /central/comunicacao?tab=devolucoes · clique pra abrir (já logado)

👤 Você faz e vê

1Acessa a Central de Comunicação no menu lateral do painel

2Seleciona uma aba: Perguntas, Avaliações, Mensagens, Reclamações ou Devoluções

3Filtra por conta Mercado Livre conectada ou visualiza todas as contas

4Para Perguntas e Avaliações: responde usando templates rápidos ou texto livre; sistema marca como respondida e publica na ML

5Para Mensagens: abre thread conversa clicando no item, lê histórico completo, responde texto ou envia mídia (imagem/vídeo)

6Para Reclamações: verifica motivo e etapa, responde para resolver ou escala para mediação ML; para Devoluções: monitora status (aberta/reembolsada/fechada)

↓ o sistema reage por baixo

⚙️ O sistema faz

Renderiza

Carrega 5 abas (Perguntas, Avaliações, Mensagens, Reclamações, Devoluções) conforme permissões do plano do usuário; exibe seletor de contas ML ativas

Busca

Chama API Mercado Livre para sincronizar dados: perguntas não respondidas, avaliações, threads de conversa, reclamações abertas/fechadas, devoluções em processamento

Filtra

Aplica filtros na tela: status de resposta (perguntas/avaliações), conta selecionada, período (últimos 90 dias)

Notifica

WhatsApp transacional via MlEventWaNotifier para pergunta nova, mensagem pós-venda, reclamação (afeta reputação), devolução; sincronização de digest 14h para gerentes/fornecedores/admins

Responde

POST para Mercado Livre: resposta de pergunta (até 2000 caracteres), reply em conversa (com suporte a mídia), mensagem em reclamação, resposta avaliação; sistema publica direto na ML

Escalona

Para reclamações abertas: envia mediation request para Mercado Livre; sistema rastreia estágio (buyer_response, seller_response, mediation_accepted) e deadline

Exporta

CSV/TXT de cada aba contendo: perguntas (ID, texto, data, status), mensagens (pack, unread, data), reclamações (ID, motivo, etapa, prazo), devoluções (pedido, motivo, status), avaliações (rating, resposta, data)

🌐 Vai pro Mercado Livre / Pix

GET /questions/search (Perguntas não respondidas com status=UNANSWERED ou todas com status=ANSWERED)POST /questions/{question_id}/answers (Enviar resposta de pergunta)POST /questions/{question_id}/hide (Ocultar pergunta como spam)DELETE /questions/{question_id} (Deletar pergunta permanentemente)GET /reviews (Avaliações de itens publicados, com rating aggregation: positive/neutral/negative)POST /reviews/{review_id}/answer (Responder avaliação)GET /messages/packs (Threads de conversa pós-venda com histórico)POST /messages/packs/{pack_id}/sellers/{seller_id}/messages (Enviar mensagem em conversa)GET /claims/search com type=claims (Reclamações abertas com motivo, etapa, deadline)POST /claims/{claim_id}/messages (Responder reclamação)POST /claims/{claim_id}/mediation (Escalar reclamação para mediação Mercado Livre)GET /claims/search com type=returns (Devoluções em processamento com status refunded/closed)

⚠️ AtençãoSincronização: perguntas/reclamações chegam a cada ~5 min via webhook ou manual (botão 'Atualizar agora'); se muita atividade, retardo é esperado — click sync forçado para obter dados frescos imediatamenteWhatsApp: notificações transacionais dependem de Blipei configurado no /perfil; killswitch global em /logs/.broadcast_paused pausa todas as notificações; opt-in por user (wa_ml_*_notif_enabled) desativa por tipo de eventoMediação ML: reclamação escalada passa por estágios (buyer_response → seller_response → mediation_accepted); prazo rigoroso — atraso na resposta desfavorece vendedor; sistema marca deadline em vermelho; responder rápido afeta reputação

10

Marketing (Mercado Ads)

Gerenciar campanhas de Product Ads (publicidade paga) no Mercado Livre para impulsionar vendas com controle de orçamento e métricas de performance (impressões, cliques, ROAS).

/central/marketing?tab=ads /central/marketing?tab=ads_pro /api/ml/ads/campaigns/api/ml/ads/metrics · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1Acessa Menu Lateral > Mercado Livre > Marketing (tela carrega Central de Marketing).

2Na aba 'Product Ads', visualiza campanhas ativas e pausadas com resumo de anúncios e orçamento/dia de cada uma.

3Clica em 'Nova Campanha', preenche nome e orçamento diário, e envia — a campanha aparece em tempo real na lista.

4Expande uma campanha e cola o ID do anúncio (MLB...) para adicionar itens — sistema sincroniza foto e título do ML automaticamente.

5Ativa/pausa campanhas ou anúncios individuais com clique, podendo também remover itens da campanha.

6Clica em 'Métricas (30d)' para visualizar impressões, cliques, custo total, CTR, vendas geradas e ROAS da campanha.

↓ o sistema reage por baixo

⚙️ O sistema faz

Autentica

Valida token OAuth do vendedor com Mercado Livre e resolve advertiser_id da conta.

Sincroniza

Busca lista de campanhas da API v2 do ML (/marketplace/advertising/MLB/advertisers/{id}/product_ads/campaigns).

Renderiza

Carrega view Alpine.js com campanhas em JSON; vendedor vê resumo: status (ativo/pausado), quantidade de anúncios, orçamento/dia.

Cria

POST para ML com nome, orçamento diário, estratégia de lucratividade e ACOS alvo (15% padrão) — sistema retorna campaign_id.

Gerencia

Alterna status (pause/resume) e atualiza orçamento via PUT na API v2; remove anúncios via DELETE.

Coleta

Recupera métricas dos últimos 30 dias (impressões, cliques, custo, CTR, pedidos, ROAS) e calcula índices de eficiência.

Exporta

Gera CSV ou TXT com relação de campanhas, status e orçamento para análise offline.

🌐 Vai pro Mercado Livre / Pix

GET /users/me — resolve ID do vendedor autenticado.GET /advertising/advertisers?product_id=PADS — obtém advertiser_id para Product Ads.GET /marketplace/advertising/MLB/advertisers/{id}/product_ads/campaigns — lista campanhas com IDs, names, budgets, status.POST /marketplace/advertising/MLB/advertisers/{id}/product_ads/campaigns — cria nova campanha (name, budget, status, strategy, acos_target).PUT /marketplace/advertising/MLB/advertisers/{id}/product_ads/campaigns/{campaign_id} — altera status (active/paused) e budget.GET /marketplace/advertising/MLB/advertisers/{id}/product_ads/campaigns/{id}/ads — lista anúncios dentro de uma campanha.POST /marketplace/advertising/MLB/advertisers/{id}/product_ads/campaigns/{id}/ads — adiciona item (MLB) à campanha.PUT /marketplace/advertising/MLB/advertisers/{id}/product_ads/campaigns/{id}/ads/{ad_id} — pausa/ativa um anúncio.GET /marketplace/advertising/MLB/advertisers/{id}/product_ads/campaigns/{id}/metrics?date_from=X&date_to=Y — métricas de campanha (impressões, cliques, custo, ROAS).

⚠️ AtençãoToken pode expirar: sistema tenta refresh automático com Mercado Livre; se falhar, vendedor vê erro e precisa reconectar conta em /lojas.ACOS alvo (15%) é default, mas deve ser ajustado conforme margem do produto — anúncios com ACOS alto (>25%) podem não ser rentáveis; sem custo cadastrado, sistema mostra 'Receita' não 'Lucro'.Adicionar mesmo MLB em duas campanhas simultâneas pode causar conflito de orçamento no ML; sistema não previne, vendedor deve atentar-se a overlaps.

11

Performance

Monitorar saúde da loja e visitas dos anúncios no Mercado Livre (raio-x com score, métricas de anúncios, visitas por item, reputação).

/central/performance /central/performance?tab=visitas /central/performance?tab=dashboard_ml · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1Acessa o painel e clica em 'Performance' (grupo Mercado Livre)

2Visualiza a tela inicial com 2 abas: Visitas (visitas por item) e Dashboard ML (contas conectadas)

3Na aba Visitas, seleciona período (7, 15 ou 30 dias) e vê ranking dos anúncios mais visitados com gráfico de barras

4Na aba Dashboard ML, vê resumo de todas as contas: total de anúncios, vendas dos últimos 30 dias, faturamento

5Acessa também ferramentas relacionadas: Raio-X (saúde da loja com score e recomendações), Reputação (nível MercadoLíder, cancelamentos, reclamações), ou Calculadora de margem

↓ o sistema reage por baixo

⚙️ O sistema faz

fetch

Busca contas Mercado Livre vinculadas do vendedor na base de dados

validate

Verifica permissão do usuário para acessar módulo Performance (checa plan_guard)

load

Carrega dados agregados de visitas e anúncios: total da conta, total por item (via API ML /items_visits/time_window)

calculate

Processa score de saúde calculando 5 dimensões: anúncios ativos, estoque, tempo de resposta a perguntas, vendas e completude de perfil

rank

Ordena anúncios por visitas descendente e coleta metadados (título, thumbnail, preço)

render

Exibe KPIs (total visitas, média diária, melhor anúncio) e lista detalhada de cada anúncio com barra de proporção

🌐 Vai pro Mercado Livre / Pix

GET /users/{ml_user_id}/items_visits/time_window — total de visitas da conta num períodoGET /users/{ml_user_id}/items/search — lista anúncios ativos do vendedorGET /items/{item_id}/visits/time_window — visitas diárias de um anúncio específico (opcional)GET /items?ids=... — metadados em lote (título, foto, preço dos anúncios)

⚠️ AtençãoVisitas em fase 3 de desenvolvimento: dados podem estar incompletos, pois integração com API ML de visitas foi iniciada recentementeScore de saúde do Raio-X calcula offline baseado em dados locais (anúncios, estoque, perguntas) e pode divergir da realidade no ML se há desyncReputação ML descontinuou /reviews/pending em 2026-04-30 — retorna 404; dados de reputação vêm apenas de transações e nível do termômetro

12

Saúde da Loja

Monitorar a saúde operacional das contas Mercado Livre do vendedor visualizando reputação, histórico de 60 dias, taxas de cancelamento e atraso para identificar problemas e solicitar limpeza de vendas comprometidas.

/relatorio-saude /relatorio-saude/exportar.csv /relatorio-saude/exportar.txt /relatorio-saude/conta/{accountId}.json · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1Acessa o painel e clica em 'Saúde da Loja' no menu do grupo 'Mercado Livre' (ícone: pacote)

2Visualiza um painel com 5 KPIs: contas críticas (vermelho), alertas (laranja), reconectadas (amarelo), pedidos atrasados e cancelados nos últimos 60 dias

3Consulta a tabela de lojas mostrando: vendedor, conta ML, reputação em termômetro de 5 barras coloridas, total de vendas, reclamações, atrasos, cancelados e taxa de problema (%)

4Filtra por criticidade (crítico, alerta, atenção, reconectar, OK) ou por vendedor para encontrar contas problemáticas

5Clica em uma linha da tabela para expandir detalhes da conta, visualizar histórico de problemas e, se necessário, solicitar remoção de venda comprometida (paga R$25 ao Rally)

6Exporta o relatório em CSV (Excel) ou TXT (legível por vendedor) para análise externa ou auditoria

↓ o sistema reage por baixo

⚙️ O sistema faz

Recupera

Busca todas as contas Mercado Livre vinculadas (respeitando escopo: vendedor vê só suas, gerente vê sua carteira, admin vê todas)

Sincroniza

Consulta dados oficiais do Mercado Livre: reputação do vendedor (nível de termômetro), transações completadas, canceladas, reclamações (claims), atrasos (handling_time), pedidos dos últimos 60 dias via API /users/{mlUserId}

Valida

Verifica se os dados estão frescos (sync < 7 dias) ou desatualizados (token expirado ou sincronização não feita); marca como 'reconectar' se precisar renovar credenciais

Calcula

Computa taxa de problema: (reclamações + atrasos + cancelados) / total de pedidos, em porcentagem

Classifica

Atribui criticidade a cada conta: crítico (reputação vermelha ou >5% problemas), alerta (laranja ou 2-5%), atenção (amarela), reconectar (dados velhos), OK (verde e <2%)

Consolida

Agrupa métricas por conta ML: uma linha por conta, mesmo que vendedor tenha múltiplas. Computa KPIs globais (total de contas críticas, alertas, pedidos atrasados em toda base)

Filtra

Restringe visibilidade por multi-tenant: vendedor vê apenas seus dados; gerente vê bindings; admin vê tudo conforme permissão; remove contas sem reputação útil (termômetro vazio)

🌐 Vai pro Mercado Livre / Pix

Reputação do vendedor: GET /users/{mlUserId} para obter seller_reputation.metrics (claims, cancellations, delayed_handling_time) e nível de termômetro (level_id: red, orange, yellow, green)Programas Decola: GET /users/{mlUserId}/programs para verificar se o vendedor é elegível ao Programa Decola (acelerador para novos sellers)Sincronização de pedidos: recupera lista de vendas do Mercado Livre com status (paid, shipped, delivered, cancelled), datas e comissões armazenadas em cache local (não faz chamada direta aqui, usa dados pré-sincronizados)

⚠️ AtençãoContas sem reputação ML: lojas recém-criadas ou sem histórico não aparecem no relatório porque o termômetro está vazio — dados não são úteis para análise operacionalDesincronização: token expirado ou sincronização > 7 dias não mostra dados confiáveis; sistema avisa 'RECONECTAR' e tenta renovação automática, mas vendedor pode precisar reconectar manualmenteComissão e frete desconhecido: métricas de custo (frete, comissão real) podem ser estimadas em vez de oficiais se a sincronização não capturou todos os pedidos — recomenda-se vincular produtos aos custos unitários para precisão

13

Modo Férias

Pausar todos os anúncios ativos do vendedor no Mercado Livre com um clique, preservando configurações e permitindo reativação automática na data agendada.

/ferias /central/anuncios /dashboard · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1Acessa o menu Mercado Livre → Modo Férias (ou /ferias direto) e visualiza o estado atual dos seus anúncios

2Define quando volta viajando (data e hora) ou deixa vazio para reativar manualmente — ambos opcionais

3Escreve mensagem automática personalizada para responder compradores durante o período (ex: 'Volto em 15/05')

4Clica 'Ativar Modo Férias' e confirma — todos os anúncios pausam em segundos no Mercado Livre

5Sistema reativa automaticamente na data escolhida (ou vendedor clica 'Reativar agora' em qualquer momento

6Vê resumo de quantos anúncios foram pausados e quantos voltaram ao ar

↓ o sistema reage por baixo

⚙️ O sistema faz

Autentica

Verifica login do vendedor e carrega permissões de acesso ao painel

Carrega

Busca todos os anúncios ativos nas contas Mercado Livre conectadas do vendedor

Pausa

Envia requisição PUT a cada anúncio ativo para o Mercado Livre (status_change=paused) agrupando por conta para reusar tokens de acesso

Persiste

Salva estado atual da pausa (data, mensagem, quais anúncios foram pausados) em arquivo JSON local do usuário

Reativa

Ao clicar reativar ou na data agendada, envia PUT ao Mercado Livre (status_change=active) restaurando anúncios ao estado anterior

Agenda

Cron job a cada hora verifica se algum usuário tem data de retorno no passado e dispara reativação automática

Notifica

Retorna contagem de sucesso (X pausados, Y falharam) e exibe alerta visual no painel informando quantos anúncios foram reativados

🌐 Vai pro Mercado Livre / Pix

PUT /items/{item_id} com status_change=paused (pausar anúncio no Mercado Livre)PUT /items/{item_id} com status_change=active (reativar anúncio no Mercado Livre)GET /users/{user_id}/items (listar anúncios ativos da conta para identificar quais pausar)

⚠️ AtençãoTimeout ao pausar muitos anúncios: se vendedor tiver mais de 200 anúncios ativos, o limite de 180 segundos pode ser insuficiente — considerar fila assíncronaDesincronização silenciosa: anúncio pode ficar pausado no Rally mas ativo no ML se chamada à API falhar — histórico de erro é limitado a 10 itensReativação automática não dispara: se cron job não estiver rodando ou se vendedor tiver plano expirado, anúncios não reativam mesmo após data agendada

14

Transportadoras

Gerenciar parceiros transportadores para entregas Flex e despachos on-demand (Frete Center, Flex, Uber Direct).

/transportadoras /transportadoras/catalogo /transportadoras/catalogo/{slug}/transportadoras/vincular /transportadoras/{id}/dispatches/transportadoras/lotes /transportadoras/reconciliacao /transportadoras/fechamentos · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

11. Acesse o menu Mercado Livre > Transportadoras (grupo oculto, em evolução) ou direto em /painel/transportadoras.

22. Explore o Catálogo de transportadoras: veja regiões, preços e avaliações. Clique em uma oferta para mais detalhes.

33. Vincule uma transportadora: obtenha um código de 8 caracteres da transportadora parceira e cole no modal ou acesse /painel/transportadoras/vincular?code=XXXXX.

44. Gerencie prioridades: com múltiplas transportadoras vinculadas, o sistema pedirá que você escolha qual notificar para cada pedido em /painel/pedidos.

55. Acompanhe dispatches: veja status (pendente, aceito, em rota, entregue), preço cobrado e pagamentos PIX por transportadora em /painel/transportadoras/{id}/dispatches.

66. Declare lotes pro hub consignado: em /painel/transportadoras/lotes, crie lotes de anúncios com quantidade esperada. O operador do hub confirma recebimento no scanner.

↓ o sistema reage por baixo

⚙️ O sistema faz

listar

Sistema busca todas as transportadoras vinculadas do vendedor (ativas), calcula KPIs: dispatches deste mês, quantidade em aberto e valor PIX a pagar.

validar

Sistema valida código de convite: checa cache local (CarrierInviteCode) ou consulta Frete.Center API para confirmar se código existe e não expirou (janela 72h).

vincular

Sistema cria vínculo (CarrierLink) entre vendedor e transportadora. Armazena PIX, chave tipo, e marcadores de hub consignado.

despachar

Quando vendedor marca pedido para dispatch, sistema consulta Frete.Center: cotação de frete, aceita/recusa, rastreia status em tempo real (pending → picked_up → in_transit → delivered).

conciliar

Sistema sincroniza descontos de frete ML com despachos Flex: se ML pagou frete direto, marca como pago; se Flex cobrou, gera débito PIX pendente.

receber

Operador do hub scaneia etiqueta de lote (ASN/WRO). Sistema registra recebimento e move estoque do nó origin_node_id para nó do hub automaticamente.

fechar

Sistema agrupa dispatches pagos por transportadora, gera comprovante PIX (upload para auditoria) e marca período como fechado.

🌐 Vai pro Mercado Livre / Pix

Frete Center API: valida código de convite (GET /carriers/invite-code/{code}).Frete Center API: busca transportadora por ID ou slug para catálogo público.Frete Center API: estima frete e cria dispatch (POST /dispatches), rastreia status.Mercado Livre API: verifica se pedido tem frete cobrado ou grátis (buyer paid frete), integra em reconciliação.Webhook Frete Center: recebe eventos de dispatch (status updates: picked_up, in_transit, delivered, refused) em tempo real.

⚠️ AtençãoMenu Transportadoras está oculto no painel (comentado em _sidebar_painel.php). Acessar direto em /painel/transportadoras exige plano 'frete_center_flex_dispatch' ativado.Com 2+ transportadoras vinculadas, cada pedido Flex novo exige escolha manual em /painel/pedidos. Auto-dispatch só funciona com 1 transportadora ativa; desvincule a segunda para retomar automático.Reconciliação: se ML descontou frete (buyer paid), mas Flex tambem cobrou, há risco de dupla cobrança. Sistema marca como 'pago' somente se ambas as fontes confirmam.

15

Fechamentos PIX

Vendedor visualiza fechamentos semanais consolidados de dispatches Flex por transportadora, localiza a chave PIX, efetua o pagamento direto e comprova o envio.

/transportadoras/fechamentos /transportadoras/fechamentos/{id}/comprovante/{filename} · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1Acessa o painel e clica em 'Fechamentos PIX' no menu Mercado Livre

2Vê lista de fechamentos por transportadora com período, número de dispatches e valor devido

3Localiza a chave PIX da transportadora (CPF/CNPJ/Telefone/Email) e realiza pagamento via seu banco

4Anexa o comprovante do PIX (foto ou PDF) no formulário de cada fechamento

5Aguarda confirmação da transportadora no painel Frete.Center; seu status muda para 'Pago'

↓ o sistema reage por baixo

⚙️ O sistema faz

consolida

Sistema agrupa todos os dispatches Flex com pagamento aberto por transportadora e período ISO (semanal), executado diariamente via cron

calcula

Para cada grupo (transportadora + semana), soma a quantidade de deliveries e o valor total devido

persiste

Cria ou atualiza registro de FlexSettlement no JSON DB do vendedor com status inicial 'aberto'

exibe

Carrega lista de fechamentos da tela, mapeando PIX e dados da transportadora via CarrierLink

recebe

Valida upload de comprovante (PDF/PNG/JPG até 5MB) e armazena em storage/uploads/flex_receipts

marca

Registra URL do comprovante no FlexSettlement como 'parcial' até transportadora confirmar em Frete.Center

confirma

Transportadora marca como pago no seu painel externo (webhook ou integração); status muda para 'pago' com timestamp

🌐 Vai pro Mercado Livre / Pix

Nenhum — PIX é direto entre vendedor e transportadora; Rally não toca no dinheiro

⚠️ AtençãoFechamentos são calculados apenas se houver dispatches Flex com status payment.status='open'; sem Flex ativo, a tela não mostra nadaComprovante é opcional no fluxo atual (marcado como 'parcial'); apenas anexo não força status 'pago' — requer confirmação da transportadora no Frete.Center

16

Minha Vitrine

Vendedor navega e gerencia produtos de seus fornecedores drop vinculados para publicar no Mercado Livre com precificação automática.

painel.xpto.com.br/fornecedorespainel.xpto.com.br/fornecedores/{id}/vitrinefornecedor.xpto.com.br/vitrine

👤 Você faz e vê

1Vendedor acessa 'Fornecedores' no painel e vê lista dos seus fornecedores drop vinculados (com nome, logo e pontuação)

2Clica em um fornecedor para entrar em 'Minha Vitrine' e visualiza o catálogo completo (fotos e nome dos produtos; preço oculto até acionar detalhes)

3Usa filtros (busca, categorias, estoque) e visualiza dados de custo + margem + estoque para cada produto via modal de detalhe

4Define preferências globais de precificação: margem (%), tipo de anúncio (bronze/ouro/premium), frete grátis e promoção De/Por

5Seleciona produtos (checkbox em lote) e clica 'Anunciar', OU clica botão de publicação individual (1-clique) para enviar ao ML imediatamente

6Vê confirmação de sucesso com URL do anúncio e feedback de erros (categoria faltante, custo zero, etc.)

↓ o sistema reage por baixo

⚙️ O sistema faz

buscar

Carrega lista de fornecedores vinculados ao vendedor com status, logotipos e pontuação

filtrar

Aplica categorias, busca por nome/SKU e filtra produtos ativos (sem pausados/inativos da vitrine)

carregar_detalhes

Busca dados completos do produto (fotos, EAN, dimensões, descrição) via endpoint /produto/{pid} ao abrir modal

ler_preferências

Recupera configurações salvas do vendedor (margem, tipo de anúncio, frete grátis, promoção) do banco de dados

calcular_preço

Aplica fórmula: Preço ML = Custo + Frete Médio, multiplicado por (1 + margem%), desconta taxa do Mercado Livre

publicar_ml

Envia anúncio ao Mercado Livre via API (fotos, dados, preço, atributos); retorna MLB (ID do item) e link permanente

persistir_prefs

Armazena preferências de margem, tipo de anúncio e modo de frete para reuso em próximos anúncios deste fornecedor

🌐 Vai pro Mercado Livre / Pix

POST para Mercado Livre: envia título, descrição, categoria, preço, foto (upload base64), atributos obrigatórios; retorna MLB + permalinkGET de dados de catálogo: valida NCM, consulta elegibilidade Flex, aplica regras de atributos obrigatórios do marketplace

⚠️ AtençãoContrato não aceito: vendedor vê modal de cláusulas antes de publicar; fluxo bloqueia até aceitar digitalmente (IP + timestamp auditado)Produto com dados incompletos (categoria não atribuída, custo zero, fotos ausentes): sistema exibe aviso de 'prontidão' (contador verde) e impede publicação até completarVinculação expirada ou plano sem permissão 'view_prices': vitrine pública oculta preços; painel do painel mostra erro 'Fornecedor não vinculado' se acessar rota diretamente

17

Vitrine Pública

Permitir que o vendedor configure e publique sua loja virtual pública com produtos curados, blog e domínio próprio, com visibilidade controlada por slug único e cidades.

/lojas (busca pública com filtros) /loja/{slug} (vitrine da loja)/loja/{slug}/p/{mlb} (página de produto)/loja/{slug}/blog (índice de posts)/loja/{slug}/blog/{post} (post individual)/perfil/loja (config no painel) /perfil/loja/produtos (curadoria ML + próprios) /perfil/loja/blog (gestão de posts) /api/v1/lojas/buscar (JSON público)/api/v1/lojas/{slug} (detalhe JSON) · clique pra abrir (já logado)

👤 Você faz e vê

1Vendedor acessa Perfil > Vitrine Pública no painel e preenche nome da loja, descrição, logo, cover e cores

2Configura contato (WhatsApp/telefone), horário de funcionamento, localidade e redes sociais opcionais

3Faz upload de domínio próprio (A+CNAME) e aguarda verificação da Hostinger/Cloudflare

4Curada produtos: liga/desliga anúncios do Mercado Livre visíveis e adiciona produtos próprios com fotos

5Publica posts no blog interno (suporta SEO score, imagens, tags)

6Acessa /loja/{slug} ou domínio próprio pra visualizar a vitrine ao vivo

↓ o sistema reage por baixo

⚙️ O sistema faz

Gerar

Sistema cria slug único automático ao salvar config da vitrine (baseado em shop_display_name ou nome do user)

Persistir

Salva todas as configurações (nome, descrição, logo, cover, cores, horas, categorias, contato) na tabela user com prefixo shop_*

Indexar

Carrega anúncios ativos do user (ML ou vitrine própria) filtrando por status e flag vitrine_visible

Buscar

API pública busca lojas por cidade, categoria ou termo, com facetas de filtro e pagination (24 itens/página)

Renderizar

Vitrine pública (VitrineController) renderiza HTML da loja com hero customizável, catálogo, blog, contactos e links legais

Verificar domínio

Sistema testa A+CNAME via Hostinger ou Cloudflare SaaS, aguarda SSL pronto, ativa quando verified_at não nulo

Gerar feed

Cria XML feed.xml para Google Shopping com todos os produtos visíveis (invalidado ao mudar config/produtos)

🌐 Vai pro Mercado Livre / Pix

GET /api/v2/items — busca anúncios ML do user para exibir na vitrine (paginado, com imagens)GET /api/v2/sites/MLB/reviews — busca avaliações do vendedor no Mercado Livre pra exibir na vitrine (reputação)GET /flex/v1/availability — verifica cobertura Flex por CEP pra avisar cliente sobre entrega express

⚠️ AtençãoDomínio próprio requer 2-3 dias após verificação da DNS para SSL ficar pronto (feedback claro no painel durante espera)Produtos ML continuam visíveis mesmo que desativados no Mercado Livre — flag vitrine_visible desacopla a curadoria da vitrine da vida real do anúncioFeed XML em cache pode ficar stale se vendedor edita produto rápido demais — cache invalidação ocorre ao salvar config

18

Produtos da Vitrine

O vendedor seleciona e gerencia produtos para sua vitrine pública, curando anúncios do Mercado Livre e adicionando produtos próprios, que são sincronizados em um feed Google Shopping para integração com Merchant Center.

/perfil/loja/produtos /loja/{slug}/feed.xml/loja/{slug} · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

11. Acessa o painel → seção Vitrine → clica em 'Produtos da Vitrine'

22. Visualiza dois painéis: seus produtos próprios (criáveis via formulário) e anúncios ativos do Mercado Livre

33. Para cada anúncio ML, usa um toggle para ativar/desativar sua visibilidade na vitrine pública

44. Cria produtos próprios preenchendo nome, preço, descrição e fazendo upload de fotos

55. A vitrine pública em /loja/{slug} exibe os produtos selecionados em uma galeria

66. Periodicamente, o feed XML gerado em /loja/{slug}/feed.xml é buscado pelo Google Merchant Center para sincronizar produtos em Google Shopping

↓ o sistema reage por baixo

⚙️ O sistema faz

carrega

Sistema obtém lista de anúncios ativos (ML) e produtos próprios (vitrine) do vendedor, respeitando a flag vitrine_visible de cada um

exibe

Renderiza dois blocos: produtos próprios com formulário de criação/edição, anúncios ML com toggle on/off para visibilidade

persiste

Salva alterações em tempo real: criação/edição/exclusão de produtos próprios, ativação/desativação de visibilidade de anúncios ML na tabela Announcements

constrói

Gera feed XML RSS 2.0 com namespace Google Shopping (LojaFeedService), mapeando cada produto para g:id, g:title, g:price, g:link (domínio próprio ou /loja/{slug}), g:image_link, g:condition, g:availability, g:brand, GTIN/MPN

cacheia

Armazena feed em storage/cache/shopping_feed_v2_*.xml com TTL 1h; Google refaz o fetch diariamente

publica

A vitrine pública em /loja/{slug} obtém os mesmos produtos via productsForLoja() e os exibe em galeria; /loja/{slug}/p/{mlb} fornece página de produto (landing para Merchant Center)

sincroniza

Envia ao Google Merchant Center via feed XML público em /loja/{slug}/feed.xml; Google Shopping aparece como outro canal de tráfego além de Mercado Livre

🌐 Vai pro Mercado Livre / Pix

GET /loja/{slug}/feed.xml → Google Merchant Center faz fetch diário do feed (autenticação via reivindicação de domínio)PUT para Mercado Livre API (legado) → quando produto é publicado no ML, Rally captura marketplace_item_id e preço para o feedGET em Google Shopping → listagem de produtos da vitrine após sincronização bem-sucedida do feed

⚠️ AtençãoDomínio próprio: se o vendedor reivindicar um domínio customizado no Merchant Center, os links de produto (g:link) devem ser do domínio verificado, não da Rally de Vendas — a tela não avisa visualmente dessa restriçãoRequisitos de dados: produto sem preço válido, foto ou permalink não entra no feed, causando silêncio sem aviso ao vendedorFoto formato: o feed usa ml_img() para converter imagens do ML para tamanho F (full), mas produtos próprios devem usar upload manual — sem validação de resolução mínima

19

Blog da Loja

Permitir que o vendedor crie e publique posts no blog da sua vitrine pública com otimização SEO e monetização via AdSense.

painel.xpto.com.br/perfil/loja/blogpainel.xpto.com.br/perfil/loja/blog/novopainel.xpto.com.br/perfil/loja/blog/{id}/loja/{slug}/blog/loja/{slug}/blog/{post}

👤 Você faz e vê

1O vendedor acessa o painel, clica em Vitrine > Blog da Loja e vê a lista de posts salvos (rascunhos e publicados)

2Clica em Novo Post ou Editar Post existente e preenche título, slug, capa, resumo, conteúdo (com editor visual WYSIWYG) e metadados SEO (descrição, palavra-chave, og:image, tags)

3Ao editar, vê em tempo real um score SEO (0-100) e um checklist com sugestões (título, densidade de palavras-chave, imagem, quantidade de subtítulos, etc)

4Faz upload de imagens inline dentro do editor (até 4MB, formatos JPG/PNG/WebP/GIF)

5Define status como Rascunho ou Publicado e salva; ao publicar, o post fica visível em /loja/{slug}/blog

6A vitrine pública do lojista mostra os posts publicados em grid (capa, título, resumo, data); clicando abre a página completa com conteúdo HTML, Open Graph, schema JSON-LD e anúncios Google AdSense

↓ o sistema reage por baixo

⚙️ O sistema faz

Listar

Carrega todos os posts do vendedor (rascunhos e publicados) ordenados por data de publicação mais recente, com score SEO e tempo de leitura estimado em cache

Validar

Calcula score SEO (0-100) checando título, conteúdo (mínimo 500 palavras), densidade de keywords, meta description (50-160 chars), imagem de capa e estrutura de subtítulos (H2); retorna score + detalhes + sugestões

Guardar

Salva o post (create/update) em JSON per-user com slug automático, status, timestamps (created_at/published_at/updated_at) e metadados SEO (title, meta_description, focus_keyword, og_image, canonical_url, tags)

Subir

Move a imagem de capa/editor para /public/uploads/loja/{userId}/blog/ com nome aleatório (img_[hex].ext) e retorna URL relativa

Renderizar (público)

Mostra grid de posts publicados em /loja/{slug}/blog com card (capa lazy-loaded, título, resumo, data); ao clicar, renderiza /loja/{slug}/blog/{post} com conteúdo HTML, Open Graph (og:title, og:image, og:description), schema JSON-LD (BlogPosting), e include do ads.txt para AdSense

Indexar

Inclui na sitemap.xml de cada vitrine: /loja/{slug}/blog (changefreq=weekly) e cada post publicado com slug (changefreq=monthly) e lastmod do updated_at

Deletar

Remove o post da coleção JSON do usuário com confirmação CSRF

🌐 Vai pro Mercado Livre / Pix

POST /perfil/loja/blog/score: envia título, meta_description, focus_keyword, cover_url, conteúdo HTML e recebe score SEO (0-100) com checklist + sugestões em JSON

⚠️ AtençãoBlog fica oculto em /loja/{slug}/blog se shop_blog_enabled não estiver ativo no perfil do vendedor — validar que o usuário tem a flag habilitada antes de usar o editor (status 404 caso contrário)Score SEO usa throttle de 3s mínimo entre requisições para evitar WAF; se o vendedor digita rápido, pode parecer travado. Draft local salvo em localStorage (7 dias) pode conflitar se sessão expirouImagens inline no editor devem ser <4MB e formatos específicos (JPG/PNG/WebP/GIF); se usuário tentar .SVG ou HEIC, será rejeitado. URLs absolutas no canonical_url/og_image são obrigatórias para SEO funcionar (não URLs relativas)

20

Cursos

O vendedor acessa cursos de capacitação, assistindo videoaulas, lendo materiais e respondendo quiz para elevar seu potencial de vendas.

/cursos /cursos/{id}/cursos/{id}/{lesson_id}/acelera /acelera/dia/{n} · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1Clica em 'Cursos' no menu de Crescimento do painel e vê a lista de treinamentos disponíveis (cursos criados pelo admin ou seu gerente).

2Escolhe um curso e clica para entrar; o player mostra videoaulas, PDFs, textos e quiz organizados em módulos com barra de progresso visível.

3Assiste cada aula, marca como concluída e navega pela próxima; se a aula tiver quiz, responde as questões (precisa passar em 70% para seguir).

4Acompanha seu percentual de conclusão em tempo real no topo da tela (ex: 45% completo).

5Opcionalmente, entra no 'Acelera' para participar de um programa de 180 dias com missões diárias, checkin de presença e prêmios por sequência.

↓ o sistema reage por baixo

⚙️ O sistema faz

Listar

Sistema busca cursos publicados visíveis para o vendedor (criados por admin ou seu gerente) e calcula o percentual de conclusão de cada um.

Renderizar

Exibe catálogo de cursos em cards com capa, título, resumo, e barra de progresso preenchida (ex: 45% — 7 de 15 aulas).

Carregar

Ao abrir um curso, carrega todos os módulos e aulas associados, e determina qual aula assistir (primeira não vista ou a última deixada aberta).

Reproduzir

Apresenta a aula no player (vídeo YouTube/Vimeo/nativo, PDF com anexos, ou texto HTML) com barra lateral mostrando todas as aulas do curso em ordem com status (concluída/pendente).

Marcar

Registra aula como concluída quando vendedor clica em 'Marcar como feito'; persiste no progresso e atualiza a porcentagem total do curso.

Avaliar

Se a aula for um quiz, processa respostas, calcula nota (pontos corretos ÷ total × 100) e bloqueia avanço se < 70% (permite tentar novamente).

Sincronizar

Atualiza progresso do curso em tempo real (barra, % concluído, status de cada aula) sem recarregar página; salva no banco JSON global.

⚠️ AtençãoQuiz com nota < 70% bloqueia a próxima aula até ser retentado; vendedor pode ficar desmotivado se pular muitas questões.Vídeos embarcados (YouTube, Vimeo) dependem de CDN externo; em conexões lentas, o player pode travá-lo.Progresso é local (por vendedor × curso); se o vendedor trocar de conta ou dispositivo, o histórico não sincroniza entre contas.

21

Check-in Diário

Vendedor registra venda do dia (faturamento + quantidade) e humor, recebendo feedback comparativo e mantendo streak de consistência diária.

/checkin /checkin/feito /checkin/historico · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

11. Acessa menu Crescimento → Check-in Diário (ou painel.rally.com.br/checkin).

22. Vê faturamento e pedidos de hoje dos marketplaces já preenchidos automaticamente; confirma ou corrige o valor de vendas fora dos marketplaces.

33. Seleciona seu humor (😡 😟 😐 🙂 😄) e escreve notas opcionais sobre o dia.

44. Clica 'Registrar check-in' e recebe página de sucesso com comparativas (vs ontem, vs média 7 dias, melhor dos 30 dias) + destaque motivacional.

55. Consulta histórico (últimos 60 dias) em /checkin/historico com tabela de data, faturamento, vendas, humor e notas.

66. Sistema mantém streak visível em ambas as telas (quantidade de dias seguidos com check-in registrado).

↓ o sistema reage por baixo

⚙️ O sistema faz

auto_fill

Sistema busca Orders do vendedor da data e preenche automaticamente faturamento_auto e vendas_auto a partir de marketplaces conectados.

validar

Valida data (Y-m-d), sentimento (um de: muito_triste, triste, neutro, feliz, muito_feliz), e valores de faturamento/vendas (não negativos).

upsert

Grava ou atualiza check-in no JSON do usuário (idempotente por user_id + data). Separa auto/manual e armazena faturamento total = auto + manual.

calcular_streak

Computa sequência de dias consecutivos com check-in terminando em hoje/ontem (função pura, não persiste).

gerar_insight

Extrai comparativas: today (faturamento, vendas, sentimento), yesterday (delta %), avg_7d (delta %), best_30d, ticket_médio, e gera 1 frase de dopamina (recorde, streak, delta, sem venda, etc).

renderizar

Exibe form.php (com 4 cards: Vendas Online, Vendas Manuais, Total Ao Vivo, Humor+Notas), done.php (com hero + comparativas), ou history.php (tabela 60 dias).

integrar_gamif

Check-in contribui indiretamente ao sistema de pontos/níveis (SellerGamificationService); gamificação é cálculo em tempo real sobre ml_orders, não persistida no check-in.

🌐 Vai pro Mercado Livre / Pix

Nenhum. Check-in é ritual local: auto-fill lê Orders do banco JSON do user (not API). Streak e insights são cálculos puros sobre histórico local.

⚠️ Atenção1. Auto-fill depende de ml_orders.json sincronizado — se marketplace desconectado, faturamento_auto = 0 (vendedor deve preencher manual).2. Streak quebra se saltar 1 dia (hoje ou ontem deve ter check-in; 2+ dias sem = streak volta a 0).3. Check-in é idempotente por data (POST /checkin com mesma data atualiza o existente) — se vendedor refizer o dia, valores novos sobrescrevem (não há log de edições).

22

Lives & Eventos

Vendedor visualiza e participa de lives institucionais (mentorias ao vivo, eventos) agendadas pela plataforma com gravações disponíveis.

/eventos /admin/eventos /admin/live /admin/live/publico /admin/live/campeao · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

11. Clica no menu Crescimento > Lives & Eventos do painel do vendedor

22. Vê lista de eventos futuros com data, horário, descrição e duração em minutos

33. Clica no botão 'Entrar' para acessar o link da live (se disponível)

44. Acessa a live ao vivo ou assiste à gravação posterior (se existir)

55. (Admin) Agenda novo evento via formulário com título, descrição, data, hora, URL da live e audiência-alvo (todos / plano acelera / enrolled)

66. (Admin) Envia lembretes via WhatsApp para usuários notificáveis do evento

↓ o sistema reage por baixo

⚙️ O sistema faz

Guard

Valida se vendedor tem permissão 'acelera.eventos' (plan guard) para acessar a tela

Query

Busca eventos institucionais futuros do banco JSON, filtrando por tenant e data agendada (scheduled_at >= agora)

Render

Exibe cartão para cada evento com data destaque, título, descrição, duração e botão 'Entrar' (se live_url existe)

Admin Create

Recebe dados do formulário, valida data/hora, cria novo evento no banco de dados JSON (InstitutionalEvent)

Admin Broadcast

Filtra audiência (todos / plano acelera / enrolled), valida quem já recebeu notificação (idempotência), dispara mensagem WhatsApp em lote

Track

Marca user_id como notificado no evento para evitar duplicação de lembrete

Public View

(Admin) Gera link público com token de 30 min para compartilhar live/tela campeão com token temporário

🌐 Vai pro Mercado Livre / Pix

Sem chamadas de API externa nesta tela — eventos e lives são gerenciados internamente via JSON Database e WhatsApp broadcast (serviço próprio da plataforma)

⚠️ AtençãoApenas usuários com permissão 'acelera.eventos' ativa veem a seção Lives & Eventos no menu (validação por PlanGuard)Links de live (live_url) são opcionais — se vazio, o botão 'Entrar' não aparece (sem erro, apenas oculto)Idempotência: mesmo após múltiplas chamadas de broadcast do mesmo evento, cada usuário recebe WhatsApp uma só vez (controle via notified_user_ids)

23

Grupos Telegram

Expor lista pública curada de 132 canais Telegram brasileiros (10k+ membros) em 15 nichos e capturar leads via bot deeplink para nurture.

/grupos /grupos/{niche}/grupos/{niche}/unlock · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1Clica em 'Grupos Telegram' (item 132) no menu Crescimento do painel ou acessa rallydevendas.com.br/grupos

2Navega pelo hub público: escolhe um nicho (Promoções, Shopee, Ofertas, Cupons, Amazon, etc.)

3Na landing SEO de cada nicho, vê 3 grupos em acesso direto + lista de outros bloqueados

4Preenche email OU WhatsApp na caixa de desbloqueio

5Recebe link de bot (t.me/RallyBot?start=grupos_niche_code) que entrega a lista completa no Telegram

6Clica no link, o bot valida o código e envia todos os grupos do nicho como mensagem

↓ o sistema reage por baixo

⚙️ O sistema faz

Valida

Confere se o niche existe, se email/WhatsApp é válido e aplica rate limit (3 unlocks/h por IP)

Gera

Cria registro de lead com unlock_code 8 chars alfanuméricos (sem 0/O/1/I para evitar confusão)

Monta

Constrói deeplink do RallyBot com parâmetros: grupo_niche_codigo para validação server-side

Armazena

Persiste lead em storage/json_db/group_unlock_leads.json com status=pending, email/WhatsApp e UTM

Retorna

Responde com JSON contendo bot_url para redirecionar o browser direto para o Telegram

Entrega

Bot recebe /start grupos_niche_code, valida unlock_code e envia lista de grupos como inline keyboard

Marca

Registra lead como status=delivered com tg_chat_id para cruzar em nurture sequence posterior

⚠️ AtençãoDeeplink do bot deve manter formato exato 'grupos_{niche}_{code}' — qualquer variação invalida a entregaOs 132 canais são carregados de telegram_groups.json (importado via TGStat); inatividade detectada por revalidação manual marca is_alive=falseEmail duplicado ou taxa esgotada (3 unlocks/hora) rejeitam unlock — usuário vê mensagem de erro no frontend

24

Ferramentas

Fornecer análise financeira e validação de anúncios para otimizar a rentabilidade das vendas no Mercado Livre.

/ferramentas/rentabilidade /ferramentas/relatorio /ferramentas/fotos-ml /integracoes/mercadopago · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1O vendedor clica em 'Ferramentas' na seção Extras do painel

2Escolhe entre: Rentabilidade (simular lucro de produtos), Relatório (análise de vendas), Checar Fotos (validar imagens contra regras ML) ou integração com Mercado Pago

3Insere dados como preço de venda, custo do produto e outras variáveis de custo

4O sistema calcula margem líquida, impostos por regime tributário e lucro esperado

5Visualiza relatório de P&L com devoluções separadas, saldo recebido do MP e alertas de reconciliação

6Exporta dados em CSV, Excel ou PDF para análise externa

↓ o sistema reage por baixo

⚙️ O sistema faz

Carregar

Busca anúncios e pedidos do usuário na base de dados local (JSON).

Calcular

Computa margem líquida usando preço bruto, comissão do ML (real ou estimada), frete, custo do produto, impostos e custos de publicidade.

Reconciliar

Compara valor esperado do ML com saldo efetivamente recebido no Mercado Pago, identifica retenções ou divergências.

Agrupar

Separa vendas válidas de devoluções, soma totalizações por período e regime tributário (CPF/MEI/Simples Nacional).

Validar

Avalia fotos de anúncios contra 20+ regras de qualidade do ML (dimensões, sobreposição de texto, marca d'água).

Exportar

Gera arquivo (CSV, XLSX ou PDF) com colunas de receita, custos, lucro e status para auditoria fiscal/contábil.

Conectar

Opcionalmente sincroniza com conta Mercado Pago (OAuth) para obter saldo oficial e status de liberação de valores.

🌐 Vai pro Mercado Livre / Pix

Valida foto contra regras JPEG/PNG (dimensões mín/máx, aspect ratio, texto em fundo, marca)Consulta saldo de conta no Mercado Pago (se conectada via OAuth)

⚠️ AtençãoComissão estimada quando falta sincronia real dos pedidos do ML — leitura desatualizada pode gerar margem incorretaCusto do produto vazio ou não sincronizado com anúncios — exibe alerta 'custo desconhecido' para que usuário vincule manualmentePeríodos de reconciliação MP podem levar 5-7 dias — nem todos os pedidos mostram saldo recebido imediatamente

25

Pesquisa de Mercado

Pesquisar concorrentes no Mercado Livre em tempo real, analisar preços/tendências e clonar anúncios vencedores sem sair do painel.

/pesquisa-mercado /pesquisa-mercado?tab=search /pesquisa-mercado?tab=my_store /pesquisa-mercado?tab=paste_html /pesquisa-mercado?tab=trends /pesquisa-mercado?tab=catalogo · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1Acessa Extras → Pesquisa de Mercado no menu lateral

2Digita uma palavra-chave (ex: airfryer) na aba Buscar no ML ou cola URL/HTML de página listada no Mercado Livre

3Seleciona a fonte: Rally Catalog (indexado, rápido) ou Mercado Livre direto (dados vivos)

4Vê resultados com preço, quantidade à venda, dias no ar e score Rally; filtra por preço e condição se quiser

5Clica em Clonar neste anúncio para copiar de um concorrente vencedor pra sua loja

6Usa abas adicionais: Analisar minha loja (comparação local vs pool), Tendências (Google Trends), Concorrência de Catálogo (repasse + buy-box)

↓ o sistema reage por baixo

⚙️ O sistema faz

Busca

Consulta palavra-chave contra o Rally Catalog (pool indexado em 6h) ou chama API pública do Mercado Livre ao vivo; se API bloqueia (403), faz scraping HTML público como fallback.

Normaliza

Padroniza dados do item (id, título, preço, disponibilidade, vendas, foto, permalink) para exibição consistente.

Cache

Guarda resultado por 6 horas compartilhado entre todos os vendedores (dados ML são públicos); avita chamadas repetidas à API.

Analisa

Calcula estatísticas: mediana de preço, distribuição de concorrentes, histórico de vendas, oportunidades de posicionamento (tabela ao vivo vs histórico).

Renderiza abas

Monta visão em tabs: busca de palavras (Buscar no ML), self-analysis (Analisar minha loja), bypass via HTML (Colar HTML ML), Google Trends, e competição por catálogo (repasse + buy-box).

Gera insights

IA nativa sugere estratégia: gap de preço, sazonalidade, produto sem fotos (risco), itens com estoque zerado, pausa recomendada.

Clonar

Prepara fluxo integrado: clica Clonar → vai pra wizard de anúncio com dados do vencedor (título, preço, fotos) pré-preenchidos.

🌐 Vai pro Mercado Livre / Pix

GET /sites/MLB/search?q=X&limit=50 (API pública Mercado Livre — busca por palavra-chave)GET /items/{MLB_ID} (API pública ML — detalhes de um anúncio)POST /pesquisa-mercado/parse-html (servidor Rally faz parsing HTML quando usuário cola página ML direto)

⚠️ AtençãoMercado Livre pode bloquear a API pública (403) em certos IPs/períodos; nesse caso o sistema fallback para scraper HTML ou oferece aba Colar HTML como workaround.Rally Catalog tem TTL 6h — dados de busca não são 100% ao vivo, mas suficientemente frescos (mostrador de age: 'dados de 2h atrás' etc.).Extensão Chrome Rally permite coleta cooperativa, mas sem ela o pool cresce mais lentamente em categorias niche; aba Colar URL/HTML sempre funciona como bypass.

26

Checar Fotos

Validar fotos dos anúncios contra as regras do Mercado Livre (resolução, proporção, fundo branco) e permitir download com dica para melhorar via IA generativa.

/ferramentas/fotos-ml /ferramentas/fotos-ml/check /ferramentas/fotos-ml/baixar · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1Acessa menu Extras > Checar Fotos no painel do vendedor

2Visualiza lista de anúncios próprios à esquerda, cada um com thumbnail e contagem de fotos

3Clica em um anúncio para ver análise automática: score (0-100) em cores + checks de quantidade/resolução/proporção/fundo/texto

4Visualiza galeria das fotos com preview em lightbox ao clicar, e botão Baixar para salvar cada imagem

5Copia o prompt de IA pré-gerado que indica como melhorar a foto em Gemini/ChatGPT (remover fundo, centralizar, etc)

6Baixa foto via proxy do Rally, abre Gemini/ChatGPT, cola prompt, anexa foto, gera versão melhorada e reuploada no ML

↓ o sistema reage por baixo

⚙️ O sistema faz

Busca

Carrega lista de todos os anúncios do vendedor (até 400, filtrados por status ≠ deleted) com título, thumbnail e contagem de fotos

Analisa

Ao clicar em anúncio, faz fetch das imagens do CDN do ML e verifica: quantidade (0 a 12), resolução (px ≥500 ok, ≥1200 recomendado), proporção da capa (1:1 ideal), cor das bordas da capa (branco ≥240 RGB)

Pontura

Gera score 0-100 subtraindo penalidades por erros (−30) e alertas (−12), e lista até 7 checks com status ok/warn/error/info

Renderiza

Mostra painel direito com score colorido, checks em 2 colunas, galeria de fotos com números, lightbox, e prompt de IA copiável

Download

Quando vendedor clica 'Baixar', proxeia requisição para https://http2.mlstatic.com/* com curl, valida MIME type (jpg/png), e envia como attachment com nome foto_N.ext

Prompt

Monta texto instruindo especialista em ecommerce a melhorar a foto para regras do ML: fundo #FFFFFF, produto 80%, sem texto/preço/selo, 1:1, ≥1200px, iluminação uniforme

Cópia

Oferece botão 'Copiar prompt' que escreve no clipboard do vendedor via navigator.clipboard.writeText(), permitindo colar direto no chat da IA

🌐 Vai pro Mercado Livre / Pix

Valida características de imagem remota do ML CDN: detecta dimensões [w,h] via getimagesizefromstring() PHP, sensibilidade 4s por fotoDetecta cor de borda via GD Library imagecolorat() em 8 pontos (cantos + meios das bordas) para estimar fundo branco (≥240 R,G,B em ≥75% das amostras)Gera prompt textual (não API call) que o vendedor copia para Gemini ou ChatGPT passando a foto baixada, recebendo imagem melhorada manualmente

⚠️ AtençãoTimeout de 4s por imagem remota: se CDN do ML estiver lento ou foto removida, check vira 'info' (não pode certificar).Detecção de texto/selo/logo é apenas lembrete manual — o GD não identifica OCR, depende de revisão visual do vendedor.Download via proxy limita a URLs autorizadas (regex #^https://http2\.mlstatic\.com/[A-Za-z0-9/_\-\.%]+$#) — qualquer URL fora do padrão retorna erro 400.

27

Prompts de IA

Criar e reutilizar prompts de IA personalizados para gerar títulos, descrições, fichas técnicas, análises e respostas de anúncios.

/ia/prompts /api/ia/prompts/api/ia/prompts/salvar/api/ia/prompts/excluir/api/ia/prompts/default · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1Acessa Painel > Extras > Prompts de IA (menu na barra lateral)

2Visualiza lista de prompts criados com filtro por tipo (Título, Descrição, Ficha técnica, Análise, Resposta)

3Clica em 'Novo prompt' ou edita um existente em modal com nome, tipo e corpo do prompt

4Insere variáveis como {produto_nome}, {categoria}, {pergunta} usando botões de atalho

5Marca prompt como padrão do seu tipo (estrela) — usado automaticamente em gerações

6Salva e vê aparecer na lista; deleta prompts se não precisar mais

↓ o sistema reage por baixo

⚙️ O sistema faz

Carrega

Busca todos os prompts do vendedor (tabela ai_prompts.json) com filtro por tipo e prompts já marcados como padrão

Valida

Verifica tipo válido (Título/Descrição/Ficha/Análise/Resposta), nome entre 1-60 caracteres e corpo entre 10-4000 caracteres

Armazena

Persiste prompt em JSON por usuário (users/{id}/ai_prompts.json) com timestamps created_at e updated_at

Marca padrão

Define prompt como padrão do seu tipo — desmarca outros prompts do mesmo tipo automaticamente

Descarta

Soft-deleta prompt (marca deleted_at) sem remover registro, para auditoria

Interpola

Substitui placeholders {var} no corpo do prompt pelos valores reais (produto_nome, categoria, etc.) na hora da geração

Resolve

Na hora de gerar IA, segue prioridade: prompt_id explícito > prompt padrão do tipo > default do sistema

🌐 Vai pro Mercado Livre / Pix

POST /api/ia/prompts/salvar: envia nome, tipo, corpo e marca padrão ao servidorGET /api/ia/prompts: recupera lista de prompts do usuário em JSONPOST /api/ia/prompts/excluir: marca prompt como deletadoPOST /api/ia/prompts/default: define prompt como padrão do seu tipo

⚠️ AtençãoPrompt precisa ter pelo menos 10 caracteres — validação no frontend e backendSó pode ter um prompt padrão por tipo — sistema desmarca os outros automaticamenteVariáveis {produto_nome}, {categoria} etc. não existem no prompt = são substituídas por string vazia na geração

28

Plugins & Extensão

Permitir vendedores gerenciar plugins de terceiros (incluindo extensão Chrome) e parceiros criar/manter integrações com acesso via Bearer token (em evolução).

/plugins /plugins/install /plugins/uninstall /parceiro/hub /ext/token /ext/status /ext/sync /ext/import-product /ext/clone-announcement · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1Vendedor acessa o painel e clica em 'Plugins & Extras' no menu Extras do grupo lateral.

2Vê a galeria de plugins (gratuitos, premium e trial) com descrição, preço e status de instalação.

3Clica 'Instalar' em um plugin — o sistema valida plano, cobra se necessário, ativa e retorna com flash de sucesso.

4Pode desativar um plugin instalado clicando 'Desativar' (desativa sem cobrar novamente).

5Para extensão Chrome: abre o popup → aba 'Conta' → copia token Bearer via GET /ext/token (gerado da sessão autenticada do painel).

6Cola o token na extensão Chrome; ela passa a fazer requisições autenticadas (GET /ext/analise, /tracking, POST /ext/import-product, /ext/clone-announcement) com Authorization Bearer.

↓ o sistema reage por baixo

⚙️ O sistema faz

Busca

Lê lista global de plugins aprovados (Plugin::all) e plugins instalados do usuário (PluginService::getUserPlugins).

Indexa

Monta dicionário installedIds[plugin_id] = status (active/inactive/revoked) para render rápido.

Valida

Na instalação: confere se plugin existe, está aprovado e se modelo de preço é compatível com plano do usuário (via PluginBillingService).

Cobra

Se plugin pago: PluginBillingService::chargeInstall incrementa wallet/créditos ou registra débito mensal.

Cria

Insere registro em user_plugins (JSON local) com id, plugin_id, status, pricing_model, paid_amount, installed_at.

Gera token

GET /ext/token cria ExtToken (Bearer) com TTL (expires_at), armazena hash em storage, devolve plain_token ao painel para vendedor copiar.

Retorna

Após ação (install/uninstall), redireciona com flash (sucesso/erro) e reload do marketplace.php.

⚠️ AtençãoTokens Bearer de extensão têm TTL fixo — extensão precisa renovar periodicamente via GET /ext/token; sem login válido no painel, devolve erro 401.Instalação de plugin pago requer saldo em carteira ou plano pago ativo; cobrança falha silenciosamente (erro em flash, sem exceção).Sem dados públicos no blueprint_flows.php — tela está em evolução e não tem fluxo mapeado oficialmente para usuários finais.

29

Blog Oficial

Acessar o blog público oficial do Rally de Vendas a partir do painel do vendedor para ler guias, tutoriais e estratégias de vendas.

/ (listagem de posts) /?q=termo (busca de artigos) /?categoria=X (filtragem por categoria) /?p=N (paginação) /{slug} (leitura do post)/{slug}/story (AMP/WebStory)/ (usuário logado no painel) · clique pra abrir (já logado)

👤 Você faz e vê

11. No painel do vendedor, clica no menu lateral no grupo 'Extras'

22. Clica no link 'Blog Oficial' (abre em nova aba, subdomain blog.xpto.com.br)

33. Vê a listagem de artigos em cards com imagem, título, categoria, tempo de leitura e data

44. Busca por termo digitando na caixa de pesquisa OU filtra por categoria (Guia, Estratégia, Ferramenta, etc)

55. Clica em um card para ler o artigo completo com índice, autor, comentários e artigos relacionados

66. Rolando a página, vê progresso de leitura, opções de compartilhamento e captura de lead (WhatsApp)

↓ o sistema reage por baixo

⚙️ O sistema faz

carrega

BlogIndexService lê índice leve (~500KB) com posts publicados, ignora o arquivo pesado blog_posts.json (13MB) na memória

renderiza

Lista até 12 posts por página em grid com imagem, categoria colorida, tempo estimado de leitura e data. Suporta busca por termo no título/keyword/descrição e filtragem por categoria

navega

Usuários logados veem blog integrado ao painel (com sidebar). Públicos veem versão standalone com header/footer público

exibe post

BlogController::post() busca artigo por slug, valida existência (404 se não encontrado), registra visualização via BlogTrackingTrait

enriquece

Adiciona metadados SEO (JSON-LD Article + BreadcrumbList + FAQ schema), Open Graph, Twitter Card, RSS link. Integra Google AdSense (ca-pub-2442955258067136)

captura

POST /api/lead coleta WhatsApp + nome do leitor e envia checklist automaticamente via BlogLeadService. Salva em blog_leads.json

tracked

Google Analytics 4 (GA4) e Microsoft Clarity rastreiam visualizações. Pixel de tracking invisível registra evento de view. Meta Pixel (881126080985979) dispara PageView.

🌐 Vai pro Mercado Livre / Pix

POST /blog/api/lead — envia WhatsApp do leitor para captura de contato (resposta JSON {success: true/false})

⚠️ AtençãoBlog posts.json tem 13MB — BlogController DEVE usar BlogIndexService (índice de 500KB), nunca carregar o arquivo inteiro na RAMAdSense e Analytics disparam píxeis de rastreamento — verificar CSP nonce e GDPR ao integrar novo tracking terceiroURLs canônicas e JSON-LD são críticas para SEO — manter consistência entre og:url, canonical e sitemap.xml gerado em tempo real

30

Afiliados

O vendedor gerencia seu programa de afiliados MLM de 2 níveis para ganhar comissões de 25%/5% sobre novos clientes indicados.

/afiliados /afiliados/apply · clique pra abrir (já logado)

👤 Você faz e vê

11. Clica em 'Afiliados' no menu (grupo Parceiros) do painel do vendedor

22. Sistema exibe painel com status: inativo ou ativo com rede de indicações (L1 e L2)

33. Se inativo, clica em 'Quero ser afiliado' para ativar (aprovação automática para planos pagos, pendente para free)

44. Copia seu link de indicação único (com código referral) ou compartilha direto via WhatsApp

55. Visualiza a rede de indicados (Nível 1 diretos + Nível 2 indiretos) com comissões acumuladas

66. Acompanha ganhos pendentes, pagos e taxa de conversão dos cliques (últimos 30 dias)

↓ o sistema reage por baixo

⚙️ O sistema faz

load

Sistema lê status do vendedor em users.json (affiliate_status: active/pending/blocked) e carrega árvore de indicados (L1 diretos + L2 indiretos via L1)

apply

Ao clicar 'Quero ser afiliado', gera código referral único, ativa imediatamente (auto_approved=true para planos pagos), cria link global de indicação no AffiliateLink

calc

Calcula comissões L1 (25% do plano = R$100-500/mês) e L2 (5% do plano = R$20-100/mês) para cada indicado com first_paid_at há ≥90 dias (carência contra churn)

rank

Atribui tier ao afiliado (Bronze 1-2, Prata 3-9, Ouro 10-24, Diamante 25+ indicados ativos) e bônus mensal por tier (0 a R$400/mês)

track

Registra clicks (utm_source=affiliate) e conversões (first_sale + recurring) em AffiliateConversion pending até elegibilidade (90d) ser atingida

payout

Cron mensal credita Wallet do afiliado com conversões elegíveis, respeitando cap individual (R$1.000/mês) e cap global (15% MRR da empresa)

⚠️ Atenção⚠️ Carência 90 dias: comissão só crédita se o indicado pagou há ≥90 dias (previne fraude e churn rápido)⚠️ Limite mensal R$1.000 por afiliado + 15% MRR global: payout para automaticamente se atingir cap (configurável em affiliate_config.json)⚠️ Aprovação automática mudou em 2026-05-21: agora TODOS os planos (free + paid) são auto-aprovados; admin apenas bloqueia suspeitos

31

Campanhas

O vendedor acessa seu painel de programa de afiliados para criar links de campanha com rastreamento UTM, acompanhar comissões de indicações e visualizar ofertas especiais de aquecimento de vendas.

mkt.xpto.com.br/painel/indicacao?tab=afiliado (dashboard afiliado)mkt.xpto.com.br/painel/afiliado/links (lista e cria campanhas)mkt.xpto.com.br/painel/afiliado/relatorios (extrato de comissões)painel.xpto.com.br/esquenta (ofertas aquecimento)mkt.xpto.com.br/afiliados (landing pública)mkt.xpto.com.br/ranking (ranking de afiliados)

👤 Você faz e vê

1Na seção 'Parceiros' do menu, clica em 'Campanhas' para ir ao painel de afiliado

2Visualiza seu link principal (sem parâmetros) e cria novos links com nome, URL de destino e tags UTM (source, medium, campaign) para rastrear cada canal

3Copia o link gerado e compartilha via WhatsApp, email ou Instagram para trazer pessoas pro Rally

4Acompanha em 'Extrato' quantas vendas geraram cada campanha e sua comissão acumulada

5Acessa 'Esquenta' para ver ofertas especiais que pode ativar (-5% em anúncios por 14 dias) para impulsionar vendas

↓ o sistema reage por baixo

⚙️ O sistema faz

autenticação

Valida que o usuário está logado e tem acesso ao programa de afiliados (status=active no banco)

carrega

Busca link principal (kind=global) e todas as campanhas do vendedor (kind!=global) no banco de dados

renderiza

Exibe modal para criar nova campanha com campos: nome, URL destino, UTM source/medium/campaign

cria

Persiste novo link no banco com código único, associado ao user_id do vendedor

copia

Gera URL completa (domínio afiliado + código + parâmetros UTM) em campo readonly + botão copiar

rastreia

Sistema de click tracking registra cada clique no link para calcular conversões e comissões no mês

🌐 Vai pro Mercado Livre / Pix

GET /api/ml/campanhas - Listar campanhas disponíveis no Mercado Livre (DEAL, Lightning, etc) que o vendedor pode participarPOST /api/ml/campanhas/participar - Adicionar produto a uma promoção ML com preço específicoPOST /api/ml/campanhas/sair - Remover produto de uma campanha ML

⚠️ AtençãoLinks criados pelo afiliado são para rastrear o próprio tráfego (ex: Instagram) - não confundir com campanhas de promoção do Mercado Livre (Ofertas do Dia, Lightning, etc)Sorteio mensal (R$500 para afiliado com mais conversões) é automático (roda 1º do mês, sem ação do usuário)Se o vendedor estiver bloqueado ou com status cancelado, não consegue acessar painel nem criar campanhas

32

Extrato

Permitir que o vendedor afiliado acompanhe todas as comissões geradas (pendentes e pagas) e as transferências de créditos para a Wallet.

/indicacao?tab=afiliado /afiliado/relatorios /afiliado/links · clique pra abrir (já logado)

👤 Você faz e vê

1Clica em Parceiros → Extrato no menu do painel (grupo 'Parceiros')

2Vê o saldo de comissões em 4 cartões: Pendente (aguardando 90 dias), Pago (já na carteira), Lifetime (total acumulado) e MRR (recorrente do mês)

3Filtra conversões por status (Todas, Pendentes, Pagas, Canceladas) e vê a tabela com data, tipo (1ª venda ou recorrente), nível (L1 ou L2), valor, origem, status e data de pagamento

4Volta à tela anterior para gerenciar links de campanha (/painel/afiliado/links)

↓ o sistema reage por baixo

⚙️ O sistema faz

Autoriza

Verifica autenticação e permissão de acesso ao programa de afiliados (roles: admin, gerente, drop, cliente)

Valida

Confirma que o usuário está ativo no programa de afiliados; se não, bloqueia acesso

Carrega

Busca todas as conversões (AffiliateConversion) do usuário ordenadas por data decrescente

Calcula

Agrega estatísticas em centavos: soma de pending, paid, lifetime e MRR (recorrente do mês corrente)

Renderiza

Exibe KPIs (cartões de saldo) e tabela filtrável com todos os registros de comissão com status visual

Formata

Converte centavos em BRL (ex: 5000 centavos = R$ 50,00) e exibe datas em ISO 8601 para legibilidade

⚠️ AtençãoComissões pendentes só liberam após 90 dias do primeiro pagamento do indicado; vendedor novo pode ficar frustrado vendo saldo travadoSe o indicado (L1) cancelar o plano retroativamente ou sofrer chargeback, a comissão é cancelada/revertida automaticamente (clawback)Nível 2 (L2) só funciona se o referidor (L1) foi indicado por outro afiliado ativo; indicações orgânicas não geram cadeia L2

33

Configurações

O vendedor acessa suas configurações de perfil pessoal, dados fiscais, nacionalidade, chaves de IA próprias (BYOK), verifica seu WhatsApp e escolhe COMO recebe cada tipo de notificação no WhatsApp.

/central/config /perfil /perfil/dados /perfil/negocio /perfil/senha /perfil/ia /perfil/ia/conectar /perfil/ia/testar /perfil/ia/remover /perfil/whatsapp/enviar-codigo /perfil/whatsapp/verificar /perfil/exportar-dados /perfil/notificacoes · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

11. Clica em 'Config & Conta' no menu lateral (ícone de engrenagem)

22. Vê as abas 'Meu Perfil', 'Carteira Digital', 'Contas ML' e 'Fornecedores'

33. Na aba 'Meu Perfil', acessa seu avatar, nome, email e plano; clica em 'Editar Perfil' ou 'Alterar Senha'

44. Em '/perfil', preenche dados pessoais: nome, email, WhatsApp, nacionalidade, país de operação, CPF/CNPJ, PIX

55. Verifica email/WhatsApp clicando no botão 'Verificar' (recebe código por email ou WhatsApp)

66. Na aba 'Integrações & IA', ativa suas próprias chaves de Claude, Gemini ou OpenAI; testa cada uma antes de salvar

77. Na aba 'Notificações', escolhe por tipo (Vendas / Perguntas & mensagens / Reclamações & devoluções) COMO receber no WhatsApp: imediato (1 mensagem por evento), resumo diário às 09:30, ou desligado

↓ o sistema reage por baixo

⚙️ O sistema faz

carrega

Busca dados do usuário no banco: perfil, plano, contas Mercado Livre, preferências

renderiza

Exibe abas (Meu Perfil, Carteira, Contas ML, Fornecedores) conforme permissões do usuário

valida

Verifica email/nome (min 3 caracteres), email único se mudar, WhatsApp com +55, nacionalidade contra lista de países

criptografa

Protege chaves de IA (Claude/Gemini/OpenAI) antes de salvar no banco

envia

Dispara código de verificação por email (SMTP) ou WhatsApp (API Blipei)

testa

Faz chamada real à API do provedor de IA para confirmar chave válida

exporta

Gera JSON com todos os dados do usuário (LGPD Art. 18 V: dados pessoais, anúncios, pedidos, histórico de IA)

notifica

Salva o modo de notificação por tipo. No imediato dispara 1 WhatsApp por evento; no diário enfileira o evento no mesmo resumo das 09:30 que já vai pra gerente/fornecedor/admin; desligado não envia. Default: imediato (zero mudança pra quem já usa).

🌐 Vai pro Mercado Livre / Pix

Envia SMS/WhatsApp via Blipei (serviço terceirizado de mensageria) para verificação de númeroFaz teste de autenticação contra API Claude (Anthropic), Gemini (Google AI Studio) ou OpenAI (se chaves BYOK forem preenchidas)

⚠️ AtençãoDocumento fiscal (CPF/CNPJ) é opcional, mas avisa se o formato não bater com o país de operação selecionadoSe mudar nacionalidade de BR para outro país, PIX é limpo automaticamente (PIX só funciona no Brasil)Chaves de IA não são salvas em pleno texto—são criptografadas e o sistema mostra apenas uma máscara (ex: 'sk-ant-***')

34

Meu Plano

Vendedor visualiza e gerencia seu plano atual, vê período de trial, compara planos (free vs paid/managed) e realiza upgrade com checkout flexível via Mercado Pago (cartão, PIX ou boleto).

/planos /planos/checkout /integracoes/mercadopago · clique pra abrir (já logado)

📸 Tela real · clique pra ampliar

👤 Você faz e vê

1Clica no ícone de coroa no menu lateral (seção 'Gestão') ou no drawer completo para acessar 'Meu Plano'

2Vê seu status atual: trial ativo com dias restantes, trial expirado, ou plano ativo (free/paid/managed)

3Compara lado a lado os planos: free (ilimitado ML + anúncios) vs paid (R$ 29,90/mês + R$ 1,00 por venda com vitrine, blog, shopping)

4Interage com simulador de custo: arrasta barra para estimar quantas vendas faria no mês e vê custo total amortizado por pedido

5Escolhe método de pagamento (Cartão = assinatura automática via Mercado Pago ou PIX/Boleto = pagamento único mensal)

6Clica 'Ativar Plano' ou 'Gerar Código PIX' e é levado ao checkout do Mercado Pago

↓ o sistema reage por baixo

⚙️ O sistema faz

Carrega

Busca plano atual do usuário (free/paid/managed), verifica status do trial (ativo/expirado/sem trial), calcula dias restantes se ativo, obtém todos os planos ativos do sistema

Compõe

Renderiza estado visual do trial/plano em banner destacado (aviso, relojoura de contagem regressiva ou cadeado de expiração)

Exibe

Mostra dois cards comparativos de plano gratuito vs plano pago com listas de features verificáveis (perguntas, mensagens, raio-X, vitrine, blog, suporte)

Calcula

Busca histórico de vendas no mês atual, apresenta simulador que recalcula taxa mensal + taxa por venda conforme usuário arrasta slider

Valida

Verifica se Mercado Pago está configurado (MP_ACCESS_TOKEN em .env), se não nega acesso com mensagem de erro

Direciona

POST /planos/checkout recebe choice de plan_id, period, payment_method; cria preference (método flex = PIX/boleto com link avulso; card = preapproval com assinatura automática) e redireciona ao initPoint do MP

Registra

Salva pref_id e billing_status (flex_pending ou preapproval_pending) para webhook processar confirmação; após sucesso, plan muda de free para paid, TrialGuardMiddleware libera acesso pleno

🌐 Vai pro Mercado Livre / Pix

Mercado Pago: createPreapproval (cartão com renovação automática) envia dados de cobrança recorrente; createPreference (PIX/boleto) gera link de checkout avulso; webhook valida approval e credita wallet + muda plan do usuário

⚠️ AtençãoTrial expirado bloqueia acesso via TrialGuardMiddleware — whitelist inclui /planos para que usuário possa ver opções de upgrade; se não chegar aqui, permanece bloqueado em redirect loopBUG-PLAN-CUSTOM-PRICE-001: administrador pode sobrescrever custom_per_order_price do usuário no admin; view respeita override individual, não preço defaultRDV-MP-FLEX-001: dois fluxos paralelos — 'card' usa Preapproval (debit automático, só cartão/conta MP) vs 'flex' usa Preference avulsa (aceita PIX, boleto, cartão mas sem renovação automática); vendedor escolhe ambos a cada mês

35

Ativar a Loja com checkout

Transformar a vitrine (que era só catálogo) numa loja que vende direto: o cliente compra, paga e recebe, tudo pelo Rally.

/perfil/loja · clique pra abrir (já logado)

Configurar minha loja →

👤 Você faz e vê

1Em Vitrine pública, as configurações ficam em 3 abas: Loja, Vender e Avançado.

2Na aba Vender, liga "Habilitar venda direta" — aí aparece o botão Comprar na vitrine.

3Escolhe o que a vitrine mostra: produtos próprios + Mercado Livre, só próprios ou só ML.

4Define como recebe: chave PIX (gera QR no checkout), Mercado Pago (conecta a conta dele) e/ou pagamento na entrega.

5Informa o CEP de origem (digite o CEP que rua/cidade preenchem sozinho via ViaCEP — você só põe o número; se não achar, preenche à mão) e liga os métodos de frete (Correios, Uber, Flex, retirada). Tudo isso só vale se você vende produto próprio; quem mostra só Mercado Livre não precisa configurar pagamento/frete.

↓ o sistema reage por baixo

⚙️ O sistema faz

Salva

Grava a config da loja (pagamento, frete, origem) no perfil do vendedor.

Gateia

O botão Comprar só aparece com a venda direta ligada; anúncio de ML sempre vai pro Mercado Livre.

Conecta

Mercado Pago via OAuth do próprio vendedor — o dinheiro cai na conta dele, nunca na do Rally.

⚠️ AtençãoLogin Google no checkout exige a origem do domínio autorizada no Google Cloud Console.Login Mercado Livre do comprador exige registrar a redirect_uri /checkout/ml/callback no app ML.

36

Comprar na vitrine (checkout rápido)

O comprador fecha o pedido em 1-2 cliques, mobile-first, com o endereço já preenchido.

/loja/{slug}/loja/{slug}/checkout

👤 Você faz e vê

1Na página do produto, clica em "Comprar agora".

2Se identifica em destaque com Mercado Livre (puxa nome + e-mail + telefone + endereço) — ou Google (1 toque) ou como visitante.

3Digita só o CEP: o endereço é preenchido sozinho (ViaCEP) e o frete é cotado na hora.

4Escolhe a entrega, escolhe o pagamento (PIX, Mercado Pago ou na entrega) e finaliza.

5Cai na página do pedido com o status e as instruções de pagamento.

↓ o sistema reage por baixo

⚙️ O sistema faz

Identidade

Login ML/Google/visitante cai no CRM de clientes (Buyer) — recompra fica em 1 clique.

Endereço

CEP via ViaCEP + cotação de frete em tempo real pelo gateway (Correios/Uber/Flex/retirada).

Lead

Captura o lead (nome+WhatsApp) já no passo 1 — base da recuperação de carrinho.

Pedido

Recalcula tudo no servidor (nunca confia no preço do cliente) e cria o pedido da loja.

🌐 Vai pro Mercado Livre / Pix

OAuth comprador: troca o code, lê /users/me + /users/{id}/addresses pra pré-preencher o endereço (não cria conta nem marketplace_account).

⚠️ AtençãoProduto de ML não entra no carrinho — só produto próprio é vendido pelo checkout (ML é fulfilled pelo Mercado Livre).Google One Tap só renderiza em domínio autorizado; em domínio próprio do lojista cai pra ML/visitante.

37

Pagamento da loja (PIX, Mercado Pago, na entrega)

Receber o pagamento do jeito que o vendedor escolheu — direto na conta dele.

/loja/{slug}/pedido/{token}

👤 Você faz e vê

1PIX: a página do pedido mostra QR Code + copia-e-cola com o valor já preenchido; o comprador paga e manda o comprovante.

2Mercado Pago: o comprador é levado ao checkout do MP do vendedor (PIX, cartão, boleto — com o parcelamento que ele liberou).

3Na entrega: o comprador combina e paga ao receber.

↓ o sistema reage por baixo

⚙️ O sistema faz

PIX

Gera o BR Code (EMV + CRC16) sem API de banco — a confirmação é o vendedor que dá (comprovante).

Mercado Pago

Cria a preference na conta MP do vendedor (token dele) com as opções configuradas (parcelas/cartão/boleto/PIX).

Confirma

O webhook do MP confirma o pagamento automático (busca no token do vendedor) e marca o pedido pago.

🌐 Vai pro Mercado Livre / Pix

Mercado Pago: createPreference na conta do vendedor (collector próprio) + webhook /webhooks/pagamento/mercadopago?store_seller=X pra confirmar e dar baixa.

⚠️ AtençãoPIX da chave própria não confirma sozinho (o banco não avisa o Rally) — pra automático, use o Mercado Pago PIX.Mercado Pago só aparece no checkout se o vendedor conectou a conta dele (MP Connect).

38

Frete + Etiqueta da loja

Cotar o frete certo pelo CEP e despachar com etiqueta — mesmo quando a transportadora não fornece uma.

/loja/{slug}/checkout/loja/pedidos · clique pra abrir (já logado)

👤 Você faz e vê

1No checkout, o comprador vê as opções de entrega válidas pro CEP dele (com preço e prazo).

2Depois de pago, o vendedor abre o pedido em /loja/pedidos e clica em Etiqueta.

3Imprime a etiqueta (remetente + destinatário + QR) e cola no pacote.

↓ o sistema reage por baixo

⚙️ O sistema faz

Cota

Gateway de frete: Frete.center (transportadora vinculada), Uber Direct (≤5km, same-day), Flex (mesmo dia em SP), retirada, ou estimativa.

Regras

Uber só aparece se o destino está na área (~5km); Flex só na região de SP e com produto elegível (peso/dimensão).

Etiqueta

Loja/Uber/Flex não têm etiqueta de transportadora → o Rally gera a própria (imprimível, com QR). Correios/transportadora trazem a oficial.

⚠️ AtençãoFrete grátis acima de um valor mínimo zera a opção padrão (transportadora).Sem CEP de origem configurado, Uber e a cotação de transportadora não rodam.

39

Gerenciar pedidos + recuperar carrinho

O vendedor acompanha as vendas, confirma pagamento, despacha e recupera quem deixou o carrinho.

/loja/pedidos /loja/leads · clique pra abrir (já logado)

Ver pedidos da loja

👤 Você faz e vê

1Em /loja/pedidos vê os pedidos por status, confirma o PIX manual, marca como enviado e abre a etiqueta.

2É avisado na hora de cada nova venda (WhatsApp → Telegram → e-mail); o comprador recebe e-mail em "pago" e "enviado".

3Em /loja/leads vê o Kanban de carrinhos abandonados e exporta o CSV pra recuperar do jeito dele.

↓ o sistema reage por baixo

⚙️ O sistema faz

Confirma

PIX manual / na entrega vira "pago" com um clique; Mercado Pago confirma sozinho pelo webhook.

Avisa

Vendedor via NotifyDispatchService (cascata); comprador via e-mail transacional (zero risco de ban WhatsApp).

Recupera

O lead+carrinho fica no CRM do vendedor; a recuperação é canal DELE (Blipei/SMTP) ou export manual — o Rally não dispara nada.

⚠️ AtençãoA recuperação por WhatsApp/e-mail é responsabilidade do vendedor (integração dele) — evita risco de ban da conta do Rally.

40

Avaliações + Produto de fornecedor (drop) na loja

Ter prova social na página do produto e vender produto de fornecedor pela loja própria.

/loja/avaliacoes /fornecedores/{id}/vitrine · clique pra abrir (já logado)

👤 Você faz e vê

1Avaliações: o comprador avalia o produto (estrelas + texto) e aparece na hora; o vendedor esconde as ruins em /loja/avaliacoes.

2Pode importar as avaliações reais do mesmo produto no Mercado Livre pra ter prova social desde o dia 1.

3Drop na loja: no catálogo do fornecedor, clica "Adicionar à minha loja" — vira produto próprio (personalizável) com vínculo oculto ao fornecedor.

4Quando esse produto vende na loja, o fornecedor é acionado pra despachar e o vendedor paga o custo (fluxo drop que já existe).

↓ o sistema reage por baixo

⚙️ O sistema faz

Avalia

Avaliações entram visíveis (auto-aprova); o vendedor modera escondendo as problemáticas.

Importa

Puxa as reviews do MLB pelo token do vendedor (/reviews/item/{MLB}), com dedup.

Drop

Venda paga de produto com drop_origin cria um pedido drop → o fornecedor despacha e o vendedor paga (margem = preço da loja − custo).

🌐 Vai pro Mercado Livre / Pix

Avaliações: GET /reviews/item/{MLB} (token do vendedor) pra importar a prova social do anúncio do mesmo produto.

⚠️ AtençãoImportar avaliações exige uma conta Mercado Livre conectada e o MLB do mesmo produto.O pedido drop entra na pipeline de /fornecedores — o vendedor paga o fornecedor (PIX/wallet) e ele despacha.

Mapa do painel — 40 fluxos

Cadastro

Conectar conta Mercado Livre

Dashboard

Assistente de IA

Anúncios

Dados Fiscais

Vendas

Clientes

Comunicação

Marketing (Mercado Ads)

Performance

Saúde da Loja

Modo Férias

Transportadoras

Fechamentos PIX

Minha Vitrine

Vitrine Pública

Produtos da Vitrine

Blog da Loja

Cursos

Check-in Diário

Lives & Eventos

Grupos Telegram

Ferramentas

Pesquisa de Mercado

Checar Fotos

Prompts de IA

Plugins & Extensão

Blog Oficial

Afiliados

Campanhas

Extrato

Configurações

Meu Plano

Ativar a Loja com checkout

Comprar na vitrine (checkout rápido)

Pagamento da loja (PIX, Mercado Pago, na entrega)

Frete + Etiqueta da loja

Gerenciar pedidos + recuperar carrinho

Avaliações + Produto de fornecedor (drop) na loja