Orbita — Central de Ajuda

Primeiros passos

1. Criar conta e workspace

Acesse login.html, clique em "Criar conta" e preencha nome, email e senha. Um workspace (empresa) é criado automaticamente.

2. Configurar o token do Tiny ERP

No Tiny ERP, vá em Configurações → Integrações → API e copie seu token. No Orbita, clique em Configurações no menu lateral, cole o token no campo "Token Tiny ERP" e salve.

Segurança: O token é salvo localmente e usado apenas para chamadas à API do Tiny. Nunca é compartilhado.

3. Executar o primeiro sync

No menu Sync, clique em "Sincronizar agora". O Orbita vai importar:

Notas Fiscais de saída e entrada (últimos meses configurados)
Contas a pagar
Produtos e estoque
Pedidos

Dependendo do volume, o sync pode levar alguns minutos. O progresso é exibido em tempo real.

4. Configurar o DE/PARA de categorias

Para o DRE funcionar, suas categorias do Tiny precisam ser mapeadas para seções do DRE (ex: "Comissões" → "Despesas Comerciais"). Veja a seção DE/PARA DRE.

Configurações gerais

Campo	O que faz
Token Tiny ERP	Chave de API do Tiny para sync de dados. Obrigatório para qualquer sync.
Meses de NF para sync	Quantos meses retroativos de NFs importar. Padrão: 3. Aumentar impacta o tempo de sync.
Meses de CP para sync	Quantos meses retroativos de Contas a Pagar importar. Padrão: 3.
Dias críticos de estoque	SKU com cobertura ≤ X dias → alerta "crítico" (vermelho). Padrão: 7.
Dias baixos de estoque	SKU com cobertura ≤ X dias → alerta "baixo" (amarelo). Padrão: 15.
Janela de análise de estoque	Quantos dias de histórico de vendas usar para calcular a média diária. Padrão: 30.
Depósito para estoque	Se configurado, usa apenas o saldo deste depósito. Deixe em branco para usar o saldo total.
Auto-sync	Quando ativo, o servidor sincroniza automaticamente a cada 4 horas.

DRE — Demonstração do Resultado

O DRE calcula o resultado financeiro mensal com base nas NFs e contas a pagar importadas do Tiny.

Como o DRE é calculado

NFs de saída com categorias mapeadas alimentam as seções de receita
NFs de entrada (fornecedores) alimentam o CMV e as seções de custo
Contas a pagar são classificadas por competência (não por vencimento)
Fórmulas do schema calculam Receita Líquida, Lucro Bruto, etc.

Filtros disponíveis

Mês: selecione o mês/ano para visualizar
Visão: resumo (totais por seção) ou detalhado (todas as linhas)

Pendências no DRE

A aba "Pendências" mostra NFs e CPs que não foram mapeados para nenhuma seção do DRE. Use o botão "Mapear" para criar regras de DE/PARA.

Atenção: NFs sem categoria ou com categoria não mapeada não aparecem no DRE. Verifique as pendências regularmente.

Fluxo de Caixa

O Fluxo de Caixa mostra entradas e saídas ordenadas por data de vencimento (não por competência).

Fontes de dados

NFs de saída emitidas no mês → entradas
Contas a pagar com vencimento no mês → saídas (independente da competência)
Lançamentos manuais → receitas ou despesas avulsas

Diferença para o DRE: Uma CP com competência em dezembro mas vencimento em março aparece no Fluxo de Caixa de março, mas no DRE de dezembro.

Lançamentos manuais

Use o botão "+ Lançamento" para registrar entradas ou saídas que não estão no Tiny (ex: transferências bancárias, cheques, etc.).

CMV — Custo da Mercadoria Vendida

O CMV é calculado pelo método EI + C − EF:

EI: Estoque Inicial (snapshot do início do mês)
C: Compras (NFs de entrada de fornecedores no mês)
EF: Estoque Final (snapshot do final do mês)

Como os snapshots funcionam

Ao executar o Sync de Estoque, o Orbita salva uma foto do estoque atual. O snapshot do mês corrente é atualizado a cada sync de estoque.

Importante: Para o CMV ficar preciso, execute um Sync de Estoque no início e no final de cada mês.

O que entra como Compras

NFs de entrada (tipoNota: E) com situacao: REGISTRADA, finalidade Normal (1) ou Complementar. Devoluções de venda (finalidade 4) são excluídas.

Margem por NF

Analisa a margem real de cada nota fiscal de saída, considerando custos de marketplace e impostos.

Importar custos de marketplace

Exporte o relatório de custos do Mercado Livre (ou outro marketplace) como CSV e importe em Margem → "Importar CSV". As colunas esperadas são: numero_nf, custo_marketplace.

Custos manuais por NF

Clique em qualquer NF na tabela para editar o custo manualmente. Os valores são salvos localmente.

BI Comercial

Visão de performance comercial: quais produtos mais vendem, quais canais geram mais receita, ranking de vendedores.

Configurar metas

Em Comercial → "Configurar Metas", você pode definir metas mensais por canal de venda e por vendedor. A meta ponderada combina canal + vendedor com pesos configuráveis.

O que é contabilizado

Apenas NFs de saída (não canceladas, não rejeitadas)
Devoluções subtraem da quantidade e valor
Transferências, bonificações e brindes são excluídos

Estoque

Previsão de ruptura por SKU calculada a partir do saldo atual e da média de vendas diárias.

Níveis de alerta

Zerado: saldo = 0 com histórico de vendas
Crítico: cobertura ≤ dias críticos configurados (padrão: 7 dias)
Baixo: cobertura ≤ dias baixos configurados (padrão: 15 dias)
OK: cobertura suficiente ou produto inativo

Sync de estoque

O sync de estoque usa a API produto.obter.estoque.php do Tiny. Ele roda em background e atualiza o estoque_atual de cada produto. Dependendo do volume, pode levar vários minutos.

Importar estoque via CSV

Exporte "Posição de Estoque" do Tiny e importe em Estoque → "Importar CSV". Colunas necessárias: codigo, saldo (ou variações).

Precificação

Calculadora de preços com sugestão baseada no histórico de vendas do SKU.

Como usar

Busque o SKU no campo de pesquisa
O Orbita calcula o histórico de preços praticados (média, mín, máx, desvio padrão)
Escolha um cenário (arrojado, conservador ou queima) ou ajuste os parâmetros manualmente
Salve a simulação para consultar depois

Cenários disponíveis

Cenário	Cálculo
Arrojado	Preço médio histórico + 1 desvio padrão
Conservador	Preço médio histórico praticado
Queima	Preço mais baixo já vendido, com piso de 3% de margem

Orçamento vs Realizado

Compare o resultado real do DRE com as metas orçadas para cada seção.

Como inserir o orçamento

Na tabela de Orçamento, clique em qualquer célula de valor para editar o orçamento do mês. Os valores são salvos automaticamente.

Como os totais são calculados

O orçamento respeita a mesma estrutura do DRE (schema de seções e fórmulas). Seções calculadas por fórmula (ex: Lucro Bruto = Receita − CMV) são calculadas automaticamente a partir dos valores digitados.

DE/PARA DRE (mapeamento de categorias)

O mapeamento define como cada categoria do Tiny se traduz para uma seção do DRE.

Acessar o mapeamento

Vá em Configurações → aba "Mapeamentos" → "Mapeamento de Categorias". A tabela mostra todas as regras ativas.

Como criar uma regra

Clique em "+ Adicionar regra" e preencha:

Regex de categoria: expressão regular que corresponde à categoria do Tiny (ex: Comiss para "Comissões de Venda")
Seção do DRE: selecione a seção de destino

Dica: Use o módulo DRE → aba "Pendências" para ver quais categorias não estão mapeadas. O botão "Mapear" abre diretamente o formulário de criação com a categoria pré-preenchida.

Mapeamento de fornecedores

Similar ao de categorias, mas para NFs de entrada: mapeia o nome do fornecedor para uma seção do DRE (ex: "Fornecedor XYZ" → "CMV").

Sincronização com Tiny ERP

Sync manual completo

Importa NFs (saída + entrada), contas a pagar, produtos e pedidos. Busca detalhes completos de cada NF (itens, impostos). Pode ser lento para grandes volumes.

Auto-sync (a cada 4h)

Roda automaticamente em background. Para economizar chamadas à API do Tiny, o auto-sync usa modo "stub" — importa apenas os cabeçalhos das NFs (sem itens individuais). Os totais ficam disponíveis, mas o detalhe por SKU pode não estar atualizado.

Recomendação: Execute um sync manual completo ao abrir o sistema pela primeira vez do dia e antes de fechar o DRE do mês.

Sync de estoque

Separado do sync principal. Usa produto.obter.estoque.php e atualiza o saldo de cada produto. Roda em background com progresso visível.

Rate limit do Tiny

A API do Tiny tem limite de requisições por segundo. O Orbita detecta automaticamente o rate limit e para o sync. O estado é salvo parcialmente — os produtos já sincronizados ficam salvos.

API Keys

Gere chaves de API para integrar o Orbita com outros sistemas sem expor suas credenciais de login.

Criar uma chave

Vá em Configurações → "API Keys" → "Nova chave". Escolha um nome descritivo e os escopos de acesso. A chave é exibida apenas uma vez — copie e guarde em local seguro.

Escopos disponíveis

Escopo	Acesso
read:dre	DRE mensal + NFs brutas
read:cashflow	Fluxo de caixa mensal
read:inventory	Posição de estoque e alertas
read:comercial	Métricas de SKUs e canais
read:margin	Margem por NF

Usar a chave

Envie o header X-Api-Key: ok_suachave ou Authorization: Bearer ok_suachave nas requisições para /api/v1/.

Atenção: Nunca exponha sua API key em código frontend público. Use apenas em servidores backend ou automações.

Multi-empresa e Consolidado

Múltiplos workspaces

Cada empresa (CNPJ) deve ter um workspace separado com seu próprio token do Tiny. Clique no seletor de empresa no topo do app para alternar.

Workspace Consolidado

Um workspace do tipo "consolidado" agrega automaticamente os dados de DRE, Cashflow e Margem de outras empresas. Para criar:

Em Configurações → "Empresas", clique em "+ Nova empresa"
Marque "Workspace Consolidado"
Selecione quais workspaces devem ser consolidados

Convidar usuários

Em Configurações → "Membros", use "+ Convidar usuário" para compartilhar o workspace. Defina o papel (admin ou visualizador) e quais módulos o usuário pode acessar.