PDF de integração do governo mudou: como guardar, comparar e testar cada revisão

O envio de XML para o sistema de compras começa a ser rejeitado numa terça, e a mensagem cita um campo que ninguém da equipe lembra de ter visto. Um desenvolvedor jura que implementou "conforme o manual". O outro abre o PDF no site e o campo está lá, na página 47. Os dois leram o manual, só que em edições diferentes. O código tinha um comentário dizendo "ver manual" e nenhuma pista de qual.

A resposta curta: o PDF de integração é especificação com data. Guarde no repositório o arquivo exato que você implementou, com hash e data de download, verifique periodicamente se o órgão publicou outro, compare as revisões em texto e transforme cada diferença em tarefa com teste. Assim "o manual mudou" vira um diff, não uma investigação.

Por que o PDF é a parte mais frágil da integração

APIs modernas costumam ter versão no endereço, changelog e esquema publicado. Muitas integrações com órgãos públicos ainda são definidas por um manual em PDF, publicado sempre no mesmo endereço. Quando sai uma nova edição, o link continua igual e o conteúdo muda. Quem baixou antes tem uma versão; quem baixa hoje tem outra.

Com o tempo, o PDF baixado vai parar na pasta de downloads de alguém que saiu da empresa. O código passa a ser a única "documentação" do que foi implementado, e ninguém sabe dizer se um comportamento foi decisão, engano ou exigência de uma revisão antiga. O post sobre anotar a data do manual de integração explica por que registrar a versão importa. Aqui o foco é o mecanismo: onde guardar, como detectar a mudança e como comparar.

Como manter o manual sob controle, passo a passo

1. Crie uma pasta da integração no repositório, por exemplo docs/integracoes/sidec/, e guarde nela o PDF que você implementou.
2. Registre a origem num arquivo de texto ao lado: URL, data do download, identificação da revisão que aparece no próprio documento e hash SHA-256 do arquivo.
3. Cite seção e revisão no código onde uma regra do manual é implementada.
4. Agende uma verificação que baixa o PDF publicado e compara com o guardado.
5. Quando mudar, extraia o texto das duas versões e compare. Cada diferença relevante vira uma tarefa.
6. Escreva um teste por regra alterada, com o XML de exemplo correspondente.
7. Atualize o arquivo guardado só quando o código estiver adaptado, no mesmo commit.

O registro de origem

Um arquivo simples resolve. Ele responde, em segundos, à pergunta "qual manual o sistema segue?".

# docs/integracoes/sidec/ORIGEM.md
Documento: Manual de integração XML (SIDEC)
URL: https://www.gov.br/compras/pt-br/acesso-a-informacao/manuais/manual-siasg/manual-siasg-sidec/manual_sidec_integracao_xml.pdf
Arquivo guardado: manual-sidec-xml-2026-03-10.pdf
Baixado em: 2026-03-10
Revisão indicada no documento: (copiar da capa ou do histórico de versões)
SHA-256: (saída do sha256sum)
Implementado no commit: (hash)

No código, a referência passa a ser precisa:

// Regra do campo de data de publicação: manual SIDEC XML guardado em
// docs/integracoes/sidec/manual-sidec-xml-2026-03-10.pdf, seção do leiaute do aviso.

Isso substitui o "ver manual" por algo que qualquer pessoa da equipe abre e confere.

A verificação agendada

O script abaixo baixa o PDF publicado, confere que o que veio é mesmo um PDF (e não uma página de erro em HTML) e compara o hash com o guardado. Rode semanalmente no CI ou num agendador.

#!/usr/bin/env bash
set -euo pipefail

URL="https://www.gov.br/compras/pt-br/acesso-a-informacao/manuais/manual-siasg/manual-siasg-sidec/manual_sidec_integracao_xml.pdf"
DIR="docs/integracoes/sidec"
TMP=$(mktemp)

curl -fsSL -o "$TMP" "$URL"

if [ "$(head -c 4 "$TMP")" != "%PDF" ]; then
  echo "O endereço não devolveu um PDF. Confira se o manual mudou de lugar." >&2
  exit 1
fi

NOVO=$(sha256sum "$TMP" | cut -d ' ' -f 1)
ATUAL=$(cut -d ' ' -f 1 "$DIR/manual.sha256")

if [ "$NOVO" != "$ATUAL" ]; then
  cp "$TMP" "$DIR/manual-publicado-$(date +%F).pdf"
  echo "O PDF publicado é diferente do implementado. Compare as versões."
  exit 2
fi

echo "Manual sem alteração."

Hash diferente nem sempre significa conteúdo diferente: um PDF regerado com outra data interna também muda o hash. Por isso o passo seguinte compara o texto. No Windows, Get-FileHash -Algorithm SHA256 no PowerShell dá o mesmo hash.

A comparação em texto

Comparar PDFs visualmente, página a página, é lento e falha. Extraia o texto das duas versões com o pdftotext, do pacote Poppler, e compare com o Git, mesmo fora de um repositório:

pdftotext -layout manual-sidec-xml-2026-03-10.pdf antigo.txt
pdftotext -layout manual-publicado-2026-10-12.pdf novo.txt
git diff --no-index --word-diff antigo.txt novo.txt

O -layout preserva a disposição das tabelas de campos, que é onde a maioria das mudanças acontece. O --word-diff mostra a palavra alterada dentro da linha, em vez de marcar a linha inteira. Tabelas que mudaram de página geram ruído; leia com atenção as diferenças em nomes de campo, obrigatoriedade, tamanho, formato e valores permitidos.

Do diff para o código

Cada diferença relevante vira uma tarefa com três partes: o trecho do manual antigo, o novo e o que muda no sistema. Se o órgão publica esquemas XSD junto do manual, valide o XML gerado contra o esquema no teste; se não publica, o teste confere o XML gerado contra um exemplo montado a partir do manual. Gerar o XML com uma biblioteca, e não concatenando texto, torna essas mudanças bem mais baratas, como mostra o post sobre gerar XML sem concatenar texto. Se o leiaute tem número de versão dentro do arquivo, trate-o como parte do contrato; veja por que a versão do leiaute faz parte do XML de compras.

Só quando o código estiver adaptado e testado, troque o PDF guardado, atualize o ORIGEM.md e o hash, tudo no mesmo commit. O histórico do Git passa a contar qual manual valia em cada época do sistema. Manual técnico publicado é documento público, mas exemplos com dados de processo, não: não cole trechos com dado real em issue aberta.

Erros comuns

• Comentário "ver manual" sem revisão: ninguém sabe qual edição foi implementada, e cada rejeição vira uma investigação.
• PDF guardado só na máquina de alguém: a pessoa sai da empresa e a referência vai junto.
• Baixar o manual de novo para "conferir" e sobrescrever o antigo: você perde a versão que o código segue e não consegue mais comparar.
• Confiar só no hash: PDF regerado muda o hash sem mudar regra, e o alarme falso faz a equipe ignorar o próximo.
• Implementar de memória o campo que você lembra: a regra mudou de tamanho ou obrigatoriedade e o envio é rejeitado.
• Atualizar o PDF guardado antes do código: o repositório passa a dizer que segue uma revisão que ainda não implementa.

Checklist

• O PDF implementado está no repositório, com data no nome.
• Existe um arquivo de origem com URL, data, revisão indicada no documento e hash.
• Regras do manual no código citam o arquivo e a seção.
• Uma verificação agendada compara o PDF publicado com o guardado.
• A verificação detecta quando o endereço devolve algo que não é PDF.
• Mudanças são comparadas em texto com pdftotext e diff.
• Cada regra alterada tem um teste com XML de exemplo.

Se hoje alguém perguntar qual revisão do manual o seu sistema segue, você abre um arquivo no repositório ou começa a procurar e-mails antigos?