Apex no Salesforce: linguagem, usos e boas práticas

Apex no Salesforce: o que é a linguagem de programação e como usá-la em projetos enterprise

Apex é a linguagem de programação de código fechado da plataforma Salesforce, usada para implementar lógica de negócio que a configuração declarativa e o Flow não atendem bem. Em uma operação enterprise, a decisão de escrever Apex não é apenas técnica: ela cria um ativo de software que precisa ser governado, testado, versionado e sustentado por anos. Este artigo explica o que é a linguagem Apex, quando ela é a escolha certa em vez do Flow, como estruturar código para escala e segurança, e como preparar ações Apex reutilizáveis por agentes de IA com o Agentforce.

O que é Apex no Salesforce?

Apex é uma linguagem de programação orientada a objetos, fortemente tipada e executada no lado do servidor da plataforma Salesforce. Ela foi desenhada para manipular diretamente os dados do CRM: objetos, registros, campos e eventos disparam lógica de negócio escrita em Apex, do mesmo modo que triggers de banco manipulam dados em sistemas tradicionais.

Isso significa que Apex não é uma linguagem de uso geral. Ela vive dentro do ecossistema Salesforce, submetida ao modelo de dados da org, ao runtime da plataforma e aos limites de governança que garantem a estabilidade de uma arquitetura multitenant, na qual milhares de organizações compartilham a mesma infraestrutura. Escrever Apex é, portanto, escrever software para a plataforma: você não gerencia servidores, mas também não controla o runtime.

As comparações mais comuns ajudam a situar a linguagem:

• Apex e Java: a sintaxe lembra Java (classes, métodos, tipagem forte), mas Apex é específico do Salesforce. Um desenvolvedor Java se adapta rápido à sintaxe. O que muda é o modelo de execução, o acesso a dados via SOQL/DML e os governor limits.
• Apex e Flow: Flow é automação declarativa, construída sem código e administrável por equipes de negócio. Apex é código, versionável, testável e capaz de expressar lógica complexa e transacional.
• Apex e Visualforce: Visualforce é uma tecnologia de camada de apresentação, enquanto Apex implementa a lógica de negócio. Na prática, interfaces modernas usam Lightning Web Components, e o Apex fica no backend como serviço da aplicação.

A documentação oficial da Salesforce resume bem a divisão de responsabilidades da plataforma: Apex para lógica de negócios, Visualforce (e hoje Lightning) para interface, e APIs para integrações. Em uma org enterprise, o Apex costuma ser a camada onde vivem as regras de negócio mais sensíveis da operação comercial.

Para que serve Apex em uma operação enterprise?

Apex serve para implementar lógica de negócio, automação transacional, validações e processamento de dados que excedem o que a configuração declarativa oferece de forma confiável. Em termos práticos, isso se materializa em classes (unidades de código organizadas), triggers (lógica disparada por eventos em registros), serviços reutilizáveis e integrações com sistemas externos via REST e SOAP.

Cenários típicos em que uma operação enterprise recorre a Apex incluem:

• Regras de negócio complexas: políticas comerciais com múltiplas condições, exceções e dependências entre objetos. O exemplo clássico são as regras de precificação e desconto em implementações de CPQ Salesforce, onde a lógica de configuração de propostas raramente cabe em um Flow administrável.
• Automações transacionais: processos que precisam acontecer de forma consistente dentro da mesma transação do CRM, com sucesso ou falha como um bloco.
• Integrações com ERP e sistemas legados: consolidação de dados, sincronização de pedidos, callouts para serviços externos e tratamento de formatos JSON e XML.
• Processamento de alto volume: recálculos e migrações de massa que exigem processamento em lotes (Batch Apex) e execução assíncrona.
• Lógica dinâmica: consultas SOQL dinâmicas, DML dinâmico e acesso a metadados quando o comportamento do código depende da configuração da org.

O princípio que deve guiar a decisão, e que vamos desenvolver na próxima seção, é simples: código deve resolver uma necessidade que não é bem atendida pela configuração declarativa. Apex escrito para resolver o que um Flow resolveria cria custo de manutenção sem contrapartida. Apex escrito para regras que só o código expressa de forma confiável é um investimento em escala e previsibilidade.

Apex ou Flow: como escolher a abordagem certa?

Flow é a escolha padrão quando a lógica é simples, administrável e bem atendida por recursos declarativos. Apex entra quando existe complexidade transacional, alto volume, necessidade de reuso, integração controlada ou requisitos avançados de segurança e governança. A decisão deve ser um critério de arquitetura, não uma preferência do desenvolvedor que está na frente do teclado naquele dia.

Uma matriz de decisão útil para comitês de arquitetura considera estes critérios:

Critério	Prefira Flow / declarativo	Prefira Apex
Complexidade da lógica	Poucas condições, caminhos lineares	Múltiplas condições, exceções, dependências entre objetos
Volume	Registros individuais ou lotes pequenos	Massas de registros que exigem bulkificação e Batch
Transação	Passos independentes	Sucesso ou falha como bloco (all-or-nothing)
Reuso	Automação específica de um processo	Serviços reutilizáveis por múltiplos processos
Integração	Callouts simples, sem retentativa complexa	Timeout, retentativas, idempotência, reconciliação
Equipe	Time administrado por analistas de negócio	Time com desenvolvedores e processo de release
Governança	Mudança rápida, baixo risco	Mudança versionada, revisada, testada

Dois pontos costumam ser negligenciados nessa decisão. Primeiro, o perfil da equipe de sustentação: um Flow bem construído pode ser mantido por um administrador, enquanto uma classe Apex exige um desenvolvedor no ciclo de mudanças, o que muda o custo operacional da solução. Segundo, o custo de manutenção no longo prazo: lógica de negócio crítica espalhada em dezenas de Flows difíceis de testar pode ser mais cara de sustentar do que um serviço Apex bem estruturado e versionado.

A recomendação prática para operações enterprise: trate o declarativo como padrão, documente as exceções que justificam código e registre a decisão em um padrão de arquitetura da organização. Assim, cada novo trecho de Apex tem um motivo rastreável, e o código não vira dívida invisível.

Fundamentos da linguagem Apex: dados, consultas e operações

Dominar Apex começa por entender como a linguagem representa e manipula dados do CRM. Os fundamentos são poucos e consistentes: tipos primitivos, sObjects (a representação em memória de registros do CRM), coleções e três operações essenciais: SOQL, SOSL e DML.

Tipos de dados e coleções. Apex oferece tipos primitivos como Integer, Boolean, Decimal, Date e String, além de enums e tipos customizados em classes. O trabalho com registros acontece através de sObjects (por exemplo, Account, Opportunity, ou objetos customizados como MyObject__c). As coleções fundamentais são List (sequência ordenada), Set (valores únicos) e Map (pares chave-valor). Dominar Map é o que separa código bulkificado de código que estoura limites.

SOQL, SOSL e DML, a diferença em uma linha cada:

• SOQL (Salesforce Object Query Language): consulta registros de um objeto com filtros, joins e relacionamentos. SELECT Id, Name FROM Account WHERE Industry = 'Technology'.
• SOSL (Salesforce Object Search Language): busca textual em múltiplos objetos ao mesmo tempo. FIND 'contrato*' IN ALL FIELDS.
• DML (Data Manipulation Language): operações de escrita (insert, update, upsert, delete, undelete) aplicadas a registros ou coleções.

Um exemplo curto, no estilo que toda operação enterprise deveria exigir: consulta e atualização em massa, com coleções.

List<Opportunity> fechadas = [SELECT Id, StageName FROM Opportunity
                              WHERE CloseDate = THIS_MONTH AND StageName = 'Closed Won'];

for (Opportunity opp : fechadas) {
    opp.Description = 'Revisão de pós-venda agendada automaticamente.';
}

update fechadas;

A regra de ouro que este exemplo ilustra: nunca coloque SOQL ou DML dentro de loops. Cada consulta e cada operação de escrita consomem limites por transação. Em um cenário de 200 registros (tamanho típico de lote de trigger), um SOQL dentro do loop multiplica o consumo por 200 e derruba a transação. Consulte antes, processe em coleções, escreva depois, em blocos. Esse padrão, chamado bulkificação, é o fundamento de todo Apex enterprise, e é o assunto da próxima seção.

Como estruturar Apex para escala e manutenção

Apex escalável é código que trata listas de registros desde a primeira linha, separa responsabilidades em camadas e evita duplicação de regras de negócio. A estruturação não é estática: é o que permite que uma org com dezenas de objetos e centenas de automações continue evoluindo sem que cada mudança vire um incidente.

Os padrões de arquitetura que uma operação enterprise deve adotar:

• Bulkificação como padrão: todo método que toca registros recebe e processa coleções, nunca um registro por vez. A pergunta de revisão de código é sempre “o que acontece se chegarem 200 registros?”.
• Um trigger por objeto: o trigger é apenas o ponto de entrada e delega imediatamente para uma classe handler. Múltiplos triggers no mesmo objeto criam ordem de execução imprevisível e dificultam a governança.
• Separação em camadas: o trigger é a entrada, o handler orquestra, as classes de domínio guardam as regras do objeto, os serviços concentram a lógica de negócio reutilizável e a camada de integrações isola os callouts do fluxo principal. Cada camada tem um motivo para existir e um teste próprio.
• Tratamento de exceções explícito: exceções capturadas com intenção, com log estruturado e decisão consciente entre reverter a transação ou seguir com registro de falha. Nada de try/catch genérico que engole erros.
• Idempotência: automações disparadas mais de uma vez (por processo, por trigger recursivo, por retentativa de integração) não devem duplicar efeitos.
• Nomenclatura e documentação: convenções da org, comentários de intenção e registro de decisões. O código será lido por pessoas que não o escreveram, possivelmente anos depois.

O objetivo final é evitar o acoplamento excessivo: regra de negócio que existe em um único serviço, testado e chamado por todos os processos que precisam dela. Quando a mesma regra aparece duplicada em trigger, Flow e batch, a mudança de política comercial que deveria levar horas passa a exigir caça manual por toda a org, com risco de esquecer um ponto.

Governor limits: o que a arquitetura precisa considerar

Governor limits são limites por transação impostos pela plataforma Salesforce para controlar o consumo de recursos em uma arquitetura multitenant e garantir que nenhuma organização comprometa a estabilidade das demais. Eles não são um detalhe técnico: são a principal restrição de design de qualquer solução Apex. Tratá-los como risco operacional, e não como curiosidade, é o que separa uma implementação enterprise de um protótipo.

Os limites mais relevantes para decisões de arquitetura abrangem:

• Consultas (SOQL): número de consultas por transação, o que reforça o padrão de consultar em coleções.
• Operações DML: número de escritas por transação, o que reforça escritas em blocos.
• CPU time: tempo de processamento por transação, sensível a loops pesados e lógica mal distribuída.
• Heap size: memória da transação, sensível a coleções grandes retidas desnecessariamente.
• Callouts: número de chamadas a serviços externos por transação, crítico em integrações.
• Volume de registros por transação: o que define quando um processo precisa ser quebrado em lotes assíncronos.

Como identificar riscos antes da produção? Com testes que usam volumes próximos do uso real. Um teste que processa três registros prova pouco. O cenário de pico (a carga de dados de fim de mês, a migração de 50 mil contas, o recálculo de um portfólio inteiro) é o que revela estouro de limite. Checklists de revisão de código devem incluir perguntas objetivas: onde estão os SOQL dentro de loop? O que acontece no pico? Qual limite estoura primeiro e qual é o plano B?

Quando o processo não cabe em uma transação, a plataforma oferece modelos de execução assíncrona, cada um com papel definido:

• Queueable Apex: encadeamento de trabalho assíncrono com estado, ideal para processos em cadeia e callouts.
• Batch Apex: processamento de grandes volumes em lotes com início, execução e finalização controlados.
• Future methods: execuções assíncronas leves e disparo simples de callout.
• Scheduled Apex: agendamento de execuções recorrentes.

A escolha do modelo é uma decisão de arquitetura, registrada com o porquê. E a regra transversal vale sempre: limite estourado em produção é incidente. Limite estourado em sandbox é correção barata.

Segurança e governança de código Apex

Código Apex seguro é código que respeita o contexto de compartilhamento de registros, verifica permissões de acesso a campos e objetos, opera com o menor privilégio possível e deixa rastro auditável do que fez. Em operações enterprise sujeitas a políticas de compliance, esses requisitos são tão mandatórios quanto a funcionalidade, e estão diretamente ligados a privacidade e segurança de dados no Salesforce.

Os pontos que uma revisão de segurança de Apex deve cobrir:

• Contexto de compartilhamento: with sharing aplica as regras de compartilhamento do CRM à execução da classe; without sharing ignora essas regras; inherited sharing herda o contexto do chamador. A escolha deve ser explícita e justificada: classes sem contexto declarado são um risco de auditoria, e o padrão seguro é declarar a intenção sempre.
• CRUD e FLS: Apex deve verificar se o usuário em nome de quem o código roda tem permissão de objeto (CRUD) e de campo (FLS) antes de ler ou escrever. Ignorar essa verificação pode expor dados que a interface jamais mostraria àquele usuário.
• Princípio do menor privilégio: automações não devem rodar com perfis administrativos por conveniência. Cada processo recebe o mínimo de acesso de que precisa.
• Dados sensíveis e credenciais: segredos de autenticação em credenciais nomeadas, nunca em código; cuidado com dados pessoais em logs; tratamento explícito de payloads de callouts.
• Logs, auditoria e revisão: log estruturado de decisões relevantes, revisão de código obrigatória para mudanças críticas e critérios formais para aprovar exceções de segurança, sempre registradas com prazo e responsável.

O alinhamento com as políticas da empresa acontece quando segurança é tratada como critério de aceite do código, não como etapa posterior de auditoria. Em operações reguladas, o custo de retrofit é muito maior do que o custo de revisão.

Testes, CI/CD e deploy entre ambientes

Implantar Apex em produção com confiança exige testes de unidade e de integração, versionamento, pipeline de promoção entre ambientes e monitoramento pós-deploy. Na plataforma, a cobertura de testes é requisito da própria plataforma para promover código. Tratar a cobertura como único indicador, porém, é o erro clássico: 100% de cobertura com asserções vazias não protege nada.

Um processo de qualidade maduro para Apex enterprise inclui:

1. Testes unitários com asserções significativas: verificar o resultado esperado do comportamento, não apenas executar o código. Asserções que comparam valores, estados e efeitos colaterais.
2. Dados de teste isolados: criação de registros de teste dentro da própria execução, sem dependência de dados da org, o que também mantém o sandbox confiável.
3. Testes negativos e de volume: cenários de falha (integração fora do ar, dados inválidos, exceções) e lotes próximos do uso real, reveladores de governor limits.
4. Testes de integração: verificação do contrato com sistemas externos, incluindo comportamento diante de timeout e erro.

Do desenvolvimento à produção:

• Ambientes: desenvolvimento em sandbox dedicado, promoção controlada por pipeline para ambientes de qualidade e produção, com nomeação clara de propósito de cada ambiente.
• Controle de versão: todo o código e metadados em repositório (Git), com revisão de pull request obrigatória para mudanças em componentes críticos.
• CI/CD: pipeline automatizado executa testes, valida o deploy e bloqueia promoção de mudanças que quebram comportamento existente.
• Validação e rollback: toda mudança é validada em ambiente de qualidade antes de produção, e a estratégia de rollback é definida antes do deploy, não durante o incidente.
• Monitoramento pós-deploy: acompanhamento de logs de erro, consumo de limites e indicadores do processo nas primeiras execuções reais.

A responsabilidade é distribuída: desenvolvimento responde pela qualidade do código, arquitetura pelo desenho e pelos padrões, operação pelo monitoramento e o negócio pela validação dos resultados. Quem sustenta o código, e o papel do desenvolvedor Salesforce na operação contínua, precisa estar na mesa desde o design, não só quando algo quebra.

Apex em integrações e processos assíncronos

Apex é frequentemente a camada de integração do CRM com o resto do parque tecnológico, via REST, SOAP e APIs, com payloads em JSON e XML. A regra central de desenho é: a integração externa nunca deve comprometer a transação do CRM. Um ERP indisponível às 9h de um dia de fechamento não pode travar a criação de pedidos no Salesforce.

Boas práticas de integração com Apex:

• Callouts fora da transação principal: chamadas externas não podem ocorrer no meio de uma transação aberta com locks (a plataforma sequencia DML e callouts por motivos estruturais). O padrão é processar a transação do CRM e delegar a chamada para o assíncrono.
• Autenticação gerenciada: credenciais nomeadas e autenticação padronizada, sem segredos em código.
• Timeout e retentativa explícitos: definir comportamento diante de lentidão e falha, com limites de retentativa para não amplificar o problema.
• Idempotência e reconciliação: o mesmo evento processado duas vezes não pode duplicar efeito no sistema externo. Processos críticos têm mecanismo de reconciliação de dados entre sistemas.

A escolha entre processamento síncrono e assíncrono segue critérios claros: síncrono quando o usuário precisa do resultado na hora e a latência é aceitável; assíncrono (Queueable, Batch, Future, Scheduled) quando o volume é alto, a latência externa é imprevisível ou o trabalho pode ser posterior. Em cenários de dados em escala, essa arquitetura conectada dialoga diretamente com plataformas como o Salesforce Data Cloud, onde o desenho de integração define o que se ganha de unificação de dados. Para um panorama completo das opções de conexão, o tema é aprofundado em Salesforce API e integrações com o CRM.

Como Apex pode ampliar o Agentforce

Agentforce pode chamar código Apex por meio de ações customizadas e métodos invocáveis (@InvocableMethod), expondo lógica de negócio já validada para um agente de IA sem duplicar regras. Essa é a ponte entre o mundo dos agentes autônomos e o patrimônio de automações que a operação já construiu, e ela precisa ser desenhada com governança, não apenas exposta.

O princípio de desenho mais importante: separar a decisão do agente da execução controlada da lógica Apex. O agente decide qual ação chamar e com quais entradas; a ação Apex valida tudo de novo, do jeito que o código de produção valida. Confiar na “boa intenção” do agente não é controle.

Uma ação Apex preparada para um agente deve garantir:

• Validação de entradas: o método invocável trata qualquer entrada do agente como não confiável, verificando tipos, valores, limites e regras de negócio.
• Autorização: verificação de contexto e permissões do usuário em cujo nome a ação executa. O agente não é uma licença para ignorar CRUD, FLS e sharing.
• Idempotência: a ação pode ser chamada novamente pelo agente sem duplicar efeitos.
• Limites e erros: a ação respeita governor limits e retorna erros tratáveis, com mensagens que permitam ao agente (ou ao humano que supervisiona) entender a falha.
• Observabilidade: logs de execução das ações, rastreio de decisões do agente e revisão humana obrigatória em processos críticos, como aprovação de descontos acima de política, ações financeiras e alterações de dados sensíveis.

O ganho estratégico desse desenho é o reuso: a regra de elegibilidade que hoje roda no Flow e no trigger vira um serviço Apex único, consumido também pela ação do agente. Uma fonte de verdade para a regra, três consumidores. Quando a política muda, muda em um lugar só, e o agente continua correto.

Checklist para avaliar uma implementação Apex enterprise

Uma implementação Apex está pronta para a realidade enterprise quando passa por seis perguntas, na ordem:

1. A necessidade realmente exige código? A solução declarativa (Flow, validações, fórmulas) foi considerada e descartada com justificativa registrada?
2. A solução é bulkificada e respeita governor limits? Métodos processam coleções, não há SOQL/DML em loop, e o cenário de pico foi testado contra os limites da transação.
3. A segurança e o contexto de acesso foram revisados? Sharing declarado e justificado, CRUD/FLS verificados, menor privilégio aplicado, credenciais fora do código.
4. Existem testes de volume, falha e integração? Asserções significativas, cenários negativos, lotes próximos do uso real e contratos de integração verificados. Cobertura alta é consequência, não meta.
5. O deploy é reproduzível e versionado? Tudo em controle de versão, pipeline automatizado, promoção validada em qualidade, estratégia de rollback definida antes do deploy.
6. A operação terá monitoramento, documentação e plano de sustentação? Logs de erro acompanhados, decisões de arquitetura documentadas, responsável definido para manter o código vivo após o go-live.

Se qualquer resposta for “não” ou “não sei”, o ponto é uma pendência de arquitetura, não um detalhe para resolver depois do incidente.

Perguntas frequentes sobre Apex no Salesforce

O que é Apex no Salesforce? Apex é a linguagem de programação orientada a objetos, fortemente tipada e executada no servidor da plataforma Salesforce, usada para implementar lógica de negócio no CRM. Ela manipula objetos, registros e eventos da plataforma, e é a camada de código para o que a configuração declarativa não atende de forma confiável.

Apex é a mesma coisa que Java? Não. A sintaxe tem semelhanças que facilitam a adaptação de quem vem do Java, mas Apex é específica da plataforma Salesforce: roda no runtime do CRM, manipula dados via SOQL/DML e está sujeita ao modelo de dados e aos governor limits da plataforma. Não é uma linguagem de uso geral fora do ecossistema Salesforce.

Quando usar Apex em vez de Flow? Use Flow para lógica simples, administrável e bem atendida por recursos declarativos; considere Apex quando houver complexidade transacional, alto volume, necessidade de reuso, integração com tratamento avançado ou requisitos mais rigorosos de segurança, testes e governança. O critério deve considerar também o perfil da equipe que vai sustentar a solução, não apenas a preferência de quem implementa.

O que são governor limits no Apex? São limites por transação (consultas SOQL, operações DML, CPU, heap, callouts e volume de registros) criados para controlar o uso de recursos em uma arquitetura multitenant e garantir a estabilidade compartilhada da plataforma. Eles devem ser tratados como restrição de design desde o início, com testes de pico, e não como surpresa de produção.

Qual é a diferença entre SOQL, SOSL e DML? SOQL consulta registros de objetos com filtros e relacionamentos (SELECT Id FROM Account WHERE ...); SOSL faz busca textual em múltiplos objetos simultaneamente (FIND 'termo'); DML executa operações de escrita (insert, update, upsert, delete) sobre registros ou coleções. Em Apex enterprise, as três operam sempre sobre coleções, nunca registro a registro dentro de loops.

Apex é obrigatório para personalizar o Salesforce? Não. Grande parte das necessidades de personalização é atendida por configuração declarativa: campos, validações, layouts, automações com Flow. Apex é indicado para cenários que exigem lógica complexa, controle transacional, alto volume ou integrações avançadas, e deve ser uma decisão justificada, não o caminho padrão.

Como tornar um código Apex seguro e escalável? Com bulkificação (processar coleções, sem SOQL/DML em loops), respeito aos governor limits, declaração explícita do contexto de compartilhamento (with sharing e variantes), verificação de CRUD/FLS, princípio do menor privilégio, tratamento de exceções, testes com asserções significativas, observabilidade e revisão periódica de arquitetura. Segurança e escala são critérios de aceite, não etapas opcionais.

Como testar e implantar código Apex em produção? Com testes unitários e de integração (incluindo cenários negativos e de volume), desenvolvimento em sandbox, versionamento em repositório, revisão de pull request, pipeline de CI/CD com validação em ambiente de qualidade, estratégia de rollback definida antes do deploy e monitoramento de logs e limites após a promoção. A cobertura de testes é requisito mínimo da plataforma, não o único indicador de qualidade.

Agentforce pode chamar código Apex? Sim, por meio de ações customizadas e métodos invocáveis (@InvocableMethod). A boa prática é tratar a ação como uma camada controlada: validação de entradas, autorização com verificação de permissões, idempotência, tratamento de erros, logs e revisão humana para processos críticos, mantendo a decisão do agente separada da execução validada da lógica de negócio.

Fale com a WeeNow

Sua operação Salesforce precisa de código Apex, Flow ou uma arquitetura combinada? Converse com um especialista da WeeNow para avaliar o cenário, os riscos de escala e o próximo passo técnico, do desenho de arquitetura à sustentação do código em produção.

Falar com um especialista da WeeNow