---
title: "Referências, retenção e exclusão de versões"
description: "Referências, retenção e exclusão de versões"
---

Cada referência retida guarda o arquivo e sua versão: a origem de um registro, o modelo XLSX de um formato e o arquivo gerado por uma exportação. `record_read` e `record_history` retornam `sourceFileId` com `sourceVersion`; `format_get` retorna `templateVersion`. Leia a origem com `file_read({fileId: sourceFileId, version: sourceVersion})`. Os recibos de exportação continuam apontando para a versão que aquela exportação gerou. Essa referência protege a versão contra retenção e exclusão individual, mas permite apagar o arquivo de saída inteiro pela lixeira e `purge`; depois disso, repetir a exportação com o mesmo `requestId` falha com `not_found`. Arquivos de origem e modelos continuam protegidos contra exclusão inteira enquanto forem referenciados.

Por padrão, a empresa guarda todas as versões. Um proprietário ou administrador pode mudar `versionRetention` com `organization_update`: `{keep: "all"}`, `{keepLast: N}` para guardar as últimas N versões existentes, ou `{keepDays: N}` para guardar as criadas nos últimos N dias. N precisa ser um inteiro positivo. `principal_get` retorna a política em `organization.versionRetention`. A manutenção aplica a política a cada cinco minutos e sempre preserva a versão atual e todas as versões presas a referências retidas.

`purge({fileId, version, confirm: true})` exclui uma versão de um arquivo ativo. Exige o criador do arquivo, um proprietário ou um administrador, além de permissão de escrita. Uma versão presa a uma referência ou a única versão do arquivo falha com `conflict`. Ao excluir a versão atual, a última versão anterior ainda existente passa a ser a atual, com seu conteúdo e índices. O conteúdo só é removido do armazenamento quando nenhuma versão o usa.

Os números de versão nunca são reutilizados. A retenção, a exclusão de uma versão e o cancelamento de uma exportação podem deixar lacunas no histórico; `file_history` lista as versões que continuam existindo. Para escrever, use sempre a versão atual como `baseVersion`, sem calcular o número da próxima versão.