API version parada no tempo: a dívida técnica que ninguém vê até doer

Durante anos, a versão da API do Salesforce foi tratada como aquele número que ninguém olha até precisar. Você cria uma classe Apex, o VS Code carimba a versão vigente no .cls-meta.xml, e ela fica ali, congelada, enquanto o resto do org evolui ao redor. O discurso oficial sempre foi "suportamos toda versão por no mínimo três anos", o que na prática virou desculpa para nunca mexer em nada. Isso mudou. Salesforce começou a de fato podar versões antigas, e hoje o suporte ativo cobre a partir da v31. Se você tem código em produção com API version de dois dígitos baixos, o relógio está correndo.

Esse tipo de dívida técnica é traiçoeira porque não dói no dia a dia. O código funciona, os testes passam, o cliente não reclama. Até o dia em que Salesforce anuncia o fim de suporte de uma versão e você descobre que tem 40 classes, 15 triggers e um punhado de Visualforce pages presos numa API de 2018, com uma janela de 12 meses para migrar tudo isso sem quebrar processo de negócio nenhum. Em codebase grande, isso não é ajuste pontual: é projeto de regressão inteiro, competindo por prioridade com o backlog de features que o cliente realmente quer.

Onde a versão da API realmente mora

Cada artefato de metadata carrega sua própria API version: Apex class, trigger, Visualforce page, Lightning Web Component, tudo isso tem um apiVersion dentro do -meta.xml. Dá para ver e editar isso direto pela aba "Version Settings" no Setup, ou simplesmente alterando o número no arquivo local e fazendo deploy de novo. Simples na mecânica, mas o trabalho pesado não é técnico, é de levantamento: saber quantos itens estão desatualizados e qual o risco de cada um.

Por que vale a pena atualizar, além de evitar susto

O lado "correr atrás do prejuízo" é óbvio, mas o motivo mais interessante para manter API version em dia é ganhar acesso a recursos que só existem a partir de determinada versão. Alguns exemplos concretos: a classe Assert em testes, que deixa a asserção muito mais legível do que o velho System.assertEquals; o with sharing passando a ser enforced por padrão a partir da v67 (Summer '26), o que muda o comportamento de segurança do seu código sem você escrever uma linha a mais; ou o BatchApexErrorEvent, Platform Event que só existe a partir da v44 e que facilita muito o monitoramento de falha em batch job.

Tem também o argumento que gosto mais de defender em projeto: atualizar API version é desculpa legítima para revisar código que ninguém mexe há anos. É a hora de perguntar se o tratamento de erro está adequado, se tem lógica duplicada que merece ser extraída, se sobrou System.debug esquecido, string que devia ser Custom Label, comentário void. Isso fica ainda mais crítico se você começou a usar Agentforce ou ferramentas de geração de código assistida por IA no seu pipeline: código gerado por IA sem revisão humana criteriosa é dívida técnica em ritmo acelerado.

Testando a mudança sem se enganar

Em teoria, subir a API version não deveria quebrar nada. Na prática, quebra quando uma feature foi deprecada ou quando você aproveitou o momento para já usar um recurso novo. O caminho é: rodar toda a suíte de testes, garantir que os próprios testes também estejam na versão atualizada (senão eles não exercitam os comportamentos novos), e depois validar via UI, API, Flow invocable action, o que for pertinente ao caso.

Aqui defendo abordagem baseada em risco: uma classe central usada em processo crítico de negócio merece regressão ampla; uma classe isolada, pouco tocada, tolera um teste mais enxuto. Gastar o mesmo esforço de validação em tudo é desperdício de tempo de projeto que ninguém vai te agradecer.

As armadilhas que pegam gente experiente

A primeira é segurança: mudanças como o enforcement automático de with sharing e user mode em SOQL/DML na v67 alteram comportamento sem alteração explícita de código. Se você não comunicar isso para o time de administração e para quem desenha permission set e sharing rule, alguém vai abrir chamado dizendo que "o sistema parou de mostrar registro que aparecia antes", e vai ser você quem vai explicar por que isso é, na verdade, o comportamento correto.

A segunda é descompasso de ambiente durante janela de release: sandbox em preview pode estar em versão mais nova que produção, então um item criado ou atualizado nessa janela pode simplesmente não dar deploy quando chegar a hora de subir para produção. Vale mapear isso no calendário de release antes de sair mexendo em API version em massa.

A terceira, e a mais sutil, é Apex dinâmico. Um getDescribe().fields.getMap().keySet() pode devolver quantidade diferente de campos dependendo da API version em que a classe está rodando. Em ambiente de teste real, a mesma chamada trouxe 186 campos na v63 e 184 na v62, só por causa de dois campos que não existiam ainda na versão anterior. Se essa lista alimenta construção dinâmica de query, e a classe que gera a string está em versão diferente da que executa a query, você tem um bug silencioso e difícil de rastrear.

Por fim, fique de olho em métodos deprecados em cada release note. Às vezes o motivo real para adiar uma atualização de versão não é medo, é dependência de um método que está de saída e que precisa ser substituído antes.