Como validar os dados recebidos por uma API de NFS-e
· 6 min de leitura
Receber uma resposta com sucesso da API não significa que o dado está pronto para uso: vale validar em três níveis antes de alimentar sistemas internos: estrutura, conteúdo fiscal e consistência geral.
Validação de estrutura
O primeiro nível é confirmar que o XML (ou JSON) retornado segue o schema esperado: campos obrigatórios presentes, tipos de dado corretos. Um documento que falha nesse nível provavelmente indica uma mudança de leiaute não acompanhada pela integração, não um problema pontual daquela nota.
Validação de conteúdo fiscal
O segundo nível confere se os valores fazem sentido: CNPJ do prestador e do tomador preenchidos e coerentes com o esperado, valor do serviço maior que zero, campos tributários (incluindo os novos de IBS/CBS) consistentes entre si. Esse nível pega problemas que passam despercebidos por uma validação puramente estrutural.
Tratamento de inconsistências
Quando algo não bate (um campo esperado ausente, um valor fora do padrão), a prática mais segura é sinalizar para revisão manual em vez de silenciosamente ignorar ou assumir um valor padrão. Um dado fiscal errado, tratado como se estivesse correto, tende a gerar problema mais adiante, na conciliação ou na escrituração.
Perguntas frequentes
O que fazer quando o dado retornado parece incompleto?
Primeiro, confirmar que não é um erro de consulta disfarçado de dado incompleto: veja erros e códigos de retorno comuns. Se o retorno realmente veio incompleto, vale registrar o caso para revisão manual em vez de descartar o documento.
Essa validação muda entre consulta em lote e individual?
Não: os mesmos três níveis de validação valem independentemente de como o documento foi obtido. Veja a diferença entre as duas formas de consulta em consulta em lote x consulta individual via API de NFS-e.
Implementar essas três camadas de validação por conta própria é trabalho real de engenharia. A IntegroBR NFS-e Recebidas já entrega o documento estruturado e organizado para o período que você escolher monitorar, poupando pelo menos a etapa de transformar o XML bruto em algo utilizável.