Esquema XML

O que é um esquema XML, em palavras simples?

Pense no esquema XML como um formulário oficial com instruções de preenchimento. Ele diz exatamente quais campos o documento precisa ter, em que ordem eles devem aparecer, quantos caracteres cada campo pode ter e se o valor deve ser um número, uma data, um texto ou um código de uma lista fechada.

Tecnicamente, o esquema é escrito em uma linguagem chamada XML Schema Definition, por isso os arquivos costumam ter a extensão .xsd. Ele não contém dados de nenhuma nota específica; contém apenas as regras que todas as notas daquele tipo devem seguir.

Para que serve o esquema XML nos documentos fiscais?

Documentos como NF-e, NFC-e, CT-e, MDF-e e NFS-e são transmitidos em XML. Para que milhões de sistemas diferentes conversem com os órgãos autorizadores sem confusão, todos precisam seguir a mesma estrutura. O esquema garante essa padronização.

Os órgãos responsáveis, como a SEFAZ no caso da NF-e e o ambiente do Padrão Nacional no caso da NFS-e, publicam pacotes de esquemas oficiais. Quando um documento chega, a primeira verificação feita é se o XML respeita esse esquema. Se não respeitar, o documento é rejeitado antes mesmo de as regras de negócio serem analisadas.

Como funciona a validação por esquema?

Um programa validador compara o XML com o arquivo XSD, item por item. Ele confere se nenhum campo obrigatório está faltando, se não há campos fora de lugar, se os valores têm o formato esperado (por exemplo, datas no padrão correto e valores com a quantidade certa de casas decimais) e se os códigos pertencem às listas permitidas.

A validação por esquema verifica a forma, não o conteúdo fiscal. Um XML pode passar no esquema e ainda assim ser rejeitado por uma regra de negócio, como uma alíquota incompatível com a operação ou um CFOP inadequado. Por isso, o esquema é a primeira barreira, mas não a única.

Qual a diferença entre esquema XML e leiaute fiscal?

O leiaute fiscal é a descrição documentada dos campos, normalmente publicada em manuais e notas técnicas, escrita para pessoas lerem. O esquema XML é a tradução dessas regras para um formato que computadores conseguem verificar automaticamente.

Quando uma nota técnica altera o leiaute, por exemplo para incluir novos grupos de tributação, os esquemas também são atualizados. Sistemas que continuam usando a versão antiga passam a gerar XMLs que não são mais aceitos.

Qual a diferença entre esquema XML e JSON Schema?

Os dois têm o mesmo propósito: descrever e validar a estrutura de dados. A diferença é o formato que validam. O esquema XML se aplica a documentos XML, enquanto o JSON Schema se aplica a dados em JSON, formato muito usado em APIs modernas.

Em uma API fiscal, é comum o sistema do cliente enviar os dados em JSON, validados por um JSON Schema, e a infraestrutura de emissão converter esses dados em um XML que respeite o esquema oficial exigido pelo órgão autorizador.

Por que o esquema XML importa para quem integra por API?

Montar XML fiscal manualmente exige acompanhar cada versão dos esquemas, tratar namespaces, ordem de elementos e detalhes de formatação. Qualquer deslize gera rejeição por falha de esquema, uma das causas mais comuns de erro em integrações.

Ao usar uma API de emissão como o Conota, o sistema do cliente envia os dados da venda e a API se encarrega de gerar o XML conforme o esquema vigente, assinar e transmitir. Isso reduz o trabalho de manutenção quando os esquemas mudam e concentra o tratamento de rejeições em um só lugar.

Exemplos de Esquema XML

• Um ERP envia uma NF-e com a data de emissão sem o fuso horário. O XML não passa na validação de esquema e o documento é rejeitado por falha de schema antes de qualquer análise tributária.
• Após a publicação de uma nota técnica que inclui novos campos de IBS e CBS, a equipe de desenvolvimento baixa o novo pacote de esquemas XSD e atualiza o validador interno para continuar emitindo sem erros.
• Uma plataforma de marketplace valida localmente cada XML de NFC-e contra o esquema oficial antes de transmitir, evitando idas e voltas desnecessárias ao autorizador.
• Um desenvolvedor recebe um erro informando que o campo de valor total tem mais casas decimais do que o permitido; o limite de casas estava definido no esquema XML do documento.