Pular para o conteúdo principal
Página inicial da Central de Ajuda de Sankhya Gestão de Negócios

Resolva em até 2 minutos com a Bia!

Antes de abrir um chamado, fale com a nossa assistente virtual. Ela esclarece suas dúvidas na hora e, se preciso, já abre o seu chamado automaticamente.

Falar com a Bia
Bia, assistente virtual

Conheça o Deploy Agent

Inovação Customer Experience
  • Atualizado

Sumário

O que é e para que serve

O Deploy Agent é o módulo de orquestração da implantação e do setup inicial no Sankhya Om. Ele reduz a parte repetitiva do trabalho, configurando do zero dezenas de cadastros e processos antes que um ambiente novo possa operar. Isso beneficia empresas, parceiros, produtos, plano de contas, naturezas de operação, entre outros.

Na maioria dos casos, o cliente já tem boa parte dos dados em algum lugar: seja nos documentos fiscais que emite todos os dias, seja em decisões de negócio que só o time de implantação pode tomar por ele. O Deploy Agent atua sobre as duas frentes:

  • Processa automaticamente os documentos fiscais do cliente: A partir de arquivos que o cliente já emite — NF-e, NFC-e, CT-e, CF-e, NFCom, NFS-e, EFD, e-Social, MDF-e, NF3-e— disponibilizados num repositório, o Deploy Agent lê e interpreta o conteúdo, e gera os cadastros e movimentos correspondentes sem que ninguém precise digitá-los. O processamento acontece em duas etapas: primeiro os cadastros (empresas, parceiros, produtos, serviços, endereços, tipos de operação, volumes, veículos), depois os documentos e movimentos (notas de compra e venda, devoluções, financeiros, custos e preços). Isso acontece no painel de processamento: você aponta para onde estão os arquivos, acompanha o andamento e confere o resultado.
  • Conduz, pelo assistente de melhores práticas, as configurações que dependem de uma decisão humana: Nem tudo pode ser inferido de um documento — decisões como política de crédito, regra de aprovação ou estrutura de centro de resultado exigem que alguém do time de implantação escolha o caminho certo para aquele cliente. Para essas mais de 70 configurações, organizadas por processo de negócio (fiscal, estoque, compras, vendas, financeiro, RH, entre outros), o Deploy Agent oferece um passo a passo guiado, chamado de Assistente de Melhores Práticas — daí o nome anterior do módulo.

Na prática, isso significa que a pessoa implantadora deixa de gastar tempo digitando o que já está escrito num documento fiscal, e concentra esse tempo nas decisões que realmente exigem julgamento.

O Deploy Agent não substitui as telas de cadastro do Sankhya Om, nem decide sozinho questões de negócio específicas do cliente: ele automatiza apenas tarefas repetitivas de setup de cadastros base e processamento de documentos fiscais já capturados. Ajustes finos, exceções e qualquer configuração específica continuam sendo feitos nas telas de cadastro correspondentes, como em qualquer outra implantação.

Antes de começar

Requisitos do ambiente

Confirme, antes de iniciar a implantação:

  • Sankhya Om instalado e em funcionamento em SaaS.

Painel do Deploy Agent

O painel é a tela principal para acompanhar o processamento automático de documentos, dividido em abas, com uma barra de ações no topo.

Acompanhamento do processamento

Use este fluxo como ponto de partida sempre que abrir o painel.

  1. Abra a tela Configurações › Rotinas › Assistente de Melhores Práticas
  2. Acesse o Deploy Agent.
  3. Observe o indicador de status no topo da tela. Ele mostra o estágio atual: Aguardando processamento, Em andamento, Conversão de NFS-e em andamento, Concluído ou Cancelado.
  4. Acompanhe a barra de progresso e o percentual de arquivos processados.
  5. Verifique o tempo restante estimado, ao lado da barra de progresso. Enquanto a estimativa ainda está sendo calculada, aguarde a mensagem de cálculo desaparecer.
  6. Permaneça na tela enquanto o processamento avança — os indicadores são atualizados automaticamente, sem precisar atualizar a página.

Botões da barra superior, e quando cada um aparece:

Botão Disponível quando O que faz
Reprocessar O agente não está em andamento Reinicia o processamento
Cancelar O agente está em andamento Interrompe o processamento
Finalizar O agente não está em andamento Encerra a tela e volta ao início
Consulta do Portal Deploy Há integração ativa com o Portal Deploy Abre a lista de oportunidades
Limpar base de prospecção O ambiente é de prospecção Exclui os dados do ambiente
Buscar novos arquivos A busca está habilitada no ambiente Solicita a busca de novos arquivos no repositório

[!NOTE] Fique atento à notificação de semáforo de memória do ambiente, exibida durante o processamento. O indicador de sucesso mostra que o ambiente opera dentro do esperado; o indicador crítico avisa que o ambiente está sob risco de memória — nesse caso, siga a ação indicada na própria mensagem.

O tempo restante é uma estimativa e pode variar conforme o volume e o tipo dos arquivos. Enquanto o status for Conversão de NFS-e em andamento, o acompanhamento das NFS-e aparece na aba Detalhamento Doc. Fiscais, no lugar do cartão de processamento fiscal, e também no indicador de status da barra superior — veja NFS-e em detalhe.

Resumo do processamento

  1. Abra a tela Configurações › Rotinas › Assistente de Melhores Práticas
  2. Acesse o Deploy Agent.
  3. Abra a aba Resumo.
  4. Leia o cartão de acompanhamento geral: total de arquivos enviados, processados com sucesso e pendências.
  5. Analise os cartões por tipo de documento: NF-e, NFC-e, CT-e, CF-e, NFCom, NFS-e, EFD, e-Social, MDF-e ou Outros documentos.
  6. Para abrir os arquivos de um tipo, clique no cartão correspondente — a aba Arquivos processados abre já filtrada por aquele tipo. Para tratar pendências, clique no indicador de pendências do cartão geral e siga o tratamento descrito em Arquivos processados.

[!NOTE] O cartão Outros documentos reúne os arquivos que não puderam ser classificados nos tipos previstos. Os números são atualizados automaticamente ao longo do processamento.

Detalhamento de documentos fiscais

  1. Abra a tela Configurações › Rotinas › Assistente de Melhores Práticas
  2. Acesse o Deploy Agent.
  3. Abra a aba Detalhamento Doc. Fiscais.
  4. Acompanhe o cartão de processamento dos arquivos fiscais, com total enviado, processados e tempo estimado.
  5. Analise os cartões de indicadores gerados a partir das notas: Empresas, Tipos de operação, Notas e devoluções de compras, Notas e devoluções de vendas, Parceiros, Produtos, Financeiros a pagar, Financeiros a receber, Endereços, Volumes, Custos e Preços.
  6. Clique num cartão para abrir a tela de origem daquele indicador no ERP e conferir ou ajustar os registros diretamente.

Para tratar pendências, clique no indicador de pendências do cartão de processamento fiscal e siga para Arquivos processados. Os indicadores de custos e preços são atualizados periodicamente enquanto o processamento avança.

Detalhamento do e-Social

[!NOTE] Esta aba só aparece em ambientes com e-Social habilitado.

  1. Abra a tela Configurações › Rotinas › Assistente de Melhores Práticas
  2. Acesse o Deploy Agent.
  3. Abra a aba Detalhamento E-Social.
  4. Acompanhe o cartão de processamento dos arquivos de e-Social, com total enviado e processados.
  5. Analise os cartões de indicadores, organizados por evento: Empresas, Rubricas, Colaboradores, Dados cadastrais, Dados contratuais, Acidentes de trabalho, Exames ocupacionais, Exames toxicológicos, Eventos de afastamento, Ambientes de trabalho, Remunerações, Pagamentos, Reintegrações e Rescisões.
  6. Clique num cartão para abrir a tela de origem no módulo de folha e conferir ou ajustar os registros.

Arquivos processados

  1. Abra a tela Configurações › Rotinas › Assistente de Melhores Práticas
  2. Acesse o Deploy Agent.
  3. Abra a aba Arquivos processados.
  4. Filtre por Tipo de documento (NF-e, NFC-e, CT-e, CF-e, NFCom, NFS-e, EFD, e-Social ou Outros documentos) e por Status (Pendente, Erro, Processado ou Processado em Duplicidade).
  5. Analise a lista resultante: data do evento, status, tipo de documento e chave do documento ou CNPJ.
  6. Para visualizar o conteúdo de um documento, selecione um único arquivo na grade e clique em Visualizar. Use Copiar conteúdo ou Baixar, se precisar, e clique em Fechar para voltar à grade.
  7. Para ver as notas inseridas por um arquivo, selecione um único arquivo e acione a opção de ver notas, para consultar as notas fiscais geradas a partir dele.
  8. Para reprocessar um registro, selecione o arquivo, acione Reprocessar registro e confirme. Só reprocesse registros com status diferente de Processado.
  9. Para excluir um registro, selecione o arquivo, acione Excluir registro e confirme na mensagem exibida. Só exclua registros com status Erro.

[!NOTE] Para visualizar o conteúdo ou ver as notas de um arquivo, selecione apenas um por vez. Com mais de um arquivo selecionado, os detalhes não são exibidos.

Reprocessamento geral

Use este fluxo quando quiser reiniciar o processamento escolhendo quais tipos de documento reprocessar.

[!NOTE] O reprocessamento fica indisponível enquanto há processamento em andamento.

  1. Abra a tela Configurações › Rotinas › Assistente de Melhores Práticas
  2. Acesse o Deploy Agent.
  3. Clique em Reprocessar, na barra superior.
  4. Selecione os modelos de documento a reprocessar: CF-e, CT-e, e-Social, EFD, MDF-e, NF-e, NFC-e, NFCom e/ou NFS-e. Por padrão, todos vêm marcados.
  5. Marque Buscar novos arquivos no repositório, se quiser incluir arquivos novos no reprocessamento.
  6. Clique em Confirmar para iniciar, ou em Cancelar, na janela, para desistir sem reprocessar.
  7. Acompanhe o andamento em Acompanhamento do processamento.

Cancelar o processamento

[!NOTE] O botão Cancelar só fica disponível com o processamento Em andamento.

  1. Abra a tela Configurações › Rotinas › Assistente de Melhores Práticas
  2. Acesse o Deploy Agent e confirme que o status está Em andamento.
  3. Clique em Cancelar, na barra superior.
  4. Leia a confirmação: "Cancelar o processamento — Ao cancelar, o processamento dos arquivos será interrompido imediatamente. Os cadastros já realizados até o momento serão mantidos no sistema. Caso deseje reiniciar o processamento, utilize o botão Reprocessar. Deseja mesmo cancelar?"
  5. Clique em Sim para confirmar, ou em Não para manter o processamento.

O cancelamento não desfaz os cadastros e movimentos já gerados antes da interrupção. Para retomar, use Reprocessamento geral.

Consulta do Portal Deploy

[!NOTE] O botão só aparece em ambientes com integração ativa com o Portal Deploy.

  1. Abra a tela Configurações › Rotinas › Assistente de Melhores Práticas
  2. Acesse o Deploy Agent e clique em Consulta do Portal Deploy, na barra superior.
  3. Consulte a lista de oportunidades disponíveis, com empresa, CNPJ e total de arquivos de cada uma.
  4. Filtre por data de início e período dos documentos, se quiser refinar a lista.
  5. Selecione a oportunidade desejada e clique em Iniciar processamento.
  6. Acompanhe a ingestão em Acompanhamento do processamento.

Quando não houver oportunidades, a tela mostra que nenhuma está disponível. Se a lista não carregar, tente consultar novamente.

Limpeza de base de prospecção

Use este fluxo para reiniciar um ambiente de prospecção ou demonstração.

[!CAUTION] Disponível apenas em ambientes de prospecção. A exclusão é permanente — confirme o escopo antes de prosseguir.

  1. Abra a tela Configurações › Rotinas › Assistente de Melhores Práticas
  2. Acesse o Deploy Agent e acione a opção de limpar base de prospecção, na barra superior.
  3. Escolha o escopo: Apenas Sankhya ou Sankhya e BUs.
  4. Clique em Confirmar.
  5. Leia a mensagem de confirmação, que informa que os dados serão excluídos permanentemente, e clique em Sim para confirmar ou em Não para desistir.
  6. Aguarde a conclusão da limpeza e leia a mensagem final, que indica se a limpeza ocorreu apenas na Sankhya ou em todos os sistemas, conforme o escopo escolhido.

A limpeza Apenas Sankhya exclui os dados da base que estão no Sankhya Om, Sankhya e BUs apagam os dados do Sankhya Om e no ambiente do Sankhya Tax.

Sankhya Tax

[!NOTE] Disponível com o processamento Concluído, e apenas em ambientes onde o Sankhya Tax está configurado. Conforme a configuração do ambiente, o acesso pode exigir login via Sankhya Pass.

  1. Abra a tela Configurações › Rotinas › Assistente de Melhores Práticas
  2. Acesse o Deploy Agent e confirme que o status está Concluído.
  3. Abra a aba Resumo.
  4. Localize a área de auditoria no cartão de acompanhamento e clique em Sankhya Tax.
  5. Conduza a validação fiscal na tela de auditoria aberta.

Configurar uma melhor prática pelo assistente

Além do processamento automático de documentos fiscais, o Deploy Agent conduz configurações manuais por meio de um assistente de melhores práticas. Todas seguem a mesma estrutura; o conteúdo de cada etapa varia conforme o processo escolhido.

Como usar a tela

  1. No menu lateral do Deploy Agent, abra a categoria desejada e clique no card da melhor prática que você quer configurar.
  2. Preencha a etapa atual. O cabeçalho de cada etapa traz um título, uma descrição e, quando há mais contexto disponível, o link Saiba mais.
  3. Clique em Avançar para seguir para a próxima etapa.
  4. Repita o preenchimento e o avanço até a última etapa de configuração. O rodapé sempre mostra em qual etapa você está: "Etapa {{ etapa atual }} de {{ total de etapas }}".
  5. Na última etapa, revise o resumo apresentado e clique em Instalar.
  6. Acompanhe a instalação na tela Acompanhamento da instalação. Cada item muda de andamento para concluído, alerta ou pausado, conforme o processamento avança. Se a instalação demorar, você pode sair da tela — o processamento continua em segundo plano e o resultado fica disponível quando você voltar.
  7. Ao final, o assistente mostra o resultado: "Configuração concluída com sucesso", "Configuração concluída parcialmente", ou uma tela de erro, quando a instalação não pôde ser concluída.
  8. Clique em Finalizar para voltar à tela principal, ou em Continuar configurando, quando a melhor prática indicar uma próxima configuração recomendada em sequência.

[!NOTE] Se algum dado da etapa estiver incorreto ou incompleto, o assistente impede o avanço e explica o que precisa ser ajustado antes de continuar.

Voltar, cancelar e consultar o log

  • Voltar leva à etapa anterior sem perder o que já foi preenchido nela.
  • Cancelar descarta a configuração em andamento, com confirmação: "As informações preenchidas serão descartadas. Deseja mesmo cancelar?"
  • Ver log mostra o detalhamento técnico da instalação.
  • Reiniciar aparece quando a instalação termina com erro ou de forma parcial, e leva de volta à primeira etapa da mesma melhor prática.

Pontos de atenção específicos

  • Configurações do tipo importação (Importação de Produtos, de Estoque, de Contratos, entre outras) seguem um padrão adicional: baixar um modelo de planilha, preencher fora do sistema, enviar o arquivo preenchido e conferir o resultado da verificação antes de instalar.
  • Configurações da área fiscal podem interromper o assistente e direcionar você para a tela de Empresas quando identificam um dado obrigatório inválido, como uma Inscrição Estadual fora do formato esperado. Corrija o cadastro da empresa e retome a melhor prática em seguida.

Artefatos de implantação

Artefatos são conjuntos de dados base importados automaticamente para inicializar o ERP. Cada um deles corresponde a um domínio funcional específico e possui seus próprios pré-requisitos, como nos exemplos de Configurações Iniciais e Processos. Para conhecer a lista completa, acesse a documentação oficial Assistente de Melhores Práticas.

Setup inicial: ingestão de documentos fiscais

O setup inicial processa documentos fiscais já emitidos para pré-popular o banco com as operações, parceiros, produtos e movimentações registrados neles — reduzindo o quanto você precisa lançar manualmente. É um processamento em lote de arquivos históricos, não uma captura em tempo real.

Documento O que extrai Comportamento
NF-e Empresas, parceiros, produtos, operações de entrada/saída, impostos (ICMS, IPI, PIS, COFINS), títulos financeiros Cancelamentos são processados marcando a nota como cancelada.
NFC-e Operações de varejo direto ao consumidor, com imposto simplificado (ICMS) Volume tipicamente maior de operações pequenas; integração com PDV
CT-e Transportadores, parceiros de origem/destino, frete e impostos O transportador é registrado como parceiro; o frete gera título financeiro
EFD Aquisições, vendas, devoluções, apuração de ICMS e PIS/COFINS de um período Arquivos acima de 50 MB são divididos automaticamente — veja Pontos de atenção
e-Social Empresas, funcionários, admissões/desligamentos, folha, afastamentos Gera impactos contábeis (débito em folha, crédito em contas a pagar)
NFS-e Prestador, tomador, serviço e tributos municipais Passa por conversão assistida por IA antes do processamento — veja NFS-e em detalhe

Como processar um arquivo

  1. Confirme que o arquivo está em formato válido: XML assinado para NF-e/NFC-e/CT-e/NFS-e, texto estruturado para EFD, XML ou estruturado conforme o padrão da Receita para e-Social.
  2. Envie o arquivo por upload direto, ou coloque-o em um bucket S3 e notifique o sistema.
  3. Acesse Buscar novos arquivos para disparar o processamento.
  4. Acompanhe pelas etapas: leitura do arquivo, processamento de cadastros base, processamento de documentos e sincronização com a API de Melhores Práticas.

Se um arquivo falhar, o erro é registrado no log e o processamento para apenas naquele arquivo — os demais seguem normalmente. Dados parcialmente inseridos não são revertidos automaticamente; corrija a causa e reprocesse pelo fluxo de Arquivos processados.

NFS-e em detalhe

Dados extraídos da NFS-e

Para quem opera. Como o formato da NFS-e varia entre municípios, o Deploy Agent padroniza a nota por IA antes de processá-la. Depois da padronização, o agente lê:

  • Identificação da nota: número, data de emissão, série, local de prestação (UF, cidade, código do município), município gerador, valor total dos serviços, base e valor total do ISS (quando há mais de um serviço) e informações complementares.
  • RPS (Recibo Provisório de Serviços): número, série e data de emissão.
  • Prestador: razão social, nome fantasia, CNPJ ou CPF, inscrição municipal, telefone, e-mail e endereço completo.
  • Tomador: razão social, nome fantasia, CNPJ, CPF ou identificação de tomador estrangeiro, telefone, e-mail e endereço completo (incluindo dados do país, quando estrangeiro).
  • Serviços (a nota pode ter mais de um): valor, classificação (item da lista de serviços, CNAE ou código de tributação municipal), discriminação, valor líquido, deduções e tributos retidos (PIS, COFINS, IRRF, INSS, CSLL).
  • ISS de cada serviço: alíquota, base de cálculo, valor calculado, valor retido, indicação de retenção e indicação de retenção no padrão nacional (para notas emitidas pelo ambiente nacional).

Campos não preenchidos na nota de origem simplesmente não são aproveitados, desde que as informações exigidas para o processamento estejam presentes.

Requisitos para processamento da NFS-e

Para quem opera. Use esta lista ao tratar uma NFS-e com erro na aba Arquivos processados.

Informações sempre exigidas: número da nota, data de emissão, razão social do prestador, logradouro e CEP do prestador, razão social do tomador, logradouro e CEP do tomador, e valor do serviço.

Informações exigidas em grupo — basta uma opção do grupo estar presente:

  • Identificação do prestador: CNPJ ou CPF.
  • Identificação do tomador: CNPJ, CPF ou identificação de tomador estrangeiro.
  • Classificação do serviço: item da lista de serviços, CNAE ou código de tributação do município.

Para tratar uma nota com erro:

  1. Abra a aba Arquivos processados e filtre pelo status Erro.
  2. Localize a NFS-e e visualize o conteúdo do documento.
  3. Compare as informações da nota com as listas acima e identifique o que está ausente.

[!NOTE] A empresa indicada na nota — prestador ou tomador, conforme o caso — precisa estar cadastrada no ERP; quando não é localizada, o processamento falha. Um serviço só é considerado quando tem valor: notas sem valor de serviço não geram o serviço correspondente.

O que a NFS-e gera no ERP

Para quem opera. A partir das informações da nota, o Deploy Agent cria ou atualiza:

  • Parceiro: o prestador ou o tomador, conforme o tipo da nota, com razão social, nome fantasia, identificação, inscrições, telefone e e-mail — e o endereço correspondente (país, estado, cidade, bairro, CEP e logradouro).
  • Serviço: criado quando ainda não existe, a partir da classificação e da discriminação da nota.
  • Dados da empresa: inscrição municipal e configurações tributárias de ISS, com associação do CNAE quando a nota é própria.
  • Nota fiscal: cabeçalho (número, data, série, código de verificação, discriminação) e um item por serviço, com valor e ISS.
  • Financeiro: o título correspondente, a partir da data de emissão e do valor total dos serviços.
  • Impostos: ISS e retenções de PIS, COFINS, IRRF, INSS e CSLL informados na nota.

A operação é classificada conforme o cenário:

Cenário Tipo de operação
Nota própria, emitida pela empresa Venda de serviço
Nota tomada, sem retenção de ISS Compra de serviço sem retenção
Nota tomada, com retenção de ISS Compra de serviço com retenção

A retenção é reconhecida quando a nota indica ISS retido pelo tomador, inclusive nas emitidas pelo ambiente nacional. Quando o RPS tem número válido, ele é usado como número da nota; caso contrário, a nota é registrada sem número de origem. O valor total da nota é a soma dos serviços, com preferência pelo valor líquido e, na ausência dele, pelo valor bruto — o total informado no cabeçalho não sobrescreve esse cálculo.

Referência técnica — XML padronizado da NFS-e

Referência técnica. Cada NFS-e municipal é normalizada por IA para este formato único antes de ser processada. Use esta referência na integração e no preparo dos arquivos.

Legenda de obrigatoriedade: Obrigatório (o campo precisa estar presente), Grupo (ao menos um campo do grupo precisa estar presente), Opcional (aproveitado quando presente).

Estrutura geral:

<nfse>
  <rps/>
  <prestador>
    <endereco/>
  </prestador>
  <tomador>
    <endereco>
      <exterior/>
    </endereco>
  </tomador>
  <servicos>
    <item>
      <iss/>
    </item>
    ...
  </servicos>
</nfse>

Identificação da nota

Tags sob a raiz <nfse>:

Tag Tipo Obrigatoriedade Descrição
<numero> inteiro Obrigatório Número da nota
<dataEmissao> data Obrigatório Data de emissão
<serie> texto Opcional Série da nota
<ufPrestacao> texto Opcional UF de prestação
<cidadePrestacao> texto Opcional Cidade de prestação
<codigoIBGEPrestacao> texto Opcional Código do município de prestação
<municipioGerador> texto Opcional Município que gerou a nota
<baseISSTotal> numérico Opcional Base do ISS total da nota
<valorISSTotal> numérico Opcional Valor do ISS total da nota
<valorTotalServicos> numérico Opcional Valor total dos serviços
<infoComplementar> texto Opcional Informações complementares

RPS

Tags sob <nfse><rps>: <numero> (inteiro, opcional), <serie> (texto, opcional), <dataEmissao> (data, opcional).

Prestador

Tags sob <nfse><prestador>:

Tag Tipo Obrigatoriedade Descrição
<razaoSocial> texto Obrigatório Razão social
<nomeFantasia> texto Opcional Nome fantasia
<cnpj> texto Grupo CNPJ
<cpf> texto Grupo CPF
<inscricao> texto Opcional Inscrição municipal
<telefone> texto Opcional Telefone
<email> texto Opcional E-mail

Grupo de identificação do prestador: ao menos <cnpj> ou <cpf>.

Endereço do prestador (<nfse><prestador><endereco>): <logradouro> e <cep> obrigatórios; <tipoLogradouro>, <numero>, <complemento>, <bairro>, <cidade>, <codigoIBGE> e <uf> opcionais.

Tomador

Tags sob <nfse><tomador>:

Tag Tipo Obrigatoriedade Descrição
<razaoSocial> texto Obrigatório Razão social
<nomeFantasia> texto Opcional Nome fantasia
<cnpj> texto Grupo CNPJ
<cpf> texto Grupo CPF
<idEstrangeiro> texto Grupo Identificação de tomador estrangeiro
<telefone> texto Opcional Telefone
<email> texto Opcional E-mail

Grupo de identificação do tomador: ao menos <cnpj>, <cpf> ou <idEstrangeiro>.

Endereço do tomador (<nfse><tomador><endereco>): <logradouro> e <cep> obrigatórios; <tipoLogradouro>, <numero>, <complemento>, <bairro>, <cidade>, <codPais>, <codigoIBGE> e <uf> opcionais. Para tomador estrangeiro, <exterior> traz <codPais> e <nomePais> (ambos opcionais).

Serviços

Tags sob <nfse><servicos><item>, um por serviço da nota; um <item> só é gerado quando há <valor>:

Tag Tipo Obrigatoriedade Descrição
<valor> numérico Obrigatório Valor do serviço
<itemLista> texto Grupo Item da lista de serviços
<cnae> texto Grupo Código CNAE
<codigoTribMunicipio> numérico Grupo Código de tributação do município
<discriminacao> texto Opcional Discriminação do serviço
<valorLiquido> numérico Opcional Valor líquido
<valorDeducoes> numérico Opcional Valor das deduções
<pis>, <cofins>, <irrf>, <inss>, <csll> numérico Opcional Tributos retidos

Grupo de classificação do serviço: ao menos <itemLista>, <cnae> ou <codigoTribMunicipio>.

ISS do serviço (<nfse><servicos><item><iss>): <aliquota>, <base>, <valor>, <valorRetido>, <retido> (booleano) e <retidoNacional> (numérico) — todos opcionais.

[!NOTE] O bloco <servicos> é sempre gerado primeiro; a ordem dos demais blocos não é determinística — use seletores por nome de tag, nunca por posição. Valores monetários e alíquotas usam ponto como separador decimal, sem formatação de moeda. O indicador de retenção no padrão nacional é numérico e distinto do indicador booleano de ISS retido — concilie a representação desse indicador entre o formato gerado pela IA e as regras de consumo no ERP.

Exemplo de XML

Exemplo com um serviço, prestador e tomador nacionais:

<?xml version="1.0" encoding="UTF-8"?>
<nfse>
  <servicos>
    <item>
      <cnae>6201501</cnae>
      <codigoTribMunicipio>620150</codigoTribMunicipio>
      <cofins>115.00</cofins>
      <csll>45.00</csll>
      <discriminacao>Desenvolvimento de software sob demanda conforme contrato 2026/001</discriminacao>
      <inss>55.00</inss>
      <irrf>50.00</irrf>
      <iss>
        <aliquota>5.00</aliquota>
        <base>5000.00</base>
        <retido>true</retido>
        <retidoNacional>1</retidoNacional>
        <valor>250.00</valor>
        <valorRetido>250.00</valorRetido>
      </iss>
      <itemLista>01.01</itemLista>
      <pis>25.00</pis>
      <valor>5000.00</valor>
      <valorDeducoes>0.00</valorDeducoes>
      <valorLiquido>4510.00</valorLiquido>
    </item>
  </servicos>
  <numero>12345</numero>
  <dataEmissao>2026-06-16</dataEmissao>
  <serie>A</serie>
  <ufPrestacao>SP</ufPrestacao>
  <cidadePrestacao>3550308</cidadePrestacao>
  <codigoIBGEPrestacao>3550308</codigoIBGEPrestacao>
  <municipioGerador>3550308</municipioGerador>
  <valorTotalServicos>6000.00</valorTotalServicos>
  <infoComplementar>Contrato firmado em 01/01/2026. Pagamento em 30 dias.</infoComplementar>
  <rps>
    <numero>100</numero>
    <serie>RPS</serie>
    <dataEmissao>2026-06-10</dataEmissao>
  </rps>
  <prestador>
    <razaoSocial>Empresa XYZ Tecnologia Ltda</razaoSocial>
    <nomeFantasia>XYZ Tech</nomeFantasia>
    <cnpj>12345678000190</cnpj>
    <inscricao>1234567</inscricao>
    <telefone>11999999999</telefone>
    <email>contato@xyztech.com.br</email>
    <endereco>
      <tipoLogradouro>Av</tipoLogradouro>
      <logradouro>Paulista</logradouro>
      <numero>1000</numero>
      <complemento>Sala 101</complemento>
      <bairro>Bela Vista</bairro>
      <cidade>São Paulo</cidade>
      <codigoIBGE>3550308</codigoIBGE>
      <cep>01310100</cep>
      <uf>SP</uf>
    </endereco>
  </prestador>
  <tomador>
    <razaoSocial>Cliente ABC S/A</razaoSocial>
    <nomeFantasia>ABC Industrias</nomeFantasia>
    <cnpj>98765432000110</cnpj>
    <telefone>11888888888</telefone>
    <email>fiscal@abcsa.com.br</email>
    <endereco>
      <tipoLogradouro>Rua</tipoLogradouro>
      <logradouro>das Flores</logradouro>
      <numero>50</numero>
      <complemento>Apto 3</complemento>
      <bairro>Centro</bairro>
      <cidade>Campinas</cidade>
      <codPais>BR</codPais>
      <codigoIBGE>3509502</codigoIBGE>
      <cep>13010001</cep>
      <uf>SP</uf>
    </endereco>
  </tomador>
</nfse>

Exemplo de tomador estrangeiro:

<tomador>
  <razaoSocial>Foreign Client Corp</razaoSocial>
  <idEstrangeiro>PASS123456</idEstrangeiro>
  <email>client@foreigncorp.com</email>
  <endereco>
    <logradouro>5th Avenue</logradouro>
    <numero>350</numero>
    <cidade>New York</cidade>
    <cep>10118</cep>
    <exterior>
      <codPais>840</codPais>
      <nomePais>Estados Unidos</nomePais>
    </exterior>
  </endereco>
</tomador>

Processamento da NFS-e no ERP

O processamento ocorre em duas etapas:

Etapa 1 - Cadastros básicos: (país, estado, cidade, bairro, CEP, endereço, empresa, parceiro, classificação da operação e serviço).

Etapa 2 - Nota e movimentos: (cabeçalho, itens, financeiro, ISS, demais impostos retidos e arquivos da nota).

Saída no ERP por bloco do XML:

Bloco do XML O que é gerado ou atualizado
Identificação da nota Cabeçalho: número, data, série, código de verificação, discriminação
Serviços Itens da nota, com valor e ISS por item
Serviços e identificação Título financeiro, a partir do valor total e da data de emissão
ISS do serviço Configuração de ISS por serviço e operação
Impostos retidos do serviço Configuração das retenções de PIS, COFINS, IRRF, INSS e CSLL
Identificação da nota e ISS Arquivos da nota armazenados no ERP
Prestador ou tomador Parceiro, com razão social, identificação, inscrições, telefone e e-mail
Serviços Serviço, criado quando ainda não existe
ISS do serviço Tipo de operação aplicado à nota
Serviços CNAE associado à empresa, apenas em nota própria
Prestador Configurações da empresa, incluindo inscrição municipal e parâmetros de ISS
Endereço Endereço, bairro, cidade, estado, país e CEP

A identificação do prestador (nota própria) ou do tomador (nota tomada) é cruzada com as empresas cadastradas no ERP; quando não localizada, o processamento falha. Em nota própria, o parceiro cadastrado é o tomador; em nota tomada, o parceiro cadastrado é o prestador — e a associação do CNAE à empresa só ocorre em nota própria.

Ao processar a nota, a empresa é ajustada para calcular IRRF, FUNRURAL e ISS, é registrada como participante do fluxo de NFS-e, e o regime especial de tributação do ISS é definido como padrão; a inscrição municipal informada na nota é gravada nos dados da empresa. Para cada tributo retido (PIS, COFINS, IRRF, INSS, CSLL) informado com valor maior que zero, é criada a configuração correspondente entre serviço, operação e imposto.

[!NOTE] Recomenda-se conciliar, entre o formato gerado pela IA e as regras de consumo, a representação do indicador de retenção no padrão nacional, para evitar divergência na classificação da operação.

Integrações complementares

Integração com Fintech

Conecta o Sankhya Om a provedoras de pagamento (Bradesco, Itaú, Santander, entre outras) para boleto, transferência, PIX e cartão. O módulo não implementa o sistema de pagamento completo — cuida da autenticação, do credenciamento de contas e do versionamento de credenciais junto à API remota.

Tipos de operação:

  • DDA (Débito Direto em Conta): o cliente autoriza, pela internet banking, o débito automático de boletos; o sistema guarda o token de autorização e debita automaticamente os títulos marcados como DDA.
  • Marketplace: conexão com o marketplace de pagamento da fintech, para consultar produtos, comissões, saldos e transações.
  • Credenciamento de conta Bradesco: fluxo específico para clientes com Bradesco API — você informa o número da conta, o sistema solicita o credenciamento e armazena o token retornado pelo banco.

Como habilitar:

  1. Confirme que há contrato ativo com a fintech e que você recebeu as credenciais (client ID e client secret).
  2. Configure as credenciais como variáveis de ambiente antes de compilar — elas são injetadas automaticamente na configuração da integração.
  3. Compile e faça deploy do módulo atualizado.
  4. Na tela de Integração com Fintech, clique em Habilitar para a fintech desejada.
  5. Rode o assistente de testes, que verifica conectividade, autenticação, permissões de conta e disponibilidade de produtos (DDA, transferência etc.). Se tudo passar, a fintech fica pronta para operações reais.

Boleto Rápido

Emissão de boletos por API de uma provedora de pagamento — com geração de código de barras pelo banco, em minutos, e rastreamento em tempo real. Use para cobrança de títulos a receber. Não use para boletos com vencimento em menos de 24 horas nem para operações que exigem layout específico (nesses casos, use CNAB tradicional).

Pré-requisitos: fintech habilitada, conta de cobrança ativa junto ao banco e títulos a receber já cadastrados.

Como emitir:

  1. Acesse Boleto Rápido e selecione um título a receber (ou crie um novo).
  2. Clique em Emitir Boleto Rápido.
  3. Confira ou preencha Valor, Vencimento, Juros/Multa (opcional) e Descrição/Linhas especiais.
  4. Clique em Enviar ao Banco.
  5. Você recebe o número do boleto, o link de visualização (PDF) e o status de emissão.

Homologação: toda fintech exige homologação antes de operações reais, em quatro etapas: validação técnica (conectividade e autenticação), validação de base (parceiros ativos e títulos em aberto), emissão de um boleto de teste em sandbox e, por fim, Concluir Homologação — que move o ambiente de sandbox para produção.

Se a emissão falhar, verifique o saldo da conta de cobrança, se o cliente está ativo no banco e se o vencimento não está no passado; consulte o log de tentativas em Histórico de Boletos.

Sankhya RH

Sincroniza a estrutura organizacional (empresas, departamentos, cargos) e eventos trabalhistas (admissão, desligamento, férias, afastamentos) com o sistema de folha de pagamento. Não processa a folha completa — apenas a estrutura de RH e os eventos que impactam a contabilidade (por exemplo, um desligamento com rescisão gera evento de folha).

Como integrar:

  1. Acesse Sankhya RH e clique em Configurar Estrutura.
  2. Envie um arquivo com a estrutura organizacional (Excel ou XML).
  3. Mapeie os campos do seu arquivo para as colunas do Sankhya Om.
  4. Clique em Sincronizar.

Depois da estrutura importada, você pode importar funcionários (upload ou API) e registrar eventos — admissão, férias, licença, afastamento ou desligamento — manualmente ou via API. Férias geram provisão de passivo; desligamento gera o cálculo de rescisão (FGTS, aviso prévio, saldo de salário).

Operações dinâmicas (artefatos customizados)

O Deploy Agent também executa artefatos dinâmicos — conjuntos de dados customizados fora da lista padrão, definidos pela API de Melhores Práticas e interpretados de forma genérica, sem exigir desenvolvimento específico. Exemplos: importação de acesso e grupos de permissão, parametrização de valores globais (como alíquota padrão de ICMS ou série de NF-e padrão) e árvores de hierarquia (categorias de produto, centros de resultado).

Como executar:

  1. Acesse Melhores Práticas › Operações Dinâmicas e selecione a operação desejada.
  2. Clique em Novo Lote.
  3. Preencha o nome da operação, o arquivo de dados e o nível de validação (rigorosa ou permissiva).
  4. Clique em Enviar.
  5. Acompanhe pelo Histórico de Operações Dinâmicas: status (pendente, processando, concluído, erro), quantidade de registros processados e mensagens de log. Se a operação falhar, o arquivo de erro fica disponível para download.

Pontos de atenção

  • Limpeza antes de reprocessar em volume. Reprocessar um artefato ou documento fiscal sem limpar dados anteriores pode gerar registros duplicados, perder referências de dados já modificados ou deixar dados inconsistentes. Antes de reprocessar um grande volume, faça backup do banco ou trabalhe num ambiente de staging.
  • Processamento sequencial e paralelo. NF-e, NFC-e, CT-e e EFD são processadas sequencialmente por tipo de documento; e-Social segue a ordem de data do evento. NFS-e usa fila de processamento e pode ser processada em paralelo. Enviar vários arquivos do mesmo tipo para o mesmo período não trava o sistema — eles são enfileirados e processados um a um.
  • Arquivos temporários. Os arquivos baixados do repositório ficam numa pasta temporária do servidor para acesso rápido. A cada novo processamento, a pasta atual é rotacionada (renomeada) e sua exclusão ocorre em segundo plano, sem bloquear o início do novo processamento; uma pasta nova é criada para os arquivos recebidos. Por isso, um arquivo processado recentemente pode ser consultado direto da pasta temporária, sem refazer a busca no repositório. Pastas antigas são limpas automaticamente após um prazo definido pelo ambiente.
  • Divisão automática de EFD grande. Arquivos EFD acima de 50 MB são divididos automaticamente em partes de até 10.000 registros por tipo de documento — você não precisa dividir manualmente. Cada parte vira um evento próprio e é processada em sequência, mas os dados descobertos numa parte (produtos, parceiros, impostos) ficam disponíveis para as partes seguintes. Se uma parte falhar, reprocesse apenas ela — as demais permanecem processadas.
  • Impacto fiscal de operações processadas. Ao importar NF-e, EFD ou NFS-e, os impostos são calculados e registrados, as operações aparecem na posição fiscal e os valores são consolidados na contabilidade. Se um arquivo estava incorreto, a correção não é automática: identifique o erro pelo log, cancele manualmente a operação no ERP e reimporte o arquivo corrigido.
  • Sincronização com a API remota. O Deploy Agent notifica a API de Melhores Práticas ao final de cada processamento. Se a notificação falhar, o processamento local é concluído normalmente (os dados já foram inseridos no banco) e você recebe um aviso; na próxima consulta, o status é replicado para a API.
  • Ambiente em uso por outra pessoa. Como a implantação altera dados compartilhados, o Deploy Agent controla quem está usando o ambiente. Quando outra pessoa já está processando, ações como Reprocessar e Cancelar ficam bloqueadas, com a indicação "Ambiente em uso por: [nome]". Quando você mesmo já ocupava o ambiente e inicia uma nova ação, o sistema confirma antes: "Sobrescrever o próprio ambiente — Você está sobrescrevendo o ambiente que você mesmo ocupou. Deseja continuar?"

Histórico de processos

Todo processo do Deploy Agent como concluído, com erro ou cancelado fica registrado para consulta posterior.

  • Histórico geral: lista as execuções de todas as melhores práticas, com filtros por Melhor prática/configuração, Status, Executante, Data de inicialização, Data de início da instalação, Data de fim da instalação, Mensagem de status e Tipo Execução.
  • Histórico de uma melhor prática: acessado a partir do card de uma melhor prática específica, já filtrado para ela.

Em cada linha, use Ver log para o detalhamento técnico da execução, ou Ver dados para consultar os dados registrados no processo. O tipo de execução indica se a configuração foi feita por Execução Manual (assistente de melhores práticas) ou Execução Automática (processamento de documentos fiscais).

Status O que significa
Concluído A instalação foi finalizada sem pendências
Erro A instalação não pôde ser concluída
Em execução O processamento ainda está em andamento
Cancelado A execução foi interrompida manualmente antes de concluir

Uma execução com status Erro não é retomada pelo Histórico — abra a melhor prática correspondente e use Reiniciar. Registros do Histórico não podem ser apagados: ele é a trilha de auditoria da implantação.

Perguntas frequentes

Como limpo os dados do banco para refazer um setup?

Use a limpeza de base de prospecção, disponível em ambientes de prospecção (veja Limpeza de base de prospecção). Ela remove as tabelas de configuração (artefatos importados, eventos processados) e preserva a estrutura base do Sankhya Om. Execute apenas em staging; em produção, faça backup antes de qualquer limpeza.

Por que o sistema me bloqueia de instalar um artefato?

As causas mais comuns são: um pré-requisito ainda não instalado (por exemplo, Composição de Produto exige Produtos já instalado), dados inconsistentes no arquivo (CNPJ duplicado, CPF inválido), um parâmetro obrigatório não preenchido, ou um recurso desativado no ambiente (como o WMS). Consulte o log de erro para identificar a causa exata.

Quanto tempo leva para processar um arquivo grande?

Depende do tamanho, da complexidade (documentos com muitos impostos levam mais tempo) e da carga do servidor e do banco no momento. Um EFD de 100 MB pode levar de 10 a 30 minutos. Processe arquivos grandes fora de horários de pico.

Posso cancelar um processamento em andamento?

Sim — veja Cancelar o processamento. Os cadastros já realizados até o momento do cancelamento permanecem no sistema; você pode retomar depois pelo reprocessamento.

O Deploy Agent sincroniza com a Fintech automaticamente?

Não. Você habilita a integração uma vez e, a cada operação (emitir boleto, consultar saldo etc.), aciona o botão correspondente; não há sincronização contínua em segundo plano.

Como sei se um documento fiscal foi processado corretamente?

Verifique o status na aba Arquivos processados, confira se a nota aparece com os dados completos na tela de origem no ERP, e compare os valores com o relatório de apuração de ICMS/PIS quando aplicável.

O Deploy Agent suporta múltiplas empresas no mesmo processamento?

Sim. O sistema identifica cada empresa pelo CNPJ presente no arquivo, cria o cadastro quando ainda não existe e associa as operações à empresa correta. Ao final, um relatório consolidado mostra quantas operações foram processadas por empresa.

Como funciona a integração com a Data Platform (Adelaide)?

Depois de cada processamento concluído com sucesso, os eventos são enviados automaticamente para a Data Platform em segundo plano, desde que o endpoint e a fila estejam configurados (veja Parâmetros de ambiente). Não é necessária nenhuma ação manual.

Quais bancos de dados são suportados?

Oracle (10g ou superior) e SQL Server (2012 ou superior).

Como peço suporte quando algo dá errado?

Verifique o log do servidor de aplicação e o log de eventos do processo, e ative o nível de log de depuração antes de reprocessar, se precisar de mais detalhe. Ao contatar o suporte da Sankhya, reúna o arquivo original (quando a privacidade permitir), os logs completos, capturas de tela da tela onde ocorreu o problema e a versão do módulo em uso.

Esse artigo foi útil?
Usuários que acharam isso útil: 0 de 0

Comentários

0 comentário

Escreva seu comentário aqui

Por favor, entre para comentar.