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 a retenção, mas permite mandar o arquivo de saída inteiro para a lixeira; depois que ele é apagado, 30 dias depois, 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. Uma política mais curta, {keepLast: N} para guardar as últimas N versões existentes ou {keepDays: N} para guardar as criadas nos últimos N dias, não pode ser definida por um agente: organization_update só aceita {keep: "all"} e recusa as outras com invalid_arguments. 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.

Os números de versão nunca são reutilizados. A retençã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.