Blog

Emitindo NFS-e no padrão nacional

25 de março de 2026 - Posted by: - In category: Sem categoria, Usando a API de NFS-e Nacional - No responses

A emissão segue os seguintes passos:

  1. Geração do XML;
  2. Assinatura do XML com certificado digital (A1 / Arquivo);
  3. Envio do XML para o servidor do governo:
    • Se der erro, deve-se corrigir as críticas retornadas e reenviar;
    • Se der certo será retornado um protocolo para consulta;
  4. Consultar protocolo:
    • Verificar se veio erro, e corrigir de acordo o retorno;
    • Se o XML foi aceito será retornado a resposta assinada (XML);
  5. Baixar o PDF da nota.

DICAS: Tenha em mãos um XML válido (emitido no site do governo) de uma NFS-e similar, com uma estrutura parecida da que deseja construir.

Inicialização (Criar conector)

A primeira chamada consiste em inicializar o conector, ele será usado nas demais funções da API. Para criar um conector chame a função “NFS-e Nacional – Inicializar” passando os seguintes parâmetros:

  1. Ambiente (Lógico): Verdadeiro para PRODUÇÃO ou Falso para HOMOLOGAÇÃO;
  2. Tipo de certificado (Letras): Valor fixo “A1” (arquivo);
  3. Caminho (Letras): Caminho completo do certificado A1 (PFX);
  4. Senha (Letras): Senha de abertura do arquivo com o certificado.

DICA: Um mesmo conector pode ser utilizado para enviar diversas notas em lote. É importante que cada envio ocorra numa transação INDIVIDUAL, gravando os dados de cada nota assim que enviada.

Geração do XML da NFS-e

As sequencia de funções a ser usada na geração é resumidamente: “NFS-e Nacional – Inicializar” (discutido anteriormente), chamar a “NFS-e Nacional – XML – Criar“, depois chamar “NFS-e Nacional – XML – Definir Valor” para cada uma das tags que deseja adicionar, e por fim chamar a função “NFS-e Nacional – XML – Montar XML” para obter o XML final. O detalhamento vai a seguir.

Criar o XML

  • Chamar a função “NFS-e Nacional – XML – Criar” passando:
    1. Conector (Variante): Criado anteriormente;
    2. Tag principal (Letras): Valor fixo “DPS“;
    3. Versão (Letras): “1.01” versão vigente (março de 2026).
  • Chamar a função “NFS-e Nacional – XML – Definir Valor” passando os seguintes parâmetros:
    1. XML (Variante): Retorno da função anterior;
    2. Caminho das tags (Letras);
    3. Valor (Inteiro / Letras / Data / …);
    4. Máscara (Letras): Manter em branco (nulo).
  1. Dados básico
    • “infDPS/tpAmb“: 1 para produção, 2 para homologação;
    • “infDPS/dhEmi”: Passar uma data e hora que será formatada internamente.
    • “infDPS/serie“: Número apenas;
    • “infDPS/nDPS“: Número sequencial;
    • “infDPS/dCompet”
    • “infDPS/tpEmit”
    • “infDPS/cLocEmi”
  2. Dados do prestador
    • “infDPS/prest/CNPJ” ou “infDPS/prest/CPF”: Só números.
    • “infDPS/prest/fone”
    • “infDPS/prest/email”
    • “infDPS/prest/regTrib/opSimpNac”
    • “infDPS/prest/regTrib/regEspTrib”
  3. Dados do tomador
    • “infDPS/toma/CNPJ” ou “infDPS/toma/CPF“: Só números.
    • “infDPS/toma/xNome”
    • “infDPS/toma/end/endNac/cMun”
    • “infDPS/toma/end/endNac/CEP”
    • “infDPS/toma/end/xLgr”
    • “infDPS/toma/end/nro”
    • “infDPS/toma/end/xCpl”
    • “infDPS/toma/end/xBairro”
    • “infDPS/toma/email”
  4. Dados do serviço
  5. Valores
    • “infDPS/valores/vServPrest/vServ”
    • “infDPS/valores/trib/tribMun/tribISSQN”
    • “infDPS/valores/trib/tribMun/tpRetISSQN”
    • “infDPS/valores/trib/tribFed/piscofins/CST”
    • “infDPS/valores/trib/tribFed/piscofins/vBCPisCofins”
    • “infDPS/valores/trib/tribFed/vRetCP”
    • “infDPS/valores/trib/tribFed/vRetIRRF”
    • “infDPS/valores/trib/tribFed/vRetCSLL”
    • “infDPS/valores/trib/totTrib/indTotTrib”

OBS: A lista é um resumo, as tags variam de acordo com o tipo de empresa/tomador/serviço. Adicione e/ou remova de acordo as suas necessidades.

  • Por fim chamar a função “NFS-e Nacional – XML – Montar XML” passando os seguintes parâmetros:
    • XML (Variante);
    • Assinar (Lógico): Indica se o XML deve ser assinado.

Enviar o XML

Depois de montar o XML utilize a função “NFS-e Nacional – Emitir NFS-e” para enviar, passando os seguintes parâmetros:

  1. Conector (Variante): Criado anteriormente;
  2. XML (Letras): Conteúdo do XML a ser enviado.

O retorno dessa função é um mapeamento contendo:

  • “XML_RETORNO”: O conteúdo completo retornado pelo servidor.
  • “ERRO_MENSAGEM“: Se houver erro este item virá preenchido;
  • “RESPOSTA_CHAVE_ACESSO“: Chave da NFS-e.

Consulta situação do DPS usando a função “NFS-e Nacional – Verificar DPS“

Por fim obter o DPS com a função “NFS-e Nacional – Obter NFS-e“

Para obter o PDF da nota utilize a função “NFS-e Nacional – Obter DANFSe“.

Obtendo o PDF da nota fiscal (DANFSE)

Utilize a função “NFS-e Nacional – Obter DANFSe” para baixar o PDF da nota. Passando:

  1. Conector (Variante);
  2. Chave de acesso (Letras);

O retorno é um mapeamento com o caminho absoluto do PDF no servidor (Tomcat/Webrun). O arquivo DEVE ser LIDO ou MOVIDO para o destino desejado através das funções nativas do Maker (usar as funções nativas “Mover arquivo” ou “Ler todo arquivo em bytes”).

IMPORTANTE: O serviço tem apresentado INSTABILIDADES (erro 502 principalmente), esse erro vem diretamente do servidor REMOTO, não há o que fazer na API, basta aguardar e tentar novamente. (Mar/2026)

OBSERVAÇÕES

  • Instruções sobre o preenchimento (conteúdo) de cada tag fogem do escopo do suporte;
  • A ordem das tags devem ser preferencialmente colocadas na ordem em que devem aparecer no XML.
  • Instruções sobre cadastro, acesso ao sistema do governo estão fora do escopo do suporte.
  • Qualquer solicitação fora do escopo serão silenciosamentem ignoradas.