Desenvolvimento em Apex na REDA

O Apex personalizado ao redor da REDA Financials segue uma regra de ouro: construa contra a superfície global e os objetos, nunca contra os componentes internos. Aqui está o conjunto de ferramentas estável e os padrões que o utilizam bem.

A superfície global — treze classes e interfaces

Em um pacote gerenciado, apenas o Apex global fica visível para o seu código; tudo o que é public vive atrás da barreira do namespace. A REDA Financials mantém essa superfície suportada deliberadamente pequena — treze tipos globais para código de clientes e parceiros. Cinco são os pontos de entrada do dia a dia; os demais são os contratos de extensão de nota fiscal eletrônica e os tipos de dados que eles trocam:

Os contratos abstratos de provedor são abordados em Pacotes de extensão; este artigo foca nas duas classes que você chama. Todas as classes de API são entregues na versão de API 65.0, e vale a promessa padrão de pacote gerenciado: uma vez lançada, uma assinatura global não pode ser removida nem alterada sob os seus pés — ela é o contrato estável.

O que você não pode chamar

A camada de serviço interna que faz o trabalho de verdade — contabilização, importação de extrato bancário, renderização de PDF, chamadas de IA e de câmbio, atualizações de status em massa, carga inicial de impostos — é public, não global. O Apex do assinante não consegue chamar essas classes de forma alguma: o compilador simplesmente não as enxerga através da fronteira do namespace, e sua forma interna pode mudar em qualquer versão. Se um recurso de que você precisa vive apenas atrás de uma classe pública, a rota suportada é o comportamento que ela viabiliza — contabilização pelo campo de status, geração de PDF via refin.PDFGeneratorAPI, carga inicial de impostos via o Assistente de Configuração de Impostos empacotado — não a classe em si.

refin.GlobalTaxService — o cálculo de impostos como serviço

Dois métodos estáticos dão ao seu código os mesmos motores que os documentos usam, sem efeitos colaterais:

• calculateTax(TaxRequest) — imposto indireto (IVA/GST/imposto sobre vendas). Informe entidade, conta, data, lado ('Sales'/'Purchase') e linhas (valor + produto ou perfil fiscal explícito, com sua própria lineKey para correlação); receba de volta linhas de imposto por linha totalmente resolvidas — alíquota, valor, sinalizador de recuperabilidade e a conta contábil em que cada imposto seria contabilizado.
• calculateWithholdingTax(WHTRequest) — o motor de retenção na fonte, mesma estrutura: linhas entram, retenção por linha sai (alíquota, base, valor, motivos de isenção, conta contábil).
• O contrato: sem DML, nenhum registro criado, nunca lança exceção — os erros retornam como success=false com uma mensagem. A persistência é inteiramente sua: perfeito para cotações, calculadoras, estimativas pré-contabilização ou verificações de paridade com sistemas externos.

A referência completa

Ambos os pontos de entrada são estáticos:

global static TaxResponse calculateTax(TaxRequest request)
global static WHTResponse calculateWithholdingTax(WHTRequest request)

A documentação da classe declara o contrato claramente: "Nenhum DML é executado. Nenhum registro de Source_Line_Tax ou WHT_Transaction é criado. Quem chama a classe é responsável pela persistência e pela contabilização." Uma resposta "sempre é retornada, nunca lança exceção para quem chamou" — problemas de validação (entidade, conta, data, lado ou linhas ausentes, ou um valor de lado inválido) retornam como success=false com o motivo em errorMessage, na mesma linguagem de validação que os próprios documentos usam. Existe uma classe GlobalTaxServiceException na superfície global, mas, sob o contrato normal, você lê a resposta em vez de capturar exceções.

Os DTOs de requisição e resposta são classes globais com membros globais — tudo abaixo é seu para definir ou ler:

O conjunto de retenção na fonte espelha isso:

Como as contas contábeis são resolvidas. As contas contábeis de impostos indiretos vêm dos registros de Mapeamento de Tipo de Imposto para o Razão (refin__Tax_Type_GL_Mapping__c): um mapeamento específico da entidade prevalece sobre um mapeamento em nível de organização, indexado pelo tipo de imposto e pela recuperabilidade referente ao lado da requisição; impostos embutidos recebem adicionalmente uma conta de dedução do lado 'Sales Deduction' / 'Purchase Deduction' do mapeamento. As contas contábeis de retenção vêm da Conta Contábil na Alíquota de Retenção na Fonte correspondente, recorrendo à conta padrão de Retenção a Pagar da entidade quando não há correspondência. Em outras palavras, a resposta informa não apenas quanto, mas onde isso cairia — a mesma resolução que a contabilização realiza.

Uma chamada mínima, ao estilo Meridian — a entidade dos EUA precificando a linha de aluguel de um locatário antes de qualquer fatura existir:

refin.GlobalTaxService.TaxRequest req = new refin.GlobalTaxService.TaxRequest();
req.entityId = meridianUsEntityId;
req.accountId = brightlineAccountId;
req.transactionDate = Date.today();
req.side = 'Sales';

refin.GlobalTaxService.TaxLineRequest line = new refin.GlobalTaxService.TaxLineRequest();
line.lineKey = 'unit-4b-rent';
line.amount = 9000;
line.productId = officeRentProductId;
req.lines = new List<refin.GlobalTaxService.TaxLineRequest>{ line };

refin.GlobalTaxService.TaxResponse res = refin.GlobalTaxService.calculateTax(req);
if (res.success) {
    for (refin.GlobalTaxService.TaxResultLine t : res.lines) {
        System.debug(t.lineKey + ' -> rate ' + t.taxRate + ', tax ' + t.taxAmount
            + ', GL ' + t.glAccountId);
    }
} else {
    System.debug(res.errorMessage);
}

O gêmeo de retenção segue o mesmo ritmo. A entidade da Índia da Meridian, estimando o TDS sobre a fatura de um prestador antes de ela ser lançada: monte um WHTRequest com side = 'Purchase', um WHTLineRequest por linha da fatura carregando lineSubtotal, chame calculateWithholdingTax e leia cada WHTResultLine — rate, base, amount e isExempt com seu exemptReason quando um certificado ou limite isenta a linha. Como nada é persistido, a equipe de contas a pagar pode informar o valor líquido a pagar ao fornecedor e os números vão bater com o documento contabilizado até o último centavo.

refin.PDFGeneratorAPI — documentos a partir de código

generateOne(sourceRecordId, sourceObjectApiName) renderiza e anexa o PDF de uma Fatura de venda, Nota de crédito, Recebimento, Desembolso ou Ordem de compra contabilizados — retornando os IDs de conteúdo e, onde o território habilita links públicos, a URL. O gêmeo em Fluxo é abordado em Integração de Fluxos do Salesforce.

A assinatura:

global static PDFResult generateOne(Id sourceRecordId, String sourceObjectApiName)

Nas próprias palavras da classe, "pacotes de extensão chamam isso a partir do Apex quando precisam de geração programática de PDF fora do contexto de Fluxo." O sourceObjectApiName deve ser um dos objetos de origem suportados:

O PDF gerado é anexado ao registro de origem como um ContentVersion com um ContentDocumentLink — um File normal do Salesforce que você pode consultar, compartilhar ou enviar por e-mail. O publicUrl do resultado só é preenchido "se a Entidade tiver a URL Pública Automática habilitada; caso contrário, é nulo" — portanto, o código que envia links por e-mail aos clientes deve verificar se é nulo em vez de presumir que existe uma URL. E você pode nem precisar de código: cada entidade traz alternadores de geração automática por tipo de documento (refin__Auto_Gen_PDF_Sales_Invoice__c, refin__Auto_Gen_PDF_Cash_Receipt__c, refin__Auto_Gen_PDF_Cash_Disbursement__c, refin__Auto_Gen_PDF_Purchase_Order__c, refin__Auto_Gen_PDF_Credit_Memo__c) — o generateOne é para os momentos fora desses casos, como regenerar sob demanda ou anexar a um envio personalizado.

Contabilizando a partir do Apex — o campo de status é a API

Não existe um método post() para chamar, por design: o motor de contabilização é executado na fase de trigger da própria atualização do objeto de origem. Seu Apex contabiliza um documento da mesma forma que um usuário faz — mude refin__Status__c de 'Draft' para 'Posted' com uma atualização de DML, e toda a maquinaria é executada: os motores de imposto e retenção na fonte, a gravação da taxa de câmbio na transição para Posted, e todas as proteções (portão de aprovação, validação de período, bloqueios de entidade/conta contábil inativa). Uma contabilização recusada aparece como uma exceção de DML carregando a mensagem exata da proteção — trate isso como o contrato da API, não como ruído.

O padrão confiável de criação é em duas etapas: inserir como Draft (cabeçalho e linhas) e, em seguida, atualizar o status para 'Posted' em uma segunda chamada. Na inserção, um status nulo assume 'Draft' por padrão, os números de documento são atribuídos automaticamente a partir da sequência de documentos da entidade (predefinir o Name significa numeração manual, e a exclusividade é validada), e os padrões da entidade são preenchidos automaticamente — livro razão, período contábil e data de vencimento a partir da condição de pagamento do fornecedor. Observe que alterar a entidade ou o tipo de fatura em um Draft reordena sua numeração, então faça suas edições antes de contabilizar.

Reagindo a eventos contábeis

Seus triggers e Fluxos disparados por registro nos objetos refin__ coexistem tranquilamente com os do próprio pacote (a ordem entre pacotes e a automação da organização segue as regras padrão da plataforma — mantenha os seus idempotentes). O padrão de maior valor: reagir a transições de status — um trigger na Fatura de venda que percebe Draft→Posted pode alimentar seu sistema downstream com o documento já totalmente validado e numerado. Reaja depois do trabalho do pacote: leia o estado final do registro em vez de tentar se intercalar.

As regras que mantêm você seguro em atualizações

Erros comuns a evitar

O que vem a seguir

1. Pacotes de extensão — os contratos de provedor para ISVs.
2. Lightning Web Components — a contraparte de interface.
3. Visão geral da API — o mapa.

Perguntas frequentes