Não encontrado não é não existe: como ler a resposta de uma consulta

Toda consulta de verificação faz a mesma pergunta a uma fonte externa: o que você sabe sobre este documento? A resposta volta em quatro formatos jurídica e operacionalmente distintos. A fonte respondeu e nada consta. Respondeu e há apontamento. Respondeu que não conhece o documento. Ou não respondeu.

Na maioria das integrações os quatro entram num campo booleano e saem como aprovado ou reprovado. É confortável de programar, e é onde nasce boa parte dos incidentes de compliance que aparecem meses depois, quando alguém pede a evidência de uma diligência e encontra um registro que afirma mais do que houve.

Este artigo separa os quatro desfechos, mostra o estrago de cada colapso e deriva três decisões de projeto: cache com prazo por classe de resposta, base vencida que vira revisão humana, e contrato de resposta que separe por escrito o não consultado do consultado sem resultado.

O protocolo já separa o que a integração junta

Antes de virar problema de compliance, isso é semântica, e o HTTP resolveu a distinção há décadas. A RFC 9110, especificação vigente da semântica do HTTP no IETF, define na seção 15.5.5 que o 404 indica que o servidor de origem não encontrou uma representação atual para o recurso alvo, ou não está disposto a revelar que uma existe, e que o código não diz se a ausência é temporária ou permanente: quando a condição é sabidamente permanente, o preferido é o 410, da seção 15.5.11.

A seção 15.6.4 trata de outra coisa: o 503 indica servidor atualmente incapaz de atender à requisição por sobrecarga temporária ou manutenção programada, com o cabeçalho Retry-After para sugerir quando tentar de novo. A diferença é de sujeito. O 404 e o 410 falam do recurso, o 503 fala do servidor: um diz que o documento não foi encontrado, o outro diz que ninguém chegou a procurar.

A distinção tem consequência na própria especificação. A seção 15.1 lista os códigos heuristicamente cacheáveis, entre eles 200, 404, 405 e 410, e diz que todos os demais não são, o que deixa os códigos de falha do servidor de fora. O protocolo já decidiu que não achei é resposta que se pode guardar e que não consegui não é. A integração que junta as duas num valor falso apaga essa decisão.

O colapso do meio é o caro

Dos quatro colapsos possíveis, três doem e um é grave.

Tratar a fonte não conhece este documento como apontamento reprova cliente legítimo por vazio de base, e ele não tem como recorrer do que ninguém sabe explicar. Tratar apontamento como reprovação genérica, sem guardar qual lista apontou, produz decisão que a própria empresa não justifica depois. Os dois custam conversão e retrabalho.

O grave é o do meio: tratar indisponibilidade como nada consta. Aí não se perde um cliente, registra-se uma diligência que não aconteceu. E registro é o que a norma cobra. A Lei 9.613/1998, no artigo 10, obriga as pessoas listadas no artigo 9º a identificar seus clientes e manter cadastro atualizado, e a manter registro das transações que ultrapassem o limite fixado pela autoridade competente; o parágrafo 2º manda conservar cadastros e registros por no mínimo cinco anos a partir do encerramento da conta ou da conclusão da transação. Para instituição regulada pelo Banco Central a régua aperta: a Circular BCB 3.978/2020 exige, no artigo 28, registro das operações com informações que permitam reconstruí-las, manda formalizar a análise em dossiê nos artigos 43 a 46 e, no artigo 67, conservar tudo por no mínimo dez anos.

Ninguém audita o instante da consulta. Audita-se o registro, anos depois. Um registro que diz consultado, nada consta, sem evidência de que a fonte respondeu, é pior que registro ausente: a ausência é lacuna, o outro é afirmação que não se sustenta.

O que o cadastro brasileiro responde de verdade

Quem integra com fonte pública brasileira aprende rápido que não encontrado e irregular vivem em planos diferentes.

A Receita Federal publica, na página Meu CPF, as situações possíveis de uma inscrição: Regular, Suspenso, Pendente de Regularização, Falecido, Cancelado e Nulo (Nulo, por exemplo, é a inscrição considerada nula em razão de fraude). Repare no que não está na lista: inexistente. Um CPF que a base não conhece não tem situação cadastral, ele não tem linha. A consulta devolve erro, não estado, e esse erro é informação diferente das seis. O mesmo vale para os estados cadastrais do CNPJ.

O dígito verificador reforça a separação. Um CPF ou um CNPJ bem formado passa no cálculo do dígito e pode nunca ter existido: o dígito prova consistência aritmética, não existência. Com o CNPJ alfanumérico, instituído pela Instrução Normativa RFB 2.229/2024, o cálculo passou a usar valores derivados da tabela ASCII dos caracteres, e a lição só fica mais visível: validar formato responde a outra pergunta.

Do lado da pessoa jurídica há um terceiro caso que confunde integração: a lista legitimamente vazia. Um quadro societário que volta sem nenhum sócio pode ser a resposta correta para naturezas jurídicas que não têm sócios, e é dado diferente de não consegui ler o quadro, distinção detalhada no artigo sobre consulta de QSA. O mesmo vale para o documento: contrato de constituição não traz CNPJ, porque a empresa ainda não tinha inscrição quando ele foi assinado. Não achar o número ali é afirmação sobre o arquivo, nunca sobre a empresa, e em KYB essa é a diferença entre pedir outro arquivo e reprovar empresa que existe.

Prazo de cache por classe de desfecho

Separados os desfechos, o prazo de cache deixa de ser número único de configuração e vira decisão por classe.

Inexistência é resposta estável: documento que a base não conhece hoje dificilmente passa a conhecer em uma hora. Nada consta envelhece rápido, porque listas de sanção, de restrição e de pessoa exposta politicamente são atualizadas em lote, e quem não estava no lote de ontem pode estar no de hoje. E indisponibilidade nunca vira linha de cache, porque não é resposta sobre o documento: é resposta sobre a fonte.

A RFC 9111, especificação de cache do HTTP, dá o vocabulário. A seção 4.2.2 permite frescor heurístico quando não há expiração explícita e sugere, para respostas com Last-Modified, uma fração do intervalo desde aquela data, com 10% como ajuste típico. A seção 4.2.4 proíbe gerar resposta obsoleta salvo cache desconectado ou permissão explícita. E a seção 5.2.2.2, sobre a diretiva must-revalidate, diz que ela cabe quando a falha em validar puder causar operação incorreta, dando como exemplo uma transação financeira silenciosamente não executada, e que cache desconectado deve gerar erro em vez de reutilizar resposta obsoleta.

Vale conhecer o atalho feito para o caso contrário: a extensão stale-if-error, da RFC 5861, autoriza servir conteúdo obsoleto quando a origem devolve 500, 502, 503 ou 504. Numa página de catálogo, é boa engenharia. Numa consulta que vira evidência de diligência, é a forma mais elegante de gravar um nada consta que ninguém consultou.

Vencido vira revisão, e a resposta diz o que consultou

As duas últimas consequências são de produto, não de infraestrutura.

A primeira: base vencida ou indisponível não aprova por inércia nem reprova por azar. O caso vai para revisão humana com o motivo explícito, e a nova tentativa segue a política de retentativa do fluxo, que exige idempotência. Como a verificação não foi feita, cobrar por ela é vender diligência que não ocorreu. Na UNIFOKAL, por exemplo, fonte que não respondeu não vira veredito, vira pendência sinalizada, e não entra na conta do cliente.

A segunda: o contrato de resposta precisa dizer, lista por lista, o que foi consultado. Um objeto que devolve só aprovado obriga quem integra a adivinhar. Um objeto que devolve, para cada base, o estado da consulta (respondida, sem resultado, indisponível), o veredito quando houver e a data do lote ao lado dele deixa reconstruir a decisão anos depois sem depender da memória de ninguém. A data do lote é o campo mais esquecido e o mais cobrado numa auditoria: dizer que alguém não estava numa lista sem dizer de quando ela era é dizer quase nada.

Uma regra de bolso para revisar sua integração hoje: ache no código o ponto em que a resposta da fonte vira booleano e conte quantos desfechos chegam ali. Se chegam quatro e sai um bit, o resto do sistema decide com menos informação do que a fonte deu.

Fontes citadas

• RFC 9110, HTTP Semantics, do IETF, seções 15.1, 15.5.5, 15.5.11 e 15.6.4: rfc-editor.org
• RFC 9111, HTTP Caching, do IETF, seções 4.2.2, 4.2.4, 4.3 e 5.2.2.2: rfc-editor.org
• RFC 5861, extensões de Cache-Control para conteúdo obsoleto, do IETF: rfc-editor.org
• Lei 9.613/1998, artigo 10, incisos I e II, e parágrafo 2º, no portal do Senado Federal
• Circular BCB 3.978/2020, artigos 28, 43 a 46 e 67, no site do Banco Central
• Receita Federal do Brasil, página Meu CPF, com as situações cadastrais possíveis: gov.br/receitafederal
• Instrução Normativa RFB 2.229/2024, da Receita Federal, que instituiu o CNPJ alfanumérico