SPM Askora: Guia Técnico Completo

1) O Que é o SPM Askora

O Askora é uma plataforma de performance comercial que reposiciona o papel do SPM na operação: em vez de tratar incentivo como um processo burocrático de fechamento, transforma incentivo em execução diária, com regras claras, leitura contínua de desempenho e decisão orientada por dados.

No nível de gestão, o Askora centraliza a modelagem e o cálculo de comissão, bônus, turbo e premiação, reduzindo erro manual e eliminando planilhas paralelas. No nível do vendedor, entrega visibilidade objetiva de meta, progresso, ranking e ganhos, com transparência de regra e resultado ao longo da competência.

Na prática, o Askora conecta quatro frentes que operam juntas: configuração técnica de regras (Gerenciador), execução operacional com governança (Operações, Liberações e Painéis), acompanhamento de performance em tempo real (Home, Performance e Painel) e consolidação financeira gerencial (Resultados e Financeiro).

• Foco em resultado real: incentivo deixa de ser um evento de pagamento e passa a ser mecanismo contínuo de comportamento e performance.
• Confiabilidade de cálculo: regras complexas de comissionamento e bônus são aplicadas de forma padronizada para todos os participantes.
• Clareza para toda a operação: gestores e vendedores leem o mesmo dado, no mesmo contexto, sem ambiguidade de critério.
• Categoria elevada: o Askora atua como infraestrutura de performance comercial, e não apenas como controle administrativo de incentivos.

Em resumo técnico: o Askora foi desenhado para aumentar performance comercial de forma sustentável, com menos atrito operacional, mais transparência de regra e maior engajamento do time.

2) Arquitetura Funcional do Askora

2.1 Perfis de acesso

• Master: tem controle total do ecossistema Askora e da assinatura do ambiente. A conta pode ter mais de um Master, mas o Master criador nunca pode ser removido.
• Administrador: tem o mesmo acesso operacional do Master, porém limitado as organizações vinculadas a ele e sem acesso ao gerenciamento da assinatura Askora.
• Vendedor: participa das competições, da performance, do comissionamento e das bonificações, com visão personalizada entre resultado individual e performance do time.

2.2 Como a regra do Askora funciona no dia a dia

A lógica do Askora é organizada por ciclo de performance (período). Em cada período, a empresa define as regras da competição e os participantes. É dentro dessa performance que o ranking acontece, os resultados são comparados e os incentivos são apurados.

Com base nessa estrutura, o sistema calcula comissionamento e bonificações do ciclo, e alimenta os dashboards de acompanhamento. Por isso, a performance é o núcleo do ecossistema Askora: ela conecta regra, execução e leitura gerencial em um único fluxo.

3) Ordem de Onboarding Recomendada

Para iniciar com consistência e evitar retrabalho, o fluxo recomendado no Askora é:

1. Organizações: é a base de estrutura do ambiente. Não serve apenas para separar empresas, mas também equipes, filiais, unidades ou operações diferentes. Essa divisão controla a visibilidade: vendedores de uma organização não visualizam performance e competições de outra, enquanto Master e Administrador acompanham o todo conforme suas permissões.
2. Usuários: define quem participa do ecossistema e com qual nível de acesso. Nesse passo você configura perfis (Master, Administrador e Vendedor), vincula cada usuário as organizações corretas e garante que cada pessoa veja apenas o que faz sentido para sua rotina operacional.
3. Performance: é o núcleo do ciclo comercial no Askora. Aqui são definidas competência, participantes, meta, regra de comissionamento, bônus, turbo, competição e premiação. A partir dessa configuração, o sistema calcula os incentivos e abastece os dashboards de acompanhamento e resultado.
4. Clientes e Produtos (opcional): esse cadastro não é obrigatório para o Askora funcionar. Ele é recomendado para operações que desejam controlar os lançamentos de vendas de forma completa dentro do sistema, com mais padronização no registro e leitura operacional.
5. 5A - Operações: início da rotina diária no Askora para registrar lançamentos, atualizar bônus e conduzir fluxo de liberações (aprovação/negação) conforme o perfil do usuário.
6. 5B - Integrações: alternativa para empresas que já possuem sistema de origem e desejam enviar dados para o Askora por API, importação ou sincronização. Nesse modelo, o Askora recebe os dados, aplica as regras de performance e mantém os resultados atualizados.
7. 5C - Módulo Financeiro (quando ativo): configure no Gerenciador Financeiro, registre informações financeiras no lançamento e acompanhe o ciclo de pagamento no Painel Financeiro e no Dashboard Financeiro.

4) Cadastro de Organizações (campo a campo)

Descrição no onboarding: é a base de estrutura do ambiente. Não serve apenas para separar empresas, mas também equipes, filiais, unidades ou operações diferentes. Essa divisão controla a visibilidade: vendedores de uma organização não visualizam performance e competições de outra, enquanto Master e Administrador acompanham o todo conforme suas permissões.

Rota: /gerenciador/organizacoes/nova | Permissão: Master

Observações: exclusão e desativação lógica para preservar histórico; organizações alimentam filtros de Performance, Resultados, Operações e gerenciadores.

5) Cadastro de Usuários (campo a campo)

Descrição no onboarding: define quem participa do ecossistema e com qual nível de acesso. Nesse passo você configura perfis (Master, Administrador e Vendedor), vincula cada usuário às organizações corretas e garante que cada pessoa veja apenas o que faz sentido para sua rotina operacional.

Rota: /gerenciador/usuarios/nova | Permissão: Master e Administrador

Billing: limite de vendedores ativos segue plano; perfis admin/master não contam no limite de vendedores.

6) Cadastro de Performance (passo a passo técnico)

Descrição no onboarding: é o núcleo do ciclo comercial no Askora. Aqui são definidas competência, participantes, meta, regra de comissionamento, bônus, turbo, competição e premiação. A partir dessa configuração, o sistema calcula os incentivos e abastece os dashboards de acompanhamento e resultado.

Rota: /gerenciador/performance/nova | Permissão: Master e Administrador (escopo permitido)

6.1 Passo 1 - Vendedores e organizações

O primeiro passo define quem vai participar da performance e em qual escopo. Aqui você escolhe as organizações e marca os vendedores participantes de cada uma. Esse passo é crítico porque ele define o universo da competição e o público que vai receber cálculo de comissão e bônus.

• Adicione uma ou mais organizações no seletor de escopo.
• Para cada organização, marque os vendedores que participarao da performance.
• Preencha meta individual e salario base conforme a estratégia da operação.
• Regra de validação: toda organização selecionada precisa ter ao menos um vendedor marcado.

Campo a campo (Passo 1):

6.2 Passo 2 - Competência

Neste passo você define a janela de tempo da performance. O Askora permite dois formatos: mensal (um único mes) ou personalizada (intervalo de meses). Essa escolha determina como o ciclo será lido em dashboards, resultados e operações.

• Mensal: use quando a regra da performance fecha em um único mes.
• Personalizada: use quando a regra precisa cobrir um intervalo (ex.: campanha trimestral).
• Regra de validação: o período final não pode ser anterior ao inicial.
• Regra de segurança operacional: evite sobrepor ciclos ativos da mesma organização.

Campo a campo (Passo 2):

6.3 Passo 3 - Comissionamento

Aqui você escolhe a regra de comissão da performance. O fluxo começa ativando o comissionamento e depois selecionando o tipo: Padrão ou OTE. Em seguida, se necessário, você pode ativar o Turbo da comissão para criar aceleracao por marcos.

• Padrão: aplica um percentual fixo sobre vendas.
• OTE: usa faixas de meta para definir bônus percentual sobre salario base.
• Turbo da comissão: opcional. Cria marcos de aceleracao quando o vendedor atinge determinados percentuais da meta.
• O Turbo funciona tanto no modo Padrão quanto no modo OTE, com comportamento adaptado ao tipo escolhido.

Campo a campo (Passo 3):

6.4 Passo 4 - Bônus

Neste passo você escolhe se a performance terá bônus e, se sim, cadastra uma ou mais regras em abas. Cada bônus tem configuração própria de métrica, alvo, regra e pagamento. Também é possível ativar Turbo no bônus para ampliar o potencial de ganho em cenários de alta performance.

• Você pode criar vários bônus na mesma performance.
• Cada bônus pode usar métrica de quantidade, valor ou percentual.
• O Turbo do bônus é opcional e pode incluir limite por fator e ponto de excelência.
• A simulação ajuda a validar a regra antes de salvar.

Campo a campo (Passo 4):

6.5 Passo 5 - Competição e premiação

O passo final define como o ranking será apurado e quais premiações serão distribuídas. Aqui você escolhe o tipo de competição (Vendas ou Meta) e configura as colocações premiadas.

• Competição por Vendas: ranking por total vendido.
• Competição por Meta: ranking por percentual de atingimento.
• Premiacoes podem ser ativadas por colocacao (1o, 2o e 3o) com nome e imagem.
• Essa configuração aparece em Home, Performance e painéis da competição.

Campo a campo (Passo 5):

6.6 Fechamento do cadastro

Depois de revisar os cinco passos, clique em Salvar performance. A partir desse momento, a performance passa a orientar ranking, comissão, bônus, premiação e dashboards do ciclo selecionado.

7) Cadastro de Clientes (campo a campo)

Descrição no onboarding: é opcional e recomendado para operações que desejam controle mais completo dos lançamentos. O cadastro de clientes padroniza o registro comercial, melhora filtros operacionais e facilita rastreabilidade de vendas por cliente.

Rota: /gerenciador/clientes/nova | Permissão: Master e Administrador (escopo permitido)

Observações: exclusão é lógica para preservar histórico; registros de cliente são reutilizados em lançamentos, buscas e auditoria operacional.

8) Cadastro de Produtos (campo a campo)

Descrição no onboarding: também é opcional e indicado para operações que precisam padronizar itens vendidos dentro do Askora. O cadastro de produtos reduz erro de preenchimento, acelera lançamentos e dá consistência para leitura de performance por item.

Rota: /gerenciador/produtos/nova | Permissão: Master e Administrador (escopo permitido)

Observações: exclusão é lógica para manter histórico; produtos podem ser filtrados por organização e utilizados para padronizar o lançamento operacional.

9) Comissão (detalhamento completo de cadastro e cálculo)

Este bloco aprofunda o Passo 3 - Comissionamento com foco técnico e prático. Abaixo estão os nomes de campos do front, a lógica do Turbo e como o cálculo é aplicado no recálculo de performance.

9.1 Campos do front (Comissionamento)

9.2 Lógica de cálculo no modo Padrão

O sistema calcula atingimento como (total_vendas / meta_valor) x 100. Em seguida:

• Sem Turbo: usa o Percentual (%) informado.
• Com Turbo ativo: verifica os marcos de meta e usa o valor do último marco atingido.
• Se existir marco repetido no mesmo percentual de meta, prevalece o último valor salvo para aquele marco.

comissao_padrao = total_vendas * (percentual_aplicado / 100)

Exemplo prático: percentual base de 1,50%; turbo com marco em 80% da meta para 2,00%. Se o vendedor fecha em 85% de atingimento, a comissão usa 2,00% sobre as vendas do ciclo.

9.3 Lógica de cálculo no modo OTE

No OTE, o valor final é calculado sobre o salário base do vendedor:

• Se atingimento >= Meta máxima (%): aplica Bônus máximo (%).
• Se atingimento >= Meta mínima (%) e abaixo da máxima: aplica Bônus mínimo (%).
• Abaixo da mínima: bônus OTE base fica zerado.
• Com Turbo OTE ativo: soma os adicionais dos marcos atingidos ao percentual base (cumulativo).

percentual_final_ote = bonus_base + soma_dos_turbos_atingidos
comissao_ote = salario_base * (percentual_final_ote / 100)

Exemplo prático: meta mínima 80%, meta máxima 100%, bônus mínimo 10%, bônus máximo 20%. Com 105% de atingimento e turbo OTE de +5% em 90% e +5% em 100%, o percentual final vira 30% (20% base + 10% turbo) sobre o salário base.

9.4 Validações importantes de comissão

• Percentuais de comissão e turbo devem ser maiores ou iguais a zero.
• No OTE, os 4 campos percentuais (meta mínima/máxima e bônus mínimo/máximo) são obrigatórios.
• No OTE, salário base de todos os vendedores selecionados é obrigatório para cálculo.
• Turbo ativo sem marco válido bloqueia o salvamento da performance.

10) Bônus (detalhamento completo de cadastro, regras e turbo)

Este bloco aprofunda o Passo 4 - Bônus. A configuração é feita por abas (um bônus por aba), com cálculo por fator e suporte a turbo com ou sem limite.

10.1 Campos do front (Bônus)

10.2 Cálculo do fator por regra

• ABOVE: libera fator a partir do atingimento do alvo para cima.
• BELOW: libera fator quando o resultado fica abaixo do alvo.
• MORE: progressivo; cresce conforme resultado/alvo.
• LESS: inverso; fator diminui conforme se aproxima do alvo.

Regras práticas:

• Se o resultado do bônus ainda não foi informado, o fator fica 0 e o valor do bônus fica 0.
• Com Turbo ativo e sem limite, regras progressivas podem gerar fator acima de 1 sem teto.
• Com limite ativo, Turbo máximo (fator) define o teto; quando há Turbo excelência (E), o crescimento até esse teto é interpolado.

10.3 Cálculo do valor final do bônus

Primeiro o sistema define a base financeira:

• FIXED: max_bonus = Valor do pagamento.
• SALARY_PERCENT: max_bonus = salario_base x (Valor do pagamento / 100).

Depois aplica o fator calculado pela regra:

valor_bonus = fator_final * max_bonus

Exemplo prático: pagamento FIXED de R$ 1.000,00 com fator 1,30 resulta em R$ 1.300,00. Em SALARY_PERCENT de 20% com salário de R$ 3.000,00, a base é R$ 600,00; com fator 1,50, o bônus final fica R$ 900,00.

10.4 Validações importantes de bônus

• Alvo (X) deve ser maior que zero.
• Valor do pagamento deve ser maior ou igual a zero.
• Quando o turbo está ativo com fator máximo, o campo Turbo excelência (E) é obrigatório.
• Em bônus com SALARY_PERCENT, todos os vendedores precisam ter salário base válido.

11) Permissões por Perfil

12) Manual Página por Página

Esta seção resume o uso prático de cada página do Askora no dia a dia da operação. A leitura ideal é: primeiro entender para que a página serve, depois usar os pontos abaixo como checklist do que você encontra e quando usar.

Home (/home)

A Home é a porta de entrada da operação. Ela serve para bater o olho no ciclo atual e entender rapidamente como o time está, sem precisar abrir vários módulos.

• Filtros por performance e organização para trocar o recorte da leitura.
• Cards executivos: total vendido, progresso da meta, vendas do dia, ticket médio e vendedores.
• Ranking local e premiacoes da competição ativa.
• Cronometro de fechamento do ciclo selecionado.

Performance (/performance)

A página Performance é para análise de desempenho. Ela transforma os dados do ciclo em leitura de ritmo, evolução e tendência, ajudando a decidir onde agir.

• Análise por vendedor, por organização ou consolidada do time.
• Filtros por performance, organizações e vendedor.
• Blocos de meta, comissão, bônus, comparativos e sinais de atenção.
• Grafico de evolução temporal do período.

Painel de Performance (/painel-performance)

O Painel de Performance é a versão de exibição contínua para acompanhamento coletivo (TV, monitor ou reunião). É ideal para dar visibilidade ao time em tempo real.

• Visão ao vivo para TV/monitor com auto-atualização.
• Exibe ranking, progresso de meta, vendas e premiacoes da competição.
• Suporta modo fullscreen para acompanhamento de equipe.

Resultados / Comissoes (/resultados, /comissoes)

Esta página é o consolidado de performance do ciclo. Aqui você valida quanto foi gerado em comissão e bônus, com visão por time ou por vendedor.

• Consolidado financeiro do período: comissão, bônus e total.
• Filtros por performance, organização e vendedor.
• Comparativos e detalhamento por participante.
• Exportacao de documentos conforme recorte aplicado.
• Para follow-up de vencimento e pagamento use a página Financeiro (/financeiro).

Operações (/operacoes)

A página Operações é a rotina diária da equipe. É onde os lançamentos e bônus entram no fluxo e passam por liberação quando necessário.

• Aba Lançamentos: registro de pedido, valor, data e dados comerciais.
• Informações financeiras no lançamento: condição de pagamento, primeiro vencimento, parcelamento, intervalo e edição de valores por parcela.
• Aba Bônus: atualização de resultados de bônus por regra ativa.
• Aba Liberações: aprovação ou negação de pendencias operacionais.
• Aba Painel Financeiro (quando ativo): follow-up de status financeiros e vencimentos.
• Fluxo por perfil: vendedor solicita; gestor aprova, nega ou ajusta.

Painel de Lançamentos (/operacoes?aba=painel-lancamentos)

O Painel de Lançamentos é a camada de auditoria e ajuste fino. Ele é usado quando a operação precisa revisar volume, corrigir inconsistências e manter rastreabilidade dos registros.

• Busca e filtros avancados para rastrear lançamentos específicos.
• Edição em lote, exclusão e exportacao para análise externa.
• Diferente do Painel Financeiro: aqui o foco é corrigir dados operacionais, não controlar vencimento/pagamento.
• Controle por permissão e organização para manter governança.

Compatibilidade: o atalho legado /painel-lancamentos redireciona para esta aba.

Painel Financeiro (/operacoes?aba=financeiro)

O Painel Financeiro é o follow-up do ciclo financeiro dos lançamentos. Ele acompanha o que precisa ser liberado, o que está no prazo, vencido, liberado ou cancelado.

• Status operacionais: liberar, no_prazo, vencidos, liberado e cancelado.
• Ações em lote para liberar, cancelar e reabrir conforme permissão.
• Atualização de status e data financeira com rastreabilidade.
• Exportacao da visão financeira para Excel.

Perfil (/perfil)

A página Perfil centraliza a manutenção da conta de cada usuário. É uma página de suporte pessoal para manter acesso e dados atualizados.

• Atualização de dados pessoais e imagem.
• Troca de senha com validação.
• Consulta de informacoes pessoais da conta.

Gerenciador (/gerenciador)

O Gerenciador é o centro administrativo do Askora. Ele organiza os módulos de configuração para montar e manter o ecossistema da conta.

• Entrada para Performance, Usuários, Organizações, Clientes, Produtos e Gerenciador Financeiro.
• Recomendado para implantação inicial e manutenção estrutural.

Gerenciador Financeiro (/gerenciador/financeiro)

Este módulo define as regras do fluxo financeiro da operação e controla como os lançamentos serão acompanhados financeiramente.

• Ativação do módulo financeiro e opção de exibir bônus no financeiro.
• Cadastro de condições de pagamento (à vista e a prazo).
• Configuração de registro de vencimentos, vencimento padrão e prazo de pagamento após liberação.

Gerenciador de Performance (/gerenciador/performance)

Este módulo é onde a estratégia comercial vira regra operacional. É nele que você cria, ajusta e replica performances.

• Lista, filtra, edita e duplica performances.
• Cadastro completo em 5 passos: participantes, competência, comissão, bônus e competição/premiação.
• Impacto direto em ranking, resultados e dashboards do ciclo.

Gerenciador de Usuários (/gerenciador/usuarios)

Aqui você controla quem acessa o Askora e qual visão cada pessoa terá. É a base de governança de permissão da plataforma.

• Controle de acessos, escopo organizacional e salario base.
• Definicao de perfil (Master, Administrador, Vendedor).
• Validacoes de login único e regras de plano/perfil.

Gerenciador de Organizações (/gerenciador/organizacoes)

Esta página estrutura o ambiente em blocos de negócio (empresa, filial, equipe ou unidade). Ela define os limites de visão e operação entre grupos.

• Cadastro e manutenção de organizações do ambiente.
• Base de escopo para performance, operações e dashboards.

Gerenciador de Clientes (/gerenciador/clientes)

O módulo de Clientes organiza o cadastro comercial para operações que fazem controle detalhado das vendas dentro do Askora.

• Cadastro de cliente (nome + CPF/CNPJ).
• Utilizado em lançamentos, filtros e histórico operacional.

Gerenciador de Produtos (/gerenciador/produtos)

O módulo de Produtos padroniza itens vendidos por organização e reduz erro de preenchimento durante os lançamentos.

• Catalogo de produtos/servicos por organização.
• Permite valor padrão para agilizar a operação.

Desenvolvedor (/desenvolvedor)

A página Desenvolvedor é voltada para integração e automação. Ela conecta o Askora a sistemas externos e rotinas de importação.

• Geracao de API Key.
• Importação de lançamentos/bônus via Excel ou CSV.
• Integração Google Sheets (single/individual, oauth, sync e descarte).
• No estado atual, integrações não cobrem o fluxo financeiro avançado (vencimentos/status financeiros).
• Links de referência técnica apontam para a documentação SPM no blog.

Financeiro (/financeiro)

A página Financeiro é o dashboard gerencial do módulo financeiro. Ela consolida o acompanhamento de liberação, vencimento e pagamento das comissões.

• KPIs financeiros: valores a liberar, no prazo, vencidos e liberados.
• Visões de fluxo financeiro realizado, provisionado e previsto.
• Relatório gerencial por organização e vendedor, com geração de documentos.

Manuais (/manuais)

A página Manuais deixou de concentrar conteúdo interno e agora funciona como redirecionamento para a documentação oficial centralizada.

• Destino atual: https://askora.com.br/blog/spm.
• FAQ complementar: https://askora.com.br/blog/faq.
• Abertura em nova aba para manter o usuário dentro do sistema Askora.

Blog (menu Blog)

O Blog é o canal público de conteúdo da Askora para artigos, guias e materiais de referência da categoria.

• Destino: https://askora.com.br/blog.
• Usado para conteúdo institucional, educacional e páginas técnicas públicas.
• Abertura em nova aba para preservar a sessão no sistema.

Suporte (/suporte)

Suporte é a página de apoio para dúvidas de operação. É o caminho recomendado quando a equipe precisa orientação para executar o processo correto.

• Canal de orientação para uso da plataforma no dia a dia.
• Ajuda em dúvidas de fluxo, permissão e comportamento esperado das telas.

13) Integração

A camada de integração do Askora foi desenhada para tres cenários reais de operação: envio sistêmico por API, sincronização assistida por Google Sheets e carga em lote por arquivos (Excel/CSV). Em todos os modelos, o objetivo é o mesmo: manter vendas e bônus atualizados no ciclo de performance sem perder governança.

Escopo atual: integrações ainda não cobrem o fluxo financeiro avançado (vencimento, status financeiros e follow-up de pagamento). Esse fluxo permanece operacional dentro do módulo financeiro no Askora.

13.1 Qual integração usar em cada cenário

13.2 Integração por API

A API é o canal recomendado para integração de sistema para sistema. Ela trabalha com dois modos: unitário (tempo real) e reconciliação (lote), usando a mesma chave de autenticação.

13.2.1 Preparação e autenticação

1. Acesse /desenvolvedor e gere a API Key da conta.
2. No seu sistema integrador, envie o header: Authorization: Bearer SUA_CHAVE.
3. Escolha o modo de envio: unitário (evento a evento) ou reconciliação (lote).

13.2.2 Endpoints oficiais

• POST /api/v1/lancamentos - lançamento unitário de venda.
• POST /api/v1/bonus - atualização unitária de bônus.
• POST /api/v1/lancamentos/reconciliacao - reconciliação em lote de vendas.
• POST /api/v1/bonus/reconciliacao - reconciliação em lote de bônus.

13.2.3 Regras essenciais de identificação

• Para identificar vendedor na API, envie apenas um: email_vendedor ou link_vendedor.
• Se enviar os dois no mesmo item, a API retorna erro.
• Em vendas, pedido deve ser estável e único no sistema origem para evitar duplicidade.

13.2.4 Campos - lançamento unitário

13.2.5 Campos - bônus unitário

Importante sobre bônus: a API de bônus atualiza um bônus existente (por vendedor + nome + competência + tipo). Ela não cria nova regra de bônus; a regra precisa existir no cadastro da performance.

13.2.6 Reconciliação em lote (items)

• Envio em lote usa payload { "items": [ ... ] }.
• Limite técnico: até 500 itens por requisição.
• O retorno vem com resumo e resultado por item (processado, erro, pulado).

13.2.7 Exemplos de envio

Lançamento unitário:

{
  "email_vendedor": "vendedor@empresa.com",
  "pedido": "PED-123456",
  "data_venda": "2026-03-10",
  "valor": 1500.75
}

Bônus unitário:

{
  "email_vendedor": "vendedor@empresa.com",
  "bonus_name": "Taxa de conversão",
  "bonus_type": "Percentual",
  "competencia": "2026-03",
  "valor_bonus": 92.5
}

Reconciliação de vendas (lote):

{
  "items": [
    {
      "email_vendedor": "vendedor@empresa.com",
      "pedido": "PED-1001",
      "data_venda": "2026-03-01",
      "valor": 890.50,
      "status": "Ativo"
    },
    {
      "pedido": "PED-0880",
      "status": "Inativo"
    }
  ]
}

13.3 Integração Google Sheets

O Google Sheets é indicado para operações que preferem preenchimento em planilha, mas querem os dados refletidos no Askora automaticamente. O fluxo funciona com conta Google conectada, geração de template e sincronização recorrente.

13.3.1 Passo a passo para conectar

1. Acesse /desenvolvedor e abra a aba Google Sheets.
2. Clique em Conectar Google.
3. Selecione a conta que vai receber as planilhas no Drive.
4. Conclua a autorização e retorne ao Askora.

Sobre a mensagem do Google "app não autenticado/não verificado": isso pode aparecer porque o domínio Askora é novo e está em análise do Google. Esse comportamento é normal nesse contexto. Para continuar, clique em Avançado e depois em Ir para askora.com.br. Essa autorização é usada para gerar/vincular o template da planilha no seu Drive. Se preferir, você pode conectar com qualquer conta Gmail dedicada para essa integração.

13.3.2 Modelos disponíveis: Planilha Única x Planilha Individual

13.3.3 Preenchimento da aba de vendas (obrigatório)

Na leitura de vendas, o Askora processa tecnicamente o intervalo A:F. Isso significa que as colunas de G em diante ficam livres para controle interno da operação (observações, canal, supervisor etc), sem impacto no processamento da venda.

13.3.4 Preenchimento da aba de bônus

Para bônus, o Askora busca dados no intervalo A:Z, localiza os campos obrigatórios por cabeçalho e ignora colunas extras que não fazem parte do processamento. Na prática: você pode manter colunas livres para uso interno sem quebrar a sincronização.

Assim como na API, a sincronização de bônus atualiza registros de bônus já existentes por vendedor/nome/competência/tipo. Ou seja: use essa aba para atualizar resultado de bônus, não para criar regra nova de bônus.

13.3.5 Regras de sincronização importantes

• Sincronização é automática e recorrente após a planilha estar vinculada.
• Em vendas: Ativo cria/atualiza; Inativo arquiva o lançamento pelo id_pedido.
• Descartar a integração remove o vínculo com o Askora, mas o arquivo permanece no Google Drive.
• Lançamentos já registrados no Askora não são apagados so por descartar o vínculo.

13.4 Integração por Importação (Excel/CSV)

A importação é o caminho de meio termo para operações sem API e sem Google Sheets em tempo real. No novo modelo, o Askora não depende mais de ordem fixa de colunas: cada cliente configura seu mapeamento na aba /desenvolvedor e depois só repete a rotina de envio de arquivo.

13.4.1 Como funciona o novo fluxo

1. Na aba Desenvolvedor, há dois blocos fixos de envio: Importar lançamentos e Importar bônus.
2. Antes de importar, salve a configuração de cada tipo (lançamentos e/ou bônus) no card de Configurações de importação.
3. Cada configuração fica salva por id_askora, em linha separada por tipo. Quem usa só lançamentos terá apenas uma configuração salva.
4. No envio, o Askora valida o tipo do arquivo (Excel/CSV), aplica o mapeamento salvo e processa as linhas conforme as regras de conciliação por pedido.
5. Quando houver pedido com múltiplos vendedores no modo multi-linha, os itens entram em liberação com sufixo (/A, /B, /C), no card exibido abaixo do botão de importar lançamentos.

13.4.2 Configuração de lançamentos (campo a campo)

Quando o status opcional não está habilitado, lançamentos são processados como ativo. Quando está habilitado, o texto da planilha é normalizado (ignorando maiúsculas/minúsculas, acentos e pontuação) para comparar com os rótulos configurados de ativo/inativo.

13.4.3 Configuração de bônus (campo a campo)

Na importação configurada de bônus, não existe coluna de tipo (bonus_type) no arquivo. O tipo é inferido a partir do bônus já cadastrado no Askora (por vendedor + nome + competência). Se o bônus não existir ou houver conflito de tipos para a mesma referência, a linha retorna erro.

13.4.4 Duplicidade, consolidação e fila de liberação

• Pedido repetido com multi-linha desativado: o Askora reconcilia pelo pedido e mantém o último registro lido como versão atual do lançamento.
• Pedido repetido com multi-linha ativado e mesmo vendedor: soma os valores do grupo e grava um único lançamento para o pedido.
• Pedido repetido com multi-linha ativado e vendedores diferentes: em vez de descartar, cria itens em liberações com sufixo no pedido (123/A, 123/B, ...).
• Aprovação/negação: no card de liberação da aba Importação, o gestor decide quais itens aprovar (vira lançamento) ou negar.

13.4.5 Formatos e conversões (data, competência e valor)

• Data de lançamentos: aceita formato fixo selecionado ou Automático; no automático, tenta múltiplos padrões e também data serial de Excel.
• Competência de bônus: representa mês/ano; use formato compatível com sua planilha para evitar ambiguidades.
• Valor em BR: espera decimal com vírgula (1.234,56). Se o arquivo usa ponto decimal (1234.56), prefira US ou Automático.
• Valor em Automático: tenta reconhecer padrões BR/US por heurística (posição de vírgula/ponto, quantidade de separadores e presença de símbolos como R$ e %).
• Recomendação prática: sempre que possível, selecione formato explícito (BR, US, Inteiro e formato de data/competência fixo). Use Automático como fallback quando a origem não mantém padrão consistente.
• Arredondamento: lançamentos são gravados com 2 casas decimais; bônus com 4 casas decimais.

13.5 Como o Askora processa os dados enviados

• Vendas usam o pedido como referência principal de conciliação.
• Quando o status opcional está mapeado, texto de ativo/inativo controla criação, atualização, reativação ou arquivamento do pedido.
• Bônus atualiza resultado de bônus já existente no ciclo correspondente e usa o tipo do bônus cadastrado para converter valor.
• Regras de performance (comissão, bônus, turbo e competição) continuam sendo definidas dentro do Askora, no cadastro da performance.

13.6 Checklist rápido para evitar erro de integração

• Confirme se a API Key está ativa e é a mesma usada no header Authorization.
• Não envie email_vendedor e link_vendedor juntos na API.
• Na importação por arquivo, salve primeiro o mapeamento correto de lançamentos e/ou bônus antes de enviar.
• Garanta que o tipo configurado (Excel/CSV) é o mesmo do arquivo enviado.
• Mantenha pedido único e estável para conciliação confiável.
• No mapeamento de status, use textos de ativo e inativo distintos e exatamente como aparecem na origem.
• Em bônus, valide se o nome e a competência existem no Askora para o vendedor antes da importação.
• No Google Sheets, preencha corretamente as colunas obrigatórias e use colunas livres apenas para controles extras.