Lendo uma mensagem XML

Os serviços fiscais, os serviços SOAP e muitas integrações antigas trocam mensagens em XML. Uma resposta XML pode trazer o resultado em um elemento, um detalhe em um atributo e uma recusa em outro nível da estrutura, e a leitura apressada de uma dessas partes leva a conclusões erradas.

As peças do formato

O XML organiza os dados em uma árvore de elementos:

• Declaração: a primeira linha, opcional, como <?xml version="1.0" encoding="UTF-8"?>, que informa a versão do XML e a codificação dos caracteres.
• Elemento: um nome entre os sinais de menor e de maior, com abertura e fechamento, como <motivo>Autorizado</motivo>.
• Atributo: um par de nome e valor dentro da abertura de um elemento, como versao="1.00" em <retorno versao="1.00">.
• Conteúdo: o texto ou os outros elementos entre a abertura e o fechamento, em vários níveis.
• Raiz: o elemento único que envolve todos os outros.

Todo valor do XML é texto. O valor 00012, dentro de um elemento, só vira número quando o programa que lê converte esse texto, e o contrato informa o tipo esperado de cada campo. O XML também não tem uma forma própria de escrever listas, e uma lista aparece como a repetição do mesmo elemento, como em <itens><item>...</item><item>...</item></itens>.

Os nomes dos elementos diferenciam letras maiúsculas e minúsculas. Os elementos <Motivo> e <motivo> são diferentes.

Namespaces

Um namespace identifica o vocabulário a que um elemento pertence, por meio de um endereço declarado no atributo xmlns. Dois serviços podem usar o mesmo nome de elemento com significados diferentes, e o namespace separa os dois. Um prefixo, como soap: em <soap:Envelope>, é só um apelido para o namespace declarado. O endereço identifica o vocabulário, e por isso a troca do prefixo não muda o significado da mensagem.

Bem-formado e válido

Um XML bem-formado segue as regras do formato: cada elemento aberto é fechado, os elementos não se cruzam, existe uma única raiz e os caracteres especiais estão escritos da forma correta. Um XML válido é bem-formado e, além disso, segue o schema, o arquivo de definição que estabelece os elementos permitidos, a ordem, os tipos e os tamanhos. Os schemas costumam usar a extensão .xsd e fazem parte do contrato.

Uma mensagem bem-formada pode ser recusada por falha de schema, como um elemento obrigatório ausente, um elemento fora da ordem ou um valor maior que o tamanho permitido. A mensagem de recusa costuma indicar o elemento e a regra violada.

Os caracteres especiais

Alguns caracteres têm função no próprio formato e, dentro do texto, aparecem escritos de outra forma:

• & representa o sinal &;
• < representa o sinal <;
• > representa o sinal >;
• " representa as aspas duplas;
• ' representa o apóstrofo.

Uma descrição de produto como Arroz & Feijão, gravada sem essa conversão, deixa o XML malformado e provoca a recusa da mensagem inteira. A codificação declarada na primeira linha também precisa corresponder aos bytes do arquivo, porque um acento gravado em uma codificação e lido em outra aparece trocado.

Vazio e ausente

Três situações aparecem com frequência e são diferentes:

• Elemento vazio: o elemento existe sem conteúdo, escrito como <complemento></complemento> ou na forma curta <complemento/>.
• Elemento ausente: o elemento nem aparece na mensagem.
• Atributo ausente: o atributo não aparece na abertura do elemento.

O schema define quais elementos podem faltar e se um elemento pode vir vazio. Muitos serviços recusam um elemento vazio no lugar de um elemento omitido, e o contrário também acontece.

A assinatura do XML

Um XML pode levar uma assinatura digital em um elemento próprio, que comprova a autoria e a integridade de uma parte da mensagem. Qualquer mudança na parte assinada, mesmo um espaço ou uma quebra de linha, invalida a assinatura. Por isso, uma cópia formatada para leitura serve para a análise, e o original assinado fica preservado para a consulta ou o reenvio. A presença do elemento de assinatura também não comprova que a assinatura é válida, porque a validação depende do certificado e do conteúdo assinado.

O resultado dentro da resposta

Na resposta de um serviço, o resultado costuma ficar em elementos com um código e um motivo, que podem aparecer em mais de um nível. Uma resposta pode informar que o lote foi processado e, em um nível abaixo, que um dos documentos foi recusado. O status HTTP descreve o atendimento da chamada, e os códigos dentro do XML descrevem o resultado do negócio.