Integração com sistema do governo: registre no código a versão do manual

Sexta, 17h, o envio para o sistema do órgão começa a voltar rejeitado. No código, o único rastro é um comentário: "conforme o manual". Qual manual? O de dois anos atrás ou o que saiu mês passado, com um campo novo obrigatório? Ninguém sabe se a rejeição é bug seu ou atraso seu. A resposta curta: registre no repositório a identificação exata do manual que você implementou (nome, versão, data de publicação, data em que você conferiu e um hash do arquivo), guarde uma cópia do documento e transforme os exemplos dele em testes. Quando sair a revisão seguinte, a diferença vira uma tarefa com escopo, não uma surpresa no fim de semana.

Manual de integração de governo muda: leiaute de compras, nota fiscal, prestação de contas. O que não pode mudar sem você saber é qual versão o seu código segue.

Por que "conforme o manual" não diz nada

O manual vive numa página que troca o PDF sem mudar o endereço, ou muda o endereço sem redirecionar. Seis meses depois, quem abre o link vê a versão atual, não a que você leu. O comentário no código continua afirmando conformidade com um documento que já não existe ali.

Isso tem três custos. No diagnóstico, a pessoa de plantão não sabe se deve procurar um bug ou uma mudança de regra. Na manutenção, ninguém consegue listar o que precisa mudar, porque não há base de comparação. E na conversa com o órgão ou com o cliente, "seguimos o manual" sem versão não sustenta nada. O post sobre PDF de integração como especificação com data trata de como ler esse documento; aqui o foco é como deixar a versão gravada no seu sistema.

Como registrar a versão que você implementou

O exemplo é um módulo que envia processos de compra para um sistema do governo. Os nomes de campos abaixo são fictícios; os do seu manual serão outros, mas a estrutura é a mesma.

1. Guarde o documento. Salve o PDF no repositório ou num armazenamento interno, com o nome contendo a versão: docs/integracao/manual-compras-v3.2.pdf.
2. Calcule o hash do arquivo. Ele prova qual arquivo exato você leu, mesmo que a capa não tenha mudado.
3. Crie um registro legível com nome, versão, data de publicação, data da conferência, endereço de origem e hash.
4. Exponha a versão no código numa constante que os logs e os registros de envio usam.
5. Transforme os exemplos do manual em testes, citando a página, e acrescente os casos de erro que o manual descreve.
6. Grave a versão junto de cada envio no banco, para saber com qual leiaute cada registro saiu.

O hash do arquivo

# Linux e macOS
sha256sum docs/integracao/manual-compras-v3.2.pdf

# Windows PowerShell
Get-FileHash docs/integracao/manual-compras-v3.2.pdf -Algorithm SHA256

A constante que o código usa

// src/compras/leiaute.js
module.exports = {
  manual: 'Manual de Integração de Compras',
  versao: '3.2',
  publicadoEm: '2025-03-10',
  conferidoEm: '2025-04-02',
  origem: 'https://www.exemplo.gov.br/manuais/compras',
  sha256: '9f2c4e...b71a',
  obrigatorios: ['cnpjOrgao', 'numeroProcesso', 'dataAbertura', 'codigoUnidade']
};

O hash aparece abreviado aqui; no seu arquivo, cole o valor completo que o comando devolveu. A lista de obrigatórios fica na mesma constante porque é a parte do manual que mais muda entre versões.

Os testes que citam o manual

// test/compras.test.js
const test = require('node:test');
const assert = require('node:assert');
const leiaute = require('../src/compras/leiaute');
const { validarProcesso } = require('../src/compras/validar');

const exemploPagina41 = {
  cnpjOrgao: '00000000000191',
  numeroProcesso: '2025/0042',
  dataAbertura: '2025-05-12',
  codigoUnidade: '123456'
};

test('manual ' + leiaute.versao + ', p. 41: exemplo completo é aceito', () => {
  assert.deepStrictEqual(validarProcesso(exemploPagina41), []);
});

test('manual ' + leiaute.versao + ': sem codigoUnidade é recusado', () => {
  const { codigoUnidade, ...semUnidade } = exemploPagina41;
  assert.deepStrictEqual(validarProcesso(semUnidade), ['codigoUnidade']);
});

// src/compras/validar.js
const leiaute = require('./leiaute');

function validarProcesso(processo) {
  return leiaute.obrigatorios.filter((campo) => !processo[campo]);
}

module.exports = { validarProcesso };

Quando a versão nova chegar, o nome do teste já diz qual manual ele cobre, e o teste que falha aponta o que mudou.

Como tratar a versão nova quando ela sai

Muitos manuais trazem um histórico de revisões nas primeiras páginas. Ele é o ponto de partida, não a lista completa: confira também as tabelas de campos e os exemplos, porque nem toda mudança entra no histórico.

1. Baixe o novo arquivo, calcule o hash e compare com o registrado. Hash igual encerra a dúvida.
2. Abra uma tarefa por mudança encontrada: campo novo, tamanho alterado, código de erro novo.
3. Copie os exemplos novos para os testes, com a página da nova versão.
4. Descubra a data de vigência. Se o órgão aceita as duas versões por um tempo, a versão em uso pode ser configuração por data, não um corte seco no deploy.
5. Atualize a constante e o registro só quando o código novo estiver em produção.

Se você usa uma biblioteca pronta para o leiaute, a mesma regra vale para ela: confira qual versão do manual ela implementa, como discute o post sobre biblioteca fiscal que não acompanha o leiaute sozinha.

Erros comuns

• Comentário "conforme o manual" sem versão: no dia da rejeição, ninguém sabe se o problema é bug ou mudança de regra.
• Guardar só o link para o PDF: a página troca o arquivo ou some, e você perde a referência do que implementou.
• Copiar tabelas para uma planilha solta: a planilha diverge do código na primeira alteração e vira uma terceira versão da verdade.
• Testar só com dados inventados: o exemplo oficial do manual é o caso que o órgão garante aceitar; sem ele, você testa a sua interpretação.
• Não gravar a versão em cada envio: quando o órgão questiona um registro antigo, não dá para saber com qual leiaute ele saiu.
• Atualizar o código no dia da publicação sem olhar a vigência: você passa a mandar campos que o órgão ainda não aceita.

Checklist

• Existe uma cópia do manual implementado, com a versão no nome do arquivo.
• O hash do arquivo está registrado no repositório.
• Uma constante no código expõe nome, versão e datas do manual.
• Os exemplos do manual são testes automatizados que citam a página.
• Os casos de recusa descritos no manual também têm teste.
• Cada envio gravado no banco carrega a versão do leiaute usada.
• Alguém verifica periodicamente se saiu revisão nova.

Abra o módulo de integração mais antigo do seu sistema e procure a versão do manual que ele segue. Se o órgão publicar uma revisão amanhã, você sabe exatamente com o que comparar?