Central de Ajuda

Primeiros passos

1. Criar conta e workspace

O primeiro acesso cria seu workspace principal. Depois voce pode adicionar outras empresas e workspaces consolidados pelo seletor de empresa.

2. Conectar o Tiny

Abra Configuracoes -> Integracoes ERP, informe o token do Tiny e salve. E esse token que libera NF, pedidos, produtos, contas a pagar e contas a receber.

3. Rodar a primeira sincronizacao

Use o botao Sincronizar no canto superior direito. No primeiro dia, prefira um sync manual completo para trazer detalhes de NF, pedidos e estoque.

• NF de saida e entrada
• Pedidos
• Produtos e estoque
• Contas a pagar e contas a receber

4. Revisar o DRE

Depois do primeiro sync, abra o DRE, confira pendencias e ajuste o DE/PARA DRE antes de usar os numeros como referencia gerencial.

5. Opcional: conectar Mercado Livre

Se voce vende no MeLi, abra Integracoes -> Mercado Livre. Quando o app OAuth estiver configurado, basta clicar em conectar e autorizar no Mercado Livre. Em ambientes sem OAuth, tambem existe o modo por token direto.

Configuracoes gerais

Campo	O que faz
Token Tiny ERP	Libera a sincronizacao principal do Orbita.
Janela de NF / CP	Define o periodo retroativo usado no sync manual.
Auto-sync	Quando ativo, Tiny e Mercado Livre sincronizam a cada 4 horas.
Custos de SKU	Melhoram margem, precificacao, plano de negocios e leituras gerenciais. A flag de creditos informa se o custo manual ja veio liquido de ICMS/PIS/COFINS.
Taxas por plataforma	Define comissao, taxa fixa, outros custos e frete padrao para Mercado Livre, Shopee, Tray e site.
PIS/COFINS padrao	Usado como complemento quando as NFs do SKU nao trazem PIS/COFINS no historico de impostos.
Perfil da empresa	Da contexto para o Assistente IA e para o Plano de Negocios com IA.
OpenAI / IA	Mesma chave usada no assistente e no botao Gerar com IA do plano.

DRE

O DRE cruza NF, contas a pagar, custos marketplace, CMV e ajustes contabeis para formar a leitura gerencial do mes.

Regras importantes da versao atual

• Receita: usa o total da nota como base principal.
• Devolucoes: usam o total da nota e aparecem separadas da receita.
• CP: entram por competencia no DRE, nao por vencimento.
• Detalhe: o drill-down tenta reproduzir o mesmo total do cabecalho, inclusive em Comissoes e Fretes no modo conciliado.

Ajustes manuais

Administradores podem usar Ajustes Contabeis para registrar reclassificacoes e acertos mensais sem mudar a estrutura do relatorio.

Pendencias

Se categoria, fornecedor ou natureza nao estiverem bem mapeados, o DRE pode deixar itens fora ou mandar para secoes erradas. Revise as pendencias sempre que notar divergencia com o contador.

Fluxo de Caixa

Fluxo de Caixa olha quando o dinheiro entra ou sai. Por isso ele pode divergir do DRE no mesmo mes.

O que entra

• recebimentos e vendas do periodo
• contas a pagar por vencimento
• lancamentos manuais

CMV

O CMV atual usa a estrutura EI + C - EF. O painel no topo do DRE mostra exatamente os valores usados no calculo.

Como ajustar EI e EF

No proprio DRE, administradores podem preencher Estoque Inicial e Estoque Final. Depois de salvar, o workspace passa a usar esses valores manuais.

Como Compras e montado

As compras do CMV usam NF de entrada registradas, com base no totalNota. Regras de CFOP podem ser personalizadas por workspace.

Margem por NF

A Margem por NF usa custo de SKU, impostos e custo de marketplace para enxergar rentabilidade por documento.

Prioridade do custo marketplace

• Mercado Livre API para pedidos ML integrados
• CSV importado para canais sem API ou retroalimentacao
• Pedido + configuracao quando so existe hint de frete ou taxa
• Fallback de configuracao como ultima opcao

Custos e creditos tributarios

Ao importar custos de SKU, marque se os custos manuais ja estao liquidos de creditos. Se a caixa estiver marcada, o Orbita usa o custo como voce importou. Se estiver desmarcada, o pricing pode abater os percentuais configurados de ICMS e PIS/COFINS.

SKU na margem

A tabela de margem considera os itens da NF para expor SKU e ajudar a investigar divergencias por produto, canal e documento.

CSV ainda continua valendo?

Sim. O CSV continua sendo o caminho principal para Shopee, Amazon, Olist e outros canais ainda nao cobertos por API de custo real.

Indicadores percentuais medios

O topo da tela exibe cards com os percentuais medios sobre receita do periodo filtrado:

• CMV medio: custo de mercadoria medio ponderado das NFs.
• Impostos medios: percentual medio de impostos operacionais sobre receita.
• Deducoes medias: percentual medio de comissao, frete e outros custos de marketplace.

Impostos operacionais

O calculo de impostos operacionais usa ICMS, IPI, DIFAL e ST da propria NF, complementado por PIS/COFINS calculado ou configurado. Tributos aproximados IBPT nao sao usados como imposto operacional.

Badges da tabela

A tabela usa badges curtos para mostrar a origem do custo marketplace, por exemplo [MeLi], [CSV], [ord] e [cfg].

Mercado Livre

O modulo de Mercado Livre serve para trazer pedidos, custos reais, anuncios e dados de promocao do MeLi para dentro do Orbita.

Conexao OAuth

Quando o app do Orbita estiver configurado, o cliente final so precisa clicar em Conectar agora, autorizar no Mercado Livre e voltar para o Orbita. O workspace e identificado por um state seguro gerado no servidor.

Modo token direto

Quando o cliente usa uma aplicacao propria ou quando o OAuth global ainda nao esta disponivel, a tela tambem aceita configuracao manual:

• Client ID
• Access Token
• Client Secret e Refresh Token, quando houver renovacao automatica

URL de retorno

A propria tela mostra a callback URL para cadastrar no MeLi Developers:

Primeiro sync

Depois de conectar, rode um sync manual usando o periodo do filtro geral do Orbita. O sync importa pedidos, consulta custos reais e atualiza o cache de anuncios.

Sync por etapas

O sync do Mercado Livre opera em etapas independentes:

• Etapa 1 - Pedidos/custos: importa pedidos e consulta custos reais do MeLi.
• Etapa 2 - Anuncios/promocoes: sincroniza listagens, status e elegibilidade promocional.
• Etapa 3 - Precificacao: reaplicacao das regras para anuncios habilitados.

Se o MeLi retornar HTTP 429, a etapa afetada e adiada. O sistema respeita o cabecalho Retry-After quando presente e retoma automaticamente; pedidos/custos ja importados sao preservados como ok_parcial e nao sao descartados.

Um lock por workspace impede dois syncs simultaneos para o mesmo workspace.

O que o Orbita pode alterar no MeLi

• Pedidos e custos: podem ser sincronizados automaticamente para alimentar margem.
• Promocoes: so podem ser alteradas em anuncios habilitados na Precificacao Automatica.
• Estoque: nunca e alterado pelo Orbita.
• Preco base: so muda quando a regra do anuncio permitir explicitamente. Em casos de credibilidade do MeLi, o Orbita orienta uma acao manual em vez de manter aumento automatico.
• Duplicar anuncio: acao admin sensivel disponivel no painel de anuncios. Exige confirmacao explicita e ciencia de que pode criar e publicar um item novo no MeLi. Em caso de falha apos a criacao, o sistema tenta rollback/fechamento do item criado.

Anuncios pausados

O Orbita identifica anuncios pausados por falta de estoque e tambem anuncios pausados que venderam nos ultimos 15 dias. Esses casos podem aparecer em alertas e em relatorio diario por e-mail para os usuarios da empresa.

Top MLB ao vivo

O painel Top MLB ao vivo usa pedidos MeLi ja importados no Orbita, nao NFs do Tiny. Pedidos cancelados sao ignorados automaticamente.

• Ranking: top anuncios (MLB) por unidades vendidas e por receita no periodo filtrado.
• Colunas: pedidos, receita, media diaria (unidades / dias filtrados) e tendencia versus o periodo anterior equivalente.
• Qualidade MLB: saude do anuncio (itemHealth) quando disponivel na resposta do MeLi; exibida como percentual com badge colorido.

Shopee e Tray

Shopee e Tray aparecem como integracoes e como canais de calculo de preco. O nivel de automacao real depende do conector disponivel para cada marketplace.

Shopee

A Shopee usa OAuth quando o app parceiro estiver homologado. Enquanto isso, o Orbita aceita cadastro assistido/manual de anuncios para simular precificacao, registrar regras e manter uma trilha operacional.

Tray

A Tray possui fluxo OAuth scaffoldado e captura de callback. A troca automatica do code por token ainda depende da etapa final com credenciais e endpoint confirmados da Tray. Para precificacao, a Loja Oficial usa as taxas configuradas em Configuracoes.

Taxas por plataforma

Em Configuracoes, revise comissao, taxa fixa, outros custos e frete padrao para cada plataforma. A calculadora de precificacao usa esses perfis para separar Mercado Livre, Shopee, Tray e site.

BI Comercial

BI Comercial cruza NF e pedidos para mostrar volume por canal, top produtos e evolucao de vendas.

• devolucoes reduzem a performance do periodo
• itens sem classificacao adequada de canal podem distorcer os rankings
• metas por canal e vendedor ajudam a comparar o realizado com o esperado

Estoque

O modulo de Estoque combina saldo atual, minimo, historico de giro e snapshots para apoiar reposicao e CMV.

Niveis de alerta

• Zerado: produto vendido sem saldo
• Critico: cobertura abaixo do limite critico
• Baixo: cobertura abaixo do limite de atencao
• OK: sem alerta relevante

Precificacao

Precificacao usa historico de NF, custos marketplace, impostos historicos e custos SKU para sugerir precos alvo por item. O modulo suporta produtos simples, KITs e calculo separado por plataforma.

1. busque o SKU (simples ou KIT)
2. escolha a plataforma: Mercado Livre, Shopee, Tray ou site
3. no Mercado Livre, escolha o perfil de anuncio: Classico ou Premium
4. revise custo, taxa fixa, impostos, comissao, frete e outros custos; KITs mostram tabela de componentes e custo reconstituido
5. ajuste a margem desejada e analise os cenarios arrojado, moderado, conservador e queima
6. salve o estudo se quiser retomar depois

KIT

SKUs do tipo KIT usam a composicao cadastrada no ERP para derivar custo pelos componentes. Quando houver historico, o Orbita tambem pode reconstruir historico sintetico quando os componentes aparecem juntos na mesma NF. Se nao houver composicao ou custo suficiente, a tela avisa que a simulacao precisa de preenchimento manual.

Impostos e frete

Impostos tentam usar a media historica do SKU nas NFs. Se PIS/COFINS vier zerado no historico, o Orbita pode complementar com a aliquota padrao configurada. Frete prioriza custos de marketplace importados; se nao houver historico, usa o fallback da plataforma.

Precificacao automatica

A Precificacao Automatica aplica regras por anuncio. Nenhum anuncio e habilitado por padrao: o cliente precisa ativar explicitamente por MLB/SKU ou por filtro.

• Filtro em lote: aplica regra a anuncios cujo SKU ou titulo contenha a palavra-chave informada. O filtro tambem pode carregar a margem minima configurada para o grupo.
• Regra individual: permite ajustar perfil, cenario, margem minima e flags de preco base por anuncio. Tambem e possivel forcar um preco final objetivo para o MLB especifico, com prioridade sobre as regras gerais mesmo que exija promocao acima do padrao.
• Simular: calcula o que seria atualizado sem alterar nada no MeLi.
• Aplicar: envia a alteracao suportada para os anuncios habilitados. A fila opera em ciclos e retoma lotes automaticamente quando o MeLi limita a API.

Cenarios disponiveis

• Ultima simulacao: repete exatamente o ultimo run salvo para o anuncio.
• Conservador / Moderado / Arrojado: os tres cenarios classicos do motor de precificacao.
• Preco de queima: margem minima aceitavel para girar estoque.

Mercado Livre

No MeLi, a automacao trabalha preferencialmente por promocoes. O Orbita preserva estoque e so altera preco base quando a regra permitir explicitamente subir ou reduzir base.

• Priorizar percentual de desconto: quando nao houver rebate disponivel, o sistema prioriza o desconto percentual direto na promocao.
• Permitir subir base sem promocao: autoriza subir preco base mesmo quando nao existe promocao ativa, dentro do limite configurado.
• Permitir subir base com promocao: autoriza subir o preco base para viabilizar a promocao.
• Promocao publica ativa abaixo do alvo: se ja existe uma promocao publica ativa com preco abaixo do alvo, a automacao aceita temporariamente desde que a margem minima seja respeitada. Se a margem minima nao for respeitada, o sistema indica acao manual.
• Credibilidade MeLi: se o MeLi recusar o desconto por credibilidade, o Orbita destaca acao manual para o cliente decidir se quer subir base fora da automacao e aguardar liberacao da promocao.

Shopee e Tray

Shopee e Tray podem ser cadastradas manualmente na grade para simulacao e log operacional. A aplicacao real segue dependente de conector especifico de cada canal.

Orcamento

O modulo de Orcamento compara o DRE real com as metas por linha. Ele respeita a mesma estrutura do DRE e recalcula as linhas derivadas automaticamente.

IA no Orbita

O Orbita tem duas frentes de IA com a mesma chave configurada no sistema:

• Assistente Orbita: responde perguntas usando dados do workspace.
• Plano de Negocios com IA: gera diagnostico, metas, KPIs e projecoes.

Como deixar a IA menos generica

Preencha o perfil da empresa em Configuracoes e mantenha vendas, estoque, contas e custos sincronizados. Quanto melhor o dado do workspace, mais util fica a resposta.

Gerar com IA

No modulo Plano de Negocios, administradores podem clicar em Gerar com IA para atualizar sugestoes com base nos dados reais do negocio.

Pre-Vendas IA

O modulo de Pre-Vendas IA usa as perguntas sem resposta do Mercado Livre e responde com o auxilio do modelo de linguagem configurado.

• Fonte: perguntas pendentes do vendedor no MeLi; nao usa outros canais.
• Seguranca: a chave OpenAI do cliente e armazenada criptografada e nao retorna em claro por nenhum endpoint.
• Modo assistido: o Orbita sugere a resposta e o operador aprova antes do envio.
• Modo automatico: respostas sao enviadas diretamente sem aprovacao manual; o worker executa a cada 60 min por padrao (configuravel via MELI_PRESALE_AI_TICK_MINUTES) e processa 1 pergunta por ciclo por padrao. Para processar mais por ciclo, configure maxQuestions explicitamente no workspace (maximo 200).
• Prompt: usa dados do proprio anuncio (titulo, descricao, atributos). Nao inventa especificacoes; responde apenas com o que esta disponivel.
• Log: cada pergunta e registrada com status pendente, enviada ou erro para rastreabilidade.

DE/PARA DRE

O DE/PARA define como categoria financeira, fornecedor e outras pistas do Tiny viram linha do DRE.

• use regex quando a categoria tiver muitas variacoes
• revise as pendencias depois de cada grande mudanca de cadastro no ERP
• em NF de entrada, o fornecedor tambem pode ser decisivo para a classificacao

Sincronizacao

Sync manual

Use o botao Sincronizar do topo quando precisar atualizar tudo com mais profundidade. Esse e o melhor caminho depois de cadastrar Tiny, Mercado Livre ou fazer ajustes grandes de custo.

Auto-sync

O scheduler roda a cada 4 horas. Ele cobre:

• Tiny ERP
• Mercado Livre, quando o workspace ja estiver configurado
• reaplicacao da precificacao automatica apenas em anuncios habilitados
• relatorios diarios de anuncios pausados com venda recente e acoes manuais de preco base

No Tiny, o autosync e mais leve para economizar chamadas. Por isso, o sync manual continua sendo recomendado no inicio do uso e em fechamentos mensais.

Sync de estoque

O estoque ainda merece um sync dedicado quando voce quiser melhorar CMV, alertas de ruptura ou cobertura por SKU.

Painel de fila MeLi

O painel de sincronizacao pode exibir o estado atual da fila do Mercado Livre: itens pendentes, proxima retomada estimada e slot/ciclo em execucao. Util para acompanhar syncs grandes ou verificar se um 429 esta sendo aguardado.

API Keys

As API Keys servem para integrar o Orbita com automacoes externas sem expor o login do usuario.

• gere a chave em Configuracoes
• copie a chave na hora da criacao
• use em X-Api-Key ou Authorization: Bearer

Multi-empresa e consolidado

Cada empresa pode ter seu proprio workspace, e o Orbita tambem suporta workspaces consolidados para agrupar varias operacoes.

• workspaces simples sincronizam direto do Tiny
• workspaces consolidados agregam os workspaces-fonte
• EI/EF e ajustes contabeis podem existir no proprio consolidado