A migração de sistemas emissores para a Declaração de Prestação de Serviços (DPS) do Sistema Nacional da NFS-e (SNNFSE v1.01) trouxe um novo patamar de rigor na validação de arquivos XML pela Receita Federal e pela SEFIN Nacional.
Diferente de webservices municipais legados que frequentemente toleravam pequenas inconsistências estruturais, o parser central do SNNFSE executa uma validação estrita contra os arquivos XSD oficiais (DPS_v1.01.xsd e tiposComplexos_v1.01.xsd). O resultado tem sido uma onda de rejeições silenciosas ou erros de schema crípticos para software houses e desenvolvedores que tentam montar os XMLs manualmente.
Entre todas as armadilhas de integração do novo layout, nenhuma causa mais travamentos do que a sutil e perigosa diferença entre os tipos de endereço do tomador (TCEndereco) e do imóvel/obra (TCEnderObraEvento).
Neste artigo técnico, dissecamos a causa raiz desse erro, apresentamos a comparação linha a linha dos tipos XSD e demonstramos como a Notaas elimina 100% dessas falhas estruturais através de normalização automática via API NFS-e Nacional.
💥 1. A Causa Raiz: Por que o <imovel> Rejeita a DPS?
Na maioria das bibliotecas de serialização XML desenvolvidas para o padrão nacional, as equipes de engenharia criam um helper genérico de endereço (ex: buildEndereco()) e o reutilizam em todos os nós do documento onde um endereço é solicitado:
- No prestador (
<prest><end>...) - No tomador (
<toma><end>...) - No destinatário alternativo do RTC (
<dest><end>...) - Na identificação de imóvel ou obra (
<imovel><end>...ou<obra><end>...)
O problema fatal é que o XSD da Receita Federal define dois tipos de dados de endereço completamente distintos e incompatíveis dentro do mesmo arquivo tiposComplexos_v1.01.xsd:
| Tipo XSD | Onde é Utilizado no XML | Estrutura de Tags Exigida |
|---|---|---|
TCEndereco |
<prest.end>, <toma.end>, <dest.end> |
Exige o wrapper <endNac> contendo obrigatoriamente <cMun> e <CEP>, seguidos de logradouro, número e bairro. |
TCEnderObraEvento |
<imovel.end>, <serv.obra.end> |
NÃO aceita <endNac> e NÃO aceita <cMun>. O elemento <CEP> é filho direto de <end>. |
📐 2. Comparativo Estrutural dos Dois Schemas XML
Veja a diferença estrutural gerada para o mesmo endereço físico em cada um dos nós:
A. Endereço do Tomador (TCEndereco — Válido em <toma>):
<toma>
<CNPJ>98765432000188</CNPJ>
<xNome>EMPRESA ADQUIRENTE LTDA</xNome>
<end>
<endNac>
<cMun>3550308</cMun>
<CEP>01310100</CEP>
</endNac>
<xLgr>Avenida Paulista</xLgr>
<nro>1000</nro>
<xBairro>Bela Vista</xBairro>
</end>
</toma>
B. Endereço de Imóvel / Obra (TCEnderObraEvento — Válido em <imovel>):
<imovel>
<inscImobFisc>99887766</inscImobFisc>
<end>
<CEP>01310100</CEP>
<xLgr>Avenida Paulista</xLgr>
<nro>1000</nro>
<xBairro>Bela Vista</xBairro>
</end>
</imovel>
⚠️ A Armadilha do TypeScript: Se você utiliza interfaces tipadas onde ambos os campos recebem um objeto comum (como
{ logradouro, numero, cep, codigo_municipio }), o compilador não acusará erro em tempo de build. O erro só será descoberto em tempo de execução quando a Receita Federal rejeitar o lote com mensagem de violação de XSD.
🚨 3. Outros Pontos Críticos de Validação no Schema DPS v1.01
Além da pegadinha do TCEnderObraEvento, a auditoria técnica da DPS Nacional revelou mais dois pontos de validação estrita:
1. Regra de Identificador Único em <dest> e <fornec>
No grupo <dest> (destinatário alternativo de IBS/CBS) e no nó <fornec> (fornecedores de despesas reembolsáveis em <gReeRepRes>), o XSD define uma escolha exclusiva (xs:choice). O sistema deve enviar exatamente um dos seguintes nós:
<CNPJ>(14 dígitos)<CPF>(11 dígitos)<NIF>(Número de Identificação Fiscal exterior)<cNaoNIF>(Código de justificativa para ausência de NIF)
A presença de mais de um identificador ou a emissão de tags nulas (como <cNaoNIF>undefined</cNaoNIF>) invalida imediatamente a DPS.
2. Wrapper Estrito de Reembolso (TCRTCListaDoc)
No grupo de reembolso e repasse (<gReeRepRes>), os documentos vinculados não podem ser colocados como array direto sob a tag raiz. Eles exigem o encapsulamento no nó <documentos>, onde cada item inicia com uma escolha exclusiva entre:
<dFeNacional>(chave de 44 ou 50 dígitos de NF-e, CT-e ou NFS-e Nacional)<docFiscalOutro>(documento fiscal municipal ou estadual com série e número)<docOutro>(comprovante ou recibo não fiscal)
💻 4. Como a Notaas Blinda sua Aplicação contra Erros de XSD
Na Notaas, o desenvolvedor não precisa memorizar a tipagem de múltiplos nós de endereço nem regras de serialização XML.
Nossa engine processa um contrato JSON único e unificado, realizando a normalização sintática e a escolha dos builders corretos em tempo real:
{
"provedor": "snnfse",
"prestador": { "cnpj": "12345678000199" },
"tomador": {
"cnpj": "98765432000188",
"razao_social": "CONSTRUTORA EXEMPLO S.A.",
"endereco": {
"logradouro": "Rua Augusta",
"numero": "500",
"bairro": "Consolação",
"codigo_municipio": "3550308",
"cep": "01305000",
"uf": "SP"
}
},
"servico": {
"descricao": "Serviços de engenharia e reforma estrutural predial.",
"valor_servicos": 45000.00,
"item_lista_servico": "07.02",
"nbs": "114012100"
},
"valores": {
"ibscbs": {
"cst": "000",
"classificacao_tributaria": "200046",
"indicador_operacao": "020301",
"imovel": {
"inscricao_imobiliaria": "12345678",
"endereco": {
"logradouro": "Rua Augusta",
"numero": "500",
"bairro": "Consolação",
"cep": "01305000"
}
}
}
}
}
Ao receber esse payload, a Notaas:
- Valida a conformidade da tupla RTC conforme o Anexo VIII da Reforma Tributária.
- Serializa o endereço do tomador com
TCEndereco(com<cMun>). - Serializa o endereço do imóvel automaticamente com
TCEnderObraEvento(com<CEP>direto). - Assina o XML digitalmente com o certificado A1 da sua organização e transmite para o SNNFSE Nacional.
- Retorna o XML autorizado e o link do DANFSe v2.0 local (NT-008).
❓ FAQ — Perguntas Frequentes sobre Schemas da DPS Nacional
1. Por que o código de município (cMun) é proibido no endereço de imóvel da DPS?
No schema TCEnderObraEvento da Receita Federal, a localização do imóvel/obra é identificada primordialmente pelo CEP ou pelo código CIB (Cadastro Imobiliário Brasileiro), dispensando a tag de município que causaria erro de validação sintática.
2. O que é o código CIB (cCIB) no grupo <imovel>?
O CIB é o identificador único nacional do imóvel com 8 dígitos. No XML da DPS, o desenvolvedor pode optar por informar o <cCIB> ou o endereço físico completo (<end>).
3. Como validar localmente o XML da DPS antes do envio?
Utilize a ferramenta xmllint apontando para o schema oficial:
xmllint --noout --schema schemas/snnfse/1.01/DPS_v1.01.xsd dps-gerada.xml
4. A Notaas realiza a validação de schema antes de transmitir para a prefeitura/SEFIN?
Sim. O motor da Notaas realiza validação síncrona prévia via schema XSD oficial e regras semânticas de negócio, retornando erros claros em JSON antes mesmo da chamada chegar aos servidores governamentais.
🚀 Evite rejeições de XML e emita NFS-e Nacional sem complexidade:
- Crie sua conta grátis na Notaas com 50 notas fiscais por mês em produção real.
- Acesse a documentação técnica para consultar os endpoints e SDKs oficiais.