NFS-e Equiplano no Paraná, Cuiabá (ISSNet Nacional) e Correção dos Erros E166, E390 e E400 no SpeedGov

Quando ativamos o mTLS nos 20 municípios da Equiplano no interior do Paraná durante a madrugada de deploy da release v0.56.73, um lembrete clássico da engenharia fiscal brasileira voltou à tona: na NFS-e municipal, o que está escrito no manual PDF da prefeitura raramente sobrevive ao primeiro handshake TLS ou ao primeiro parser XSD em produção.

Na mesma janela de engenharia — compreendida entre as versões v0.56.72, v0.56.73 e v0.56.77 dos nossos workers fiscais — atacamos três frentes críticas para Software Houses e ERPs que escalam operação pelo Brasil:

1. A entrada em operação completa da engine Equiplano SOAP/mTLS em 20 municípios paranaenses (incluindo polos econômicos como Toledo, Francisco Beltrão, Dois Vizinhos e Prudentópolis).
2. A migração transparente de Cuiabá/MT (IBGE 5103403) e mais 10 municípios atendidos pela Nota Control para o motor issnet_nacional, absorvendo o layout híbrido ABRASF 2.04 com blocos da Reforma Tributária (IBS/CBS) sem quebrar uma única linha de código nos clientes da nossa API.
3. A cirurgia de precisão no conector SpeedGov para eliminar em definitivo os temidos erros E166, E390, E400 e o falso positivo de duplicidade de NumeroLote em retentativas de RPS.

Se você mantém um emissor próprio ou lidera a arquitetura de um SaaS que sofre com particularidades municipais, quero abrir o código e compartilhar exatamente o que encontramos nas trincheiras desses três provedores — e como resolvemos cada gargalo na Notaas.

Na NFS-e brasileira, a diferença entre uma API de slides e uma infraestrutura de produção está no tratamento de arredondamento de centavos, nos domínios divergentes de regime tributário e no desacoplamento entre lote e RPS.

Engine Equiplano SOAP/mTLS: 20 municípios do Paraná em produção na v0.56.73

O estado do Paraná tem uma das malhas municipais mais industrializadas do país e uma forte concentração do provedor Equiplano em cidades de médio porte do Oeste, Sudoeste e Centro-Sul paranaense. Diferente dos provedores que adotaram o padrão ABRASF puro, a Equiplano opera com um contrato WSDL próprio (EsfsService) que exige atenção cirúrgica na montagem do envelope SOAP, na assinatura digital XML-DSig e na correlação de códigos de serviço.

Até a release v0.56.72, o catálogo municipal já mapeava as cidades da Equiplano, mas na versão v0.56.73 concluímos a implementação ponta a ponta da camada de transporte equiplanoSoapRequest sobre mTLS com Certificado Digital A1 ICP-Brasil, homologando e ativando a emissão síncrona/assíncrona, consulta de lote e cancelamento nos 20 municípios:

Anatomia do Webservice EsfsService da Equiplano

Quem tenta integrar a Equiplano usando geradores genéricos de SOAP em Node.js ou Python costuma esbarrar em três barreiras técnicas imediatas:

1. Envelope SOAP e Métodos Específicos: O webservice não expõe RecepcionarLoteRps padrão ABRASF. Os métodos oficiais do EsfsService são esRecepcionarLoteRps, esConsultarLoteRps, esConsultarNfsePorRps e esCancelarNfse, exigindo que o XML de negócio seja trafegado assinado dentro do nó <xml> com nrVersaoXml estritamente pareado com o schema da prefeitura.
2. Assinatura XML-DSig Enveloped sem Whitespace Indevido: O validador criptográfico da Equiplano rejeita assinaturas quando o canonicalizador (C14N) preserva quebras de linha entre as tags <lote> ou <rps> e o bloco <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">. Nossa engine aplica normalização determinística da árvore DOM antes de calcular o DigestValue SHA-1/SHA-256 com a chave privada extraída do .pfx.
3. Dualidade entre Item da LC 116/2003 e Subitem Municipal: Cidades como Toledo e Francisco Beltrão validam o código de atividade municipal em conjunto com a tabela de alíquotas vinculada ao Simples Nacional. Se você enviar apenas 01.05 com ponto ou sem o desdobramento esperado no cadastro econômico do prestador, o lote retorna protocolo mas falha no processamento assíncrono.

Para ilustrar a diferença estrutural, veja como o envelope SOAP exigido pelo EsfsService da Equiplano difere radicalmente do ABRASF 2.04:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:esf="http://services.equiplano.com.br">
  <soapenv:Body>
    <esf:esRecepcionarLoteRps>
      <esf:nrVersaoXml>1</esf:nrVersaoXml>
      <esf:xml><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<es:enviarLoteRpsEnvio xmlns:es="http://www.equiplano.com.br/esnfs">
  <lote>
    <nrLote>20261029001</nrLote>
    <prestador>
      <nrCnpj>12345678000199</nrCnpj>
      <idEntidade>142</idEntidade>
    </prestador>
    <listaRps><rps><nrRps>1042</nrRps>...</rps></listaRps>
  </lote>
  <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">...</Signature>
</es:enviarLoteRpsEnvio>]]></esf:xml>
    </esf:esRecepcionarLoteRps>
  </soapenv:Body>
</soapenv:Envelope>

Observe detalhes como <idEntidade> (identificador interno de cada prefeitura dentro da malha da Equiplano no Paraná) e a exigência de CDATA assinado via XML-DSig. Na v0.56.73, todo esse mapeamento de idEntidade, desmembramento de item/subitem da LC 116 e handshake mTLS no equiplanoSoapRequest é resolvido internamente pela Notaas a partir do código IBGE de 7 dígitos.

⚡ Fluxo Arquitetural da Engine Equiplano na Notaas:

• 1. Entrada Unificada REST: O ERP envia um único JSON padronizado para POST /api/v1/nfse informando codigoMunicipio: "4127700" (Toledo/PR).
• 2. Normalização & Assinatura: A engine equiplano traduz o payload para o XML nativo da Equiplano, higieniza o código de serviço e aplica assinatura XML-DSig com o Certificado A1 do tenant.
• 3. Transporte mTLS (equiplanoSoapRequest): Disparo SOAP para esRecepcionarLoteRps com handshake mTLS completo e polling inteligente automático em esConsultarLoteRps.
• 4. Retorno e Webhook: Assim que a prefeitura retorna o número da NFS-e e o código verificador de autenticidade, a Notaas gera o PDF padronizado e dispara o webhook nfse.authorized.

Essa adição faz parte da nossa expansão contínua documentada no artigo sobre a API de NFS-e com cobertura nacional em 4.780+ municípios, garantindo que o desenvolvedor nunca precise escrever uma linha de SOAP.

Cuiabá (MT) e mais 10 cidades no motor issnet_nacional (v0.56.72)

Enquanto o interior do Paraná exige domínio de SOAP clássico, as capitais e polos do Centro-Oeste e Norte protagonizaram outra mudança silenciosa nos últimos meses: a transição dos municípios atendidos pela Nota Control / ISSNet para o modelo híbrido issnet_nacional.

Na release v0.56.72, atualizamos o roteamento oficial de Cuiabá/MT (5103403) e de mais 10 municípios (incluindo cidades estratégicas do Mato Grosso, Mato Grosso do Sul e Pará) do conector issnet tradicional para a engine issnet_nacional.

O que muda sob o capô no issnet_nacional?

Para se adequar às Notas Técnicas da Reforma Tributária (IBS e CBS) sem abandonar o sistema municipal de arrecadação, a Nota Control atualizou seus webservices para exigir uma variante do layout ABRASF 2.04 estendido. Na prática, quem continuou enviando o XML antigo do ISSNet (baseado no ABRASF 1.00 ou 2.04 puro sem os novos namespaces e regras de validação nacional) passou a receber rejeições de schema XSD ou erros de validação de local de incidência.

Quando você integra diretamente com a prefeitura, uma mudança dessas significa parar o time de engenharia na segunda-feira de manhã, baixar novos arquivos .xsd, refatorar classes de serialização XML e publicar hotfix em todos os clientes de Cuiabá.

Aqui na Notaas, quem consome nossa API de NFS-e Nacional e Municipal sequer percebeu a transição. Nosso roteador municipal (MunicipalityRouter) identifica pelo código IBGE 5103403 que Cuiabá agora opera em issnet_nacional, converte o mesmo JSON REST que você já envia hoje, injeta as tags exigidas pelo novo XSD da Nota Control e mantém a emissão fluindo em milissegundos.

Cirurgia no provedor SpeedGov: como eliminamos os erros E166, E390, E400 e a colisão de NumeroLote

Se você atende clientes no Nordeste (especialmente no Ceará, Pernambuco, Rio Grande do Norte e Piauí), certamente já cruzou com o provedor SpeedGov. Nas releases v0.56.72 e v0.56.77, fizemos um mergulho profundo nos validadores internos do SpeedGov após analisarmos logs reais de rejeição em produção.

O resultado dessa investigação explica por que tantos desenvolvedores perdem os cabelos tentando homologar notas nesse provedor — e como resolvemos três armadilhas clássicas de forma definitiva.

1. O paradoxo dos erros E166 e E390: dois regimes tributários com códigos incompatíveis no mesmo XML

Esse é, de longe, um dos bugs conceituais mais traiçoeiros das prefeituras que implementaram layouts híbridos para a Reforma Tributária.

O XML de envio do SpeedGov moderno carrega duas estruturas simultâneas dentro do mesmo documento:

• Na camada externa (o RPS padrão ABRASF), existe a tag <RegimeEspecialTributacao>.
• Na camada interna aninhada (o bloco de compatibilidade com a NFS-e Nacional / Reforma Tributária), existe a tag <DadosDPS><RegEspTrib>.

Quando um desenvolvedor olha para os dois campos, a intuição imediata é preencher ambos com o mesmo número. É aí que nasce o pingue-pongue entre os erros E166 e E390:

• Se você envia 0 ("Nenhum" no padrão da NFS-e Nacional) para ambos os campos, o validador ABRASF externo rejeita a nota com o Erro E166 (Regime Especial de Tributação inválido), porque a tabela municipal ABRASF do SpeedGov só aceita códigos no intervalo 1..12 (ou exige a omissão da tag quando não há regime especial).
• Se você tenta corrigir enviando 6 ("ME/EPP Simples Nacional" na tabela ABRASF) ou 1 ("Microempresa Municipal") direto para ambos os campos sem traduzir a semântica, o validador do bloco <DadosDPS> dispara o Erro E390 (Código de Regime Especial de Tributação da DPS inválido para o contribuinte), porque na tabela do Padrão Nacional (Sefin/ADN) o domínio válido é 0..6 com significados completamente diferentes (0 = Nenhum, 1 = Ato Cooperado, 2 = Estimativa, 3 = Microempresa Municipal, 4 = Notário ou Registrador, 5 = Profissional Autônomo, 6 = Sociedade de Profissionais).

Veja na tabela abaixo a colisão semântica que derruba 90% das integrações próprias no SpeedGov:

Na release v0.56.72, reescrevemos o mapper do SpeedGov na Notaas com separação estrita de domínio: nossa engine nunca repassa o código bruto de um bloco para o outro. A partir dos parâmetros fiscais do emitente (optanteSimplesNacional, regimeEspecialTributacao), calculamos de forma independente o código 1..12 do RPS ABRASF e o código 0..6 do bloco DadosDPS.RegEspTrib.

2. O Erro E400 (Valor do ISS informado difere do calculado) e a matemática de ponto flutuante

Na release v0.56.77, eliminamos outra dor de cabeça recorrente no SpeedGov: o Erro E400.

Imagine uma nota de serviço no valor de R$ 1.357,89 com alíquota de ISS de 2,79% (muito comum nas faixas variáveis do Simples Nacional):

$$\text{BaseCalculo} \times \text{Aliquota} = 1357,89 \times 0,0279 = 37,885131$$

Dependendo de como o ERP do cliente trunca ou arredonda esse valor em JavaScript (Math.floor, toFixed(2) com imprecisão IEEE 754) antes de enviar ou de como o serializador XML preenche <ValorIss>, uma diferença de R$ 0,01 (37.88 vs 37.89) faz o SpeedGov abortar o lote inteiro com o código E400.

Como corrigimos isso na v0.56.77:

• Antes de serializar o XML do SpeedGov, nosso motor intercepta BaseCalculo e Aliquota e recalcula deterministicamente ValorIss e ValorLiquidoNfse utilizando arredondamento aritmético HALF_UP para exatamente 2 casas decimais (round2(BaseCalculo * Aliquota)).
• Mesmo que o payload de entrada traga dízimas periódicas ou que o ERP não tenha enviado o campo valorIss explícito, o XML assinado chega à prefeitura matematicamente idêntico ao cálculo interno do validador Java do SpeedGov.

// Envio JSON na Notaas (sem preocupação com E166, E390, E400 ou NumeroLote)
const response = await fetch("https://api.notaas.com.br/api/v1/nfse", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.NOTAAS_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    externalId: "pedido-erp-98412",
    ambiente: 1,
    servico: {
      valorServicos: 1357.89,
      aliquotaIss: 2.79, // round2 HALF_UP (37.89) aplicado na engine
      itemListaServico: "01.05",
      discriminacao: "Licenciamento mensal de software"
    },
    tomador: {
      cpfCnpj: "12345678000199",
      razaoSocial: "Clínica Médica Exemplo LTDA",
      endereco: { codigoMunicipio: "2304400", uf: "CE", cep: "60115000" }
    }
  })
});

3. Desacoplamento entre NumeroLote e NumeroRps em retentativas de falha

O terceiro ajuste cirúrgico da v0.56.77 no SpeedGov resolve uma armadilha silenciosa de idempotência.

Quando você envia um RPS número 105 dentro do <NumeroLote>105</NumeroLote> e a prefeitura rejeita o lote por um erro cadastral do tomador (por exemplo, CEP inválido), o RPS 105 não foi convertido em NFS-e. Portanto, pela regra contábil e fiscal, o ERP corrige o CEP do cliente e reenvia o mesmo RPS 105 para não abrir buraco na sequência numérica.

Porém, se a engine fiscal amarrar NumeroLote = NumeroRps (105), o SpeedGov recusa a segunda tentativa alegando que o Lote 105 já foi recebido anteriormente — mesmo que o lote tenha sido rejeitado sem gerar nota!

Na v0.56.77, desacoplamos completamente o gerador de NumeroLote do NumeroRps no conector SpeedGov:

• O <Numero> do RPS permanece fiel à sequência fiscal controlada da empresa (105), garantindo zero salto de numeração.
• O <NumeroLote> do envelope de transporte passa a usar um identificador monotônico de alta resolução exclusivo por tentativa de transmissão, permitindo que o mesmo RPS seja corrigido e reprocessado quantas vezes forem necessárias até a autorização.

Se você já enfrentou falhas parecidas de timeout ou rejeição de lote no ambiente nacional, recomendo também a leitura do nosso diagnóstico sobre erro ao gerar chave NFS-e e falha de conexão com a API do integrador nacional.

Do XML autorizador ao PDF na tela do cliente sem depender da prefeitura

Resolver a autorização no Paraná (Equiplano), no Mato Grosso (Cuiabá issnet_nacional) e no Nordeste (SpeedGov) é metade da batalha. A outra metade é entregar um PDF de nota fiscal rápido e padronizado para o seu usuário final — especialmente agora que a renderização precisa respeitar os novos campos da Reforma Tributária, tema que detalhamos no nosso guia técnico do DANFSe v2.0 e NT-008.

Seja para um ERP tradicional que gerencia centenas de clientes via arquitetura Multi-CNPJ na Org API, seja para quem está construindo um SaaS moderno com Vibe Coding fiscal no Cursor, Lovable ou Next.js, manter dezenas de conectores SOAP/mTLS e regras de arredondamento municipal dentro do próprio repositório drena a energia que deveria ir para o seu produto principal.

Na Notaas, você tem toda essa engenharia pronta no Dia 1:

• 20 notas fiscais gratuitas por mês em produção real (1 CNPJ) + até 5 projetos simultâneos grátis em homologação via Org API, sem exigir cartão de crédito.
• Cobertura ativa em 4.782+ municípios, já incluindo as novas releases da Equiplano, Cuiabá (issnet_nacional) e SpeedGov.

👉 Crie sua conta gratuita na Notaas agora ou consulte todos os endpoints na nossa Documentação Oficial da API.