Como importar NFS-e no Deploy Agent

O que é e para que serve

A importação de NFS-e (Nota Fiscal de Serviços Eletrônica) no Deploy Agent traz para o Sankhya Om as notas de serviço que o cliente já emitiu ou tomou, com prestador, tomador, serviços e tributos municipais. Como o formato da NFS-e varia entre municípios, cada nota passa por uma conversão assistida por IA antes do processamento. Enquanto isso acontece, o status do Deploy Agent fica como Conversão de NFS-e em andamento.

Para enviar os arquivos, reprocessar ou cancelar o processamento, confira o artigo Enviar e reprocessar documentos fiscais.

Dados extraídos da NFS-e

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

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.

ℹ️ Nota

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

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:

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.

Processamento da NFS-e no ERP

O processamento ocorre em duas etapas:

Saída no ERP por bloco do XML:

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. 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.

ℹ️ Nota

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.

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

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>

Clique nas opções abaixo para expandir as tags de cada bloco:

ℹ️ Nota

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.

Clique nas opções abaixo para expandir os exemplos de XML:

<?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>

<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>

Saiba mais

• Conheça o Deploy Agent: visão geral, abas, indicadores e arquivos processados.
• Enviar e reprocessar documentos fiscais: envio de arquivos, reprocessamento e tratamento de erros.
• Limites e dúvidas frequentes: pontos de atenção e perguntas frequentes sobre o Deploy Agent.