Pacotes de extensão

Algumas integrações são produtos por si só — feeds bancários com credenciais de provedor, fatura eletrônica em APIs governamentais. A REDA Financials estrutura essas integrações como pacotes de extensão: o núcleo define um contrato abstrato global, a extensão o implementa, e um registro de configuração conecta os dois. Hoje são dois contratos base, mais três interfaces de capacidade opcionais que um provedor implementa apenas se precisar delas.

Como o padrão funciona

Ambos os contratos seguem a mesma arquitetura, e ambos os cabeçalhos de classe descrevem isso com as mesmas palavras: "The core package resolves the provider at runtime via: Type.forName(setup.Provider_Class__c).newInstance()". Nenhum dos dois contratos codifica um fornecedor de forma fixa. Há quatro partes móveis, cada uma com um responsável claro:

refin.BankFeedProvider — extratos bancários automatizados

• O contrato: três métodos que uma implementação fornece — connect (o fluxo de vinculação do provedor), sync (buscar transações desde o cursor e entregar linhas de extrato), disconnect (revogar o acesso). Os resultados retornam em um formato padrão (sucesso, transações importadas, cursor atualizado, saldo, erro).
• A conexão: um registro de Configuração de feed bancário por conta conectada — nome do provedor, ambiente (Sandbox/Production), o nome da classe implementadora, cursor de sincronização e status (Active / Paused / Error / Disconnected), última sincronização. As configurações ficam na página de registro da conta bancária.
• As credenciais permanecem com a extensão — o núcleo nunca vê os tokens do provedor; a extensão é responsável por toda a sua autenticação de ponta a ponta.
• O resultado: os extratos chegam como extratos bancários comuns (origem de importação marcada de acordo) e seguem para a mesma correspondência e conciliação que um CSV teria — automação a montante, fluxo de trabalho familiar a jusante.

O contrato de feed bancário, método a método

Cada método recebe o registro de configuração como seu contexto. A documentação da classe explica o modelo: "Each method receives the Bank_Feed_Setup__c record as the primary context — the provider reads the linked bank account and its own credentials to execute sync logic."

global abstract BankFeedResult sync(refin__Bank_Feed_Setup__c setup);

global abstract BankFeedResult connect(
    refin__Bank_Feed_Setup__c setup,
    Map<String, String> params
);

global abstract void disconnect(refin__Bank_Feed_Setup__c setup);

BankFeedResult é uma classe interna global — todo membro é @AuraEnabled global, e o construtor define success como false e transactionsImported como 0 por padrão, de modo que uma implementação precisa conquistar um sucesso:

refin__Bank_Feed_Setup__c — referência de campos

Um esqueleto de implementação

Aqui está o formato de um provedor — a equipe da Meridian esboçando um contra a API direta do banco americano deles. Apenas as peças do contrato são reais; os comentários marcam onde entra a lógica do seu provedor:

global class MeridianBankFeedProvider extends refin.BankFeedProvider {

    global override refin.BankFeedProvider.BankFeedResult connect(
            refin__Bank_Feed_Setup__c setup, Map<String, String> params) {
        refin.BankFeedProvider.BankFeedResult result =
            new refin.BankFeedProvider.BankFeedResult();
        // Exchange the connection parameters (e.g. public_token) with the
        // provider. Store credentials in YOUR package — never in core objects.
        result.success = true;
        return result;
    }

    global override refin.BankFeedProvider.BankFeedResult sync(
            refin__Bank_Feed_Setup__c setup) {
        refin.BankFeedProvider.BankFeedResult result =
            new refin.BankFeedProvider.BankFeedResult();
        // 1. Fetch transactions since setup.refin__Sync_Cursor__c
        // 2. Deliver them as bank statement lines
        // 3. Return the new cursor so it can be persisted
        result.transactionsImported = 42;
        result.updatedCursor = 'cursor-after-this-batch';
        result.success = true;
        return result;
    }

    global override void disconnect(refin__Bank_Feed_Setup__c setup) {
        // Revoke tokens and webhooks on the provider side; the core
        // sets Sync_Status to Disconnected after this completes.
    }
}

refin.EInvoiceProvider — fatura eletrônica obrigatória

• O contrato: submit (montar o payload da jurisdição a partir do documento e chamar a autoridade), checkStatus (consultar autoridades assíncronas), cancel (regras específicas por jurisdição se aplicam — a própria nota do contrato cita a janela de 24 horas do Brasil e a aceitação do destinatário no México).
• A conexão: uma Configuração de fatura eletrônica por entidade/país — provedor, ambiente, classe implementadora, quais tipos de documento participam, e uma opção Auto Submit On Post; toda tentativa de envio é registrada como um Histórico de fatura eletrônica no documento (status, UUID e número fiscal, payloads, resposta, contagem de tentativas) — a trilha de auditoria de conformidade que os reguladores exigem.
• Nota sobre disponibilidade: os históricos e listas relacionadas são visíveis em todo o aplicativo (você já viu Históricos de fatura eletrônica nas páginas de fatura); o envio ao vivo requer a extensão de provedor da sua jurisdição — confirme o que está disponível para o seu país com a REDA.

O contrato de fatura eletrônica, método a método

Os três retornam um EInvoiceResult — membros: success, status, fiscalUUID, fiscalNumber, responseCode, responseMessage, xmlPayload, responsePayload, errorMessage.

Os objetos de fatura eletrônica — referência de campos

O registro refin__E_Invoice_Trail__c é a linha de auditoria de cada envio: referências à configuração e à fatura de origem, Document_Type__c, Status__c, Fiscal_UUID__c, Fiscal_Number__c, XML_Payload__c, os campos de resposta (Response_Code__c/Message__c/Payload__c/Date__c), Submitted_Date__c, Retry_Count__c e Provider_Document_Id__c — a cadeia de evidências que os reguladores exigem, uma linha por tentativa. Status__c tem oito valores: Draft, Ready to Send, Queued, Submitted, Accepted, Rejected, Cancelled, Error.

Interfaces de capacidade opcionais — como um contrato congelado ainda cresce

O refin.EInvoiceProvider foi publicado como classe abstrata global em uma versão Managed-Released, o que significa que nenhum método pode mais ser adicionado a ele. Em vez de congelar o framework junto com ele, a REDA adiciona o comportamento novo como interfaces globais separadas, algo que o Salesforce permite. Um provedor estende EInvoiceProvider e implementa as interfaces de capacidade que suporta; o núcleo detecta o suporte com instanceof e simplesmente pula a capacidade para os provedores que não a implementam.

Os três tipos de dados que elas trocam

• refin.EInvoiceEvent: um marco na vida de um documento perante a autoridade. O núcleo o correlaciona com uma trilha por erpDocumentId, um valor que o seu provedor carimba no envelope de saída e que a autoridade devolve. O status é normalizado para Accepted, Rejected, Cancelled ou InProgress: o núcleo baseia as novas tentativas e os estados terminais nesse campo, nunca no responseCode bruto. Também carrega notificationId, processType (Outbound / Inbound), responseMessage, fiscalUUID, fiscalNumber, uma lista opcional documents, payload e eventDate.
• refin.EInvoiceDocument: um artefato, com title, fileExtension ('xml' ou 'pdf'), base64Body e documentKind ('Legal', 'LegalResponse' ou 'Representation'). O núcleo o decodifica e o anexa à trilha e à fatura de origem como arquivos do Salesforce, para que os usuários vejam os artefatos em conformidade no registro com que já trabalham.
• refin.EInvoiceProvisionResult: success (que por padrão é false), externalId (o identificador do lado do provedor) e message.

documentKind, processType e status são todos String e não enums, deliberadamente, para que o conjunto permitido possa crescer sem quebrar uma assinatura global congelada. Não faça um switch exaustivo sobre eles: trate os valores que você conhece e deixe os demais passarem.

Erros comuns a evitar

Para equipes que constroem uma extensão

• Implemente a classe abstrata no namespace do seu pacote; registre o nome de classe totalmente qualificado no registro de configuração.
• Seja responsável pelas suas credenciais (credenciais nomeadas no seu pacote), pelo seu mapeamento de API, pela sua semântica de erros — retorne resultados honestos; o núcleo os exibe em Sync Status e nos históricos.
• Programe apenas contra o contrato — a superfície global documentada é a estável (as regras).

O que vem a seguir

1. Importação de extratos bancários — para onde os feeds fluem.
2. Integrações do AppExchange — o panorama mais amplo do ecossistema.
3. Desenvolvimento em Apex na REDA — as regras da superfície global.

Perguntas frequentes