# Registro de requisições sem o corpo: o histórico de API que não vira banco de dado pessoal Guia · UNIFOKAL · 23 de setembro de 2026 · 7 min de leitura · Produto e integração Guardar a carga de cada chamada para o cliente inspecionar cria um segundo banco de CPFs. Como desenhar um registro de requisições só com metadado, e por que a ausência da coluna é a garantia. Quando uma integração de verificação de identidade dá errado, a primeira pergunta do time é sempre a mesma: o que exatamente a minha aplicação mandou, e o que voltou? Alguns provedores respondem guardando a carga completa de requisição e resposta para o cliente inspecionar no painel. É conveniente e é um erro de desenho: numa API que recebe CPF, nome e documento em cada chamada, esse histórico é um segundo banco de dados pessoais, com prazo próprio, superfície de leitura própria e uma segunda chance de vazar o mesmo dado. Este artigo explica como o registro de requisições da UNIFOKAL foi desenhado para responder à pergunta do time sem guardar o corpo, e por que a garantia é estrutural, não uma regra que alguém lembra de seguir. ## O que o registro guarda Cada chamada autenticada à API deixa uma linha com o que é preciso para localizar e entender a chamada: o identificador da requisição, a credencial que a autenticou (chave secreta, sessão do painel ou credencial do widget), a chave ou o membro que agiu, o método, a rota, o status HTTP, a duração e o código de erro do envelope, quando houve erro. O registro fica trinta dias e pode ser filtrado por identificador, por chave ou membro e por período, direto no painel. O identificador é o mesmo `x-request-id` que a resposta devolve. Se a sua aplicação envia o próprio identificador no cabeçalho, ele é ecoado e gravado, e a correlação entre o seu log e o nosso registro passa a ser uma busca por texto exato. É por esse identificador que você cita uma chamada no suporte. ## O que o registro não guarda, e por que isso é estrutural O registro não guarda o corpo da requisição, o corpo da resposta, os cabeçalhos, a query string nem o endereço IP. Não guarda a mensagem de erro, só o código: a mensagem é texto livre, e texto livre é por onde um dado pessoal volta a entrar num lugar que prometia não ter nenhum. A parte importante é como isso é garantido. Não é uma instrução no manual de quem escreve o código. A tabela do registro não tem coluna onde o corpo caberia: não existe `payload`, `body`, `headers` nem `query`. Acrescentar uma exigiria uma migração de banco, uma mudança na porta do repositório e a alteração de uma lista fechada de colunas num teste de esquema, que são três atos deliberados. Dois testes cobram a promessa: um compara o conjunto de colunas da tabela, e de cada partição mensal, contra a lista fechada; o outro faz uma requisição real com um CPF sintético no corpo e outro na query string e afirma que nenhum pedaço de seis caracteres de nenhum dos dois aparece em nenhuma coluna da linha gerada. A rota gravada é o padrão da rota, como `/v1/verifications/:id`, e nunca o caminho concreto com o identificador do recurso. Identificador de recurso é a porta por onde um identificador de titular entraria num registro que promete ser só metadado. Perde-se pouco, porque a correlação é pelo identificador da requisição, e fecha-se a porta inteira. ## Log de aplicação não é a mesma coisa Vale separar dois objetos que costumam ser confundidos. O log de aplicação é o que a equipe do provedor lê para depurar o produto: mensagens, pilhas de erro, contexto interno. O registro de requisições é dado de produto, por cliente, que o cliente lê no painel dele sob isolamento de organização e de ambiente. Os dois têm leitores diferentes, prazos diferentes e regras diferentes, e misturá-los produz o pior dos dois mundos: um log que expõe o interno ao cliente e um registro que cresce sem prazo. O guia de registro de eventos da OWASP recomenda, entre os dados a excluir de logs, os dados pessoais além do necessário e os segredos de autenticação, e tratar o que se grava com a mesma cautela do que se protege. O registro sem corpo é a aplicação literal dessa recomendação ao caso em que o próprio cliente é o leitor. Já discutimos o outro lado dessa moeda em [auditoria de logs e dados pessoais](https://unifokal.com/blog/auditoria-de-logs-e-dados-pessoais) e no [prazo de guarda de registros do Marco Civil](https://unifokal.com/blog/guarda-de-logs-marco-civil): guardar mais do que a finalidade pede é passivo, não ativo. ## Escrita fora do caminho da requisição Um registro de requisições que derruba a API que ele observa é pior do que registro nenhum. Por isso a linha não é gravada no caminho da requisição: ela entra num buffer em memória quando a resposta termina e sai num lote periódico para o banco. O buffer é limitado de propósito, e quando ele estoura sob uma rajada a linha nova é descartada e o descarte é contado numa métrica, nunca silenciado. Sob carga, perder algumas linhas de metadado é aceitável; segurar memória até derrubar o processo não é. O desligamento do serviço esvazia o buffer antes de fechar a conexão com o banco, porque as últimas centenas de milissegundos de registro de um restart são exatamente a janela que alguém vai querer ler quando investigar um deploy ruim. ## Só requisição autenticada vira linha Uma chamada sem credencial não tem a quem ser atribuída: não há organização para isolar a linha nem cliente para lê-la. Ela não vira linha, e isso também é o freio natural contra inundação por tráfego anônimo, que numa API pública é a regra e não a exceção. O que não vira linha é contado numa métrica própria, separada da métrica de descarte, para que tráfego de varredura nunca seja lido como perda de registro. ## Como usar no dia a dia Três usos cobrem a maior parte dos chamados. O primeiro é confirmar que uma chamada aconteceu: filtre pelo identificador que a sua aplicação registrou e leia o status. O segundo é encontrar a origem de um erro recorrente: filtre pela chave, ordene pelo período e veja qual rota concentra os códigos de erro. O terceiro é conferir o comportamento de um membro no painel: filtre pelo membro e veja as rotas de painel que ele chamou, sem nunca ver o que foi digitado. A integração de [webhooks assinados](https://unifokal.com/blog/webhooks-seguros-em-kyc) continua sendo o lugar do resultado; o registro é o lugar da chamada. ## Perguntas frequentes ### O registro substitui o meu log de aplicação? Não. Ele confirma o que chegou à UNIFOKAL e como foi respondido; o que aconteceu antes e depois, na sua aplicação, continua sendo assunto do seu log. Os dois se encontram pelo identificador da requisição. ### Por que a mensagem de erro não é gravada? Porque a mensagem é texto livre e pode mudar; o código é estável e é por ele que a sua aplicação deve ramificar. Gravar o código e não a mensagem fecha uma porta por onde dado pessoal poderia voltar ao registro. ### Consigo ver o corpo da resposta de uma chamada antiga? Não, e essa é a promessa. O resultado de uma verificação está na própria verificação, no painel e no webhook; o registro guarda que a chamada aconteceu, nunca o que ela devolveu. ## Fontes citadas - OWASP Cheat Sheet Series, Logging Cheat Sheet: dados a excluir do registro de eventos. OWASP Foundation. https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html - Lei nº 13.709/2018 (Lei Geral de Proteção de Dados Pessoais), artigo 6º, inciso III, e artigo 46, medidas de segurança. Presidência da República. https://www.planalto.gov.br/ccivil_03/\_ato2015-2018/2018/lei/l13709.htm - [Documentação do painel de operação da UNIFOKAL](https://unifokal.com/docs/painel-de-operacao): o registro de requisições.